The ParGeo Package

Module contents

Submodules

pargeo.constraint module

This module defines constraints for geometric objects in the pargeo library.

It includes an abstract base class Constraint that defines the interface for all constraints, and DistanceConstraint.

DistanceConstraint allows setting distance constraints between different geometric objects. These objects can be domain multipolygons, addressed by their level or shapely Geometry objects. The distances can be set between any two objects, or to the boundary of an object. The constraints are stored in three dictionaries, one for distances between domain multipolygons, one for distances to the boundaries of domain multipolygons, and one for distances to shapely Geometry objects.

class pargeo.constraint.DistanceConstraint[source]

Bases: Constraint

Distance constraint.

set_distance(obj_1, obj_2, distance, to_boundary=False)[source]

Set distance constraint.

If one of the objects is “all”, the distance constraint is set for all levels.

Parameters:

  • distance (float) – Minimal distance between obj_1 and obj_2.

  • obj_1 (Level | Literal["all"]) – The first object.

  • obj_2 (Level | Literal["all"] | ShapelyGeometry) – The second object.

  • to_boundary (bool) – If True, the distance is measured to the boundary. Defaults to False.

__call__(subdomain, level, domain, **kwargs)[source]

Compute the distance constraint.

Parameters:

  • subdomain (SubDomain) – The subdomain to check.

  • level (Level) – The level of the subdomain.

  • domain (Domain) – The domain to check against.

  • kwargs (Any) –

Return type:

bool

show()[source]

Print the distance constraints.

pargeo.domain module

This is the main module of pargeo.

The module provides the Domain class, which can be used to generate complex two-dimensional geometries, also called domains.

The Domain class simplifies the process of sequentially modifing the domain by adding geometries, in form of shapely polygons, to some initial domain.

The polygons that are added to the domain are equipped with a level, which is used to introduce a hierarchy between them. The higher the level of the polygon is, the more visible it is, i.e. it covers the polygons with a lower level.

Additionally, holes can be defined, holes are levels, and polygons whose level is in holes are not visible, basically they are holes in the domain.

Example:

>>> from pargeo.domain import Domain
>>> from shapely.geometry import Polygon

>>> domain = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
>>> domain = Domain(domain, holes={1})
>>> subdomain = Polygon(...) # Some shapely polygon
>>> domain.add(subdomain, level=1)
class pargeo.domain.Transform(*args, **kwargs)[source]

Bases: Protocol

The Transform protocol represents a callable that takes a SubDomain, a Level, a Domain, and any number of additional keyword arguments, and returns a SubDomain.

This is used to define the interface for transformations that can be applied to a SubDomain.

__call__(subdomain, level, domain, **kwargs)[source]

Applies the transformation to the given SubDomain.

Parameters:

  • subdomain (SubDomain) – The SubDomain to transform.

  • level (Level) – The Level of the subdomain.

  • domain (Domain) – The underlying domain.

  • **kwargs – Additional keyword arguments for the transformation.

Returns:

The transformed SubDomain.

Return type:

SubDomain

class pargeo.domain.Constraint(*args, **kwargs)[source]

Bases: Protocol

The Constraint protocol represents a callable that takes a SubDomain, a Level, a Domain, and any number of additional keyword arguments, and returns a boolean.

This is used to define the interface for constraints that can be applied to a SubDomain.

__call__(subdomain, level, domain, **kwargs)[source]

Applies the constraint to the given SubDomain.

Parameters:

  • subdomain (SubDomain) – The SubDomain to apply the constraint to.

  • level (Level) – The Level of the SubDomain.

  • domain (Domain) – The underlying domain.

  • **kwargs – Additional keyword arguments for the constraint.

Returns:

True if the SubDomain satisfies the constraint, False otherwise.

Return type:

bool

class pargeo.domain.Domain(background, holes={}, grid_size=1e-15)[source]

Bases: object

Class for the creation of complex two-dimensional domains.

