energy-based-ising

An energy-based learning substrate — an Ising / Boltzmann machine — tested on parity-3 along two co-equal axes:

1. Compute (representability): a hand-derived 2-local Ising Hamiltonian whose ground state encodes parity-3, found by simulated annealing / mean-field.
2. Learn (learnability): the couplings J set by a local, physics-native contrastive rule (ΔJᵢⱼ = η(⟨sᵢsⱼ⟩_data − ⟨sᵢsⱼ⟩_model)) using only the substrate's own sampled statistics — not an external CPU optimizer.

Part of the Physical Learning Substrates portfolio (project 03). The portfolio throughline: a learning substrate where the signal being processed is the same physical event that reshapes the processor. The audit question, asked of every weight change: who computes the update? An audit hook tags every update physics-local vs offline-gradient and asserts the headline learning run is 100 % physics-local.

Why this substrate

The ionic line of this research established that passive monotone networks obey a maximum principle, which forecloses parity (the readout is monotone in every input; parity flips on every bit). An energy-based substrate has no maximum principle: the answer lives in the ground state / fixed point, so it is non-monotone by construction and escapes that wall. Thermal noise drives the sampler (the p-bit / heat-bath sampler samples the Boltzmann distribution); whether that noise helps or taxes learnability is an empirical question this project pins down — see Status. Short answer: noise is both — a tax under the vanilla rule, removable by a gentle physics-local temperature anneal, and at the frustrated (low-capacity) edge a genuine resource (stochastic sampling reliably beats the deterministic mean-field learner) — though that resource is a low-k effect that does not grow with parity-k (decisive at parity-3, non-monotone and washing out by k=4–5).

Status

Fully implemented. All modules are complete, the test suite passes, and python experiment.py prints VERDICT=PASS: with mean-field (idealized full-equilibrium) statistics, the physics-native local rule learns parity-3 to 8/8, matching the offline baseline (8/8), with 100% physics-local weight updates. The compute demo anneals the hand-derived Hamiltonian to 8/8.

Honest caveat — the p-bit noise tax. With realistic finite-sample p-bit statistics (genuine noisy sampling, the same local rule), learning is slower and seed-dependent: ~3/5 seeds reach 8/8 in 300 epochs and more samples don't reliably fix the rest. So the substrate represents parity and can learn it, but learnability degrades under realistic measurement noise — noise is a tax here, not a resource. See the findings doc.

…but a gentle temperature anneal removes the tax (it was the hot schedule, not fundamental). A pre-registered six-arm study (20 seeds, AWS; schedule_study.py) first found that a learning-rate schedule, hot temperature annealing (T 2.0→0.8), persistent-chain CD, and 3× variance reduction all failed to close the gap (best 0.85), and the hot anneal made it worse — a pre-registered FUNDAMENTAL. A second pre-registered follow-up (gentle_temp_study.py) then tested one a-priori gentle schedule (T geometric 1.0→0.5, no hot start): all three gentle arms reach 20/20 seeds at 8/8 — verdict GAP-CLOSED — and ~2× faster when paired with the lr-schedule. So the p-bit tax was an artifact of the hot schedule, not fundamental: a well-chosen, physics-local temperature anneal makes the noisy finite-sample rule learn parity-3 reliably. Every one of the 220 trajectories stayed 100% physics-local (temperature is a global operating knob, not a CPU gradient). See the interventions findings doc (incl. its "Gentle-temperature follow-up").

…and at the frustrated edge, noise becomes a resource. A third pre-registered study (noise_resource_study.py; parity-k ladder, 12 seeds, AWS) asked the inverse question: is there a regime where the deterministic mean-field learner fails but the stochastic gentle-p-bit learner succeeds? At capacity-constrained parity-3 (H=3) — where a solution provably exists (exact-gradient ceiling solves 12/12) — mean-field learns on only 3/12 seeds while gentle-p-bit learns on 12/12, under the identical schedule. Pre-registered verdict: NOISE-HELPS — noise is the inverse of the tax here. (Honest scope: the higher-k rungs foreclosed even for the offline ceiling, so the signal is from the frustrated edge of parity-3, and the contrast is under the gentle schedule; details in the findings doc.)

…but the advantage does not grow with k — it's a low-k effect. A fourth pre-registered study (noise_scaling_study.py; 9-cell ladder k∈{3,4,5} × H∈{k,k+2,k+4}, 12 seeds, AWS) closed the prior arc's honest gap by giving the offline ceiling enough steps (3000·(k−2)) to be informative at every rung — so the high-k regime was, for the first time, genuinely tested. The frustrated-edge noise gaps are non-monotone: +0.30 at k=3, −0.06 at k=4 (mean-field wins), +0.09 at k=5. Pre-registered verdict: ADVANTAGE-FLAT — the noise advantage is real and decisive only at parity-3 (gentle-p-bit 12/12 at every H, mean-field 3–7/12) and does not scale with k. The "grows-with-k" hypothesis is falsified on this substrate; details and the graded-vs-strict caveats in the findings doc.

