Biologically Detailed Brain Cell Modeling in JAX

braincell provides a unified interface for biophysically detailed brain cell models — from single-compartment Hodgkin-Huxley neurons to fully morphological multi-compartment cells with realistic dendrites and axons. It is built on top of JAX and brainstate, offering highly parallelized, differentiable simulation of biologically realistic neural dynamics.

Features

• Single-compartment neurons — braincell.SingleCompartment with a rich library of ion channels (Na, K, Ca, HCN, K-Ca) and numerical integrators.
• Multi-compartment cells — braincell.Cell with declarative mechanism painting (cell.paint) and point-process placement (cell.place) onto morphological regions.
• Morphology system — braincell.morph: immutable Branch geometry, typed subclasses (Soma, Dendrite, Axon, BasalDendrite, ApicalDendrite), and the mutable Morphology tree.
• IO readers — SWC, ASC, and NeuroML2 file readers; a full NeuroMorpho.Org client with search, download, and local caching.
• Visualization — braincell.vis: 2D tree layouts (matplotlib) and 3D rendering (PyVista / Plotly), color-by-values, morphometry plots, and movie export.
• Integrator registry — braincell.quad: explicit (Euler, RK2/3/4), implicit, exponential-Euler, staggered cable solve, and diffrax-backed adaptive solvers, all selectable by name.
• Declarative mechanisms — braincell.mech: Channel, Ion, CableProperty, CurrentClamp, Synapse, Junction specs for the Cell frontend.
• CLI — braincell-neuromorpho command for searching and downloading from NeuroMorpho.Org.

Quick start

Single-compartment neuron

import braincell
import brainstate
import braintools
import brainunit as u

class HTC(braincell.SingleCompartment):
    def __init__(self, size, solver: str = 'ind_exp_euler'):
        super().__init__(size, V_initializer=braintools.init.Constant(-65. * u.mV), V_th=20. * u.mV, solver=solver)

        self.na = braincell.ion.SodiumFixed(size, E=50. * u.mV)
        self.na.add(INa=braincell.channel.INa_Ba2002(size, V_sh=-30 * u.mV))

        self.k = braincell.ion.PotassiumFixed(size, E=-90. * u.mV)
        self.k.add(IKL=braincell.channel.IK_Leak(size, g_max=0.01 * (u.mS / u.cm ** 2)))
        self.k.add(IDR=braincell.channel.IKDR_Ba2002(size, V_sh=-30. * u.mV, phi=0.25))

        self.ca = braincell.ion.CalciumDetailed(size, C_rest=5e-5 * u.mM, tau=10. * u.ms, d=0.5 * u.um)
        self.ca.add(ICaL=braincell.channel.ICaL_IS2008(size, g_max=0.5 * (u.mS / u.cm ** 2)))
        self.ca.add(ICaT=braincell.channel.ICaT_HM1992(size, g_max=2.1 * (u.mS / u.cm ** 2)))

        self.kca = braincell.MixIons(self.k, self.ca)
        self.kca.add(IAHP=braincell.channel.IAHP_De1994(size, g_max=0.3 * (u.mS / u.cm ** 2)))

        self.Ih = braincell.channel.Ih_HM1992(size, g_max=0.01 * (u.mS / u.cm ** 2), E=-43 * u.mV)
        self.IL = braincell.channel.IL(size, g_max=0.0075 * (u.mS / u.cm ** 2), E=-70 * u.mV)

Multi-compartment cell

Build a morphological neuron from an SWC file and paint ion channels onto it declaratively:

import braincell
import braincell.mech as mech
import brainunit as u
from braincell.filter import region

# Load morphology from SWC
morpho = braincell.Morphology.from_swc("path/to/neuron.swc")

# Declare and simulate a multi-compartment cell
cell = braincell.Cell(morpho)

# Paint passive cable properties everywhere
cell.paint(region.all(), mech.CableProperty(
    cm=1.0 * u.uF / u.cm**2,
    Ra=100.0 * u.ohm * u.cm,
    Vm=-65.0 * u.mV,
))

# Paint ion channels onto specific regions
cell.paint(region.all(),      mech.Channel("IL",  g_max=0.0003 * u.S / u.cm**2, E=-70 * u.mV))
cell.paint(region.soma(),     mech.Channel("INa_Ba2002", g_max=0.12 * u.S / u.cm**2))
cell.paint(region.dendrite(), mech.Channel("ICaL_IS2008", g_max=0.002 * u.S / u.cm**2))

# Inject current at the soma
cell.place(region.soma(), mech.CurrentClamp.step(0.2 * u.nA, duration=50 * u.ms, delay=10 * u.ms))

Morphology and visualization

import braincell
import braincell.vis as vis

# Load from NeuroMorpho.Org (cached locally)
morpho = braincell.load_neuromorpho("cnic_001")

# 2-D layout plot
vis.plot2d(morpho)

# 3-D rendering
vis.plot3d(morpho)

Installation

pip install braincell --upgrade

Optional dependency groups:

Extra	What it installs
braincell[vis]	matplotlib, pyvista, plotly (visualization backends)
braincell[io]	requests (NeuroMorpho.Org client)
braincell[quad]	diffrax (adaptive ODE solvers)
braincell[all]	all of the above
braincell[cpu]	jax[cpu]
braincell[cuda12]	jax[cuda12]

For example, to install with visualization and IO support:

pip install "braincell[vis,io]" --upgrade

Alternatively, install BrainX to get braincell together with the rest of the brain modeling ecosystem:

pip install BrainX -U

If you are a Windows user and need a WSL-based development setup with NEURON 8.2.6 and nrnivmodl, see develop_doc/windows_wsl_neuron_setup.md.

Documentation

The official documentation is hosted on Read the Docs: https://braincell.readthedocs.io

See also the ecosystem

BrainCell is one part of our brain modeling ecosystem: https://brainmodeling.readthedocs.io/