A domain is a two-dimensional geometry, which can be modified by adding subdomains to it. The subdomains are shapely polygons, or multipolygons, and can be added using the add method. The subdomains are equipped with a level, which is used to introduce a hierarchy between them.

Subdomains with a higher level will be cut out from those with a lower level. Visually speaking the higher level subdomains are more visible and cover the lower level subdomains. The lowest level is the Domain.background_level.

Subdomains with the same level are merged together.

Parameters:

  • background (SubDomain) –

  • holes (set[Level]) –

  • grid_size (float) –

background_level = 0
property level_to_subdomain: dict[int, Polygon | MultiPolygon]

Dictionary mapping each level to its corresponding subdomain.

property holes: set[int]

Set of levels that are considered as holes.

set_holes(new_holes)[source]

Set self.holes.

Parameters:

new_holes (set[int]) –

property grid_size: float

Used grid_size for shapely geometry manipulating operations.

property profile: Polygon | MultiPolygon

The profile of the domain.

If the added subdomains are clipped to the background, then the profile matches the background. Otherwise it can be bigger.

property levels: list[int]

Present levels in sorted order.

property subdomains: list[Polygon | MultiPolygon]

Return a list of all subdomains.

add_subdomain(subdomain, level, transform=None, constraint=None, clip=True, **kwargs)[source]

Adds a subdomain to the domain.

This method performs the following steps before potentially adding the subdomain:

  1. Transforms the incoming subdomain using transform.

  2. If clip is True, clips the subdomain to the domain’s profile.

  3. If constraint are given, only proceede if these are met.

  4. Add the subdomain.

Parameters:

  • subdomain (SubDomain) – The subdomain to be added.

  • level (Level) – The associated level of the subdomain.

  • transform (Transform) – A function to transform the subdomain before adding it. It will call transform(subdomain, level, self).

  • constraint (Constraint) – A function to check if the subdomain should be added. It will call constraints(subdomain, level, self).

  • clip (bool) – If True, clips the subdomain to the background.

  • kwargs (Any) –

Return type:

bool

Note: If level == Domain.background_level and clip == True, then the

background might be modified.

Returns:

True if the subdomain was added, False otherwise.

Return type:

bool

Parameters:

  • subdomain (Polygon | MultiPolygon) –

  • level (int) –

  • transform (Transform | None) –

  • constraint (Constraint | None) –

  • clip (bool) –

  • kwargs (Any) –

plot(title='Domain', color_holes=False, color_hole_boundaries=True, make_legend=True, safe_file=None, color_map=None)[source]

Plot the domain.

Parameters:

  • title (str, optional) – Title of the plot. Defaults to “Domain”.

  • color_holes (bool, optional) – If True, the holes are colored. Defaults to False.

  • color_hole_boundaries (bool, optional) – If True, the boundaries of the holes are colored. Defaults to True.

  • make_legend (bool, optional) – If True, a legend is added to the plot. Defaults to True.

  • safe_file (str, optional) – If given, the plot is saved to the file. Defaults to None.

  • color_map (Mapping[Level, Color], optional) – A mapping of levels to colors. If None, the default color map is used. Defaults to None.

Return type:

None

as_list()[source]

Return a list of all subdomains with their levels.

Return type:

list[tuple[Polygon, int]]

as_tree()[source]

Represent the domain as a tree.

Each node of the tree represents a subdomain of the domain. If node A is a parent of node B, then the subdomain of node A includes the subdomain of node B.

Return type:

InclusionTree

class pargeo.domain.InclusionTree(root)[source]

Bases: object

Represents a Domain object as a tree.

The tree is used to plot the domain.

The tree is a directed acyclic graph, where the root is just an auxiliary node. Each (non-root) node represents a polygon, with a level. All polygons represented by the nodes are disjoint. The nodes represent the polygons in the flattened domain.

