BrainPy in BrainX#
brainpy is one package in brainx. This page explains where it
sits among the other packages, which package fits which kind of model, and what an
existing brainpy project can and cannot combine with the rest of the ecosystem.
It describes brainpy 2.x and the component versions pinned by the current
brainx release; see the change log for the exact pins.
Background#
brainpy was initially developed in Professor Si Wu’s lab at Peking University.
It predates BrainX and served as the testbed for the ideas the ecosystem grew from.
brainpy and the rest of BrainX are now mainly maintained by
Chaoming Wang’s lab and the community.
2021: The BrainPy 1.0 approach was presented at ICONIP in A Just-In-Time Compilation Approach for Neural Dynamics Simulation.
2022–2023: The BrainPy 2.x framework appeared as a 2022 preprint and a peer-reviewed 2023 eLife article.
2025: The work expanded into the BrainX ecosystem.
Limitations#
Three boundaries separate the original brainpy API from the rest of the BrainX ecosystem:
1. No brainunit quantities in brainpy.math.
brainpy depends on
brainunit internally, but its array layer does not accept quantities:
>>> import brainpy.math as bm, brainunit as u
>>> bm.exp(10. * u.mV)
TypeError: exp requires ndarray or scalar arguments, got <class 'saiunit.Quantity'> at position 0.
Strip units at the boundary — (10. * u.mV).to_decimal(u.mV) — or move the model to
brainpy.state. End-to-end unit safety exists only on the brainstate side.
2. No online learning for brainpy models.
braintrace attaches
eligibility traces to operations inside brainstate modules. It cannot see a
brainpy.math.Variable graph.
3. No mixed model trees.
Modules built on brainpy.math.Variable and on
brainstate.State cannot be composed into one model. A brainpy.state module placed
inside a brainpy.DynSysGroup never gets its states initialized and fails at run time:
AttributeError: 'LIF' object has no attribute 'V'
The two can still live in the same script as separate models. The same applies to
braincell and brainmass models: usable alongside a brainpy
project, but not inside one brainpy model.
Should you port?#
Your existing brainpy projects do not need to be rewritten; they keep working on the same
foundations as the rest of the ecosystem. Porting a model to brainpy.state or another
brainstate-based package pays off when it needs unit-safe parameters, multicompartment
cells, neural-mass infrastructure, or online learning. Port whole models, not individual
layers, and keep a reduced brainpy model around if you still need brainpy.analysis.
brainpy.state for ecosystem compatibility#
Since BrainPy 2.7.0 the brainpy distribution ships two APIs built on different state
systems:
|
|
|
|---|---|---|
import |
|
|
state objects |
|
|
module base class |
|
|
simulation loop |
|
|
parameters |
plain floats (ms, mV by convention) |
|
brainpy.state was created to connect brainpy with the
brainx ecosystem. Its models are brainstate modules, the same
state runtime as the other modeling packages, so they work with the whole ecosystem: they
take brainunit quantities as parameters, they can be trained online with
braintrace, and they compose with braincell and
brainmass models. The rest of brainpy predates the ecosystem and keeps
its own state system.
Both APIs are installed by pip install -U BrainX and import cleanly into the same
process, so a project can move one model at a time. For a hands-on introduction, work
through the point-neuron network tutorial.
Choosing a package in BrainX#
your situation |
recommendation |
|---|---|
Maintaining a working |
keep it; see Should you port? above |
Modeling large-scale point-neuron spiking neural networks |
|
Modeling ions, ion channels, or morphology |
|
Modeling neural-mass or whole-brain dynamics |
|
Phase-plane or bifurcation analysis |
|