UP | HOME

C ABI (minimage_*)

Function symbols use the minimage_ prefix. Every buffer is caller-owned. Coordinates, lattice vectors, and origins share one consistent length unit; minimage_cell_from_con_box takes angles in degrees. Displacements compute wrap(q - p).

Every int-returning function returns 0 on success and 1 on failure (null pointer, invalid cell, buffer/index mismatch, or overflow). Read minimage_last_error() on the same thread immediately after a nonzero return; do not free the returned pointer. The next successful minimage_* call on that thread clears the slot so minimage_last_error() returns NULL. minimage_version() returns a process-static string and neither reads nor modifies the error slot.

Symbol Role
mi_cell Lattice vectors a, b, c (columns of H) and origin
mi_cell_ortho Header-only diagonal box with zero origin
minimage_cell_from_vectors Columns a, b, c and origin
minimage_cell_from_lammps Dump-bound xlo xhi ylo yhi zlo zhi plus tilts
minimage_cell_from_lammps_bounds Dump bound spans, tilts, and bound lo
minimage_cell_from_ase Row-major 3x3 plus optional origin (NULL -> zero)
minimage_cell_from_con CON 3x3 (zero origin)
minimage_cell_from_con_box Lengths and angles in degrees (zero origin)
minimage_cell_from_vesin vesin 3x3 (zero origin)
minimage_displacement Engine wrapped q - p
minimage_displacement_euclidean Smith test, else the Selling slicer (exact Voronoi MIC)
minimage_wrap_many Engine wrap of n packed difference vectors
minimage_dist2 Squared minimum-image distance
minimage_dist2_many One source, n packed candidates
minimage_dist2_pairs n packed pair rows
minimage_dist2_euclidean_many Euclidean nearest image, one source, packed candidates
minimage_dist2_euclidean_pairs Euclidean nearest image, packed pair lists
minimage_dist2_euclidean_pairs_warm Euclidean pairs from previous frame's int32_t shifts
minimage_dist2_ortho_diffs Highway-shaped ortho wrap, AVX/NEON when present
minimage_dist2_shifted_many One lattice shift, many candidates
minimage_fixed_many Positions to 64-bit fixed-point fractions
minimage_dist2_fixed Squared distance between two 64-bit fixed-point positions
minimage_dist2_many_fixed One 64-bit fixed-point source, packed candidates
minimage_dist2_pairs_fixed Packed 64-bit fixed-point pair lists
minimage_fixed32_many, minimage_dist2_fixed32 32-bit fixed-point fractions and distance
minimage_dist2_many_fixed32, minimage_dist2_pairs_fixed32 32-bit fixed-point batches
mi_pbc_cell An mi_cell with three periodicity flags (pbc_a, pbc_b, pbc_c)
minimage_pbc_cell_from_ase Row-major 3x3, mask of three ints, optional origin (NULL -> zero)
minimage_displacement_euclidean_pbc Nearest image over the periodic axes only
minimage_dist2_euclidean_pbc Squared length of minimage_displacement_euclidean_pbc
minimage_filter_shifted Filter (ii, jj, shift) pairs below cut2; out_vector may be NULL
minimage_ring_centroid Bead-major ring-polymer centroids wrapped into primary cell
minimage_reduce_pairs Drop self images, sort and deduplicate (i, j) pairs
minimage_last_error Thread-local error string (NULL after success)
minimage_version Process-static version string

Function symbols use minimage_, the full crate name, to avoid mimalloc's mi_ namespace. The non-default capi-compat-names Cargo feature exports deprecated thin mi_ aliases for migration and must not be linked with mimalloc.

C++ (include/minimage.hpp)

Requires C++17 or later. Wraps minimage.h in namespace minimage and throws minimage::Error (with status() and what()) on failure.

Symbol Role
minimage::Error Exception carrying C ABI status() and what()
minimage::check Throws minimage::Error when a C ABI status is nonzero
minimage::Cell::ortho noexcept diagonal box (validated on first query)
minimage::Cell::from_vectors, from_lammps, from_lammps_bounds Column / LAMMPS dump-bound constructors
minimage::Cell::from_ase, from_con, from_con_box, from_vesin Row-major / crystallographic constructors
minimage::Cell::raw, operator mi_cell Convert back to C mi_cell
minimage::Cell::displacement, dist2 Single-pair engine MIC displacement and squared distance
minimage::Cell::displacement_euclidean Single-pair Euclidean nearest-image displacement
minimage::Cell::dist2_many, dist2_shifted_many Packed candidate batches (engine MIC and shifted)
minimage::Cell::dist2_euclidean_many, dist2_euclidean_pairs, dist2_euclidean_pairs_warm Batched and warm-started Euclidean nearest-image distances
minimage::dist2_ortho_diffs SoA orthorhombic batch wrap
minimage::reduce_pairs Sorted unique pairs with self images dropped

Rust

