Validation

`pyvoro2.validation`

Strict validation utilities.

This module provides post-hoc validators that can be used to sanity check:

1) tessellation outputs (via :func:pyvoro2.validate_tessellation, implemented as a thin wrapper around :func:pyvoro2.analyze_tessellation), and 2) topology/normalization outputs (via :func:validate_normalized_topology).

The core goal is to turn subtle periodic bookkeeping mistakes into explicit, actionable errors.

`NormalizationError`

Bases: ValueError

Raised when strict normalization validation fails.

`validate_normalized_topology(normalized, domain, *, level='basic', check_vertex_face_shift=True, check_face_vertex_sets=True, check_incidence=True, check_euler=True, max_examples=10)`

Validate periodic shift/topology consistency after normalization.

The most important invariant (and the one most likely to detect subtle periodic bookkeeping bugs) is:

For every periodic face i -> j with adjacent_shift = s,
every shared vertex gid must satisfy:

    vertex_shift_i(gid) == vertex_shift_j(gid) + s

where vertex_shift_* are the per-cell lattice-image shifts returned by :func:pyvoro2.normalize_vertices.

Parameters:

Name	Type	Description	Default
`normalized`	`NormalizedVertices \| NormalizedTopology`	Output of :func:`pyvoro2.normalize_vertices` or :func:`pyvoro2.normalize_topology`.	required
`domain`	`Domain`	Domain used to compute the tessellation.	required
`level`	`Literal['basic', 'strict']`	'basic' returns diagnostics; 'strict' raises :class:`NormalizationError` on any error-level issue.	`'basic'`
`check_vertex_face_shift`	`bool`	Check the key vertex/face shift invariant.	`True`
`check_face_vertex_sets`	`bool`	Check that reciprocal faces reference the same set of global vertex IDs.	`True`
`check_incidence`	`bool`	In fully periodic domains, check minimal incidence counts for vertices (>=4) and edges (>=3). Only runs when `normalized` includes edges (i.e., is a NormalizedTopology).	`True`
`check_euler`	`bool`	Check Euler characteristic per cell (V - E + F == 2) as a warning-level sanity check.	`True`
`max_examples`	`int`	Max number of example tuples to attach per issue.	`10`

Returns:

Type	Description
`NormalizationDiagnostics`	NormalizationDiagnostics

:::