Skip to main content

Crate ferrotherm

Crate ferrotherm 

Source
Expand description

§ferrotherm — thermodynamic sampling for Physical AI

The IPAI @ BMI equivalent of the thermodynamic-computing software stack, in pure Rust: sparse energy-based models, chromatic block-Gibbs sampling, and — first-class, not an appendix — the device energy ledger that prices every sample, read, and write in joules.

The physics is old and open: Ising (1925), Glauber dynamics (1963), Gibbs sampling (Geman & Geman 1984), graph-colored parallel sweeps (standard checkerboard decomposition). What a “thermodynamic sampling unit” accelerates is exactly this loop; what it charges for is I/O. Both belong in the open commons, runnable on every compute fabric — CPU today, WebGPU next, physics-native silicon when it exists to measure.

Design positions, each earned from a verified source:

  • The ledger is first-class. Extropic’s Thermalizers appendix (arXiv:2608.01615, Table IV) prices a Z1-class node at 7.09 fJ per Gibbs cycle, 1.692 pJ per read, 153.6 pJ per write — a write costs ~21,700 samples. Any honest account of this hardware class is an I/O story, so every ferrotherm simulation carries a ledger::Ledger and reports what the device WOULD pay, crossings included.
  • Sparse and 2-colorable is the native shape. The published Z1 topology is a planar grid with odd-Manhattan couplings (degree 16, longest edge sqrt(17)), which is bipartite: one full sweep = two parallel half-sweeps. device::z1_grid reproduces it.
  • Verification against exact physics before any claim. The sampler must reproduce the exact Boltzmann distribution on enumerable systems and the Onsager magnetization on the 2D lattice before it is used for anything else. See examples/ring_tv.rs, examples/onsager.rs.

§Quickstart

use ferrotherm::{ising, gibbs::Sampler, ledger::{Ledger, Z1_SPICE}};

// a 16x16 Ising magnet below its critical temperature
let g = ising::lattice2d(16, 1.0);
let mut led = Ledger::default();
let mut smp = Sampler::new(&g, 0.6, 42);
smp.sweeps(500, Some(&mut led));

let m = (smp.s.iter().map(|&v| v as i64).sum::<i64>().abs() as f64) / g.n as f64;
assert!(m > 0.9, "ordered phase: |M| = {m}");
// What those sweeps WOULD cost on a Z1-class device. `joules` returns an Option because a
// device whose per-operation energy nobody has published has no answer here -- and borrowing
// another device's prices produces a figure indistinguishable from a measured one.
assert!(led.joules(&Z1_SPICE).unwrap() > 0.0);
assert_eq!(led.joules(&ferrotherm::ledger::Prices::UNSTATED), None);

§What “deterministic by seed” does and does not promise

Measured across three machines – macOS/arm64 (Apple M5 Max), Linux/x86_64 (AMD EPYC 9R14) and Linux/aarch64 (Graviton3), all on rustc 1.97.1 – running the identical program:

macOS arm64Linux x86_64Linux aarch64
compiled .ftp programidenticalidenticalidentical
CSR neighbour orderidenticalidenticalidentical
sampled stateidenticalidenticalidentical
exp() and the sigmoididenticalidenticalidentical
energy computed from that state..a7b3..a7b2..a7b2

The answer is bit-reproducible. The state a seed produces is the same on every platform tested, which is what the promise is for: a run can be repeated and a result checked.

A derived float may differ by one ULP across operating systems. The two Linux boxes agree with each other across DIFFERENT architectures, and macOS disagrees with Linux on the SAME architecture – so it is not architecture. It is not libm either: exp and the sigmoid were measured bit-identical on both. It is floating-point contraction, w * s_i * s_j accumulating through an fma on one target and a separate multiply and add on another, which round differently. Same values, same order, one bit apart.

So: compare states, hashes and programs with ==; compare energies with a tolerance. A test asserting bit-equality of a derived float across platforms asserts something this crate does not promise and could only deliver by disabling contraction everywhere, which costs more than the property is worth.