Full API docs build with cargo doc and are hosted at docs.rs/minimage. Fallible functions return Result<_, Error> with variants Error::BadBox, Error::BufferSize, and Error::Empty.

Item Role
Cell::ortho, ortho_origin, from_vectors, from_lammps, from_lammps_bounds, from_ase, from_con, from_con_box, from_vesin Periodic cell constructors
Cell::a, b, c, origin, widths, h, hinv, is_ortho, is_restricted, tilts_reduced Cell geometry and basis queries
Cell::fractional, cartesian, lattice_shift, displacement, dist2, dist2_shifted, dist2_shifted_many, dist2_shifted_indexed Engine wrap, coordinate conversion, and linked-cell shifts
Cell::displacement_cartesian, fractional_matches_cartesian, displacement_euclidean, dist2_euclidean 27-image check and exact Selling-superbasis Euclidean MIC
Cell::reduce_tilts, Cell::to_restricted Unimodular tilt reduction and restricted-frame rotation
minkowski_reduce, is_minkowski_reduced 3D Minkowski basis reduction and predicate
Cell::fixed, displacement_fixed, dist2_fixed, fixed32, displacement_fixed32, dist2_fixed32 64-bit and 32-bit fixed-point fractional wraps
wrap_many, dist2_many, dist2_pairs, dist2_ortho_diffs Batched engine MIC wraps and squared distances
dist2_euclidean_many, dist2_euclidean_pairs, dist2_euclidean_pairs_warm Batched and warm-started Euclidean nearest-image distances
fixed_many, dist2_many_fixed, dist2_pairs_fixed, fixed32_many, dist2_many_fixed32, dist2_pairs_fixed32 Batched fixed-point conversions and distances
PartialCell::from_ase, periodic_count, full, displacement_euclidean, dist2_euclidean Slabs (2D), wires (1D), open (0D), and full (3D) cells
filter_shifted, FilterOut, ring_centroid Verlet-skin candidate filter and ring-polymer bead centroids
reduce_pairs, reduce_pairs_packed, dump_bounds_to_h vesin pair deduplication and LAMMPS dump bound conversion
simd_path() Active SIMD path: scalar, avx, avx2, avx512, or neon
Error BadBox, BufferSize, Empty

A slab rounds its in-plane coordinates and tries the nine neighbouring images on a Lagrange-reduced basis of its two vectors; a wire rounds along its one. The component normal to the periodic vectors is kept. A half-box tie keeps the engine wrap s - floor(s + 1/2), as Cell::displacement_euclidean does. With all three axes periodic a PartialCell is a Cell and returns its displacement bit for bit.

MINIMAGE_SIMD overrides the SIMD path choice. An unknown name is ignored. A name this CPU cannot run selects scalar. The selection is cached. Details are on SIMD paths and dispatch.

Python

Exported module items: Cell, reduce_image_pairs, and __version__. Array arguments accept any host CPU DLPack producer, read in place when contiguous and aligned; array results return a NumPy array (or a list when NumPy is absent). Invalid inputs raise ValueError, TypeError, or BufferError.

Method / function Role
Cell.ortho, from_vectors, from_lammps_bounds, from_ase, from_con, from_vesin Construct a periodic cell
is_ortho, is_restricted, tilts_reduced, is_minkowski_reduced, fractional_matches_cartesian Basis predicates
reduce_tilts(), to_restricted() Return a tilt-reduced or restricted-frame Cell
dist2(p, q), displacement(p, q), wrap(diff) Single-pair engine wrap
displacement_euclidean(p, q), dist2_euclidean(p, q), displacement_cartesian(p, q) Single-pair Euclidean and 27-image MIC
dist2_many(p, qs), dist2_pairs(ps, qs), wrap_many(diffs) Batched engine MIC
dist2_euclidean_many(p, qs), dist2_euclidean_pairs(ps, qs) Batched Euclidean nearest image
dist2_euclidean_pairs_warm(ps, qs, images=None) Distances and updated int32 shifts across frames
fixed(r), fixed_many(rs), dist2_fixed(a, b), dist2_many_fixed(p, qs), dist2_pairs_fixed(ps, qs) 64-bit fixed-point (uint64)
fixed32(r), fixed32_many(rs), dist2_fixed32(a, b), dist2_many_fixed32(p, qs), dist2_pairs_fixed32(ps, qs) 32-bit fixed-point (uint32)
reduce_image_pairs(pairs) Drop self images, sort and deduplicate (i, j) pairs

Burn (minimage-burn)

Item Role
Lattice::new(cell, device, dtype) H and Hinv on a Burn device
Lattice::rows Packed rows to an (n, 3) tensor
Lattice::fractions Fold on the CPU in double precision, upload
Lattice::fractional Fold on the device
Lattice::wrap, dist2_pairs, dist2_many Cartesian rows
Lattice::displacement_fractional, dist2_pairs_fractional, dist2_many_fractional Fraction rows, exact wrap
rows_tensor, to_vec Convert row slices and read back rank-one f64 tensors