This tree encodes the semi-ordering of the polygons, that is given by the inclusion relation. This means, a directed edge from node A to node B exists if and only if the polygon represented by node A includes the polygon of node B. Note: The polygon of the exterior of the polygon (spoken in terms of shapely) is taken into account for the inclusion.

Parameters:

root (Node) –

property root: Node
add(polygon, level)[source]

Recursively add a node to the tree.

This function adds a node to the tree by finding its correct position in relation to the parent node. The node is added as a child of the parent node if the parent node includes the node. If the node includes a child of the parent node, the child is removed from the parent node’s children and added to the node’s children. The depth of the node and any affected children is updated accordingly.

Parameters:

  • parent – The parent node.

  • node – The node to be added.

  • polygon (Polygon) –

  • level (int) –

Returns:

None

Return type:

None

show()[source]

Print the tree recursively.

Return type:

None

class pargeo.domain.Node(level, polygon, children=None)[source]

Bases: UserDict

Node of the inclusion tree, representing a polygon.

Nodes are semi-ordered by the inclusion relation.

Parameters:

  • level (Level) –

  • polygon (Polygon) –

includes(node)[source]

Check if this node includes the incoming node.

Parameters:

node (Node) –

Return type:

bool

plot(colormap, color_hole_boundaries, holes, show=False, boundary_color=None)[source]

Plot the node.

Parameters:

  • colormap (Mapping[int, str | tuple[int, int, int] | tuple[int, int, int, int]]) –

  • color_hole_boundaries (bool) –

  • holes (set[int]) –

  • show (bool) –

  • boundary_color (str | tuple[int, int, int] | tuple[int, int, int, int] | None) –

pargeo.geometry module

Geometry module.

Utility module for creating geometries. The module provides a set of classes for creating geometries such as rectangles, circles, ellipses, and star-like geometries. These geometries can be discretized using the to_polygon method, and used in the Domain class.

Example

>>> from pargeo.domain import Domain
>>> from pargeo.geometry import Rectangle, Circle

>>> domain = Rectangle(center=(0, 0), width=1, height=1).to_polygon()
>>> domain = Domain(domain, holes={1})
>>> hole = Circle(center=(.5, .5), radius=.1).to_polygon()
>>> domain.add(polygon=hole, level=1)
class pargeo.geometry.Geometry[source]

Bases: ABC

Abstract class for geometries.

abstract to_polygon(*args, **kwargs)[source]

Return a shapely polygon representation of self.

Return type:

Polygon

class pargeo.geometry.Box(left_bottom, right_top)[source]

Bases: Geometry

Box geometry.

Parameters:

  • left_bottom (tuple[float, float]) –

  • right_top (tuple[float, float]) –

classmethod from_center(center, width, height)[source]

Creates a box from the center.

Parameters:

  • center (tuple) – The (x, y) coordinates of the center of the box.

  • width (float) – The width of the box.

  • height (float) – The height of the box.

Returns:

The created box object.

Return type:

Box

to_polygon()[source]

Return the corners of the rectangle in counter-clockwise order.

Return type:

Polygon

class pargeo.geometry.NStar(center, radius_in, radius_out, n_peaks, alpha=0.0)[source]

Bases: Geometry

NStar geometry.

Parameters:

  • center (tuple[float, float]) –

  • radius_in (float) –

  • radius_out (float) –

  • n_peaks (int) –

  • alpha (float) –

to_polygon()[source]

Return a shapely polygon representation of self.

Return type:

Polygon

class pargeo.geometry.StarLike(center)[source]

Bases: Geometry

Abstract class for star-like geometries.

Parameters:

center (tuple[float, float]) –

abstract radius_at(angle)[source]

Returns the distance at a given angle to the center.

Parameters:

angle (float) –

Return type:

float

to_polygon(refs)[source]

Return a shapely polygon representation of self.

Parameters:

refs (int) –

Return type:

Polygon

discretize(refs)[source]
Parameters:

refs (int) –

Return type:

Polygon

class pargeo.geometry.Circle(center, radius)[source]

