UP | HOME

Embed from C

#include "minimage.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 (mi_dist2(&box, p, q, &d2) != 0) {
    fprintf(stderr, "%s\n", mi_last_error());
}

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});

The header is a RAII wrap of minimage.h. Failures throw minimage::Error.

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]))

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; move it to the host, or run the wrap on the device with minimage-burn.

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 and the four Meson wrap snippets.

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 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.