Skip to content

Planar high-level API

compute(...) returns the common pyvoro2.TessellationResult by default. The deprecated return_result: bool | None = None selector is retained for compatibility during v0.7. None means that the selector was omitted; passing either boolean warns. The selector is removed in v0.8. New code uses output='result'|'cells'.

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, return_result=None, 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. return_result= remains as a deprecated compatibility selector; its default None means that no legacy selection was supplied. Passing True or False emits :class:DeprecationWarning; use output= in new code. 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.

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.

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.

:::