Normalization

pyvoro2.normalize

Topology-level post-processing utilities.

Voro++ returns each Voronoi cell with its own local vertex list. In periodic systems, many of those local vertices represent the same geometric vertex but in different periodic images.

This module provides a correctness-first normalisation routine that builds a global vertex pool in the 000 cell (primary periodic domain) and, for each cell, maps local vertices to: - a global vertex index, and - an integer lattice shift (na, nb, nc) such that:

    v_local ~= v_global + na*a + nb*b + nc*c

All coordinates exposed by the public API are Cartesian.

NormalizedTopology dataclass

Result of :func:normalize_topology.

This extends :class:NormalizedVertices with globally deduplicated edges and faces. These are useful for building periodic Voronoi graphs.

All coordinates exposed here are Cartesian. Periodicity is represented via integer lattice shifts (na, nb, nc) relative to the domain lattice vectors.

Attributes:

Name	Type	Description
global_vertices	ndarray	Array of unique vertices in Cartesian coordinates, remapped into the primary cell for periodic domains.
global_edges	List[Dict[str, Any]]	List of unique edges. Each edge dictionary contains: - vertices: (gid0, gid1) global vertex indices - vertex_shifts: ((0,0,0), (na,nb,nc)) such that the second endpoint is V[gid1] + naa + nbb + nc*c, while the first is V[gid0].
global_faces	List[Dict[str, Any]]	List of unique faces. Each face dictionary contains: - cells: (cid0, cid1) particle ids (first is the canonical anchor) - cell_shifts: ((0,0,0), (na,nb,nc)) shift of cid1 relative to cid0 - vertices: list[int] global vertex ids in canonical cyclic order - vertex_shifts: list[(na,nb,nc)] shifts aligned with vertices, with the first vertex shift always (0,0,0).
cells	List[Dict[str, Any]]	Per-cell dictionaries (copies by default) including the vertex mapping fields plus: - edges: list[(u,v)] local vertex index pairs (u<v) - edge_global_id: list[int] aligned with edges - face_global_id: list[int] aligned with faces

NormalizedVertices dataclass

Result of :func:normalize_vertices.

Attributes:

Name	Type	Description
global_vertices	ndarray	Array of unique vertices in Cartesian coordinates, remapped into the primary cell for periodic domains.
cells	List[Dict[str, Any]]	A list of per-cell dictionaries. Each dictionary contains the original fields returned by :func:pyvoro2.compute plus: - vertex_global_id: list[int] of length n_local_vertices - vertex_shift: list[tuple[int,int,int]] aligned with vertices

normalize_edges_faces(nv, *, domain, tol=None, copy_cells=True)

Build global edge and face pools based on an existing vertex normalization.

normalize_topology(cells, *, domain, tol=None, require_face_shifts=True, copy_cells=True)

Convenience wrapper: normalize vertices, then edges/faces.

normalize_vertices(cells, *, domain, tol=None, require_face_shifts=True, copy_cells=True)

Build a global vertex pool and per-cell vertex mappings.

Parameters:

Name	Type	Description	Default
cells	List[Dict[str, Any]]	Output list from :func:pyvoro2.compute. Must include local vertices (return_vertices=True). For periodic domains, faces and face shifts are required unless require_face_shifts=False.	required
domain	Box | OrthorhombicCell | PeriodicCell	The domain used for the computation.	required
tol	float | None	Quantization tolerance used for coordinate keys and residual verification. If None, defaults to 1e-8 * L where L is a domain length scale.	None
require_face_shifts	bool	If True and domain is PeriodicCell, require face-level adjacent_shift entries to build robust topology keys.	True
copy_cells	bool	If True, return shallow copies of the cell dicts with added mapping fields. If False, mutate the input dictionaries.	True

Returns:

Type	Description
NormalizedVertices	NormalizedVertices with global_vertices and augmented cell dicts.

Raises:

Type	Description
ValueError	if required fields are missing.

:::