Conventions and units
minimage is unit-agnostic: coordinates, lattice vectors, origins, and
displacements share one caller-chosen Cartesian length unit, and
squared distances and cutoffs use that unit squared. The single
exception is from_con_box (minimage_cell_from_con_box), which takes
the three cell angles alpha, beta, and gamma in degrees.
Fractional coordinates from Cell::fractional are dimensionless in
[0, 1).
Internally, Cell stores the three lattice vectors a, b, and c
as the columns of the 3x3 matrix H, so Cartesian coordinates are
r = H s + origin and fractional coordinates fold via
s = Hinv (r - origin). Constructors that take three separate vectors
(Cell::from_vectors, minimage_cell_from_vectors) pass columns,
whereas ASE, CON, and vesin constructors (from_ase, from_con,
from_vesin, PartialCell::from_ase, and their minimage_* C
equivalents) accept row-major 3x3 arrays [a, b, c].
Every displacement function computes the wrapped vector from p to
q, meaning wrap(q - p). The cell origin cancels in every
displacement and squared distance call.
Fractional wrap and triclinic cells
A periodic cell is a parallelepiped whose edges are the columns of H.
Cartesian coordinates fold to fractional coordinates
s = Hinv (r - origin), wrap each component into the central image,
then map back r = H s. Squared engine distance is
|H wrap(Hinv (q - p))|^2.
Orthorhombic cells
Orthorhombic boxes are the diagonal case (Allen and Tildesley; Frenkel
and Smit). Each axis is d - L floor(d/L + 1/2) for every image, not
a single subtraction. The half-box tie keeps -L/2 and maps +L/2
onto -L/2, matching LAMMPS dump relDist in d-SEAMS (Goswami et al.,
J. Chem. Inf. Model. 60, 2169, 2020,
doi:10.1021/acs.jcim.0c00031).
Two positions folded into the box are less than one length apart on
every axis, so the wrap is two selects and the floor runs only past
that. A squared distance needs no sign: for |d| < L the wrapped
length is min(|d|, L - |d|), the same square bit for bit with a third
of the selects.
Baseline x86-64 has no rounding instruction, so f64::round and
floor are libm calls. Rounding half away from zero adds the largest
double below one half, with the sign of the argument, and truncates
toward zero. That is the same integer for every finite double, and the
expansion LLVM itself uses when SSE4.1 is present. The same truncation
runs on every architecture. Truncation of a negative zero is +0.0,
so floor_fast(-0.0) is +0.0 and the fractional part of -0.0 is
-0.0. f64::floor(-0.0) keeps the minus sign and is not used.
See SIMD paths and dispatch.
Restricted and general triclinic cells
A restricted triclinic box (a along x, b in the xy plane, with
upper-triangular tilts xy, xz, yz) uses the triangular lamda
step of LAMMPS Domain::minimum_image, HOOMD BoxDim::minImage,
OpenMM applyPeriodic, and GROMACS pbc_dx (Tuckerman, Statistical
Mechanics: Theory and Molecular Simulation,
doi:10.1093/oso/9780198825562.001.0001; Wassenaar). It wraps sz,
then sy, then sx using half-away-from-zero rounding (round_away),
avoiding a general 3x3 inverse multiply.
A general triclinic orientation (is_restricted() = false=) computes
two 3x3 products with Hinv and H. Cell::reduce_tilts applies
unimodular GROMACS correct_box reduction so that |xy| < |lx|/2=,
|xz| < |lx|/2=, and |yz| < |ly|/2= (tested by tilts_reduced()),
preserving the Cartesian lattice. Cell::to_restricted rotates a
general parallelepiped into the restricted-triclinic frame (LAMMPS
define_general_triclinic).
Batch fusion
dist2_many, dist2_pairs, and wrap_many are one SIMD pass over
the packed rows for every cell shape: four rows load as three vectors,
subtract while still packed, and transpose once in registers, with no
staging buffer (map fusion in the sense of DaCe and Futhark). An
orthorhombic wrap is per element and does not transpose at all. Each
lane runs the per-pair operations in the per-pair order, so a batch
squared distance equals the per-pair call bit for bit and a wrapped
vector equals it up to the sign of a zero. dist2_ortho_diffs keeps
the Highway BatchPeriodicDistSq shape: precomputed differences, one
reciprocal per axis, abs, then round.
Where the processor has AVX-512F and DQ, eight rows go per pass:
two-source permutes transpose them, and the last rows load and store
under a lane mask, so no batch ends in a scalar tail. The intrinsics
are stable from Rust 1.89, which build.rs checks; an older compiler
keeps the AVX path. The orthorhombic wrap stays at four rows. It
stores as much as it loads, and a 64-byte store splits a cache line
on all but one alignment in eight.
Euclidean nearest image and Selling reduction
Smith, CCP5 Newsletter 1989: the engine wrap is the Euclidean nearest image when its length is strictly below half the smallest face altitude. That is the cutoff regime. Linkcell k-NN has no cutoff. A hex-prism body diagonal is an engine wrap that is longer than another image, even when the cell is already tilt-reduced and Minkowski-reduced.
Past that test, displacement_euclidean (minimage_displacement_euclidean
in C) finds the closest lattice image from the obtuse superbasis every
three-dimensional lattice has (Selling, J. Math. Pures Appl. 1874;
Conway and Sloane, Proc. R. Soc. Lond. A 436, 55, 1992,
doi:10.1098/rspa.1992.0004).
A near-parallel basis makes the one-vector Delone step linear in the
reciprocal of the angle, so Lagrange's size reduction (1773; Gauss,
- shortens the edges first, keeping the Delone loop within the
1000-step bound used by spglib and Andrews, Bernstein, and Sauter
(Acta Cryst. A 75, 115, 2019,
doi:10.1107/s2053273318015413).
The superbasis is cached on the calling thread, keyed by H, and is
built on the first query that fails the Smith test. Constructors do
not build it.
The query rounds in three of the four superbasis vectors (Babai,
Combinatorica 6, 1, 1986,
doi:10.1007/bf02579403), then
runs the iterative slicer of Sommer, Feder, and Shalvi (SIAM J.
Discrete Math. 23, 715, 2009,
doi:10.1137/060676362): while
some relevant vector r has 2 |x . r| > |r|^2, step by r. Every
Voronoi-relevant vector of an obtuse superbasis is one of seven
classes +/- v_S (Conway and Sloane, 1992), so where the walk stops
x is the shortest vector of its coset. A restricted cell with its
tilts inside half an edge starts from the engine wrap instead of
Babai's point. McKilliam, Grant, and Clarkson (SIAM J. Discrete Math.
28, 1405, 2014,
doi:10.1137/140952806) search
the same subset sums in three rounds of fifteen. A tie keeps the
engine vector.
dist2_euclidean_many and dist2_euclidean_pairs look the superbasis
up once per call and run the slicer on eight rows per AVX-512 pass: a
row's seven dot products are one lane of eight vectors, the select
tree runs lane by lane, and a lane's Gram row is one vpermpd of the
stored rows. The Smith test becomes a lane mask, so the branch that a
single query mispredicts is gone, and a group whose lanes all pass it
skips the slicer. Each lane keeps the scalar order, its step choice,
and its step count, so a batch equals the per-pair call bit for bit.
Without AVX-512 the batch runs the per-pair code with the one lookup.
Across frames a pair seldom leaves its image.
dist2_euclidean_pairs_warm keeps each pair's cell-basis shift n
from the previous call: subtracting H n and testing the seven
relevant vectors replaces the search for a pair still in its Voronoi
cell, and the others take the full search and store their new shift.
Integer shifts stay right when the cell deforms. While the pairs fit
in cache this is 2.2 to 2.8 times faster than the batch; from main
memory, where the shifts are one more stream, 1.15 times. The image is
the one the search finds, and the distance equals it to rounding,
since H n is subtracted directly rather than through the engine
wrap.
Nguyen and Stehle (ACM Trans. Algorithms 5, 46, 2009,
doi:10.1145/1597036.1597050)
Minkowski-reduce a basis (minkowski_reduce and is_minkowski_reduced,
supporting the 27-image check displacement_cartesian), though
Minkowski reduction alone does not eliminate the hex-prism body
diagonal check without searching all 27 combinations. The linked-cell
pair itself is Rapaport's shift, |q + shift - p|^2, exposed as
dist2_shifted_many. A bin that is an index list rather than a
contiguous slice is dist2_shifted_indexed: it gathers a chunk of
those positions into the same kernel. The gather copies every point
first. On a long index list that copy was slower than the inlined
subtract, so the production walk keeps the subtract.
Partial periodicity
PartialCell (mi_pbc_cell in C) handles systems periodic along zero,
one, two, or three axes. An open system (zero periodic axes) returns
q - p. A wire (one periodic vector a) projects onto a and wraps
with s - floor(s + 1/2). A slab (two periodic vectors) Lagrange-reduces
its 2D basis and checks the nine neighbouring lattice combinations
around the rounded reduced coordinates, preserving the component normal
to the periodic plane. With all three axes periodic, PartialCell
delegates to Cell and returns the exact same bits.
Fixed-point fractions
Cell::fixed stores a position folded into the cell as three
fractions on 64 bits, round(s * 2^52) * 2^12: the low 52 bits of
s + 1 are that integer, so a position converts with an add and a
mask, no conversion instruction and no branch, and fixed_many does
four or eight at once. The engine wrap of a difference is
then integer arithmetic: b - a modulo 2^64, read as signed, is the
wrapped fraction in [-1/2, 1/2), exactly. The top 52 bits of that
difference convert to a double exactly, and one product with H gives
the Cartesian vector, for any cell shape, with no Hinv and no
rounding step. That is the exact integer split of the Ozaki scheme
(Ozaki, Ogita, Oishi, and Rump, Numer. Algorithms 59, 95, 2012,
doi:10.1007/s11075-011-9478-1)
applied to the periodic wrap, and the fixed-point positions of Anton
(Shaw et al., Commun. ACM 51, 91, 2008,
doi:10.1145/1364782.1364802).
The wrap is the symmetric residue a - m floor(a/m + 1/2) of Ozaki
Scheme II (Ozaki, Uchino, and Imamura,
arXiv:2504.08009, 2025) with
the one modulus m = 2^64; two's complement computes it, so no Chinese
remainder step is needed. The orthorhombic wrap above is the same
residue with m = L. Scheme II splits a product over several small
moduli so that INT8 units compute each part exactly, then rebuilds it
by the Chinese remainder theorem; that pays when many products share
one rebuild, as along the inner dimension of a matrix product. A wrap
has one subtraction per axis and the product with H has three terms,
so on a CPU the double-precision units are already the fast path.
Convert positions once per frame; a pair list over them then costs a
subtraction, a conversion, and a matrix product per pair. A fraction
exactly one half apart wraps to -1/2, and the distance agrees with
dist2 to a few units in the last place.
Cell::fixed32 and the _fixed32 batches round each fraction to its
top 32 bits: 12 bytes a position instead of 24. Past the second-level
cache a batch moves more bytes than it computes on, about 56 a pair,
so the bytes set the time. On the measured Xeon host the 32-bit batches
are 2.7 to 3.5 times faster than the double batches at 64K pairs, 1.8
to 2.0 times at 16M, and 2 times in cache. The wrap is still exact,
modulo 2^32, and a displacement is within 2^-32 (|a| + |b| + |c|)
of the engine wrap, about 7e-9 in a cell 10 long: a tier for
neighbour searches and histograms, beside the double contract.
Arrays and devices
The Python methods take any host DLPack producer (numpy, PyTorch, JAX,
or CuPy host memory; see also metatensor and metatomic,
doi:10.1063/5.0304911) and read
contiguous rows where they lie; the result is a numpy array that owns
its buffer through a DLPack 1.0 capsule, so torch.from_dlpack shares
it too.
minimage-burn puts the wrap on Burn tensors. Burn 0.22 picks the
backend from the device at run time, so one code path serves the CPU,
wgpu, Vulkan, Metal, CUDA, and ROCm, and every step is a matrix
product or an element-wise map that Burn's fusion joins per batch.
Positions folded into [0, 1) on the CPU in double precision wrap
exactly on the device in any float width: for |ds| < 1, ds -
round(ds) subtracts zero or a neighbour of ds, which is exact by
Sterbenz's lemma. A single- or half-precision device then rounds only
ds and the product with H. That is the reduced precision of
kernel_float (Heldens, Netherlands eScience Center), chosen per call,
around an exact wrap. Folding on a single-precision device would lose
the digits of a position far from the origin, so the fold stays on
the CPU.
Error behaviour
- Rust: constructors and slice-validated functions return
Result<_, Error>.Error::BadBoxcovers singular (|det(H)| < 1e-18), non-finite, or zero-width cells, non-positive lengths infrom_con_boxordist2_ortho_diffs, and collinear or non-finite periodic basis vectors inPartialCell::from_ase.Error::BufferSizecovers mismatched slice lengths or out-of-range atom indices infilter_shifted.Error::Emptycovers zero beads, empty coordinates, or misaligned bead lengths inring_centroid. Once constructed, per-pair methods onCellandPartialCellare infallible (dist2_shifted_indexedpanics on an out-of-bounds index). - C ABI (
minimage_*): everyint-returning function returns0on success and1on failure (null pointer, invalid cell, length/index error, or integer overflow). On failure, a thread-local NUL-terminated UTF-8 error string is stored and returned byminimage_last_error(). The next successfulminimage_*call on that thread clears the slot, andminimage_last_error()then returnsNULL.minimage_version()neither reads nor modifies the slot. - C++ (
minimage.hpp): wraps C ABI status codes and throwsminimage::Error(carryingstatus()andwhat()fromminimage_last_error()).Cell::orthoisnoexceptand defers validation until a query runs; the other constructors validate immediately. - Python: raises
ValueErroron invalid cells, length-3 / 3x3 /(N, 3)shape errors, or length mismatches;TypeErroron unsupported dtypes, non-CPU DLPack devices, or invalid DLPack objects; andBufferErroron unsupported DLPack capsule versions or re-exported buffers.
Dump bounds are not H
LAMMPS ITEM BOX BOUNDS stores bound spans plus tilt xy, xz, yz.
Cell::from_lammps_bounds recovers the restricted-triclinic H and
origin:
xlo_bound = xlo + min(0, xy, xz, xy+xz)
A CON header may already hold the 3x3 lattice (readcon-core,
doi:10.5281/zenodo.22019397),
or lengths and angles in the crystallographic convention. ASE and vesin
pass rows (a, b, c).
vesin images
vesin enumerates periodic images. A particle can appear as its own
neighbour through an image, and one neighbour can arrive through
several images. reduce_pairs keeps each ordered pair once and drops
the self image.
Consumers
linkcell re-exports minimage::Cell for the fold and the lattice
shift. d-SEAMS (doi:10.1021/acs.jcim.0c00031)
calls the C ABI from lammpsBoxToLcCell, periodicDistSq / relDist,
the ortho batch kernel, and the vesin pair collapse.