Scope note: binary (pbit) nodes with pairwise couplings are the sampling core. Categorical and continuous nodes arrive through the program layer (program) and the thermodynamic linear-algebra module (tla); the compiler (compile) targets device topologies.

Modules§

adaptive
Ladders that fix themselves — adaptive parallel tempering over beta, and over (beta, coupling).
bls
Breakout local search — the algorithm that holds the max-cut record on most of G-set.
bound
Lower bounds on the ground energy — how far from optimal a sampler’s answer might be.
branch
Branch and bound: the only thing here that returns a proof.
calibration
Are the error bars honest? A harness that asks, and the crate’s own answers.
categorical
Categorical variables as a workload: does the encoding choice actually pay?
certify
Proof that a sampler did what it claimed.
cluster
Cluster updates: Swendsen–Wang and Wolff, and the gauge that says when they apply.
compile
Variational compilation — fit a target conditional kernel P(y|x) with the conditional of a DEVICE-NATIVE Boltzmann machine: couplings restricted to the hardware graph’s actual edges, inputs clamped, hidden spins marginalized.
conform
A conformance suite any fabric can run.
continuous
Continuous units, and the exact answers that keep them honest.
dense
The [n, k] interaction layout the CPU, GPU and hardware emitters share.
dense_memory
Dense associative memory — the modern Hopfield network, and attention as its update.
device
Device topologies. The published Z1-class fabric is a planar grid with four coupling displacement rules — (1,0), (2,1), (2,3), (4,1), each applied in 4 rotations — giving interior degree 16 and longest edge sqrt(17) grid units. Every displacement has ODD Manhattan length, so the graph is bipartite under checkerboard parity: chromatic Gibbs needs exactly two half-sweeps per full sweep. (Topology per arXiv:2608.01615; exact die dimensions unpublished — the builder is parametric, and published totals like “269,568 pbits” are the vendor’s figures for silicon nobody outside has measured.)
dimacs
DIMACS CNF and WCNF: the MAX-SAT benchmark corpus, as an Ising model.
dtm
Denoising Thermodynamic Models — the flagship architecture of the thermodynamic-computing program (Jelincic et al., arXiv:2510.23972 / npj Unconventional Computing 2026): a chain of shallow Boltzmann machines, each denoising one step of a closed-form forward noising process. Capacity comes from the CHAIN, not any single EBM — each conditional stays easy to sample, which is the same capacity-through-factorization law our chain benches measured.
duty
What a machine costs when it is mostly WAITING.
ebm
Fitting an energy-based model to data — six methods, and the exact likelihood and the exact gradient to judge all six by.
embed
Minor embedding: put a program on a machine whose graph is not the program’s graph.
encode
How a discrete variable is spelled in spins.
eqprop
Equilibrium propagation for Boltzmann machines — learning from two nearby equilibria.
exact
Exact answers on sparse graphs, well past where enumeration stops.
fabric
What a fabric can do, declared — and checked before a program reaches it.
factor
Factors, and the mistakes a factor must not be able to express.
ffi
C ABI for WebAssembly and host-language bindings.
free_energy
Free energy — the number a sampler owes, with the bound it can prove.
ftp
The .ftp program format.
gibbs
Chromatic block-Gibbs sampling.
graph
Sparse pairwise energy-based model over binary spins, with graph coloring for parallel Gibbs.
gset
G-set: the standard max-cut benchmark, and the sign convention that decides everything.
hdl
The hardware backend: lower a sampling graph to a fixed-point p-bit fabric and emit synthesizable Verilog for it — the same design for every deployment target in crate::targets, from an Alchitry board to an Alveo card to an AWS F2 instance.
het
Heterogeneous factor-graph Gibbs — the general engine the spin sampler is a special case of.
hfs
Hamze–de Freitas–Selby: solve a low-treewidth block exactly, over and over.
hopfield
The Hopfield model — statistical mechanics of learning, with its closed forms as oracles.
host
What the machine was doing while the clock ran.
hubo
Higher-order models, solved without reducing them to pairwise.
hybrid
What the part you did NOT accelerate does to the headline.
icm
Isoenergetic cluster moves, and parallel tempering built on them.
ising
Ising-model constructions and the exact results the sampler must reproduce before it is trusted with anything else: exact Boltzmann enumeration for small systems, and Onsager’s spontaneous magnetization for the 2D nearest-neighbor lattice (Onsager 1944 / Yang 1952): M(beta) = (1 - sinh(2 beta J)^-4)^(1/8) for beta > beta_c = ln(1+sqrt(2))/2 ~ 0.4407, M = 0 above.
kernel
The update. One implementation, every caller.
ledger
The device energy ledger — first-class, because on this hardware class the story IS the I/O.
linalg
Minimal dense linear algebra used by the compiler and the thermodynamic linear-algebra modules: a cyclic Jacobi eigensolver for symmetric matrices. std-only, deterministic.
lp
Read a problem written in LP format.
lrw
Lattice Random Walk SDE discretisation — the published algorithm behind Normal Computing’s CN101 “stochastic sampling with lattice random walk” (arXiv:2508.20883).
matching
Minimum-weight perfect matching on a general graph — Edmonds’ blossom algorithm.
meanfield
Mean-field, TAP and belief propagation — the fast approximations, and the one that is a bound.
model
Writing a model in the problem’s own words.
mppi
Sampling-based control: choosing an action by weighting sampled futures.
multispin
Multi-spin coding: 64 replicas in one machine word, updated with bitwise operations.
ommx
Export a ferrotherm program as an OMMX instance.
oracle
Things that find ground states, including one that must never work.
perceptron
The binary perceptron — Gardner’s storage problem, where the couplings are spins.
planar
Planar embedding — the rotation system every surface algorithm is written against.
planarcut
Exact max-cut on a planar graph, in polynomial time.
planted
Instances whose ground state is known because it was put there.
popanneal
Population annealing: a sequential Monte Carlo annealer that reports how much to believe it.
portfolio
A portfolio: several solvers under one budget, and the budget stated in one unit.
program
Stochastic differentiable programs — the program layer over the sampler.
receipt
A run’s answer, its cost, and its claims — as a file someone else can check.
reduce
Higher-order reduction: run a k-body model on pairwise hardware.
rng
Deterministic, seedable RNG (PCG-XSH-RR 64/32). std-only, wasm-clean, no external deps. Determinism is a feature: every published number must be reproducible from its seed.
samples
What a sampler returned: many states, and what may honestly be computed from them.
sbm
Simulated bifurcation — the Toshiba Ising-machine algorithm line (Goto et al.; ballistic bSB and discrete dSB per the 2021 Science Advances formulation), as portable deterministic Rust.
schedule
What changes while a program runs.
sdp
A certified SDP lower bound on the ground energy, in std-only Rust.
sparsify
COPY-gate sparsification: bound a model’s degree by splitting its heavy variables.
sqa
Simulated quantum annealing: path-integral Monte Carlo on the transverse-field Ising model.
tabu
Tabu search — the baseline every new max-cut heuristic is measured against.
targets
FPGA deployment-target database for the ferrotherm VM — from edge parts a classroom owns to the cloud instances a lab rents. Every number is labelled: [DS] datasheet fact, [EST] engineering estimate, [SWEEP] verified market/status research (Aug 2026). The capacity model (p-bits per LUT budget, flips/s at a colored-update clock) is an ESTIMATE until the calibration-anchor pass lands; the published-machine anchors below bound it from above.
tempering
Optimization-grade sampling: simulated annealing and parallel tempering.
tensor
General tensor networks: the contraction engine the exact solver already was, said out loud.
tla
Thermodynamic linear algebra — the continuous (pmode) side of the field.
wanglandau
Wang–Landau: estimate the density of states, and get every temperature from one run.
wgsl
The sweep, emitted as a WebGPU compute shader.
wire
The protobuf wire format, written against the specification rather than against examples.