Planar 2D API

`pyvoro2.planar`

Planar 2D namespace for pyvoro2.

`Box` `dataclass`

Axis-aligned non-periodic planar box.

`from_points(points, padding=2.0)` `classmethod`

Create a bounding box that encloses planar points.

`DuplicateError`

Bases: ValueError

Raised when near-duplicate points are detected.

`NormalizationError`

Bases: ValueError

Raised when strict planar normalization validation fails.

`NormalizedTopology` `dataclass`

Result of :func:normalize_topology for planar tessellations.

Attributes:

Name	Type	Description
`global_vertices`	`ndarray`	Unique planar vertices in Cartesian coordinates.
`global_edges`	`list[dict[str, Any]]`	Unique geometric edges. Each edge dict contains: - cells: (cid0, cid1) - cell_shifts: ((0, 0), (sx, sy)) - vertices: (gid0, gid1) - vertex_shifts: ((0, 0), (sx, sy))
`cells`	`list[dict[str, Any]]`	Per-cell dictionaries including `vertex_global_id`, `vertex_shift`, and `edge_global_id` aligned with local edges.

`NormalizedVertices` `dataclass`

Result of :func:normalize_vertices for planar tessellations.

Attributes:

Name	Type	Description
`global_vertices`	`ndarray`	Array of unique planar vertices in Cartesian coordinates, remapped into the primary cell for periodic domains.
`cells`	`list[dict[str, Any]]`	Per-cell dictionaries augmented with: - vertex_global_id: list[int] aligned with local vertices - vertex_shift: list[tuple[int, int]] aligned with local vertices

`PlanarComputeResult` `dataclass`

Structured return value for :func:pyvoro2.planar.compute.

Attributes:

Name	Type	Description
`cells`	`list[dict[str, Any]]`	Raw planar cell dictionaries returned by the compute wrapper after any temporary internal geometry has been stripped according to the caller's requested output flags.
`tessellation_diagnostics`	`TessellationDiagnostics \| None`	Wrapper-computed tessellation diagnostics, if requested directly or needed for `tessellation_check`.
`normalized_vertices`	`NormalizedVertices \| None`	Vertex-normalized planar output, if requested via `normalize='vertices'` or `normalize='topology'`.
`normalized_topology`	`NormalizedTopology \| None`	Edge-normalized planar topology, if requested via `normalize='topology'`.

The normalized structures intentionally carry their own augmented cell copies. They are not aliases of cells and may therefore still contain geometry that was omitted from the raw wrapper output.

`global_edges` `property`

Global planar edges if topology normalization is available.

`global_vertices` `property`

Global planar vertices from the available normalized output.

`has_normalized_topology` `property`

Whether topology normalization output is present.

`has_normalized_vertices` `property`

Whether vertex normalization output is present.

`has_tessellation_diagnostics` `property`

Whether tessellation diagnostics are present.

`require_normalized_topology()`

Return topology normalization output or raise a helpful error.

`require_normalized_vertices()`

Return vertex normalization output or raise a helpful error.

`require_tessellation_diagnostics()`

Return tessellation diagnostics or raise a helpful error.

`RectangularCell` `dataclass`

Axis-aligned planar cell with optional x/y periodicity.

This is the honest first public 2D domain scope for pyvoro2.planar. It intentionally does not cover non-orthogonal periodic cells.

`lattice_vectors` `property`

Return lattice vectors (a, b) in Cartesian coordinates.

`remap_cart(points, *, return_shifts=False, eps=None)`

Remap Cartesian points into the primary rectangular domain.

`TessellationError`

Bases: ValueError

Raised when planar tessellation sanity checks fail.

`analyze_tessellation(cells, domain, *, expected_ids=None, mode=None, area_tol_rel=1e-08, area_tol_abs=1e-12, check_reciprocity=True, check_line_mismatch=True, line_offset_tol=None, line_angle_tol=None, mark_edges=True)`

Analyze planar tessellation sanity and optionally annotate edges.

`annotate_edge_properties(cells, domain, *, tol=1e-12)`

Annotate 2D edges with basic geometric descriptors in-place.

Added edge fields (when computable): - midpoint: [x, y] - tangent: [tx, ty] unit tangent from vertex[0] -> vertex[1] - normal: [nx, ny] unit normal oriented from site -> edge - length: float - other_site: [x, y] if the neighboring site can be resolved

