Skip to content

Planar high-level API

compute(...) returns the common pyvoro2.TessellationResult by default. Use output='result'|'cells' to select structured or raw output explicitly.

tessellation_check='diagnose'|'warn'|'raise' computes one final diagnostic; warning and raising behavior is driven only by its ok value.

pyvoro2.planar.api

High-level 2D API for planar Voronoi and power tessellations.

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', weights=None, 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, output=_DEFAULT_OUTPUT, 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

By default, planar compute returns one :class:~pyvoro2.TessellationResult. Set output="cells" for the explicit raw cell list, or (cells, diagnostics) when return_diagnostics=True. Structured results always carry computed diagnostics inside result.tessellation_diagnostics and never return a tuple.

Wrapper-level normalization convenience is also available via normalize='vertices' or 'topology'. Any request for normalized output returns a :class:~pyvoro2.TessellationResult. 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.

tessellation_check='diagnose' attaches the completed diagnostics without acting on failure. 'warn' emits one summary warning when the final diagnostic is not okay, and 'raise' raises :class:~pyvoro2.planar.TessellationError in the same case. tessellation_require_reciprocity=None preserves the default requirement for periodic standard and power tessellations; False retains optional reciprocity findings without making them fatal.

In mode='power', supply exactly one of weights or radii. Mathematical weights follow the power convention ||x - p_i||^2 - w_i and have squared-length units; positive, zero, and negative finite weights are valid when the common-shift conversion remains finite and representable. Non-finite input or overflow during conversion raises ValueError before native computation. Finite representability does not guarantee a numerically resolvable native tessellation. Voro++ evaluates radical geometry with binary64 squared-radius arithmetic, so very large absolute radii**2 values or genuine weight ranges relative to squared coordinate/domain scales can lose geometric resolution. There is no universal safe cutoff: the onset depends on scale, geometry, platform, and compiler, and periodic power tessellations are a particularly sensitive regime. pyvoro2 converts valid weights to non-negative backend radii with one common global shift, so adding the same constant to every weight does not change the diagram. Radii have length units and are a non-unique backend representation, not necessarily physical radii. Standard mode rejects both weights and radii because neither representation has meaning there.

init_mem and explicit length-2 blocks must contain positive exact non-Boolean integers in the C++ int range. block_size, when supplied, must be positive and finite. Points and radii are validated for shape and finiteness before construction, and the aggregate estimate of known eager native construction allocations may be at most exactly 1 GiB. Generators must lie in each non-periodic half-open interval [lo, hi); periodic axes are remapped before native dispatch. Backend-unsafe pairs at squared distance at most 1e-10 always raise. duplicate_check and its threshold/wrap options control only diagnostics above that floor.

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.

init_mem and explicit length-2 blocks use positive exact-integer semantics; block_size is positive and finite. Malformed or non-finite points, queries, radii, domains, and over-cap known eager native allocation estimates raise ValueError before construction. Both persistent sites and each temporary ghost generator use half-open containment and mandatory duplicate safety. Periodic axes are remapped; an outside non-periodic ghost query raises instead of producing an empty ghost cell.

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.

init_mem and explicit length-2 blocks use positive exact-integer semantics; block_size is positive and finite. Malformed or non-finite points, queries, radii, domains, and over-cap known eager native allocation estimates raise ValueError before construction. Generator points use the same half-open containment and mandatory duplicate safety as :func:compute; locate queries themselves are not inserted and retain their existing query semantics.

:::