braincell.mech module

Declarative mechanism specs for braincell.Cell.

The braincell.mech package is purely declarative: it describes what to install on a cell without touching runtime state, JAX, or brainstate. Every declaration type inherits from the Mechanism marker base class.

• Density mechanisms — distributed over a region of a cell. See Density and its concrete subclasses Channel (for ion channels) and Ion (for ion species). Both accept a registry key string or a class object for their first positional argument.

• Point mechanisms — attached to a single location. See Point and its concrete subclasses CurrentClamp, SineClamp, FunctionClamp, StateProbe, MechanismProbe, CurrentProbe, ProbeMechanism, and Synapse. Junction is the gap-junction point declaration and lives in braincell.mech._junction.

Passive cable properties are recorded via CableProperty.

Class lookup by name is handled by MechanismRegistry (accessed through get_registry()). Concrete channel / ion / synapse classes register themselves with the global registry via the register_channel() / register_ion() / register_synapse() decorators, which run as a side effect of importing braincell.channel / braincell.ion / braincell.synapse.

See also

braincell.channel

Concrete ion-channel implementations.

braincell.ion

Concrete ion-species implementations.

braincell.synapse

Concrete synapse implementations.

braincell.mech is the purely declarative mechanism layer for braincell.Cell. It describes what to install on a cell without touching runtime state, JAX, or brainstate. Every declaration inherits from the Mechanism marker base class and splits into two families:

• Density mechanisms are distributed over a region of a cell (Density and its concrete subclasses Channel for ion channels and Ion for ion species).

• Point mechanisms are attached to a single location (Point and its subclasses, including Synapse, Junction, and the probe declarations).

The passive cable property and the stimulus clamps (CableProperty, CurrentClamp, SineClamp, FunctionClamp) are also declared here but are re-exported at the top level; see braincell module for their reference entries.

Base

Mechanism	Marker base class for every mechanism declaration.
Params	Frozen, hashable, order-preserving mechanism parameter mapping.

Density Mechanisms

Density	Base class for distributed mechanism declarations.
Channel	Distributed ion-channel declaration.
Ion	Distributed ion-species declaration.

Spatial Parameters

Cable-property fields and density-mechanism parameters may be callables that accept a CVContext. Cable-property callables are resolved during discretization; channel and ion callables are resolved once per active CV by Cell.init_state(). They are not called during every simulation step.

import brainunit as u
from braincell.filter import AllRegion
from braincell.mech import Channel

def na_gmax(context):
    distance = context.path_distance_from_soma.to_decimal(u.um)
    return (0.02 + 0.00008 * distance) * (u.mS / u.cm ** 2)

cell.paint(
    AllRegion(),
    Channel("Na_HH1952", name="na_distance", g_max=na_gmax),
)
cell.init_state()

path_distance_from_soma is zero for every soma CV and starts at zero at each first-order neurite attachment. path_distance_to_root retains the path through the root/soma branch. Callable results must be scalar and must use a consistent unit type across all selected CVs.

CVContext

Read-only geometry context for one control volume.

Point Mechanisms

Point	Marker base class for point-located mechanism declarations.
Junction	Gap-junction coupling declaration (placeholder).
Synapse	Registry-keyed synapse declaration.

Probes

StateProbe	Probe for cell-owned state at one placed location.
MechanismProbe	Probe for runtime state on a named mechanism.
CurrentProbe	Probe for current at a placed location.
ProbeMechanism	Observer that records a named variable at a point location.