site_analysis.pbc_utils

Utilities for handling periodic boundary conditions.

Includes PBC correction, reference-centre unwrapping, and incremental PBC shift updates (with optional numba acceleration).

apply_legacy_pbc_correction(frac_coords: ndarray) → ndarray[source]

Apply the legacy spread-based periodic boundary condition handling.

If the range of fractional coordinates along x, y, or z exceeds 0.5, assume that the site wraps around the periodic boundary in that dimension. Fractional coordinates for that dimension that are less than 0.5 will be incremented by 1.0.

Parameters:

frac_coords – Array of fractional coordinates with shape (n, 3).

Returns:

Adjusted fractional coordinates with the same shape.

Warning

This algorithm can produce incorrect results for sites spanning periodic boundaries in small unit cells. Consider using reference centre-based approaches for robust PBC handling.

correct_pbc(frac_coords: ndarray, reference_center: ndarray | None, lattice_matrix: ndarray) → tuple[ndarray, ndarray][source]

Apply PBC correction to fractional coordinates.

Selects the appropriate unwrapping strategy based on whether a reference centre is provided. When a reference centre is given, vertices are unwrapped to their closest periodic images relative to that centre. Otherwise, the legacy spread-based correction is applied.

Parameters:

  • frac_coords – Fractional coordinates, shape (n, 3).

  • reference_center – Reference centre for unwrapping, or None for legacy spread-based correction.

  • lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors. Passed to the reference-centre unwrapping path; unused by the legacy spread-based path.

Returns:

Tuple of (corrected_coords, image_shifts) where both have shape (n, 3) and image_shifts has int64 dtype.

unwrap_vertices_to_reference_center(frac_coords: ndarray, reference_center: ndarray, lattice_matrix: ndarray, return_image_shifts: Literal[False] = False) → ndarray[source]
unwrap_vertices_to_reference_center(frac_coords: ndarray, reference_center: ndarray, lattice_matrix: ndarray, return_image_shifts: Literal[True] = False) → tuple[ndarray, ndarray]

Vectorised unwrapping of vertices to their closest periodic images relative to a reference centre.

Parameters:

  • frac_coords – Array of fractional coordinates with shape (n, 3).

  • reference_center – Reference centre position for unwrapping.

  • lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors.

  • return_image_shifts – If True, also return the per-vertex integer image shifts (from _PERIODIC_SHIFTS), separate from the uniform non-negative shift.

Returns:

Unwrapped fractional coordinates with the same shape, shifted to ensure all coordinates >= 0. If return_image_shifts is True, returns a tuple of (unwrapped_coords, image_shifts).

update_pbc_shifts(frac_coords: ndarray, cached_raw_frac: ndarray, image_shifts: ndarray) → tuple[bool, ndarray, ndarray]

JIT-compiled variant of _numpy_update_pbc_shifts.

Same algorithm with early exit on first invalid vertex, avoiding full array traversal on cache misses.

See _numpy_update_pbc_shifts for full documentation.