Cadence

Website · Documentation · Application demos · Paper · PyPI

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

from cadence import Brain

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

Execute the returned action, then pass its measured reward with the next observation: brain.live(next_observation, reward=reward). Tune named settings with compose or brain.retune(...); inspect them with brain.describe(). The composition guide explains the defaults and which learning rates each operation uses.

Cadence builds a simulated animal-like brain from simplified biological mechanisms. Its default System 1 is one continuing brain with perception, plastic connections, memory and action; optional System 2 adds observing cortical regions that feed back into the same neural graph. Biological names describe functional software roles.

One continuing equilibrium brain is the guide to this lifecycle and its boundaries. compose constructs the brain; live runs its life. Integrated learned world prediction, repair localized to what failed and cheap stable operation are work in progress. Cadence is alpha research software.

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, which the orientation page 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.

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

Start with System 1

Python 3.11+ and NumPy are required. Install the published release, whose released documentation describes the APIs in that package:

python -m pip install cadence-net==0.85.0

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,)

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). A calm brain acts greedily without learning; youth (the first 100 moments) or arousal enables exploration, learning and writes to the associative memory. There is no training/inference mode switch. The working trace advances at every accepted moment; with the opt-in recall memory (recall=True) its slots advance at every accepted moment too. 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; the opt-in episodic memory (memory_choice=True) records them. Memory lists every memory of the composed brain and which one suits which task.

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 the quickstart 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.

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 (composition guide, quickstart); 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).

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.