Diagnostics

Spatial diagnostics use error severity as the final failure policy. Missing or invalid non-empty cell volumes and valid-measure closure gaps/overlaps are errors. Missing expected IDs are errors in standard mode, informational hidden cells in power mode, and warnings when mode=None. A requested periodic reciprocity check is required. See Topology and neighbor graphs for the cross-dimensional policy.

`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

Required invariant failures are explicit error-severity issues and make diagnostics.ok false.
Warning- and info-only findings do not fail diagnostics.ok.
For periodic domains, faces should 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') selecting expected-ID semantics. Missing standard IDs are errors, missing power IDs are informational hidden cells, and `None` leaves them as warnings.	`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). An explicitly requested public check is required, so missing shifts, reciprocals, or geometric agreement are errors.	`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, reset and then annotate the analyzer-owned face flags in place. If False, existing caller annotations are untouched.	`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 selecting standard, power, or undeclared expected-ID semantics.	`None`
`level`	`Literal['basic', 'strict']`	'basic' returns diagnostics; 'strict' raises :class:`TessellationError` when validation fails.	`'basic'`
`require_reciprocity`	`bool \| None`	If True, periodic reciprocity findings are errors. If False, they are inspected as warning/info findings. 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

:::