Skip to main content

Crate minimage

Crate minimage 

Source
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_box takes crystallographic angles in degrees. Fractional coordinates from Cell::fractional are dimensionless in [0, 1).
  • Matrix storage: Cell::from_vectors and Cell::h store lattice vectors a, b, c as the columns of H, so r = H s + origin. Cell::from_ase, Cell::from_con, Cell::from_vesin, and PartialCell::from_ase accept row-major 3x3 arrays [a, b, c].
  • Displacement sign: Cell::displacement returns the wrapped vector from p to q, i.e., wrap(q - p). The origin cancels in every displacement and distance call.
  • Engine wrap vs Euclidean MIC: Cell::displacement and Cell::dist2 compute the fractional wrap ds = wrap(Hinv (q - p)), then dr = H ds (the LAMMPS lamda / eOn / HOOMD convention). Orthorhombic boxes use d - L floor(d/L + 1/2) on every image, keeping -L/2 and mapping +L/2 to -L/2. Restricted triclinic boxes use the triangular lamda step. Cell::reduce_tilts is GROMACS correct_box; Cell::to_restricted is the LAMMPS general-to-restricted rotation.
  • Euclidean nearest image: Cell::displacement_euclidean runs 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.
FilterOut
Rows that survived filter_shifted.
PartialCell
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_euclidean from p to each row of qs, bit for bit.
dist2_euclidean_pairs
Cell::dist2_euclidean for 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 p to each packed candidate in qs.
dist2_many_fixed
Squared engine-wrap distances from fixed-point p to each fixed-point qs (Cell::fixed). Integer wrap, one product with H.
dist2_many_fixed32
Cell::dist2_fixed32 from p to each row of qs, 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 ps and qs.
dist2_pairs_fixed
Squared engine-wrap distances for fixed-point pair lists.
dist2_pairs_fixed32
Cell::dist2_fixed32 for 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::fixed32 for packed positions.
fixed_many
Cell::fixed for packed positions: one AVX2 pass folds, floors, and takes the mantissa of t + 1 for four rows at once.
is_minkowski_reduced
True when the three columns of H satisfy the 3D Minkowski inequalities (Jaber; Nguyen and Stehlé, https://doi.org/10.1145/1597036.1597050).
minimage_cell_from_ase⚠
Fill out from an ASE-style row-major 3x3 cell ([a, b, c]) in consistent length units. origin defaults to zero when NULL.
minimage_cell_from_con⚠
Fill out from a CON 3x3 lattice (rows a, b, c) with origin defaulting to zero.
minimage_cell_from_con_box⚠
Fill out from CON lengths (boxl in length units) and crystallographic angles (angles_deg [alpha, beta, gamma] in degrees). Origin defaults to zero.
minimage_cell_from_lammps
Fill out from LAMMPS dump-bound coordinates xlo xhi ylo yhi zlo zhi and tilt factors xy, xz, yz in consistent length units.
minimage_cell_from_lammps_bounds
Fill out from LAMMPS dump bound spans, tilts, and bound origins, all in consistent length units.
minimage_cell_from_vectors⚠
Fill out from lattice vectors a, b, c and origin, all in consistent length units.
minimage_cell_from_vesin⚠
Fill out from a vesin 3x3 box (rows a, b, c) with origin defaulting to zero.
minimage_displacement⚠
Engine minimum-image displacement from p to q (wrap(q - p)) into dr, in the cell’s length units.
minimage_displacement_euclidean⚠
Euclidean MIC displacement from p to q into dr, 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 p to q over the periodic axes of simbox into dr, in cell length units. Open axes take no image.
minimage_dist2⚠
Squared minimum-image distance from p to q into out, in the cell’s squared length units.
minimage_dist2_euclidean_many⚠
Euclidean nearest-image squared distances from p to n packed candidates: minimage_displacement_euclidean per pair, bit for bit, with one superbasis lookup per call and eight pairs per slicer pass.
minimage_dist2_euclidean_pairs⚠
minimage_dist2_euclidean_many for paired rows.
minimage_dist2_euclidean_pairs_warm⚠
minimage_dist2_euclidean_pairs for pairs that persist across frames. images is n rows of three int32_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_pbc into out, 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 p to n packed candidates in qs, in squared cell length units. When n == 0, returns 0 after validating simbox and p.
minimage_dist2_many_fixed⚠
Squared engine-wrap distances from fixed-point p to n packed fixed-point candidates.
minimage_dist2_many_fixed32⚠
Squared engine-wrap distances from 32-bit fixed-point p to n packed fixed-point candidates.
minimage_dist2_ortho_diffs⚠
Orthorhombic wrap of precomputed differences (Highway kernel).
minimage_dist2_pairs⚠
Squared MIC distances for n packed pairs (ps[k], qs[k]), in squared cell length units. When n == 0, returns 0 after validating simbox.
minimage_dist2_pairs_fixed⚠
Squared engine-wrap distances for n packed fixed-point pairs.
minimage_dist2_pairs_fixed32⚠
Squared engine-wrap distances for n packed 32-bit fixed-point pairs.
minimage_dist2_shifted_many⚠
Squared distances from p to n points in qs, plus one lattice shift (sx, sy, sz) on every candidate, in squared length units. Rapaport’s bin pair. When n == 0, returns 0 after validating p and shift.
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 n packed positions: three uint32_t per position, each the 64-bit fraction of minimage_fixed_many rounded to its top 32 bits.
minimage_fixed_many⚠
Fixed-point fractional coordinates of n packed positions: three uint64_t per position, each fraction as round(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 out from ASE-style rows, a periodicity mask and an origin. pbc holds three ints (0 open, nonzero periodic); origin defaults to zero when NULL. 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 matches minimage_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 n packed difference vectors (q - p) into out, in the cell’s length units. When n == 0, returns 0 without dereferencing diffs or out (after validating simbox).
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_pairs over a packed n * 2 buffer.
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.