BrainPy to BrainX

brainpy is the experimental precursor of brainx. It served as the prototype for the later ecosystem: the ideas first explored in brainpy — stateful dynamical systems, event-driven operators — were developed into the focused, production-level packages that make up brainx today.

The neural-mass modeling explored in brainpy evolved into the dedicated brainmass package. Its Hodgkin-Huxley cell models inspired the more comprehensive conductance-based models, ion-channel systems, and neuronal morphology support now provided by braincell. Its point-neuron modeling — the part brainpy was best at — became brainpy.state.

This page explains how the packages relate and whether your project should move. When you decide to move, the migration notes cover the mechanics: API mappings, a worked before/after example, and the cases that need care.

brainpy and brainpy.state

brainpy and brainpy.state are two different packages. They share an import root and little else: they are distributed separately on PyPI (brainpy and brainpy-state), and they are built on different state systems — brainpy on its own brainpy.math.Variable, brainpy.state on brainstate.

Most of the confusion around migration comes from this one fact. Both are installed by pip install -U BrainX and import cleanly into the same process, so a project can migrate one model at a time. The migration notes tabulate the differences.

Status and support

This page describes brainpy 2.x and the component versions pinned by the current brainx release; see the change log for the exact pins.

brainpy ships in the BrainX pin set and is in maintenance: it receives compatibility and bug fixes (for example the recent JAX 0.11 fix), and its analysis module is still unique in the ecosystem. New modeling features land in the brainx packages, not in brainpy.

Existing brainpy projects do not need to be rewritten. Migration pays off when a project needs unit-safe parameters, multicompartment cells, online learning, or long-term feature work.

Where each modeling scale now lives

Point-neuron networks → brainpy.state. This was brainpy’s main strength, and it is the scale that carried over most directly. Model names and projection patterns stay recognizable; the state system and the runner are what change.

Cells, ions, and morphology → braincell. Migrate rather than mix. The older ion and channel APIs in brainpy have known design limitations and its compartmental support is restricted to single-compartment models. braincell provides comprehensive conductance-based and Hodgkin-Huxley models together with morphologically structured, multicompartment cells.

Neural-mass and whole-brain models → brainmass. The brainpy rate models cover FitzHugh-Nagumo, Stuart-Landau, threshold-linear, and Wilson-Cowan dynamics. brainmass provides direct counterparts, plus models brainpy never had — Jansen-Rit, Epileptor, Hopf, Montbrió-Pazó-Roxin, Wong-Wang, Larter-Breakspear — and the infrastructure whole-brain work needs: explicit coupling schemes, structured noise processes, forward models for BOLD, EEG, and MEG signals, and parameter fitting against empirical data. Unlike the cellular case this is not a warning; the brainpy rate models still work, this scale is simply developed in brainmass now.

Why existing brainpy code still works

The current brainpy codebase was reconstructed on top of brainstate, brainevent, and braintools. This is not only a dependency relationship: many internal functions delegate to the production-level implementations, so the two share the same underlying code rather than maintaining parallel ports.

• brainpy.math.surrogate is an alias of braintools.surrogate, and the einops-style helpers in brainpy.math are re-exported from brainunit.math.

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

• brainpy.losses and brainpy.measure delegate to braintools.metric, and brainpy.initialize delegates to braintools.init.

• brainpy.inputs builds its current waveforms from braintools.input, and brainpy.visualization from braintools.visualize.

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

So a brainpy project keeps working and stays on the same foundations as the rest of the ecosystem. Two packages sit outside that arrangement: brainunit, whose quantities brainpy.math cannot consume, and braintrace, whose online-learning traces attach to brainstate modules only. Sharing foundations also does not mean models from both sides can be composed into one — see the migration notes for both limits in detail.

What brainpy still owns

brainpy.analysis — phase-plane analyzers, Bifurcation1D / Bifurcation2D, slow-fast decomposition — has no counterpart in brainx. This is the one capability for which brainpy remains the right tool, and the reason it stays in the pin set rather than being retired.

Should I migrate?

your situation	recommendation
Starting a new point-neuron project	brainpy.state
Maintaining a working brainpy project	stay; migrate when you need something below
Modeling ions, ion channels, or morphology	brainpy.state + braincell — migrate
Modeling neural-mass or whole-brain dynamics	brainmass
Wanting unit-safe parameters (brainunit)	migrate — brainpy.math cannot consume quantities
Wanting online learning (braintrace)	migrate — traces attach to brainstate modules only
Depending on brainpy.analysis	stay on brainpy for that part

In short

Treat brainpy as the experimental embryo that inspired the brainx ecosystem. It remains maintained and usable for established projects and for its unique analysis tools, while brainx is where new work belongs: brainpy.state for point-neuron networks, braincell for ions, channels, and morphology, and brainmass for neural-mass and whole-brain models.

Ready to move? Continue with the BrainPy migration notes.