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.

Shared foundations#

The current brainpy codebase is built on brainstate, brainevent, braintools, and brainunit. Many internal functions delegate to their implementations, so brainpy and these packages share the same code rather than maintaining parallel ports:

  • State handling, environment settings, and compiled transformations come from brainstate, through State, environ, and transform.

  • brainpy.math.sparse, brainpy.math.event, and brainpy.math.jitconn build brainevent structures such as CSR and the just-in-time connectivity types, then hand the computation over to them.

  • brainpy.math.surrogate is an alias of braintools.surrogate; brainpy.losses and brainpy.measure delegate to braintools.metric, brainpy.initialize to braintools.init, brainpy.inputs to braintools.input, and brainpy.visualization to braintools.visualize.

Using brainx packages internally is not the same as being compatible with the ecosystem. These modules borrow implementations, but their models still run on brainpy.math.Variable, so they do not gain unit safety, online learning, or composability with brainstate-based models. Only brainpy.state provides those.

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:

brainpy

brainpy.state

import

import brainpy as bp

import brainpy.state

state objects

brainpy.math.Variable

brainstate.State

module base class

brainpy.DynamicalSystem

brainstate.nn.Module

simulation loop

brainpy.DSRunner

brainstate.transform.for_loop

parameters

plain floats (ms, mV by convention)

brainunit quantities

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 brainpy project

keep it; see Should you port? above

Modeling large-scale point-neuron spiking neural networks

brainspike

Modeling ions, ion channels, or morphology

braincell

Modeling neural-mass or whole-brain dynamics

brainmass

Phase-plane or bifurcation analysis

brainpy.analysis