Cell#

class braincell.Cell(morpho, *, pop_size=1, cv_policy=None, V_th=Quantity(0, 'mV'), V_init=None, spk_fun=ReluGrad(alpha=0.3, width=1.0), solver='staggered', subsolver=None, substeps=None, cache_ion_total_current=True, ion_channel_update_order='family', membrane_linearizer='point', name=None)#

Multi-compartment cell with explicit declaration / initialization phases.

Parameters:
  • morpho (Morphology) – Morphology tree.

  • cv_policy (CVPolicy | None) – Control-volume splitting policy; defaults to CVPerBranch.

  • V_th (Quantity) – Spike-detection threshold (default 0. mV).

  • V_init (Array | ndarray | bool | number | bool | int | float | complex | Quantity | Callable | None) – Initial voltage. None means “use per-CV resting potential”.

  • spk_fun (Callable) – Surrogate-gradient spike function.

  • solver (str | Callable) – Integrator name (registry lookup) or callable step function.

  • subsolver (str | Callable | None) – Integrator for Markov channels and kinetic ions. Together with substeps=None, None selects "backward_euler".

  • substeps (int | None) – Number of subsolver steps per main cell step. Together with subsolver=None, None selects one step.

  • ion_channel_update_order (str) – Post-voltage ion/channel scheduling. "family" updates all ions before all channels; "integration" preserves the previous IndependentIntegration-grouped scheduling.

  • membrane_linearizer (str) – Compatibility selector for the membrane-current linearization strategy. Both values currently differentiate the assembled CV-space membrane derivative; painted density mechanisms already live on the CV axis, while sparse point contributions are gathered first.

  • name (str | None) – Cell name.

add_reduction(name, model)[source]#

Register one interchangeable reduced model under a Cell-local name.

bind_synapse_input(synapse, source, *, weight=1.0, transform=None)[source]#

Deprecated compatibility adapter for per-boundary event payloads.

Parameters:
  • synapse (str) – Synapse instance name, matching braincell.mech.Synapse(name=...) or its default instance name.

  • source (array-like or callable) – Presynaptic drive source. Callables are evaluated every step; this supports bindings such as lambda: pre_cell.spike.value.

  • weight (array-like, optional) – Multiplicative weight applied to source.

  • transform (callable, optional) – Optional mapping called as transform(source_value) before weighting, useful when the source shape does not directly broadcast to the target synapse shape.

Return type:

Cell

cache_ion_total_currents(V=None)[source]#

Cache ion source currents before voltage advances in staggered mode.

Return type:

None

property clamps: ClampView#

Return a view over all logical current-clamp instances.

clear_ion_total_current_cache()[source]#

Remove per-step ion source-current caches.

Return type:

None

compute_derivative()[source]#

Fill in the derivative of every state this neuron integrates.

Parameters:
  • *args – Positional arguments defined by the subclass.

  • **kwargs – Keyword arguments defined by the subclass.

Raises:

NotImplementedError – Always, in the base class. Subclasses must override.

property connections#

Return a unified view over all direct event-routing rows.

property cv_contexts: tuple[CVContext, ...]#

Return read-only spatial contexts in stable CV order.

Returns:

Geometry and path-distance metadata used to resolve callable cable and density parameters.

Return type:

tuple of CVContext

property cv_midpoints: LocsetMask#

Return one resolved continuous midpoint for every control volume.

discretize()[source]#

Atomically rebuild the declaration preview before initialization.

Creation, policy assignment, initialization and dirty preview reads call this method automatically. Existing selections expire on success. Runtime parameters never trigger rediscretization.

Returns:

This Cell with a refreshed discrete preview.

Return type:

Cell

Raises:

RuntimeError – If already initialized. Call reset() before editing declarations.

property event_outputs: EventOutputCollection#

Return named live event-output ports for this cell population.

get_placement_state(placement_id)[source]#

Return runtime state for one independent point placement.

get_point_placement(placement_id)[source]#

Return one static point placement by its stable id.

init_state(batch_size=None)[source]#

Lower the declaration into runtime state and allocate V / spike.

Raises:

RuntimeError – If the cell is already initialized. Call reset() first.

Return type:

None

mech_table()[source]#

Return the point-domain mechanism table for this cell.

Returns:

Rows are mechanism identities, columns are point ids.

Return type:

MechanismObjectTable

Raises:

RuntimeError – If init_state() has not been called.

property morphology: Morphology#

Return the declaration morphology (morpho compatibility alias).

property n_compartment: int#

Number of compartments per neuron.

Returns:

How many compartments – soma, dendrite, axon sections – each neuron in the group is divided into.

Return type:

int

Raises:

NotImplementedError – Always, in the base class. Subclasses must override.

property name: str | None#

Name of the model.

property network_owner#

Return the Network that owns execution of this cell, if any.

property outputs: Mapping[str, object]#

Return the selected model’s initialized raw outputs.

paint(region, *mechanisms)[source]#

Paint mechanisms onto region. Returns self for chaining.

Return type:

Cell

place(locset, *mechanisms)[source]#

Place point mechanisms at shared or per-cell locations.

Parameters:
  • locset (LocsetExpr | LocsetMask | LocsetBatch) – One shared locset, an aligned rectangular batch, or one possibly ragged locset per population member.

  • *mechanisms (Point) – Point-mechanism declarations placed independently at each row.

Returns:

This Cell for chaining.

Return type:

Cell

property point_placements#

Return point-mechanism placements in stable declaration order.

Returns:

Static placement records available before and after initialization.

Return type:

tuple of PointPlacement

property pop_size: tuple[int, ...]#

Neuron-population shape, that is size without the compartment axis.

Returns:

The population size in each dimension: (100, 50) is a 2-D population of 100 by 50 neurons.

Return type:

tuple of int

Raises:

NotImplementedError – Always, in the base class. Subclasses must override.

post_integral()[source]#

Run whatever must happen after each integration step.

Does nothing by default. Subclasses override it to publish spikes, clamp concentrations, or otherwise fix up state the solver wrote.

Parameters:
  • *args – Positional arguments defined by the subclass.

  • **kwargs – Keyword arguments defined by the subclass.

pre_integral()[source]#

Run whatever must happen before each integration step.

Parameters:
  • *args – Positional arguments defined by the subclass.

  • **kwargs – Keyword arguments defined by the subclass.

Raises:

NotImplementedError – Always, in the base class. Subclasses must override.

property recordings: Mapping[str, RecordingSpec]#

Return a read-only snapshot of Cell recording declarations.

property reductions: ReductionViewCollection#

Return all Cell-local registered reduction models.

reset()[source]#

Drop runtime and per-step state; return to DECLARING.

Raises:

RuntimeError – If the cell is not initialized.

Return type:

None

Notes

reset() is distinct from reset_state(). reset_state reseeds V / spike / current_time in place and stays in the INITIALIZED phase. reset() fully tears down the runtime and returns to DECLARING so paint / place can run again.

reset_state(batch_size=None)[source]#

Reseed V / spike / current_time without leaving INITIALIZED.

Distinct from reset(): reset_state is the in-phase brainstate lifecycle hook; reset tears down the runtime entirely and returns the cell to DECLARING.

Return type:

None

run(*, dt, duration)[source]#

Run the cell for duration at dt and return probe traces.

If init_state() has not been called yet, run calls it automatically. Once initialized the cell will not be re-initialized on subsequent run invocations.

runtime_objects(*args, **kwargs)[source]#

Return runtime graph objects from the inherited container API.

property subsolver#

Return the effective Markov/kinetic-ion integrator callable.

property subsolver_name: str#

Return the effective Markov/kinetic-ion integrator name.

property substeps: int#

Return the effective Markov/kinetic-ion substep count.

property synapses: SynapseView#

Return a view over all logical point-synapse instances.

update()[source]#

Advance the cell by one simulation step.

This method is the standalone cell-level step wrapper. It applies already-prepared synaptic events, advances continuous membrane and mechanism dynamics by one dt, computes the spike output, and prepares synaptic input for the next standalone step.

Returns:

Spike value produced by the transition from the previous membrane voltage to the updated membrane voltage.

Return type:

object

Notes

The standalone update order is:

  1. Apply prepared runtime synapse events.

  2. Advance voltage and mechanism dynamics through self.solver.

  3. Detect and store the current spike.

  4. Prepare discrete event payloads for the next step.

In network execution, delayed event delivery is scheduled outside the cell. Network.run(...) writes arrivals into runtime state buffers before calling the corresponding internal cell phases.

use_model(name='detailed')[source]#

Select the detailed model or one registered reduction for the next initialization.

Return type:

Cell

property varshape: tuple[int, ...]#

Get the shape of variables in the neuron group.

This property provides access to the geometry (shape) of the neuron population, which determines how variables and states are structured.

Returns:

A tuple representing the dimensional shape of the neuron group, matching the in_size parameter provided during initialization.

Return type:

tuple

See also

in_size

The input geometry specification for the neuron group