compute(points, *, domain, ids=None, duplicate_check='off', duplicate_threshold=1e-05, duplicate_wrap=True, duplicate_max_pairs=10, block_size=None, blocks=None, init_mem=8, mode='standard', radii=None, return_vertices=True, return_adjacency=True, return_edges=True, return_edge_shifts=False, edge_shift_search=2, include_empty=False, validate_edge_shifts=True, repair_edge_shifts=False, edge_shift_tol=None, return_diagnostics=False, return_result=False, normalize='none', normalization_tol=None, tessellation_check='none', tessellation_require_reciprocity=None, tessellation_area_tol_rel=1e-08, tessellation_area_tol_abs=1e-12, tessellation_line_offset_tol=None, tessellation_line_angle_tol=None)

Compute planar Voronoi or power tessellation cells.

Supported domains

:class:~pyvoro2.planar.domains.Box
:class:~pyvoro2.planar.domains.RectangularCell

Planar compute mirrors the 3D wrapper's diagnostics convenience path: set return_diagnostics=True to also return a :class:~pyvoro2.planar.TessellationDiagnostics object, and/or set tessellation_check='warn' or 'raise' to have common area and reciprocity issues handled directly by the wrapper.

Wrapper-level normalization convenience is also available via normalize='vertices' or 'topology'. Any request for normalized output returns a :class:~pyvoro2.planar.PlanarComputeResult, as does return_result=True. The normalized structures intentionally carry their own augmented cell copies, so the raw cells field can stay lightweight even when internal geometry was needed for diagnostics or normalization.

For periodic domains, diagnostics and normalization automatically compute temporary edge shifts and the required edge/vertex geometry internally, even when those fields were not requested by the caller. Any such temporary fields are stripped from the raw returned cells unless they were explicitly requested.

`duplicate_check(points, *, threshold=1e-05, domain=None, wrap=True, mode='raise', max_pairs=10)`

Detect planar point pairs closer than an absolute threshold.

`ghost_cells(points, queries, *, domain, ids=None, duplicate_check='off', duplicate_threshold=1e-05, duplicate_wrap=True, duplicate_max_pairs=10, block_size=None, blocks=None, init_mem=8, mode='standard', radii=None, ghost_radius=None, return_vertices=True, return_adjacency=True, return_edges=True, return_edge_shifts=False, edge_shift_search=2, include_empty=True, validate_edge_shifts=True, repair_edge_shifts=False, edge_shift_tol=None)`

Compute ghost Voronoi/Laguerre cells at planar query points.

`locate(points, queries, *, domain, ids=None, duplicate_check='off', duplicate_threshold=1e-05, duplicate_wrap=True, duplicate_max_pairs=10, block_size=None, blocks=None, init_mem=8, mode='standard', radii=None, return_owner_position=False)`

Locate the owning generator for each planar query point.

`normalize_edges(nv, *, domain, tol=None, copy_cells=True)`

Build a global edge pool based on an existing planar normalization.

`normalize_topology(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)`

Convenience wrapper: normalize vertices, then deduplicate edges.

`normalize_vertices(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)`

Build a global planar vertex pool and per-cell vertex mappings.

`plot_tessellation(cells, *, ax=None, domain=None, show_sites=False, annotate_ids=False)`

Plot planar cells using matplotlib.

Parameters:

Name	Type	Description	Default
`cells`	`Iterable[dict]`	Iterable of raw 2D cell dictionaries as returned by `pyvoro2.planar.compute` or `pyvoro2.planar.ghost_cells`.	required
`ax`	`Axes \| None`	Optional existing matplotlib axes.	`None`
`domain`	`_SupportsPlanarBounds \| None`	Optional planar domain. When it exposes `bounds`, the domain rectangle is drawn as a simple outline.	`None`
`show_sites`	`bool`	If True, draw the reported cell sites.	`False`
`annotate_ids`	`bool`	If True, label cell IDs at their reported sites.	`False`

Returns:

Type	Description
`tuple[Figure, Axes]`	`(fig, ax)`.

`validate_normalized_topology(normalized, domain, *, level='basic', check_vertex_edge_shift=True, check_edge_vertex_sets=True, check_incidence=True, check_polygon=True, max_examples=10)`

Validate periodic shift and topology consistency after normalization.

`validate_tessellation(cells, domain, *, expected_ids=None, mode=None, level='basic', require_reciprocity=None, area_tol_rel=1e-08, area_tol_abs=1e-12, line_offset_tol=None, line_angle_tol=None, mark_edges=None)`