Bases: StarLike

Parameters:

center (tuple[float, float]) –

radius_at(angle)[source]

Returns the distance at a given angle to the center.

Parameters:

angle (float) –

Return type:

float

class pargeo.geometry.Ellipse(center, axis, angle=0)[source]

Bases: StarLike

Parameters:

  • center (tuple[float, float]) –

  • axis (tuple[float, float]) –

  • angle (float) –

radius_at(angle)[source]

Returns the distance at a given angle to the center.

Parameters:

angle (float) –

Return type:

float

discretize(refs)[source]
Return type:

Polygon

class pargeo.geometry.Stellar(center, radius, coefficient=None)[source]

Bases: StarLike

Stellar bubble.

Parameters:

  • center (tuple[float, float]) –

  • radius (float) –

  • coefficient (list[tuple[float, float]] | None) –

radius_at(angle)[source]

Returns the distance at a given angle to the center.

Parameters:

angle (float) –

Return type:

float

generate_coefficients(k=0.2)[source]

Generate coefficients for the stellar function.

Parameters:

k (float) – Scaling factor.

Return type:

list[tuple[float, float]]

class pargeo.geometry.RainDrop(center, a, scale)[source]

Bases: StarLike

Raindrop geometry.

Parameters:

  • center (tuple[float, float]) –

  • a (float) –

  • scale (float) –

radius_at(angle)[source]

Returns the distance at a given angle to the center.

Parameters:

angle (float) –

Return type:

float

discretize(refs)[source]

pargeo.transform module

Transform for the pargeo package.

class pargeo.transform.Periodic(levels='all', x_length=inf, y_length=inf, alpha=0)[source]

Bases: Transform

Periodic transform.

Parameters:

  • levels (int | list[int] | str) –

  • x_length (float | list[float]) –

  • y_length (float | list[float]) –

  • alpha (float | list[float]) –

property affected_levels

Return the levels affected by the periodicity transform.

update(level, x_length, y_length, alpha)[source]

Update the periodic behavior of the transform.

Note: If level is “all” then the periodicity is applied to all levels, meaning all levels are overwritten.

Parameters:

  • level (int) –

  • x_length (float) –

  • y_length (float) –

  • alpha (float) –

__call__(subdomain, level, domain, **kwargs)[source]

Apply the periodicity to the polygon.

Parameters:

  • subdomain (Polygon | MultiPolygon) –

  • level (int) –

  • domain (Domain) –

  • kwargs (Any) –

Return type:

Polygon | MultiPolygon

class pargeo.transform.Repeat(repeat_info, repeat_info_2=None, excluded_levels=[])[source]

Bases: Transform

Repeat transform.

Parameters:

  • repeat_info (tuple[tuple[float, float], float, int, bool]) –

  • repeat_info_2 (tuple[tuple[float, float], float, int, bool] | None) –

  • excluded_levels (list[int]) –

__call__(subdomain, level, domain, **kwargs)[source]

Apply the repeat transform to the SubDomain.

Parameters:

  • subdomain (Polygon | MultiPolygon) – The SubDomain to transform.

  • level (int) – The Level of the transformation.

  • domain (Domain) – The Domain of the transformation.

  • **kwargs (Any) –

    Additional keyword arguments for the transformation.

    clip (bool): If True, clips the repeated elements to the domain. Default is False.

Returns:

The transformed SubDomain.

Return type:

SubDomain

class pargeo.transform.Diffeomorphism(mapping)[source]

Bases: Transform

Diffeomorphism transform.

Parameters:

mapping (Callable[[list[float], list[float]], tuple[list[float], list[float]]]) –

__call__(subdomain, level, domain, **kwargs)[source]

Apply the diffeomorphism to the polygon.

Parameters:

  • subdomain (Polygon | MultiPolygon) –

  • level (int) –

  • domain (Domain) –

  • kwargs (Any) –

Return type:

Polygon | MultiPolygon