brainmass documentation#
brainmass implements neural mass models with brainstate, enabling whole-brain modeling with differentiable programming and JAX.
Where other whole-brain toolkits run forward simulations and fit parameters with grid or evolutionary search, brainmass backpropagates through the ODE solve: it brings gradient-based fitting, high-dimensional parameter fields, GPU/TPU batching, and the ability to train neural-mass-style networks on tasks — all unit-safe and end-to-end from parameters to BOLD / EEG / MEG signals.
Features#
20+ neural mass models from phenomenological oscillators to physiological population models, covering EEG, MEG, and fMRI applications
Fit model parameters to empirical data using gradient-based (JAX) or gradient-free
(Nevergrad / SciPy) optimization through one Fitter
Built-in BOLD hemodynamics and EEG/MEG lead-field models for linking neural activity to neuroimaging signals
Automatic dimensional analysis with brainunit prevents unit errors in scientific
computing
How brainmass compares#
brainmass shares the neural-mass / whole-brain modeling space with The Virtual Brain (TVB) and neurolib. Its distinguishing design choice is a fully differentiable, JAX-native core. The table below is a deliberately conservative summary of capabilities at the time of writing; consult each project for its current state.
Capability |
brainmass |
The Virtual Brain |
neurolib |
|---|---|---|---|
Differentiable / gradient-based fitting (backprop through the solve) |
Yes |
No |
No |
JAX backend with GPU / TPU acceleration |
Yes |
No |
No |
In-package orchestration & fitting ( |
Yes |
Partial |
Partial |
Unit-safe quantities (dimensional analysis) |
Yes |
No |
No |
Next-generation / exact mean-field models (e.g. Montbrió-Pazó-Roxin, Coombes-Byrne) |
Yes |
Partial |
Partial |
In-package BOLD + EEG/MEG forward models |
Yes |
Yes |
Partial |
The deeper rationale lives in Why Differentiable?.
Installation#
pip install -U brainmass[cpu]
pip install -U brainmass[cuda12]
pip install -U brainmass[cuda13]
pip install -U brainmass[tpu]
See Installation for detailed instructions.
Choose your path#
brainmass serves three kinds of users. Pick the on-ramp that fits you — each is a signposted route through the documentation, detailed in Learning Paths.
New to neural mass models or brainmass. Install, run a first simulation, and build the mental model, then explore the model zoo.
Have empirical data (EEG / MEG / fMRI). Map models to signals, fit them to your data, analyze the results, and study the case studies.
Build and extend models. Custom couplings and objectives, performance, and differentiable / data-driven workflows.
Data-Driven Modeling#
The flagship of brainmass is data-driven modeling — constructing, fitting, and training neural-mass networks against data. The Data-Driven Modeling hub curates a guided path through the differentiable workflow, and its roadmap reserves homes for the growth areas (model discovery / system identification, a task-shaped trainer, and simulation-based inference).
BrainX Ecosystem#
brainmass is one part of our brain modeling ecosystem.