Cadence

Pragma Research · Documentation · Application demos · Paper · PyPI

One continuing equilibrium brain: learn a world, act in it, repair what fails.

Cadence is a Python library (NumPy, Python 3.11 or later) for brains that settle rather than compute a pass: a graph of rate neurons relaxes to an equilibrium under the observation, the action is read from that equilibrium, and every synapse learns from the difference between two settles, with no backward pass and no training/inference switch.

python -m pip install cadence-net==0.93.1

import numpy as np
from cadence import Brain

brain = Brain.compose(inputs=4, actions=2, arousal=True)
observation = np.array([[1.0, 0.0, 0.0, 0.0]])
action = brain.live(observation)

# A tiny environment rewards action 0 and supplies the next observation.
reward = (action == 0).astype(float)
next_observation = np.array([[0.0, 1.0, 0.0, 0.0]])
action = brain.live(next_observation, reward=reward)
assert action.shape == (1,)

By default Brain.compose builds one association region of 64 neurons between the senses and the motor choice, settling together with them; a working trace that carries the last interpretation into the next settle; and an associative store that keeps each situation's outcomes. Under live the brain learns while young (its first 100 moments) or aroused by surprise or want, and otherwise answers greedily from one settle; under step it learns from every outcome and from teacher= labels. Everything else is opt-in: System 2 observers, the episodic memory, the recall memory, a learned code, images.

The documentation index lists the rest: wide inputs, growing and grafting, evaluation, your own anatomy, how the brain settles, backends; the released documentation describes the APIs of the installed package. Integrated learned world prediction, repair localized to what failed and cheap stable operation are work in progress; Cadence is alpha research software.

Start with System 1

live takes the preceding action's measured reward, then chooses the next action for one continuing stream; supply one observation row per call. It needs arousal=True (the founder arousal settings). The working trace advances at every accepted moment; with the opt-in recall memory (recall=True) its slots advance at every accepted moment too. Tune named settings with compose or brain.retune(...) and inspect them with brain.describe() (tune and read). Continuous interaction covers arousal, resets and saved continuation.

For explicit teaching, batched streams or learning from every outcome, use the lower-level step loop, which works with or without arousal=True; its teacher= labels the current observation. The continuing brain example runs that loop through changed conditions and saved continuation.

A teacher label changes graph parameters. The default associative memory ignores labels. Add memory_choice=True when remembered demonstrations and outcomes should vote in the choice. Add learned_code=units, attention=True when the brain should retrieve a relevant recent context and its successor, and recall_heads=k when one answer needs several witnessed facts at once. The options can be used together. Memory starts with these common cases before giving the complete reference. A brain trained without one of them gets it later: brain.grow(recall=True), or new output slots with brain.grow(slots=...), returns a new brain, the trained one with the part added, settling as the trained one did until learning gives the part weight. brain.graft(donor, ...) puts trained regions of another brain into a larger one, such as a trained visual system, or a whole connectome as one region of a larger anatomy (grow and combine brains).

phases = brain.imagine([observation, next_observation])
assert phases  # Inspect phase.qualified before using an imagined response.

Imagination carries a private trace without changing live memory, random state or pending feedback; the composed brain builds no model of the world's consequences.

Each action solve reports its residual, qualification, sweeps and check counts in read-only brain.last_settlement, as start a continuing brain shows. An action whose settle exhausts its budget is refused without changing live state; qualification and refusal says when to retry live(observation) without resubmitting the reward.

To work from source, install the library repository root as an editable package:

python -m pip install -e .

Add optional System 2

recursive = Brain.compose(
    inputs=4, actions=2, modules=(16, 8), observers=(8,), seed=7,
    arousal=True,
)

Observer regions read and return influence to the base, motor regions and earlier observers. They join the same settlement and use the same interaction interface. Whether recursive feedback helps on a task is a question for experience and evaluation.

How a Cadence brain differs from a feed-forward network

Brain.compose(inputs=4, actions=2, modules=(64, 32, 16)) builds reciprocal regions whose activity settles together, so later regions shape earlier ones while an answer forms, and the action comes from the qualified neural state. The learner compares local activities in a free and a nudged phase, without a backward differentiation pass. The relevant comparison with a recurrent backprop network is acquired behavior and total work on the same task, as the comparison below sets out; other model families have their own learning contracts.

Why Cadence

The library puts continuing state, reciprocal interpretation, local plasticity and memory behind one small interface. A saved brain resumes an action that awaits its actual outcome, and private imagination inspects responses without rewriting live experience. These are mechanisms for testing acquisition, retention and recovery through a life. Biological names describe functional software roles; one continuing equilibrium brain states the design direction.

The target includes full-sentence language and reusable world understanding; a small fixed-label task is a control.

For machine-learning readers

This section maps Cadence onto models you know: which brain corresponds to which familiar model, where each one's learning signal comes from, what the arrays look like and what the words mean. The application interface is Brain.compose(..., arousal=True), then brain.live(observation, reward=...) for each real outcome (tune and read, start a continuing brain); the families below are the numerical mechanisms underneath and beside it.

The picture

A Cadence brain is a set of patches joined by ports. A patch holds a bounded local state (the potentials of a group of neurons, or one context vector), reads its inputs through ports and updates by its declared equations. Graph models qualify a settled state and learn from detuned phases. The contract guide separates these cases.