• Spec: docs/superpowers/specs/2026-06-18-energy-based-ising-design.md
• Plan: docs/superpowers/plans/2026-06-18-energy-based-ising.md
• Findings (noise tax): docs/superpowers/findings/2026-06-19-pbit-noise-tax-findings.md
• Findings (interventions → gentle anneal closes the gap): docs/superpowers/findings/2026-06-19-pbit-noise-tax-interventions-findings.md
• Spec (gentle-temp follow-up): docs/superpowers/specs/2026-06-19-gentle-temp-anneal-design.md
• Findings (noise as a resource → NOISE-HELPS): docs/superpowers/findings/2026-06-20-noise-as-resource-findings.md
• Spec (noise-as-resource ladder): docs/superpowers/specs/2026-06-20-noise-as-resource-design.md
• Findings (does the advantage grow with k? → ADVANTAGE-FLAT): docs/superpowers/findings/2026-06-21-noise-scaling-ladder-findings.md
• Spec (noise-advantage scaling ladder): docs/superpowers/specs/2026-06-21-noise-scaling-ladder-design.md

Layout

Module	Responsibility
ising.py	Energy model: Layout, energy, local_fields, learn masks, init
samplers.py	The sample seam: Metropolis / p-bit (heat-bath) MCMC, mean-field, simulated annealing
baselines.py	Exact enumeration: partition function, statistics, conditional gradient, offline (CPU) baseline
boltzmann_learning.py	The heart: the two-phase contrastive local update
tasks.py	Parity-3 data, output-spin readout, accuracy + two-sided separation/SNR metrics
compute_demo.py	Hand-derived parity Ising (half-adder gadgets), enumerate-verified ground state
audit.py	Provenance tagging — "who computes the update?" as a checkable fact
experiment.py	Driver: compute + learn + baseline → pre-registered verdict, table + JSON
pbit_study.py	p-bit learnability study: trajectories across seeds under realistic noisy sampling
schedules.py	Scalar T/η training schedules (constant / linear / cosine / geometric anneal)
persistent_cd.py	Persistent-chain CD: warm negative-phase chains across epochs (reuses the unchanged local update)
schedule_study.py	Six-arm interventions study + pre-registered classify_tax/classify_gentle verdicts (parallel fan-out)
gentle_temp_study.py	Gentle-temperature follow-up (5 arms) — the run that closes the p-bit gap (20/20)
noise_resource_study.py	Parity-k ladder (mean-field vs gentle-p-bit) — the run where noise becomes a resource
noise_scaling_study.py	Noise-advantage scaling ladder (9-cell, graded metric) — tests whether the advantage grows with k (→ ADVANTAGE-FLAT)
infra/	AWS spot/on-demand harness (ported); --gentle / --noise / --scaling run the three follow-up studies

Setup

pip install -r requirements.txt

Run

pytest                  # the full test suite (TDD; one test module per source module)
python compute_demo.py  # representability: anneal the hand-set Hamiltonian, read parity off the output spin
python experiment.py    # full experiment: learn the couplings, compare to baseline, print the verdict
python pbit_study.py    # p-bit noise-tax study: how reliably the noisy rule learns across seeds (~minutes)
python schedule_study.py --seeds 20 --epochs 300 --nproc 8   # six-arm interventions study (hot anneal → FUNDAMENTAL)
python gentle_temp_study.py --seeds 20 --epochs 300 --nproc 8 # gentle-temp follow-up → GAP-CLOSED (20/20)
python noise_resource_study.py --seeds 12 --epochs 300 --nproc 8 # parity-k ladder → NOISE-HELPS (MF 3/12 vs p-bit 12/12 @ k3 H3)
python noise_scaling_study.py --seeds 12 --epochs 600 --nproc 8 # scaling ladder → ADVANTAGE-FLAT (edge gaps +0.30/−0.06/+0.09 over k=3/4/5)

Pre-registered verdicts

Verdict	Condition
PASS	compute demo reads 8/8 and the local/sampled rule reaches 8/8 within tolerance of the offline baseline, 100 % physics-local
BOUNDARY	representable (compute 8/8) but the local rule fails where offline GD succeeds → representability without learnability
FORECLOSE	even offline / compute can't encode parity in this topology (unlikely) → indicts the substrate, not the rule
AMBIGUOUS	learns but misses the baseline, or accuracy unstable across seeds

Scientific conventions

Compute-first (no hardware until the simulation earns it); foreclosure is a valid, documented outcome; observation is kept separate from interpretation; and every learning result states explicitly whether the physics or a CPU optimizer produced the weight change.

References

• Ackley, Hinton, Sejnowski (1985) — Boltzmann machine learning rule.
• Hinton (2002) — contrastive divergence.
• Mohseni, McMahon, Byrnes, Nat. Rev. Phys. (2022) — Ising machines.
• Camsari, Faria, Sutton, Datta — p-bits / probabilistic computing.
• Scellier & Bengio (2017) — equilibrium propagation.

Parity-task idioms (parity3_data, separation, verdict) are ported with attribution from the self-assembly research line.