Expand description
Minimum-image convention for a periodic parallelepiped.
Cell holds the 3x3 lattice H and a dump-cell origin.
Constructors accept a LAMMPS bound box plus tilts, a CON lattice or
length-angle box, an ASE-style 3x3 cell, and a vesin box.
§Units and conventions
- Length units: arbitrary, provided
H,origin, positions, and cutoffs share one unit (squared cutoffs use that unit squared).Cell::from_con_boxtakes crystallographic angles in degrees. Fractional coordinates fromCell::fractionalare dimensionless in[0, 1). - Matrix storage:
Cell::from_vectorsandCell::hstore lattice vectorsa,b,cas the columns ofH, sor = H s + origin.Cell::from_ase,Cell::from_con,Cell::from_vesin, andPartialCell::from_aseaccept row-major 3x3 arrays[a, b, c]. - Displacement sign:
Cell::displacementreturns the wrapped vector fromptoq, i.e.,wrap(q - p). The origin cancels in every displacement and distance call. - Engine wrap vs Euclidean MIC:
Cell::displacementandCell::dist2compute the fractional wrapds = wrap(Hinv (q - p)), thendr = H ds(the LAMMPSlamda/ eOn / HOOMD convention). Orthorhombic boxes used - L floor(d/L + 1/2)on every image, keeping-L/2and mapping+L/2to-L/2. Restricted triclinic boxes use the triangularlamdastep.Cell::reduce_tiltsis GROMACScorrect_box;Cell::to_restrictedis the LAMMPS general-to-restricted rotation. - Euclidean nearest image:
Cell::displacement_euclideanruns Smith’s half-altitude test, then Babai’s rounding and the Sommer-Feder-Shalvi slicer on the Selling superbasis cached on the calling thread (with Lagrange size reduction before the Delone step). On a tie it keeps the engine wrap.
§Batch kernels, fixed-point, and partial periodicity
dist2_many, dist2_pairs, wrap_many, and
dist2_ortho_diffs batch the engine wrap. Each batch reads
simd_path once and runs AVX-512, AVX2, AVX, NEON, or scalar.
Cell::fixed stores a position as 64-bit fixed-point fractions,
and the wrap between two of them is exact integer arithmetic
(Cell::dist2_fixed, dist2_many_fixed, dist2_pairs_fixed);
Cell::fixed32 keeps the top 32 bits for half the memory traffic.
Cell::dist2_shifted_indexed gathers a linked-cell bin’s index
list into the shifted kernel. reduce_pairs turns a vesin image
pair list into one minimum-image pair and drops the self image.
PartialCell is periodic along some axes only: a slab, a wire, or
an open system, with no image along an open axis.
§Error behaviour
Fallible functions return Result<_, Error>. Error::BadBox
signals a singular, non-finite, or degenerate cell; Error::BufferSize
signals mismatched slice lengths or out-of-range atom indices;
Error::Empty signals an empty or misaligned ring-polymer input.
Individual distance and displacement methods on Cell and
PartialCell are infallible once the cell has been constructed.
It is a LODE library. The Rust crate is the implementation. The C
ABI (minimage_*) is the hourglass waist, the same shape as
linkcell and
readcon-core. C++ is a
RAII header over that ABI.
use minimage::Cell;
let sim = Cell::ortho(10.0, 10.0, 10.0)?;
let left = [0.2, 0.0, 0.0];
let right = [9.4, 0.0, 0.0];
assert!((sim.dist2(left, right) - 0.64).abs() < 1e-12);Structs§
- Cell
- Periodic parallelepiped: columns of H, origin, and an ortho flag.
- Filter
Out - Rows that survived
filter_shifted. - Partial
Cell - Periodic along the axes of a mask, open along the others.
- mi_cell
- Periodic parallelepiped.
- mi_
pbc_ cell - Cell periodic along the axes of a mask (a slab or a wire). The rows of open axes are carried but ignored.
Enums§
- Error
- Why a cell construction, reduction, or batch call could not run.
Functions§
- dist2_
euclidean_ many Cell::dist2_euclideanfrompto each row ofqs, bit for bit.- dist2_
euclidean_ pairs Cell::dist2_euclideanfor paired rows, bit for bit, with one superbasis lookup per call.- dist2_
euclidean_ pairs_ warm - Euclidean nearest-image squared distances for pairs that persist across frames.
- dist2_
many - Squared MIC distances from
pto each packed candidate inqs. - dist2_
many_ fixed - Squared engine-wrap distances from fixed-point
pto each fixed-pointqs(Cell::fixed). Integer wrap, one product withH. - dist2_
many_ fixed32 Cell::dist2_fixed32frompto each row ofqs, bit for bit: sixteen rows per AVX-512 pass, eight per AVX2 pass.- dist2_
ortho_ diffs - Orthorhombic wrap of precomputed differences, one reciprocal per axis.
- dist2_
pairs - Squared MIC distances for packed pair lists
psandqs. - dist2_
pairs_ fixed - Squared engine-wrap distances for fixed-point pair lists.
- dist2_
pairs_ fixed32 Cell::dist2_fixed32for paired rows, bit for bit.- dump_
bounds_ to_ h - Recover restricted-triclinic
H(columns[a, b, c]) and origin from a LAMMPS dump bound box. - filter_
shifted - Drop candidates whose shifted distance is not strictly below
cut2. - fixed32_
many Cell::fixed32for packed positions.- fixed_
many Cell::fixedfor packed positions: one AVX2 pass folds, floors, and takes the mantissa oft + 1for four rows at once.- is_
minkowski_ reduced - True when the three columns of
Hsatisfy the 3D Minkowski inequalities (Jaber; Nguyen and Stehlé, https://doi.org/10.1145/1597036.1597050). - minimage_
cell_ ⚠from_ ase - Fill
outfrom an ASE-style row-major 3x3 cell ([a, b, c]) in consistent length units.origindefaults to zero whenNULL. - minimage_
cell_ ⚠from_ con - Fill
outfrom a CON 3x3 lattice (rowsa,b,c) with origin defaulting to zero. - minimage_
cell_ ⚠from_ con_ box - Fill
outfrom CON lengths (boxlin length units) and crystallographic angles (angles_deg[alpha, beta, gamma]in degrees). Origin defaults to zero. - minimage_
cell_ from_ lammps - Fill
outfrom LAMMPS dump-bound coordinatesxlo xhi ylo yhi zlo zhiand tilt factorsxy, xz, yzin consistent length units. - minimage_
cell_ from_ lammps_ bounds - Fill
outfrom LAMMPS dump bound spans, tilts, and bound origins, all in consistent length units. - minimage_
cell_ ⚠from_ vectors - Fill
outfrom lattice vectorsa,b,candorigin, all in consistent length units. - minimage_
cell_ ⚠from_ vesin - Fill
outfrom a vesin 3x3 box (rowsa,b,c) with origin defaulting to zero. - minimage_
displacement ⚠ - Engine minimum-image displacement from
ptoq(wrap(q - p)) intodr, in the cell’s length units. - minimage_
displacement_ ⚠euclidean - Euclidean MIC displacement from
ptoqintodr, in the cell’s length units: Smith half-altitude test, else the slicer on the Selling superbasis cached on the calling thread. A tie keeps the engine vector. - minimage_
displacement_ ⚠euclidean_ pbc - Nearest-image displacement from
ptoqover the periodic axes ofsimboxintodr, in cell length units. Open axes take no image. - minimage_
dist2 ⚠ - Squared minimum-image distance from
ptoqintoout, in the cell’s squared length units. - minimage_
dist2_ ⚠euclidean_ many - Euclidean nearest-image squared distances from
ptonpacked candidates:minimage_displacement_euclideanper pair, bit for bit, with one superbasis lookup per call and eight pairs per slicer pass. - minimage_
dist2_ ⚠euclidean_ pairs minimage_dist2_euclidean_manyfor paired rows.- minimage_
dist2_ ⚠euclidean_ pairs_ warm minimage_dist2_euclidean_pairsfor pairs that persist across frames.imagesisnrows of threeint32_t: the cell-basis lattice shift of each pair’s image from the previous call, zeros to start, updated in place. A pair whose stored image still lies in the Voronoi cell skips the search; its distance equals the full search to rounding.- minimage_
dist2_ ⚠euclidean_ pbc - Squared length of
minimage_displacement_euclidean_pbcintoout, in squared cell length units. - minimage_
dist2_ ⚠fixed - Squared engine-wrap distance between two fixed-point positions.
- minimage_
dist2_ ⚠fixed32 - Squared engine-wrap distance between two 32-bit fixed-point positions.
- minimage_
dist2_ ⚠many - Squared MIC distances from
ptonpacked candidates inqs, in squared cell length units. Whenn == 0, returns0after validatingsimboxandp. - minimage_
dist2_ ⚠many_ fixed - Squared engine-wrap distances from fixed-point
ptonpacked fixed-point candidates. - minimage_
dist2_ ⚠many_ fixed32 - Squared engine-wrap distances from 32-bit fixed-point
ptonpacked fixed-point candidates. - minimage_
dist2_ ⚠ortho_ diffs - Orthorhombic wrap of precomputed differences (Highway kernel).
- minimage_
dist2_ ⚠pairs - Squared MIC distances for
npacked pairs(ps[k], qs[k]), in squared cell length units. Whenn == 0, returns0after validatingsimbox. - minimage_
dist2_ ⚠pairs_ fixed - Squared engine-wrap distances for
npacked fixed-point pairs. - minimage_
dist2_ ⚠pairs_ fixed32 - Squared engine-wrap distances for
npacked 32-bit fixed-point pairs. - minimage_
dist2_ ⚠shifted_ many - Squared distances from
ptonpoints inqs, plus one lattice shift(sx, sy, sz)on every candidate, in squared length units. Rapaport’s bin pair. Whenn == 0, returns0after validatingpandshift. - minimage_
filter_ ⚠shifted - Squared-distance filter of candidate pairs
(ii[k], jj[k], shift[k]). - minimage_
fixed32_ ⚠many - 32-bit fixed-point fractional coordinates of
npacked positions: threeuint32_tper position, each the 64-bit fraction ofminimage_fixed_manyrounded to its top 32 bits. - minimage_
fixed_ ⚠many - Fixed-point fractional coordinates of
npacked positions: threeuint64_tper position, each fraction asround(s * 2^52) * 2^12. - minimage_
last_ error - Thread-local last-error string from this thread’s most recent
minimage_*failure. - minimage_
pbc_ ⚠cell_ from_ ase - Fill
outfrom ASE-style rows, a periodicity mask and an origin.pbcholds three ints (0open, nonzero periodic);origindefaults to zero whenNULL. Rows use consistent length units; rows of periodic axes must be finite and linearly independent, while rows of open axes may be zero. All three periodic matchesminimage_cell_from_ase. - minimage_
reduce_ ⚠pairs - Drop self images (
i == j) and collapse duplicate(i, j)rows. - minimage_
ring_ ⚠centroid - Ring-polymer centroid in the cell’s length units.
- minimage_
version - Library version string. Process-static, NUL-terminated. Do not free.
- minimage_
wrap_ ⚠many - Engine wrap of
npacked difference vectors (q - p) intoout, in the cell’s length units. Whenn == 0, returns0without dereferencingdiffsorout(after validatingsimbox). - minkowski_
reduce - Unimodular Minkowski reduction. Same Cartesian lattice, new basis
with
|a| <= |b| <= |c|and the origin preserved. - reduce_
pairs - Drop self images and collapse duplicate
(i, j)rows. - reduce_
pairs_ packed - Same reduction as
reduce_pairsover a packedn * 2buffer. - ring_
centroid - Mean position of each atom across the beads of a ring polymer.
- simd_
path - Name of the SIMD path the next batch will use.
- wrap_
many - Minimum-image wrap of packed difference vectors.