braincell 0.1.0

Biologically Detailed Brain Cell Modeling in JAX

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, and staggered cable solve, 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.Na_Ba2002(size, V_sh=-30 * u.mV))

        self.k = braincell.ion.PotassiumFixed(size, E=-90. * u.mV)
        self.k.add(IKL=braincell.channel.K_Leak(size, g_max=0.01 * (u.mS / u.cm ** 2)))
        self.k.add(IDR=braincell.channel.KDR_Ba2002(size, V_sh=-30. * u.mV, q10=2.0, temp=u.celsius2kelvin(16.)))

        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.CaL_IS2008(size, g_max=0.5 * (u.mS / u.cm ** 2)))
        self.ca.add(ICaT=braincell.channel.CaT_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.AHP_De1994(size, g_max=0.3 * (u.mS / u.cm ** 2)))

        self.Ih = braincell.channel.HCN_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 AllRegion, RootLocation, branch_in

# 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(AllRegion(), mech.CableProperty(
    resting_potential=-65.0 * u.mV,
    membrane_capacitance=1.0 * u.uF / u.cm**2,
    axial_resistivity=100.0 * u.ohm * u.cm,
))

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

# Inject current at the soma
cell.place(RootLocation(0.5), mech.CurrentClamp(delay=10 * u.ms, durations=50 * u.ms, amplitudes=0.2 * u.nA))

Morphology and visualization

import braincell
import braincell.vis as vis

# Load from NeuroMorpho.Org by neuron id (downloaded and cached locally)
morpho = braincell.Morphology.from_neuromorpho(12345)

# 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[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

Documentation

The official documentation is hosted on Read the Docs: https://brainx.chaobrain.com/braincell

See also the ecosystem

BrainCell is one part of our brain modeling ecosystem: https://brainx.chaobrain.com/