Cadence

Documentation · Quickstart · Examples · Interactive overview · Preprint · Pragma Research

Start with a small flat network. Add ordinary depth when the task needs it.

Cadence is an experimental learning library built from bounded patches with local state, input and output ports, retained relations and prediction-error readback. Connected patches settle together to answer; learning repairs their relations from experience. Recursive observers read other patches' live states and exact errors, feeding back into that same settlement. This is the observer-like, self-reading structure behind Cadence.

This README describes 0.60.0.dev1 on main. Flat and ordinary deep networks are the recommended starting points. Choose the smallest ordinary network that learns the task, and measure prediction quality and latency before scaling it. Depth can support a capable routine; arbitrary depth is not a speed guarantee.

Recursive observers are experimental. They participate in every synchronous solve and may slow every call, including familiar routine work. Their benefit over capable ordinary networks is unproven. Automatic on-demand attention and independent population clocks are not public features. See the experimental capability boundary.

Choose how the brain responds

All three use the same patch rule, learning methods and whole-brain qualification. These are choices of wiring, not three neuron classes or speed settings. A small flat layout is a useful fast baseline; actual latency depends on size, coupling, learning and the task. Ordinary layers already provide feedback through joint settlement; observers are not needed to enable it.

System 1 means learned routine competence; it can need several ordinary layers. System 2 names the intended useful recursive correction when routine competence fails. The complete cycle—cheap routine, useful correction, then retained cheap routine—has not been demonstrated. A coherent changing beat, a familiar game situation or walking a known path can all be routine. Equilibrium in this behavioral sense means sustained competence, not an unchanging output. Numerical settlement alone can still give a wrong answer about the world: compare forecasts with later observations and measure actual task outcomes.

Build the layout inside one Cortex. The application supplies observations, executes actions and reports outcomes through one brain/body interface; it does not attach an evaluator to every population. Start with the flat and ordinary deep quickstarts. Explicit observer wiring remains available in the experimental recipes.

Install the development version

Python 3.11 or later. The default engine needs only the standard library:

python -m pip install "cadence-net==0.60.0.dev1"
python -c "import cadence; print(cadence.__version__)"

For reproducible work, retain the installed package and its source with saved brains; see checkpoint requirements.

Optional PyTorch execution uses the same learning rule and final reference check. Install the gpu extra, then choose Cortex(device="cpu"), Cortex(device="mps") or Cortex(device="cuda"):

python -m pip install "cadence-net[gpu]==0.60.0.dev1"

Small brains can be faster on the default engine. Measure the complete workload; see devices, precision and batching.

Teach a small body model

This flat brain learns how a supplied one-dimensional simulator moves. It sees position and commanded velocity, then predicts the next position. Teaching, readiness checks and final probes use different inputs. Predictions come from the settled brain; the simulator supplies only measured teaching and test values.

from cadence import Brain, Cortex, bootstrap

# Supplied simulator: one quarter-second of movement.
def advance(position, velocity):
    return position + 0.25 * velocity


def measurements(positions, velocities):
    return [
        ({"body": [x, u]}, {"next_position": [advance(x, u)]})
        for x in positions for u in velocities
    ]


layout = Cortex(seed=2)
body = layout.input("body", shape=2)
response = layout.column("response", patches=1, inputs=body)
layout.output("next_position", shape=1, reads=response)
brain = layout.build()

report = bootstrap(
    brain,
    measurements((-0.5, 0.5), (-0.8, 0.8)),
    checks=measurements((-0.25, 0.25), (-0.4, 0.4)),
    max_error=0.06, epochs=30,
)
assert report["passed"], report

# Final free predictions: no answer is clamped or supplied as an input.
for position, velocity in ((0.35, -0.4), (-0.35, 0.4)):
    forecast = brain.predict({"body": [position, velocity]})["next_position"][0]
    assert abs(forecast - advance(position, velocity)) < 0.06

# Live operation: retain activity, execute, then learn the actual consequence.
inputs = {"body": [0.35, -0.4]}
activity = brain.step(inputs)
assert activity["accepted"]
measured = advance(0.35, -0.4)
assert brain.observe(inputs, {"next_position": [measured]})["accepted"]

saved = brain.snapshot()  # JSON text: state, learned relations and source identity
restored = Brain.from_snapshot(saved)
assert restored.predict(inputs) == brain.predict(inputs)

This learns a small forward model, not a navigation policy. The live-control example uses a learned model to compare candidate actions and move an actual simulated body toward a goal. Its action search is supplied application code. It does not demonstrate automatic attention or a benefit from recursion.

settle and predict query without changing the brain. step retains qualified activity. observe also learns from supplied output witnesses; observe_batch learns from several independent examples while preserving live activity. Check qualified or accepted; predict raises SettlementError on refusal. A teaching clamp matching its target is not evidence of learning—check later predictions without targets.

Run the current examples

From a checkout of this development version:

python -m pip install -e .
python examples/layout_learning.py --layout flat
python examples/layout_learning.py --layout deep
python examples/live_control.py --decisions 20 --seed 0
python examples/live_learning.py --seeds 0 2 7

All examples include batch learning, independent parallel brains, delayed reward and layout costs. History supplies explicit external memory; Reinforcement supplies discrete action-value learning and replay. Neither is an automatic planner or a guarantee of long-term success.

The public demos also include Amen, Atari, Patch World and Doom experiments. Their original engines and results have different versions and representations. They are historical application evidence, not completed reproductions on 0.60.0. In particular, the original Amen record-cell brain is not equivalent to one current flat patch. Consult the versioned performance evidence and current capability boundary before comparing them.

Learn more

Qualification means constrained numerical stationarity, not a unique global minimum or task success. Saved brains bind exact implementation sources; retain those sources and application preprocessing with checkpoints. Broader capability and comparative efficiency require measured task evidence.

Development

Changes follow minimalism, user-friendliness and agent-friendliness. See the contributor instructions.

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check src tests
python -m ruff format --check src tests

Tests execute the README and documentation examples and check learning, mathematical derivatives, refusal and checkpoint continuation. Licensed under GPL-3.0-or-later.