Core Concepts#
One differentiable substrate, two worlds#
brainpy.state exists to make a single argument: brain simulation and
brain-inspired computing are the same computation, expressed once. The neurons,
synapses, and projections you assemble to simulate a biophysical network are the
exact objects you train with gradients and scale with linear-memory online
learning. There is no second framework, no re-implementation, no translation layer
between the two worlds — one substrate carries both.
That substrate rests on a few deliberate design choices, and this spine explains each one in the order it builds on the last:
State. Functional JAX has no mutable variables, yet a spiking network is nothing but evolving state (membrane potentials, conductances, traces). Explicit
Stateobjects reconcile the two — and, crucially, make every variable visible to autodiff and compilation.Physical units. Voltages are in millivolts, time constants in milliseconds, conductances in nanosiemens. Carrying units through construction turns a whole class of modeling errors into exceptions raised before a simulation runs.
Model anatomy. Neurons and synapses share one
Dynamicscontract: initialize state, receive input,update()one step, exposeget_spike(). Understanding that contract is what lets projections wire populations together.AlignPre / AlignPost — the keystone. The same alignment of synaptic state to a neuron dimension that makes simulation memory-efficient is what makes gradient-based and online learning memory-efficient. This is the hinge of the whole framework, and the one chapter to read if you read only one.
Differentiability and online learning — the two halves of the bridge. Surrogate gradients make spikes trainable through backpropagation-through-time; neuron-aligned state then collapses real-time recurrent learning from cubic to linear memory, putting whole-brain-scale online training within reach.
The keystone, in one sentence
A naive simulator stores one synaptic variable per synapse — O(p · N_pre · N_post). AlignPre and AlignPost instead store one variable per neuron — O(N_pre) or O(N_post) — without approximation. That same reduction, reused on the backward pass, is what makes linear-memory online learning possible. Read AlignPre / AlignPost — the keystone.
Recommended reading order#
The pages are written to be read in sequence; each assumes the one before it.
Why functional JAX needs explicit State; init_all_states,
environ.context, and the transform primitives that drive a model
without a bare Python loop.
brainunit quantities, unit-safe construction, unit-aware initializers,
and the pitfalls they catch at construction time.
The Dynamics → Neuron / Synapse hierarchy, state variables,
update() / get_spike(), and how a neuron receives current — the
contract projections rely on.
The keystone. Three memory regimes, the four projection components, an exact (not approximate) reduction, and a decision table for choosing between the two alignments.
The simulator → trainable half of the bridge: surrogate gradients and
backpropagation-through-time via transform.
The trainable → scalable half: linear-memory RTRL enabled by
neuron-aligned state, and the braintrace engine.
Where to go next#
Once the concepts click, put them to work. The BrainPy-style Modeling tutorials and how-to guides apply this vocabulary to concrete modeling and training tasks, and the API Reference is the authoritative model lookup. Migrating from NEST? The NEST-Compatible Models hub links back up into this same spine.