High-level API

compute(...) returns pyvoro2.TessellationResult by default. Use output='cells' only when a low-level workflow deliberately needs raw cell dictionaries or the raw diagnostics tuple.

tessellation_check='diagnose' computes diagnostics without acting on the result. 'warn' emits one summary warning when diagnostics.ok is false, and 'raise' raises TessellationError in exactly the same case.

pyvoro2.api

High-level API for computing Voronoi 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_faces=True, return_face_shifts=False, face_shift_search=2, include_empty=False, validate_face_shifts=True, repair_face_shifts=False, face_shift_tol=None, return_diagnostics=False, output='result', tessellation_check='none', tessellation_require_reciprocity=None, tessellation_volume_tol_rel=1e-08, tessellation_volume_tol_abs=1e-12, tessellation_plane_offset_tol=None, tessellation_plane_angle_tol=None)

Compute Voronoi tessellation cells.

Supported domains

• :class:~pyvoro2.domains.Box (non-periodic)
• :class:~pyvoro2.domains.OrthorhombicCell (orthogonal with optional per-axis periodicity)
• :class:~pyvoro2.domains.PeriodicCell (fully periodic triclinic)

Supported modes

• mode='standard': classic Voronoi midplanes; both weights and radii must be None
• mode='power': power/Laguerre (radical) diagram using exactly one of mathematical power weights or backend-compatible radii

Notes

Internally, the C++ layer always uses point indices 0..n-1 as particle IDs. If ids is provided, results are remapped back to those user IDs on return.

Parameters:

Name	Type	Description	Default
points	Sequence[Sequence[float]] | ndarray	Point coordinates, shape (n, 3).	required
domain	Box | OrthorhombicCell | PeriodicCell	Domain object.	required
ids	Sequence[int] | None	Optional integer IDs returned in output. Defaults to range(n).	None
duplicate_check	Literal['off', 'warn', 'raise']	Optional policy above the mandatory backend-safety distance. "off" skips that additional policy, "warn" emits a warning, and "raise" raises :class:pyvoro2.DuplicateError. Backend-unsafe pairs always raise before native insertion.	'off'
duplicate_threshold	float	Absolute distance for the optional policy. Values at or below 1e-5 add no range above mandatory safety.	1e-05
duplicate_wrap	bool	Whether the optional policy uses periodic minimum-image distance. Mandatory periodic safety always uses certified wrapping.	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Positive finite approximate grid block size. If provided, block counts are derived unless explicit blocks are supplied.	None
blocks	tuple[int, int, int] | None	Explicit positive exact-integer (nx, ny, nz) grid counts. These select the counts instead of block_size derivation.	None
init_mem	int	Positive exact-integer initial per-block particle capacity in Voro++. Known eager native construction allocations are subject to an aggregate cap of exactly 1 GiB.	8
mode	Literal['standard', 'power']	'standard' or 'power'.	'standard'
weights	Sequence[float] | ndarray | None	Per-point mathematical power weights for mode='power', with shape (n,) and squared-length units. Positive, zero, and negative finite values are accepted when the common-shift conversion remains finite and representable. Non-finite input or overflow during conversion raises ValueError before native computation. One common global shift is applied before conversion to non-negative backend radii; adding a common constant to every weight therefore leaves the diagram unchanged. The convention is ||x - p_i||^2 - w_i. Supplying both weights and radii is an error in power mode. Standard mode rejects both arguments.	None
radii	Sequence[float] | ndarray | None	Per-point non-negative backend radii for mode='power', with length units. This backend representation is not unique and should not be interpreted as physical radii. Radii are rejected in standard mode. Finite values do 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.	None
return_vertices	bool	Include vertex coordinates.	True
return_adjacency	bool	Include vertex adjacency.	True
return_faces	bool	Include faces with adjacent cell IDs.	True
return_face_shifts	bool	For periodic domains, include an integer lattice shift (na, nb, nc) for each face neighbor indicating which periodic image of the adjacent cell generated that face. Requires return_faces=True and return_vertices=True.	False
face_shift_search	int	Search radius S for determining neighbor shifts. Candidate shifts (na,nb,nc) in [-S..S]^3 are considered (restricted to periodic axes for :class:~pyvoro2.domains.OrthorhombicCell).	2
include_empty	bool	If True, include explicit empty-cell records for sites that do not produce a Voronoi/Laguerre cell (possible in extreme power settings). Empty records have 'empty': True, volume 0.0, and empty geometry lists.	False
validate_face_shifts	bool	If True and return_face_shifts=True, validate that each face's chosen adjacent_shift yields a near-zero plane residual, and that reciprocal faces carry opposite shifts.	True
repair_face_shifts	bool	If True and return_face_shifts=True, attempt to repair rare reciprocity mismatches by enforcing opposite shifts on reciprocal faces.	False
face_shift_tol	float | None	Optional absolute tolerance (in container distance units) for the face-shift plane residual check. If None, a conservative default is used.	None
tessellation_check	Literal['none', 'diagnose', 'warn', 'raise']	"none" disables diagnostic analysis; "diagnose" attaches it without acting on failure; "warn" emits one summary warning when the final diagnostic is not okay; and "raise" raises :class:~pyvoro2.TessellationError in the same case.	'none'
tessellation_require_reciprocity	bool | None	Whether periodic reciprocity is a required invariant. None preserves the default requirement for periodic standard and power tessellations. Optional inspection still records missing-shift, orphan, and mismatch findings without making them fatal.	None
output	Literal['result', 'cells']	"result" (the default) returns one :class:~pyvoro2.TessellationResult. "cells" selects the explicit raw cell list, or (cells, diagnostics) when return_diagnostics=True.	'result'

