Cadence

Machine learning by patch-net settlement.
Owner-local repair, no backward pass, held-out tests, receipts.

Docs · Quickstart · How it learns · Examples · Play the demos

A patch net is a set of owners, each holding one patch of state, joined by declared seams. Nothing is computed globally. Every owner repairs its own patch from what arrives over its seams, and the state the net comes to rest in is the answer. Learning is the same settlement run again with the outputs nudged: every seam moves on what its own two ends did. Cadence is the library for building, settling, training, testing, and certifying such nets, from a six-owner toy to a 161,827-owner nervous system read from a connectome.

import cadence as cd

wiring = cd.layered(64, 32, 10, density=1.0, seed=0)        # input, hidden, output owners
learner = cd.Learner(cd.Settlement(wiring, cd.learning_rule()), wiring.sets["output"],
                     cd.LearnerConfig(eta=3.0, beta=0.1, temperature=0.1))
for idx in batches:
    learner.step(drive[idx], labels[idx])                    # settle free, settle nudged, update locally
learner.accuracy(drive_test, labels_test)                    # 0.96 on the 8x8 digits

Why Cadence

• One rule for answering and learning. A settlement makes the prediction; a nudged settlement teaches. There is no forward pass, no backward pass, no controller that stores activations and transposes weights. The goal enters through the nudge and nowhere else.
• Every update is local and provably so. A seam reads two activations; an owner reads one. A reference engine settles the net one owner at a time with a message ledger, and conformance certifies that a fast backend computed nothing an owner could not see.
• It is a gradient. With symmetric seams the settlement descends an energy, and the local contrast is the loss gradient (equilibrium propagation). The tests check it against finite differences.
• Measured, not claimed. Every example selects on a validation split, reads its test set once, trains the obvious backprop baseline on the same split, and writes a receipt that binds every number to the code and data that produced it.
• Runs where you are. NumPy float64 with a fused kernel for receipts; torch on CUDA, MLX or torch on Apple silicon for scale, the settled state and the learning contrast staying on the device; a block transport for layered nets and a scatter for connectome-sized ones.

How it learns

1. Settle free. Clamp the inputs and let every owner repair its own patch until nothing moves. The output owners at rest are the answer; no target has entered.
2. Tilt, and settle again. Add a small drive on the output owners toward the target (+β) and, from the same rest state, away from it (−β). The net finds a new equilibrium each time, and the change reaches the hidden owners through the very seams the answer used.
3. Contrast. Each seam moves by η (s⁺ᵢ s⁺ⱼ − s⁻ᵢ s⁻ⱼ) / 2β, each bias by η_b (s⁺ᵢ − s⁻ᵢ) / 2β. For a small nudge that is minus the loss gradient.

Labels, a teacher's moves, and rewards all enter the same way: as the target of the nudge (and, for a reward, its weight). How it learns has every equation and a worked six-owner example with every number; differences sets it against a feed-forward network with backprop.

Install

pip install cadence-net            # NumPy only; the import is `cadence`
pip install "cadence-net[accel]"   # adds torch for CUDA and Apple silicon
pip install "cadence-net[apple]"   # adds MLX, the faster Apple silicon path
pip install "cadence-net[fast]"    # adds the fused CPU kernel (numba)

Python 3.11 or newer.

Sixty seconds

A wiring is n owners plus directed overlaps with a contact count and a sign. Build one from edge lists (a connectome), or let layered build a learnable one.

w = cd.Wiring.from_edges(3, pre=[0, 0, 1], post=[1, 2, 2], count=[80, 20, 80], sign=[1, 1, -1],
                         sets={"input": [0], "output": [2]})

A rule is what an owner does with its inbox. GradedRule is the connectome rule; learning_rule() is the one a net that learns needs; Adaptation adds rhythm.

engine = cd.Settlement(w, cd.GradedRule(gain=0.02), backend="torch")   # or "cpu"
state = engine.settle(w.members("input"), steps=100, trajectory=True)
state.activation, state.trajectory.shape

A protocol declares held-out facts with preconditions, and a shuffled control that keeps every count, sign, and set.

protocol = cd.Protocol(stimuli={"rest": (), "drive": ("input",)},
                       training=[("drive", "output", "active")],
                       rows=[cd.Row("R1", "rest", "output", "inactive", "nothing in, nothing out")])
protocol.score(engine)["passed"], protocol.score(cd.Settlement(cd.shuffled(w, 0), engine.rule))["passed"]

Certify and record.

cd.conformance(engine, w.members("input"))["max_abs_deviation"]           # ~1e-16 on cpu
receipt = cd.Receipt.build("my-lane/v1", {"score": protocol.score(engine)}, sources=[("lane.py", Path("lane.py"))])
receipt.write(Path("receipt.json")); cd.Receipt.verify(Path("receipt.json"), sources=[("lane.py", Path("lane.py"))])

The quickstart does all of this on a connectome, end to end.

Examples

Everything in cadence-examples is a tutorial, a script that trains something and measures the backprop baseline in the same run, a receipt, the trained net, and a page in which the net settles live. The hub links them all; How a patch net learns is the tutorial they build on.

Every rung has a page: draw a digit, write a memory and ask it, play Connect Four or Pong against the net. The earlier rungs (MNIST, Shakespeare, the sign writer, cart-pole, the chorale writer, the C. elegans connectome) are at tag v0.5.0 with their receipts, which the docs still cite where they measured something.

What is in the box

Documentation

Against backprop, plainly

Same shape, same count of numbers, same data: on the supervised rungs of the examples the rule reaches the accuracy of the backprop baseline in fewer passes over the data; from reward it learns less than REINFORCE with Adam from the same rollouts (Pong: 88% of balls against 93%). It costs ten to a hundred times the wall-clock on a laptop core, because a settlement is tens of steps where a pass is one. It gives no parameter advantage: a seam is a weight. Every receipt records all three numbers.

Discipline

1. Owner-local or nothing. The reference engine reads one owner and its inbox at a time and ledgers every delivery; conformance compares any backend against it.
2. Held out means held out. Selection on training data only; a test set read once; a control that must fail.
3. A result is a receipt. Canonical JSON, a digest, the digests of the code and data, every pass flag recomputable. A receipt that fails to verify is not a result.

Where it comes from

Cadence consolidates the lanes of the observer patch net programme: a C. elegans connectome scored against classical ablation phenotypes, the FlyWire Drosophila brain and the MANC nerve cord joined by their descending neurons and scored against held-out taste, grooming, escape, olfaction, and motor facts, and that nervous system driving a biomechanical fly in MuJoCo. Every one of those lanes is a wiring, a rule, a protocol, a control, and a receipt; the library is what they had in common. The learning rule is equilibrium propagation (Scellier and Bengio, 2017) written for the graded settlement, with a leak, tied seams, and a centered nudge.

Status

0.7.0: the core (wiring, rule, engine, reference, protocol, receipts, custody), the free/nudged learning rule with labels, teachers, and rewards, the three-factor learners, seams with a life, the block transport and the fused kernel, on NumPy, torch and MLX. Four worked rungs with receipts live in cadence-examples. On the roadmap: closure sub-nets for in-browser settlement of large wirings, environment adapters for embodiment, and connectome loaders. Issues and pull requests are welcome.

MIT licensed.