High-level API

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', 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, 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
• mode='power': power/Laguerre (radical) diagram using per-site radii as supported by Voro++

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 near-duplicate pre-check for generator points. If set to "raise", pyvoro2 runs :func:pyvoro2.duplicate_check and raises :class:pyvoro2.DuplicateError before entering the C++ layer when a potentially fatal near-duplicate is detected. If set to "warn", a warning is emitted but computation proceeds. Important: "warn" does not protect you from Voro++ hard exits. If points are closer than Voro++'s internal absolute threshold (~1e-5 in container units), the process may still terminate. Use duplicate_check="raise" to prevent this.	'off'
duplicate_threshold	float	Absolute distance threshold used by the pre-check.	1e-05
duplicate_wrap	bool	If True, points are remapped into the primary domain for periodic domains before checking (matching Voro++ behavior).	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Approximate grid block size. If provided, blocks is derived.	None
blocks	tuple[int, int, int] | None	Explicit (nx, ny, nz) grid blocks. Overrides block_size.	None
init_mem	int	Initial per-block particle memory in Voro++.	8
mode	Literal['standard', 'power']	'standard' or 'power'.	'standard'
radii	Sequence[float] | ndarray | None	Per-point radii for mode='power'.	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

Returns:

Type	Description
list[dict[str, Any]] | tuple[list[dict[str, Any]], TessellationDiagnostics]	List of cell dictionaries.

Raises:

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

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. 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 near-duplicate pre-check for generator points. See :func:pyvoro2.duplicate_check. Use "raise" to prevent Voro++ hard exits on near-duplicates. "warn" is diagnostic only and does not prevent hard exits.	'off'
duplicate_threshold	float	Absolute distance threshold used by the pre-check.	1e-05
duplicate_wrap	bool	If True, points are remapped into the primary domain for periodic domains before checking.	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Approximate grid block size. If provided, blocks is derived.	None
blocks	tuple[int, int, int] | None	Explicit (nx, ny, nz) grid blocks. Overrides block_size.	None
init_mem	int	Initial per-block particle memory in Voro++.	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.

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 near-duplicate pre-check for generator points. See :func:pyvoro2.duplicate_check. Use "raise" to prevent Voro++ hard exits on near-duplicates. "warn" is diagnostic only and does not prevent hard exits.	'off'
duplicate_threshold	float	Absolute distance threshold used by the pre-check.	1e-05
duplicate_wrap	bool	If True, points are remapped into the primary domain for periodic domains before checking.	True
duplicate_max_pairs	int	Maximum number of near-duplicate pairs reported.	10
block_size	float | None	Approximate grid block size. If provided, blocks is derived.	None
blocks	tuple[int, int, int] | None	Explicit (nx, ny, nz) grid blocks. Overrides block_size.	None
init_mem	int	Initial per-block particle memory in Voro++.	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.

:::