Against models you know

The composed brain's memories key on the observation, on the fixed sparse code code=units (the observation code), or, opt-in, on a code the brain learns while it lives (learned_code=units, the learned code), both described under Code in the glossary. evolve mutates and selects genomes across lives (evolution). The opt-in Brain.compose(..., learned_code=units, attention=True) recipe uses that learned code as a two-moment Recall address and holds one selected memory read through the shared settle; with recall_heads=k it reads the same memories through k heads, each learning its own address (several heads). No read revises its query during that settle (memory guide).

Where the learning signal comes from

• The settling brain uses no backward pass through time. The free settle is the answer. A second settle with the outputs nudged by beta toward the target and a third nudged away give every synapse the product of its two neurons in each phase; the difference over 2 beta is the update. On a smooth stable equilibrium with symmetric effective weights the contrast tends to the loss gradient as beta tends to zero (learning). At a finite beta it is an estimate with a beta^2 error term and a phase-solve term that grows as 1/beta; the default activation's kink at zero lies outside the smooth-branch argument. benchmarks/local_equilibrium compares the contrast learner with an implicit-gradient learner on the same network.
• Memory stores learn by one write of the error into the rows of the key, so two keys share records exactly as far as they overlap (one correction).
• Reward enters the settling brain as a broadcast prediction error gating every synapse's eligibility trace, a three-factor rule (reward).

Compared with a backprop network

The table compares update mechanisms. Networks trained by backprop can also be recurrent, online, model-based and memory-using, so a fair comparison measures acquired behaviour and total work on the same task and information.

Shapes

Batch rows are independent streams sharing parameters. imagine is private: it changes no learned parameter, record or live activity, though cost counters may count its work.

Glossary

• Patch. A bounded unit with local state, ports, readback and a repair rule: a group of neurons with their synapses.
• Port. A declared band of a patch's state that another patch, or the world, reads or drives: a population of a connectome.
• Settle, settling. Repeating local updates under fixed evidence. A settle qualifies when the component's declared equation or stationarity check passes; small movement or an exhausted iteration budget is insufficient.
• Equilibrium. A state satisfying the component's settlement contract under fixed boundary conditions. For the neural graph these include drive, parameters and held memory readback.
• Residual. A model-specific number, for the neural graph the equation error (contracts). A residual says nothing about task success.
• Certificate. The contraction bound that says settling has a unique equilibrium and how far the last step's movement leaves the state from it.
• Free phase, nudged phase, beta. The settle under the inputs alone; the settle with the outputs pulled toward (or away from) the target with strength beta (default 0.1), where smaller is closer to the gradient and weaker; the plus and minus beta phases are contrasted over 2 beta.
• Detuning, contrast. Perturbing an equilibrium and reading the difference between the perturbed and the free state; the learning signal of the settling brain.
• Code. The fixed random expansion of an observation onto expansion units, of which the winners strongest positive entries stay (code=units, PatternSeparator); the sparse key of a store. The learned code (learned_code=units, LearnedCode) is a region of the brain's own neurons that settles to a sparse code of the observation and learns it by local rules while the brain lives; the cortex reads it, and every memory keys on it joined to the observation's own identity.
• Readback. The detached state, residuals, counters and revision of a patch, as observations an application or another patch's port can read.
• Genome, develop, region, cortex, projection. The declaration of a settling brain's regions and projections; its deterministic layout into one connectome; a named population; a builder of a standard region; a declared bundle of synapses.
• Connectome. The synapse list of a settling brain (pre, post, count, sign) and its named populations.
• Efficacy, gain, log_gain, bias. The learned signed strength of a synapse; the neuron model's global gain (NeuronModel.gain); the per-neuron scale of a neuron's outgoing synapses, applied as exp(log_gain[pre]) and fixed by the learner; the learned per-neuron offset.
• Eligibility trace, dopamine. Per-synapse memory of recent contrasts; the broadcast prediction error, capped, that gates them.
• Receipt. A JSON file binding a result to the sources that produced it, with a digest and a verifier (receipts).

Reading the numbers

Measure settling, learning and memory maintenance separately on the same held-out data, and compare against the simple control the task admits: the majority outcome, persistence, a linear predictor, the search alone or the algorithmic solver. Evaluate a brain lists the checks and common missteps.

Further reading

• Learning rule: equilibrium propagation and its centered estimator.
• Memory stores: the cerebellar sparse expansion with a linear readout of Marr (1969) and Albus (1971); the delta-rule fast-weight memory; fast and slow complementary learning systems (McClelland et al., 1995) with their retention and interference tradeoffs.
• Reward: prediction errors (Schultz et al., 1997); eligibility-based online recurrent learning (Bellec et al., 2020), from whose e-prop Cadence's rule differs.
• Acquisition and language: word/referent learning across ambiguous situations (Smith and Yu, 2008); live interaction in infant phonetic learning (Kuhl et al., 2003); communication and thought as distinct (Fedorenko et al., 2024); speech-planning experiments on incremental formulation.

The paper states the hypotheses, the theorems and the evidence.

Go further

MANIFESTO.md states the design points, including the language goal of whole consistent sentences from the settled state. Your own anatomy covers custom wiring. cadence-demos contains the application demos.

Documentation · API · Contributing · Changelog · Research tasks

Licensed under GPL-3.0.