Validate planar tessellation sanity, optionally raising in strict mode.

:::

Planar 2D API

pyvoro2.planar

Box dataclass

from_points(points, padding=2.0) classmethod

DuplicateError

NormalizationError

NormalizedTopology dataclass

NormalizedVertices dataclass

PlanarComputeResult dataclass

global_edges property

global_vertices property

has_normalized_topology property

has_normalized_vertices property

has_tessellation_diagnostics property

require_normalized_topology()

require_normalized_vertices()

require_tessellation_diagnostics()

RectangularCell dataclass

lattice_vectors property

remap_cart(points, *, return_shifts=False, eps=None)

TessellationError

analyze_tessellation(cells, domain, *, expected_ids=None, mode=None, area_tol_rel=1e-08, area_tol_abs=1e-12, check_reciprocity=True, check_line_mismatch=True, line_offset_tol=None, line_angle_tol=None, mark_edges=True)

annotate_edge_properties(cells, domain, *, tol=1e-12)

duplicate_check(points, *, threshold=1e-05, domain=None, wrap=True, mode='raise', max_pairs=10)

locate(points, queries, *, domain, ids=None, duplicate_check='off', duplicate_threshold=1e-05, duplicate_wrap=True, duplicate_max_pairs=10, block_size=None, blocks=None, init_mem=8, mode='standard', radii=None, return_owner_position=False)

normalize_edges(nv, *, domain, tol=None, copy_cells=True)

normalize_topology(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)

normalize_vertices(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)

plot_tessellation(cells, *, ax=None, domain=None, show_sites=False, annotate_ids=False)

validate_normalized_topology(normalized, domain, *, level='basic', check_vertex_edge_shift=True, check_edge_vertex_sets=True, check_incidence=True, check_polygon=True, max_examples=10)

validate_tessellation(cells, domain, *, expected_ids=None, mode=None, level='basic', require_reciprocity=None, area_tol_rel=1e-08, area_tol_abs=1e-12, line_offset_tol=None, line_angle_tol=None, mark_edges=None)

`pyvoro2.planar`

`Box` `dataclass`

`from_points(points, padding=2.0)` `classmethod`

`DuplicateError`

`NormalizationError`

`NormalizedTopology` `dataclass`

`NormalizedVertices` `dataclass`

`PlanarComputeResult` `dataclass`

`global_edges` `property`

`global_vertices` `property`

`has_normalized_topology` `property`

`has_normalized_vertices` `property`

`has_tessellation_diagnostics` `property`

`require_normalized_topology()`

`require_normalized_vertices()`

`require_tessellation_diagnostics()`

`RectangularCell` `dataclass`

`lattice_vectors` `property`

`remap_cart(points, *, return_shifts=False, eps=None)`

`TessellationError`

`analyze_tessellation(cells, domain, *, expected_ids=None, mode=None, area_tol_rel=1e-08, area_tol_abs=1e-12, check_reciprocity=True, check_line_mismatch=True, line_offset_tol=None, line_angle_tol=None, mark_edges=True)`

`annotate_edge_properties(cells, domain, *, tol=1e-12)`

`duplicate_check(points, *, threshold=1e-05, domain=None, wrap=True, mode='raise', max_pairs=10)`

`locate(points, queries, *, domain, ids=None, duplicate_check='off', duplicate_threshold=1e-05, duplicate_wrap=True, duplicate_max_pairs=10, block_size=None, blocks=None, init_mem=8, mode='standard', radii=None, return_owner_position=False)`

`normalize_edges(nv, *, domain, tol=None, copy_cells=True)`

`normalize_topology(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)`

`normalize_vertices(cells, *, domain, tol=None, require_edge_shifts=True, copy_cells=True)`

`plot_tessellation(cells, *, ax=None, domain=None, show_sites=False, annotate_ids=False)`

`validate_normalized_topology(normalized, domain, *, level='basic', check_vertex_edge_shift=True, check_edge_vertex_sets=True, check_incidence=True, check_polygon=True, max_examples=10)`

`validate_tessellation(cells, domain, *, expected_ids=None, mode=None, level='basic', require_reciprocity=None, area_tol_rel=1e-08, area_tol_abs=1e-12, line_offset_tol=None, line_angle_tol=None, mark_edges=None)`