Domains API
pyvoro2.domains
Domain specifications for Voronoi tessellation.
pyvoro2 currently supports: - Box: orthogonal bounding box (non-periodic, for 0D systems) - OrthorhombicCell: orthogonal cell with optional per-axis periodicity (1D/2D/3D periodic) - PeriodicCell: fully periodic triclinic cell (3D crystals), implemented via a coordinate transform into Voro++'s lower-triangular representation.
Box
dataclass
Orthogonal bounding box domain.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bounds
|
tuple[tuple[float, float], tuple[float, float], tuple[float, float]]
|
Three (min, max) pairs for x, y, z. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If bounds are malformed or degenerate. |
from_points(points, padding=2.0)
classmethod
Create a box that encloses points with optional padding.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
ndarray
|
Array of shape (n, 3). |
required |
padding
|
float
|
Padding added on each side, in the same units as points. |
2.0
|
Returns:
| Name | Type | Description |
|---|---|---|
Box |
'Box'
|
Bounding box. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If points shape is invalid. |
OrthorhombicCell
dataclass
Orthorhombic cell with optional periodicity along each axis.
This domain corresponds to Voro++'s rectangular containers (container and
container_poly) with per-axis periodic flags.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bounds
|
tuple[tuple[float, float], tuple[float, float], tuple[float, float]]
|
Three (min, max) pairs for x, y, z. |
required |
periodic
|
tuple[bool, bool, bool]
|
Tuple of three booleans (px, py, pz). If an axis is periodic, points may lie outside the corresponding bounds and will be remapped by Voro++ into the primary domain. |
(True, True, True)
|
Notes
- For periodic axes, the primary domain uses a half-open convention: x in [xmin, xmax), etc.
- For non-periodic axes, the container has walls at the bounds.
lattice_vectors
property
Return lattice vectors (a, b, c) for this orthorhombic cell.
Vectors are returned in Cartesian coordinates and correspond to translations that map the cell onto itself.
remap_cart(points, *, return_shifts=False, eps=None)
Remap Cartesian points into the primary orthorhombic domain.
For each periodic axis, points are wrapped into the half-open interval [min, max). For non-periodic axes, coordinates are left unchanged.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
ndarray
|
Array of shape (n, 3). |
required |
return_shifts
|
bool
|
If True, also return integer shifts (nx, ny, nz) such that: where a/b/c are the cell lattice vectors. |
False
|
eps
|
float | None
|
Optional snapping tolerance. If None, defaults to 1e-12 * L where L is the maximum periodic axis length. |
None
|
Returns:
| Type | Description |
|---|---|
ndarray | tuple[ndarray, ndarray]
|
If return_shifts is False: Remapped coordinates, shape (n, 3). |
ndarray | tuple[ndarray, ndarray]
|
If return_shifts is True: (remapped_points, shifts) where shifts has shape (n, 3) and contains integer (nx, ny, nz). |
PeriodicCell
dataclass
Fully periodic triclinic cell for 3D crystals.
The user provides three lattice vectors in Cartesian coordinates. Internally, pyvoro2 converts them into the Voro++ periodic container representation: a = (bx, 0, 0) b = (bxy, by, 0) c = (bxz, byz, bz)
and transforms points into that coordinate system before tessellation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vectors
|
tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]
|
Three lattice vectors (a, b, c), each length-3. |
required |
origin
|
tuple[float, float, float]
|
Origin of the unit cell in Cartesian coordinates. |
(0.0, 0.0, 0.0)
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If vectors are malformed or degenerate. |
cart_to_internal(points)
Transform Cartesian points into the internal coordinate system.
from_params(bx, bxy, by, bxz, byz, bz, *, origin=(0.0, 0.0, 0.0))
classmethod
Create a PeriodicCell from Voro++ internal cell parameters.
Voro++ represents a triclinic periodic cell via the lower-triangular lattice vectors:
a = (bx, 0, 0)
b = (bxy, by, 0)
c = (bxz, byz, bz)
This constructor allows users to initialize a :class:PeriodicCell
directly using those parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bx
|
float
|
x component of vector a. |
required |
bxy
|
float
|
x component of vector b. |
required |
by
|
float
|
y component of vector b. |
required |
bxz
|
float
|
x component of vector c. |
required |
byz
|
float
|
y component of vector c. |
required |
bz
|
float
|
z component of vector c. |
required |
origin
|
tuple[float, float, float]
|
Origin of the unit cell in Cartesian coordinates. |
(0.0, 0.0, 0.0)
|
Returns:
| Name | Type | Description |
|---|---|---|
PeriodicCell |
'PeriodicCell'
|
A fully periodic triclinic cell. |
Notes
This constructor does not impose additional validation beyond what
is performed by :meth:to_internal_params. In particular,
:meth:to_internal_params will raise a ValueError if bx, by, or bz
are non-positive (which would indicate an invalid handedness).
internal_to_cart(points_internal)
Transform internal points back into Cartesian coordinates.
remap_cart(points, *, return_shifts=False, eps=None)
Remap Cartesian points into the primary cell.
This is a convenience wrapper around :meth:cart_to_internal,
:meth:remap_internal, and :meth:internal_to_cart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
ndarray
|
Cartesian coordinates, shape (n, 3). |
required |
return_shifts
|
bool
|
If True, also return integer lattice shifts (na, nb, nc) applied to each point. |
False
|
eps
|
float | None
|
Snapping tolerance passed through to :meth: |
None
|
remap_internal(points_internal, *, return_shifts=False, eps=None)
Remap internal coordinates into the primary periodic domain.
Voro++ stores a triclinic periodic domain using the lower-triangular vectors:
a = (bx, 0, 0)
b = (bxy, by, 0)
c = (bxz, byz, bz)
Remapping into the primary domain is not an independent modulo on x/y/z when the cell is sheared (bxy/bxz/byz != 0). In particular, wrapping in z shifts x and y, and wrapping in y shifts x.
This routine performs a lattice-consistent remap equivalent to applying integer translations along c, then b, then a. It enforces a half-open convention for the primary cell:
x in [0, bx), y in [0, by), z in [0, bz)
To make the mapping deterministic at boundaries (and stable under repeated remapping), an epsilon snapping rule is applied:
- values within `eps` of 0 are set to 0
- values within `eps` of the upper boundary are wrapped to 0 and the
corresponding lattice shift is incremented
Notes
- This method is provided as an explicit helper.
- The main
compute(...)API does not pre-wrap points for periodic domains; Voro++ remaps points internally.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points_internal
|
ndarray
|
Points in the internal coordinate system, shape (n, 3). |
required |
return_shifts
|
bool
|
If True, also return integer lattice shifts (na, nb, nc) applied to each point. |
False
|
eps
|
float | None
|
Snapping tolerance in internal distance units. If None, defaults to 1e-12 * L where L = max(bx, by, bz). |
None
|
Returns:
| Type | Description |
|---|---|
ndarray | tuple[ndarray, ndarray]
|
If return_shifts is False: Remapped coordinates, shape (n, 3). |
ndarray | tuple[ndarray, ndarray]
|
If return_shifts is True: (remapped_points, shifts) where shifts has shape (n, 3) and contains integer (na, nb, nc). |
to_internal_params()
Convert lattice vectors into Voro++ periodic cell parameters.
Returns:
| Type | Description |
|---|---|
tuple[float, float, float, float, float, float]
|
Tuple of (bx, bxy, by, bxz, byz, bz). |
wrap_internal(points_internal)
Alias for :meth:remap_internal.
This name existed in early versions of pyvoro2 but previously used an incorrect independent modulo for sheared cells.
:::