ferrotherm/lib.rs
1//! # ferrotherm — thermodynamic sampling for Physical AI
2//!
3//! The IPAI @ BMI equivalent of the thermodynamic-computing software stack, in pure Rust: sparse
4//! energy-based models, chromatic block-Gibbs sampling, and — first-class, not an appendix — the
5//! device energy ledger that prices every sample, read, and write in joules.
6//!
7//! The physics is old and open: Ising (1925), Glauber dynamics (1963), Gibbs sampling
8//! (Geman & Geman 1984), graph-colored parallel sweeps (standard checkerboard decomposition).
9//! What a "thermodynamic sampling unit" accelerates is exactly this loop; what it charges for is
10//! I/O. Both belong in the open commons, runnable on every compute fabric — CPU today, WebGPU next,
11//! physics-native silicon when it exists to measure.
12//!
13//! Design positions, each earned from a verified source:
14//! * **The ledger is first-class.** Extropic's Thermalizers appendix (arXiv:2608.01615, Table IV)
15//! prices a Z1-class node at 7.09 fJ per Gibbs cycle, 1.692 pJ per read, 153.6 pJ per write —
16//! a write costs ~21,700 samples. Any honest account of this hardware class is an I/O story,
17//! so every `ferrotherm` simulation carries a [`ledger::Ledger`] and reports what the device
18//! WOULD pay, crossings included.
19//! * **Sparse and 2-colorable is the native shape.** The published Z1 topology is a planar grid
20//! with odd-Manhattan couplings (degree 16, longest edge sqrt(17)), which is bipartite: one
21//! full sweep = two parallel half-sweeps. [`device::z1_grid`] reproduces it.
22//! * **Verification against exact physics before any claim.** The sampler must reproduce the
23//! exact Boltzmann distribution on enumerable systems and the Onsager magnetization on the 2D
24//! lattice before it is used for anything else. See `examples/ring_tv.rs`, `examples/onsager.rs`.
25//!
26//! ## Quickstart
27//!
28//! ```
29//! use ferrotherm::{ising, gibbs::Sampler, ledger::{Ledger, Z1_SPICE}};
30//!
31//! // a 16x16 Ising magnet below its critical temperature
32//! let g = ising::lattice2d(16, 1.0);
33//! let mut led = Ledger::default();
34//! let mut smp = Sampler::new(&g, 0.6, 42);
35//! smp.sweeps(500, Some(&mut led));
36//!
37//! let m = (smp.s.iter().map(|&v| v as i64).sum::<i64>().abs() as f64) / g.n as f64;
38//! assert!(m > 0.9, "ordered phase: |M| = {m}");
39//! // What those sweeps WOULD cost on a Z1-class device. `joules` returns an Option because a
40//! // device whose per-operation energy nobody has published has no answer here -- and borrowing
41//! // another device's prices produces a figure indistinguishable from a measured one.
42//! assert!(led.joules(&Z1_SPICE).unwrap() > 0.0);
43//! assert_eq!(led.joules(&ferrotherm::ledger::Prices::UNSTATED), None);
44//! ```
45//!
46//! # What "deterministic by seed" does and does not promise
47//!
48//! Measured across three machines -- macOS/arm64 (Apple M5 Max), `Linux/x86_64` (AMD EPYC 9R14) and
49//! Linux/aarch64 (Graviton3), all on rustc 1.97.1 -- running the identical program:
50//!
51//! | | macOS arm64 | Linux `x86_64` | Linux aarch64 |
52//! |---|---|---|---|
53//! | compiled `.ftp` program | identical | identical | identical |
54//! | CSR neighbour order | identical | identical | identical |
55//! | **sampled state** | identical | identical | identical |
56//! | `exp()` and the sigmoid | identical | identical | identical |
57//! | energy computed from that state | `..a7b3` | `..a7b2` | `..a7b2` |
58//!
59//! **The answer is bit-reproducible.** The state a seed produces is the same on every platform
60//! tested, which is what the promise is for: a run can be repeated and a result checked.
61//!
62//! **A derived float may differ by one ULP across operating systems.** The two Linux boxes agree
63//! with each other across DIFFERENT architectures, and macOS disagrees with Linux on the SAME
64//! architecture -- so it is not architecture. It is not libm either: `exp` and the sigmoid were
65//! measured bit-identical on both. It is floating-point contraction, `w * s_i * s_j` accumulating
66//! through an `fma` on one target and a separate multiply and add on another, which round
67//! differently. Same values, same order, one bit apart.
68//!
69//! So: compare states, hashes and programs with `==`; compare energies with a tolerance. A test
70//! asserting bit-equality of a derived float across platforms asserts something this crate does not
71//! promise and could only deliver by disabling contraction everywhere, which costs more than the
72//! property is worth.
73//!
74//! Scope note: binary (pbit) nodes with pairwise couplings are the sampling core. Categorical
75//! and continuous nodes arrive through the program layer ([`program`]) and the thermodynamic
76//! linear-algebra module ([`tla`]); the compiler ([`compile`]) targets device topologies.
77
78pub mod rng;
79pub mod ftp;
80pub mod graph;
81pub mod categorical;
82pub mod certify;
83pub mod calibration;
84pub mod continuous;
85pub mod free_energy;
86pub mod meanfield;
87pub mod hopfield;
88pub mod dense_memory;
89pub mod eqprop;
90pub mod perceptron;
91pub mod conform;
92pub mod dense;
93pub mod embed;
94pub mod encode;
95pub mod exact;
96pub mod tensor;
97pub mod fabric;
98pub mod factor;
99pub mod kernel;
100pub mod schedule;
101pub mod gibbs;
102pub mod samples;
103pub mod sparsify;
104pub mod ising;
105pub mod device;
106pub mod ledger;
107pub mod multispin;
108pub mod duty;
109pub mod hybrid;
110pub mod host;
111pub mod bound;
112pub mod branch;
113pub mod gset;
114pub mod dimacs;
115pub mod popanneal;
116pub mod portfolio;
117pub mod tabu;
118pub mod bls;
119pub mod icm;
120pub mod cluster;
121pub mod sqa;
122pub mod hfs;
123pub mod hubo;
124pub mod matching;
125pub mod planar;
126pub mod planarcut;
127pub mod sdp;
128pub mod lp;
129pub mod ommx;
130pub mod wire;
131pub mod model;
132pub mod mppi;
133pub mod oracle;
134pub mod planted;
135pub mod receipt;
136pub mod reduce;
137pub mod program;
138pub mod ebm;
139pub mod adaptive;
140pub mod compile;
141pub mod tempering;
142pub mod wanglandau;
143pub mod wgsl;
144pub mod tla;
145pub mod linalg;
146pub mod het;
147pub mod lrw;
148pub mod sbm;
149pub mod dtm;
150pub mod targets;
151pub mod hdl;
152pub mod ffi;
153
154/// The README's own code blocks, compiled by `cargo test`.
155///
156/// Its headline "Use it" snippet did not compile: `Ledger::joules` returns `Option<f64>` and the
157/// snippet formatted it with `{:.2e}`, which `Option` does not implement. That is the first thing
158/// anyone copies, and nothing was checking it -- a README is documentation the compiler can read,
159/// so it should.
160#[cfg(doctest)]
161#[doc = include_str!("../README.md")]
162struct ReadmeDoc;