Embed from C
Every exported C function uses the minimage_ prefix. Functions return
0 on success and 1 on failure; on failure, call
minimage_last_error() on the same thread before any other
minimage_* call.
#include "minimage.h"
#include <stdio.h>
mi_cell box = mi_cell_ortho(10.0, 10.0, 10.0);
const double p[3] = {0.2, 0.0, 0.0};
const double q[3] = {9.4, 0.0, 0.0};
double d2 = 0.0;
if (minimage_dist2(&box, p, q, &d2) != 0) {
fprintf(stderr, "%s\n", minimage_last_error());
}
/* Triclinic cell and Euclidean nearest-image displacement. */
mi_cell hex;
if (minimage_cell_from_lammps_bounds(
15.0, 8.660254037844386, 10.0, 5.0, 0.0, 0.0, 0.0, 0.0, 0.0, &hex) != 0) {
fprintf(stderr, "%s\n", minimage_last_error());
}
const double origin[3] = {0.0, 0.0, 0.0};
const double diag[3] = {
0.49 * (hex.ax + hex.bx + hex.cx),
0.49 * (hex.ay + hex.by + hex.cy),
0.49 * (hex.az + hex.bz + hex.cz),
};
double dr[3] = {0.0, 0.0, 0.0};
if (minimage_displacement_euclidean(&hex, origin, diag, dr) != 0) {
fprintf(stderr, "%s\n", minimage_last_error());
}
For slabs or wires in C, build an mi_pbc_cell with
minimage_pbc_cell_from_ase and query
minimage_displacement_euclidean_pbc or minimage_dist2_euclidean_pbc.
Link libminimage and add include/ to the include path. Meson
exposes minimage_dep. CMake exposes minimage::minimage.
Embed from C++
#include "minimage.hpp"
const minimage::Cell box = minimage::Cell::ortho(10.0, 10.0, 10.0);
const double d2 = box.dist2({0.2, 0.0, 0.0}, {9.4, 0.0, 0.0});
const minimage::Cell hex = minimage::Cell::from_lammps_bounds(
15.0, 8.660254037844386, 10.0, 5.0, 0.0, 0.0, 0.0, 0.0, 0.0);
const std::array<double, 3> diag = {
0.49 * (hex.a[0] + hex.b[0] + hex.c[0]),
0.49 * (hex.a[1] + hex.b[1] + hex.c[1]),
0.49 * (hex.a[2] + hex.b[2] + hex.c[2]),
};
const auto dr = hex.displacement_euclidean({0.0, 0.0, 0.0}, diag);
The header is a RAII wrap of minimage.h. Failures throw
minimage::Error, whose status() carries the C ABI return code and
whose what() carries minimage_last_error(). Cell::ortho is
noexcept and does not validate lengths until a distance or
displacement method is called; the other constructors validate
immediately.
Embed from Python
import minimage cell = minimage.Cell.ortho(10.0, 10.0, 10.0) print(cell.dist2([0.2, 0.0, 0.0], [9.4, 0.0, 0.0])) rows = [[10.0, 0.0, 0.0], [5.0, 8.660254037844386, 0.0], [0.0, 0.0, 10.0]] hex_cell = minimage.Cell.from_ase(rows) diag = [0.49 * (rows[0][k] + rows[1][k] + rows[2][k]) for k in range(3)] dr = hex_cell.displacement_euclidean([0.0, 0.0, 0.0], diag) d2 = cell.dist2_pairs(ps, qs) # (n, 3) arrays in, numpy out f = cell.fixed_many(positions) # uint64 (n, 3) d2 = cell.dist2_pairs_fixed(f[i], f[j])
Array arguments go through DLPack: numpy, PyTorch, JAX, and CuPy host
arrays are read in place, and the result is a numpy array that owns
its buffer. A list in gives a list out. A device array raises
TypeError; move it to the host, or run the wrap on the device with
minimage-burn. Bad cells, shape mismatches, and wrong dtypes raise
ValueError, TypeError, or BufferError.
Run on a GPU with Burn
burn/ is the minimage-burn crate, outside the workspace because
Burn needs Rust 1.95. Enable the backend features you need (wgpu,
vulkan, metal, cuda, rocm, cpu, flex, fusion).
use burn_tensor::{DType, Device, DeviceKind};
use minimage_burn::{to_vec, Lattice};
let device = Device::wgpu(DeviceKind::DefaultDevice);
let lat = Lattice::new(&cell, &device, DType::F32);
let sp = lat.fractions(&cell, &ps);
let sq = lat.fractions(&cell, &qs);
let d2 = to_vec(lat.dist2_pairs_fractional(sp, sq));
fractions folds on the CPU in double precision and uploads; the wrap
on the device is then exact in single or half precision.
dist2_pairs, dist2_many, and wrap take Cartesian rows instead.
pkg-config
pkg-config --cflags --libs minimage
Meson and CMake both write minimage.pc. Libs includes -L${libdir}
so a wrap consumer can find -lminimage.
Cut a release
The version is written by hand in one place, [workspace.package].version in Cargo.toml.
Meson and CMake read it through scripts/crate_version.py, and maturin reads it from the crate.
scripts/sync-version.py rewrites the other copies.
Those are CITATION.cff, burn/Cargo.toml, Cargo.lock, the four Meson wrap snippets and the find_package(minimage X.Y) lines in README.md, docs/orgmode/getting-started.org, website/getting-started.html and tests/cmake-consumer/CMakeLists.txt.
Install cocogitto, which provides cog bump, and the two Python packages its hooks import.
cargo install cocogitto --locked python3 -m pip install cogapp towncrier
cogapp installs a cog command too.
When that one comes first on PATH, call cocogitto by its full path, for example ~/.cargo/bin/cog.
Bump from a clean checkout of the main branch, then push the commit and the tag.
cog bump --version 0.3.0 git push origin main v0.3.0
The pre_bump_hooks in cog.toml run in this order:
scripts/crate_version.py --set 0.3.0writes the version into[workspace.package].scripts/sync-version.py --releasesets[workspace.metadata.release].tagtov0.3.0and theCITATION.cffdate-releasedto today (UTC), then rewrites every copy.towncrier buildmoves the newsfragments intoCHANGELOG.md.scripts/check_version_lockstep.py --tag v0.3.0reads every copy back and checks the tag.
cog bump then makes the release commit and tags it v0.3.0.
A failed hook stops it before the commit.
The wrap tag rule
A wrap snippet can only name a tag that exists, since Meson fetches each wrap at a git tag.
The snippets sit in README.md, packaging/wrapdb/minimage.wrap, getting-started.org and its HTML page.
Each one names [workspace.metadata.release].tag, the newest pushed release tag.
Between releases, sync-version.py without --release leaves them on that tag while the version moves on.
Only the release commit moves the tag to v<version>, and the git tag goes on that commit.
The tag check
On a tag push, CI, the crates.io job and the wheels job run the tag check.
They pass the pushed tag name to scripts/check_version_lockstep.py --tag.
It fails unless the pushed tag is v<version> and equals the wrap tag.
So a tag on any other commit fails the check before anything is published.
The CI version job runs the sync on every push.
That job fails when git diff is not empty.