UP | HOME

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:

  1. scripts/crate_version.py --set 0.3.0 writes the version into [workspace.package].
  2. scripts/sync-version.py --release sets [workspace.metadata.release].tag to v0.3.0 and the CITATION.cff date-released to today (UTC), then rewrites every copy.
  3. towncrier build moves the newsfragments into CHANGELOG.md.
  4. scripts/check_version_lockstep.py --tag v0.3.0 reads 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.