Diagnostics

pyvoro2.diagnostics

Tessellation diagnostics and sanity checks.

These utilities help detect when the computed collection of cells may not form an expected partition of the domain (e.g. due to numerical issues or missing cells in the output when empty cells are omitted).

Key ideas

• A cell returned by Voro++ is always a closed convex polyhedron (if it exists).
• For periodic domains, faces should generally be reciprocal: if cell i has a face to (j, s), then cell j should have a face to (i, -s).

The public entry point is :func:analyze_tessellation.

TessellationError

Bases: ValueError

Raised when tessellation sanity checks fail under strict settings.

analyze_tessellation(cells, domain, *, expected_ids=None, mode=None, volume_tol_rel=1e-08, volume_tol_abs=1e-12, check_reciprocity=True, check_plane_mismatch=True, plane_offset_tol=None, plane_angle_tol=None, mark_faces=True)

Analyze tessellation sanity and (optionally) annotate faces.

This function is designed to be conservative: it reports issues but does not modify geometry. If mark_faces=True, it will annotate face dicts with local flags such as orphan and reciprocal_mismatch.

Parameters:

Name	Type	Description	Default
cells	Sequence[dict[str, Any]]	Output of :func:pyvoro2.compute.	required
domain	Box | OrthorhombicCell | PeriodicCell	Domain used for computation.	required
expected_ids	Sequence[int] | None	Optional list of expected cell ids (useful when ids were remapped by the user). If provided, missing ids are reported.	None
mode	str | None	Optional mode string ('standard'|'power') used only for messaging.	None
volume_tol_rel	float	Relative tolerance for domain volume comparison.	1e-08
volume_tol_abs	float	Absolute tolerance for domain volume comparison.	1e-12
check_reciprocity	bool	Whether to check face reciprocity (periodic domains only).	True
check_plane_mismatch	bool	Whether to check that reciprocal faces represent the same geometric plane (periodic domains only).	True
plane_offset_tol	float | None	Absolute tolerance for reciprocal plane offset mismatch. If None, a conservative default based on domain length is used.	None
plane_angle_tol	float | None	Tolerance for reciprocal plane normal mismatch (radians). If None, a conservative default is used.	None
mark_faces	bool	If True, annotate faces in-place with local flags.	True

Returns:

Type	Description
TessellationDiagnostics	TessellationDiagnostics

validate_tessellation(cells, domain, *, expected_ids=None, mode=None, level='basic', require_reciprocity=None, volume_tol_rel=1e-08, volume_tol_abs=1e-12, plane_offset_tol=None, plane_angle_tol=None, mark_faces=None)

Validate tessellation sanity, optionally raising in strict mode.

This is a convenience wrapper around :func:analyze_tessellation.

Parameters:

Name	Type	Description	Default
cells	Sequence[dict[str, Any]]	Output of :func:pyvoro2.compute.	required
domain	Box | OrthorhombicCell | PeriodicCell	Domain used for computation.	required
expected_ids	Sequence[int] | None	Optional list of expected ids.	None
mode	str | None	Optional mode label (used for messaging).	None
level	Literal['basic', 'strict']	'basic' returns diagnostics; 'strict' raises :class:TessellationError when validation fails.	'basic'
require_reciprocity	bool | None	If True, require that periodic face reciprocity checks pass. If None, defaults to True for periodic domains and False otherwise.	None
volume_tol_rel	float	Relative tolerance for volume closure.	1e-08
volume_tol_abs	float	Absolute tolerance for volume closure.	1e-12
plane_offset_tol	float | None	Absolute tolerance for reciprocal plane offset mismatch.	None
plane_angle_tol	float | None	Tolerance for reciprocal plane normal mismatch (radians).	None
mark_faces	bool | None	Whether to annotate faces with local flags.	None

Returns:

Type	Description
TessellationDiagnostics	TessellationDiagnostics

:::