Returns:

Name	Type	Description
A	TessellationResult | list[dict[str, Any]] | tuple[list[dict[str, Any]], TessellationDiagnostics]	class:~pyvoro2.TessellationResult by default. The explicit
	TessellationResult | list[dict[str, Any]] | tuple[list[dict[str, Any]], TessellationDiagnostics]	output="cells" route returns raw cell dictionaries and is a
	TessellationResult | list[dict[str, Any]] | tuple[list[dict[str, Any]], TessellationDiagnostics]	supported low-level output mode.

Raises:

Type	Description
ValueError	If inputs are inconsistent or an unknown mode is provided.

Every generator must lie in each non-periodic half-open interval [lo, hi); periodic axes are remapped before native dispatch. Generator pairs at squared distance at most 1e-10 always raise before insertion. The public duplicate options control only additional diagnostics above this backend-safety 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_faces=True, include_empty=True)

Compute ghost Voronoi/Laguerre cells at arbitrary query positions.

This is a stateless wrapper around Voro++'s compute_ghost_cell routine. Each query is temporarily inserted, so it uses the same containment and mandatory duplicate-safety rules as persistent generators. An outside non-periodic query therefore raises before native dispatch; a contained, distinct query may still have an empty cell geometrically. It is useful for probing the tessellation at positions that are not part of the generator set (e.g. along a line/trajectory, or at grid points).

Compared to :func:pyvoro2.compute, ghost cells are not part of a global tessellation and therefore:

• Ghost cells are returned with id = -1.
• The returned faces' adjacent_cell values refer to generator IDs (0..n-1, or remapped to ids if provided).
• No periodic face-shift annotation is performed.

Parameters:

Name	Type	Description	Default
points	Sequence[Sequence[float]] | ndarray	Generator coordinates, shape (n, 3).	required
queries	Sequence[Sequence[float]] | ndarray	Query coordinates, shape (m, 3).	required
domain	Box | OrthorhombicCell | PeriodicCell	Domain (Box, OrthorhombicCell, or PeriodicCell).	required
ids	Sequence[int] | None	Optional user IDs aligned with points. If provided, face neighbor IDs are remapped to these values.	None
duplicate_check	Literal['off', 'warn', 'raise']	Optional off/warn/raise policy above the mandatory backend-safety distance. Backend-unsafe persistent or temporary ghost generators always raise.	'off'
duplicate_threshold	float	Absolute distance for the optional policy.	1e-05
duplicate_wrap	bool	Whether the optional policy uses periodic minimum-image distance. Mandatory periodic safety always wraps.	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Positive finite approximate grid block size. If provided, block counts are derived unless explicit blocks are supplied.	None
blocks	tuple[int, int, int] | None	Explicit positive exact-integer (nx, ny, nz) grid counts. These select the counts instead of block_size derivation.	None
init_mem	int	Positive exact-integer initial per-block particle capacity in Voro++. Known eager native construction allocations are subject to an aggregate cap of exactly 1 GiB.	8
mode	Literal['standard', 'power']	'standard' or 'power'.	'standard'
radii	Sequence[float] | ndarray | None	Per-point radii for mode='power'.	None
ghost_radius	float | Sequence[float] | ndarray | None	Radius (or array of radii) for each ghost query point in mode='power'. Must be provided for power mode.	None
return_vertices	bool	Include vertex coordinates.	True
return_adjacency	bool	Include vertex adjacency.	True
return_faces	bool	Include faces with adjacent generator IDs.	True
include_empty	bool	If True, return an explicit empty record for queries for which Voro++ cannot compute a cell (e.g. outside a non-periodic box). Empty records have empty=True and volume 0.0. If False, those queries are omitted from the output list.	True

Returns:

Type	Description
list[dict[str, Any]]	A list of cell dicts (length m unless include_empty=False).
list[dict[str, Any]]	Each element contains: - query_index: index of the query in the input array - query: original query coordinate (Cartesian) - site: coordinate used by Voro++ for the ghost. For periodic domains, this is wrapped into the primary domain. Returned in Cartesian coordinates. - empty: boolean - volume: float - optional vertices, adjacency, faces

Raises:

Type	Description
ValueError	if inputs are inconsistent.

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 which generator owns each query point.

This is a stateless wrapper around Voro++'s find_voronoi_cell. Persistent generators use half-open containment and mandatory duplicate safety. Query points are not inserted and retain the existing query semantics, including queries outside a non-periodic domain.

Parameters:

Name	Type	Description	Default
points	Sequence[Sequence[float]] | ndarray	Generator coordinates, shape (n, 3).	required
queries	Sequence[Sequence[float]] | ndarray	Query coordinates, shape (m, 3).	required
domain	Box | OrthorhombicCell | PeriodicCell	Domain object (Box, OrthorhombicCell, or PeriodicCell).	required
ids	Sequence[int] | None	Optional user IDs aligned with points. If provided, returned owner IDs are remapped to these values.	None
duplicate_check	Literal['off', 'warn', 'raise']	Optional off/warn/raise policy above the mandatory backend-safety distance. Backend-unsafe pairs always raise.	'off'
duplicate_threshold	float	Absolute distance for the optional policy.	1e-05
duplicate_wrap	bool	Whether the optional policy uses periodic minimum-image distance. Mandatory periodic safety always wraps.	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Positive finite approximate grid block size. If provided, block counts are derived unless explicit blocks are supplied.	None
blocks	tuple[int, int, int] | None	Explicit positive exact-integer (nx, ny, nz) grid counts. These select the counts instead of block_size derivation.	None
init_mem	int	Positive exact-integer initial per-block particle capacity in Voro++. Known eager native construction allocations are subject to an aggregate cap of exactly 1 GiB.	8
mode	Literal['standard', 'power']	'standard' or 'power'.	'standard'
radii	Sequence[float] | ndarray | None	Per-point radii for mode='power'.	None
return_owner_position	bool	If True, also return the (possibly periodic-image) position of the owning generator as reported by Voro++.	False

Returns:

Type	Description
dict[str, Any]	A dict with: - found: (m,) boolean array - owner_id: (m,) integer array (internal 0..n-1, or remapped to ids) - owner_pos: (m, 3) float array (only if return_owner_position=True)

Notes

For periodic domains, Voro++ may return the owner position in a periodic image of the primary domain. This is useful when you need a consistent nearest-image geometry for a given query.

:::