Mechanisms

Mechanisms#

A mechanism is anything you install on a cell that affects its dynamics: an ion channel, an ion species, a passive cable property, a current clamp, a synapse, or a probe. In braincell, mechanisms are purely declarative — they live in braincell.mech and describe what to install without touching JAX, time, or runtime state.

import braincell.mech as mech

Two families: density and point#

Every declaration inherits from the Mechanism marker base and falls into one of two families:

Family

Base class

Distributed how?

Density

Density

spread over a region of cable (a quantity per unit area). Painted.

Point

Point

attached at a single location. Placed.

This distinction drives the two verbs you use to decorate a cell:

   cell.paint(region,  density_mechanism)   # distribute over cable
   cell.place(locset,  point_mechanism)      # attach at points

The region and locset arguments are selection expressions from braincell.filter — see Regions & Locsets.

Density mechanisms (paint these)#

Declaration

Describes

Channel

an ion channel, distributed with a maximal conductance density g_max.

Ion

an ion species (its dynamics / reversal potential model).

CableProperty

passive cable: resting potential, membrane capacitance, axial resistivity, temperature.

Channel and Ion name the concrete implementation either by class or by string, then take its parameters as keywords:

import brainunit as u
import braincell.mech as mech

# by string name
mech.Channel("Na_Ba2002", g_max=0.12 * u.S / u.cm**2)

# passive cable
mech.CableProperty(
    resting_potential=-65. * u.mV,
    membrane_capacitance=1.0 * u.uF / u.cm**2,
    axial_resistivity=100. * u.ohm * u.cm,
)

The string names correspond to the concrete classes in braincell.channel and braincell.ion, which self-register at import time (see Ions & Channels).

Point mechanisms (place these)#

Declaration

Describes

CurrentClamp

injected current; CurrentClamp(delay=..., durations=duration, amplitudes=amp) for a step.

SineClamp / FunctionClamp

sinusoidal or arbitrary-function current injection.

Synapse

a synaptic point process.

Junction

a gap junction.

StateProbe / MechanismProbe / CurrentProbe

recording probes — what you place to read out a simulation.

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

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

# record membrane voltage there
cell.place(RootLocation(0.5), mech.StateProbe("V"))

Important

A multi-compartment run needs at least one placed probe — the probes define what Cell.run(...) returns. Without one you will get ValueError: Cell.run(...) requires at least one placed probe.

Why declarations are separate from the runtime#

Because a mechanism is plain, hashable data, braincell can:

  • deduplicate identical paints across regions (via Params, an order-insensitive frozen mapping);

  • inspect and diff a model before it runs;

  • compile the whole decorated cell into a single differentiable kernel.

This is the declaration layer of the Architecture.

See also#