Can be: - A single Constraint instance, - A single float value, - A tuple of two floats representing a range (lower, upper), - A list of floats representing a range (lower, upper).

This flexible type allows defining constraints either as explicit Constraint objects or as simple numeric bounds.

class arborize.constraints.ConstraintsDefinition(use_defaults=False)[source]¶

Bases: Definition[CableTypeConstraints, CablePropertyConstraints, IonConstraints, MechanismConstraints, SynapseConstraints]

A specialized Definition that supports parameter constraints for cable types, ions, mechanisms, and synapses.

This class wraps all components with Constraint instances, allowing ranges or tolerances to be applied to physiological parameters. Use define_constraints to create an instance from a dictionary and apply a global tolerance.

Example:

constraints = define_constraints(
    {
        "cable_types": {
            "dend": {
                "cable": {"Ra": (100, 200), "cm": 1.0},
                "ions": {
                    "na": {
                        "rev_pot": -65.0,
                        "int_con": (10.0, 15.0),
                        "ext_con": 150.0,
                    },
                },
                "mechanisms": {"hh": {"gnabar": (0.1, 0.3), "gl": 0.0003}},
            }
        }
    },
    tolerance=0.1,
)

Variables:

cable_type_class (type[CableTypeConstraints]) – The class used for representing constrained cable types.
cable_properties_class (type[CablePropertyConstraints]) – The class used for constrained cable properties (e.g., Ra, cm).
ion_class (type[IonConstraints]) – The class used for constrained ion properties.
mechanism_class (type[MechanismConstraints]) – The class used for constrained mechanism parameters.
synapse_class (type[SynapseConstraints]) – The class used for constrained synapse parameters.

Parameters:

tolerance (float or None) – Optional tolerance to apply to all parameter constraints (e.g., 0.1 = ±10%).

Returns:

A fully structured ConstraintsDefinition with all values wrapped in Constraint objects.

Return type:

ConstraintsDefinition

cable_properties_class[source]¶: alias of CablePropertyConstraints

cable_type_class[source]¶: alias of CableTypeConstraints

ion_class[source]¶: alias of IonConstraints

mechanism_class[source]¶: alias of MechanismConstraints

set_tolerance(tolerance=None)[source]¶

synapse_class[source]¶: alias of SynapseConstraints

class arborize.constraints.ConstraintsDefinitionDict[source]¶

Bases: TypedDict

cable_types: dict[str, CableTypeConstraintsDict]¶

synapse_types: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], dict[str, Constraint | float | tuple[float, float] | list[float]] | SynapseConstraintsDict]¶

class arborize.constraints.IonConstraints(rev_pot: arborize.constraints.Constraint = None, int_con: arborize.constraints.Constraint = None, ext_con: arborize.constraints.Constraint = None)[source]¶

Bases: Ion

Parameters:

rev_pot (Constraint)
int_con (Constraint)
ext_con (Constraint)

class arborize.constraints.IonConstraintsDict[source]¶

Bases: TypedDict

ext_con: Constraint | float | tuple[float, float] | list[float]¶

int_con: Constraint | float | tuple[float, float] | list[float]¶

rev_pot: Constraint | float | tuple[float, float] | list[float]¶

class arborize.constraints.MechanismConstraints(parameters: dict[str, Constraint | float | tuple[float, float] | list[float]])[source]¶

Bases: Mechanism

Parameters:: parameters (dict[str, Constraint])

parameters: dict[str, Constraint]¶

class arborize.constraints.SynapseConstraints(parameters, mech_id: str | tuple[str] | tuple[str, str] | tuple[str, str, str])[source]¶

Bases: Synapse, MechanismConstraints

Parameters:

parameters (dict[str, Constraint])
mech_id (tuple[str] | tuple[str, str] | tuple[str, str, str])

arborize.constraints.SynapseConstraintsDict = dict[str, arborize.constraints.Constraint | float | tuple[float, float] | list[float]] | arborize.constraints.SynapseConstraintsDict¶

Type definition for synapse constraints.

This can be either:

A dictionary mapping parameter names to ConstraintValues, or
A TypedDict with optional keys:
- mechanism: Identifier for the synapse mechanism (type
  MechId).
- parameters: Dictionary of parameter names to
  ConstraintValues.

This flexible type supports simple parameter dicts or more structured dicts including the synapse mechanism identifier.

arborize.constraints.define_constraints(constraints: ConstraintsDefinitionDict, tolerance=None, use_defaults=False) → ConstraintsDefinition[source]¶

Create a ConstraintsDefinition instance from a dictionary of constraints, applying an optional global tolerance and default values.

Parameters:

constraints (ConstraintsDefinitionDict) – Dictionary specifying constraint values structured as ConstraintsDefinitionDict.
tolerance (float or None) – Optional tolerance to apply to all parameter constraints (e.g., 0.1 means ±10%), defaults to None.
use_defaults (bool) – Whether to fill in missing constraint values with defaults, defaults to False.

Returns:

A fully constructed ConstraintsDefinition instance with all values wrapped in Constraint objects and tolerance applied.

Return type:

ConstraintsDefinition

arborize.definitions module¶

class arborize.definitions.CP¶

Type variable for cable properties.

alias of TypeVar(‘CP’, bound=CableProperties)

class arborize.definitions.CT¶

Type variable for cable types.

alias of TypeVar(‘CT’, bound=CableType)

class arborize.definitions.CableProperties(Ra: float = None, cm: float = None)[source]¶

Bases: Copy, Merge, Assert, Iterable

Parameters:

Ra (float)
cm (float)

Ra: float = None¶

cm: float = None¶: Axial resistivity in ohm/cm.

to_dict() → dict[source]¶

Return type:: dict

class arborize.definitions.CablePropertiesDict[source]¶

Bases: TypedDict

Ra: float¶

cm: float¶

class arborize.definitions.CableType(cable_property_class=<class 'arborize.definitions.CableProperties'>)[source]¶

Bases: object

add_ion(key: str, ion: Ion)[source]¶

Parameters:

key (str)
ion (Ion)

add_mech(mech_id: str | tuple[str] | tuple[str, str] | tuple[str, str, str], mech: Mechanism)[source]¶

Parameters:

mech_id (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
mech (Mechanism)

add_synapse(label: str | tuple[str] | tuple[str, str] | tuple[str, str, str], synapse: Synapse)[source]¶

Parameters:

label (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
synapse (Synapse)

classmethod anchor(defs: ~typing.Iterable[~arborize.definitions.CableType], synapses: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], ~arborize.definitions.Synapse] = None, use_defaults: bool = False, ion_class=<class 'arborize.definitions.Ion'>) → CableType[source]¶

Parameters:

defs (Iterable[CableType])
synapses (dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Synapse])
use_defaults (bool)

Return type:

CableType

assert_()[source]¶

cable: CableProperties¶

copy()[source]¶

classmethod default(ion_class=<class 'arborize.definitions.Ion'>)[source]¶

ions: dict[str, Ion]¶

mechs: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Mechanism]¶

merge(def_right: CableType)[source]¶

Parameters:: def_right (CableType)

set(param: Parameter)[source]¶

Parameters:: param (Parameter)

synapses: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Synapse]¶

to_dict()[source]¶

class arborize.definitions.CableTypeDict[source]¶

Bases: TypedDict

cable: CablePropertiesDict¶

ions: dict[str, IonDict]¶

mechanisms: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], dict[str, float]]¶

synapses: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], dict[str, float] | ExpandedSynapseDict]¶

class arborize.definitions.Definition(use_defaults=False)[source]¶

Bases: Generic[CT, CP, I, M, S], ABC

add_cable_type(label: str, def_: CT)[source]¶

Parameters:

label (str)
def_ (CT)

add_synapse_type(label: str | tuple[str] | tuple[str, str] | tuple[str, str, str], synapse: S)[source]¶

Parameters:

label (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
synapse (S)

abstract class property cable_properties_class: type[CP]¶

abstract class property cable_type_class: type[CT]¶

copy()[source]¶

get_cable_types() → dict[str, CT][source]¶

Return type:: dict[str, CT]

get_synapse_types() → dict[str, S][source]¶

Return type:: dict[str, S]

abstract class property ion_class: type[I]¶

abstract class property mechanism_class: type[M]¶

abstract class property synapse_class: type[S]¶

to_dict() → dict[source]¶

Return type:: dict

class arborize.definitions.ExpandedSynapseDict[source]¶

Bases: TypedDict

mechanism: str | tuple[str] | tuple[str, str] | tuple[str, str, str]¶

parameters: dict[str, float]¶

class arborize.definitions.I¶

Type variable for ions.

alias of TypeVar(‘I’, bound=Ion)

class arborize.definitions.Ion(rev_pot: float = None, int_con: float = None, ext_con: float = None)[source]¶

Bases: Copy, Merge, Assert, Iterable

Parameters:

rev_pot (float)
int_con (float)
ext_con (float)

ext_con: float = None¶

int_con: float = None¶

rev_pot: float = None¶

to_dict() → dict[source]¶

Return type:: dict

class arborize.definitions.IonDict[source]¶

Bases: TypedDict

ext_con: float¶

int_con: float¶

rev_pot: float¶

class arborize.definitions.M¶

Type variable for mechanisms.

alias of TypeVar(‘M’, bound=Mechanism)

class arborize.definitions.Mechanism(parameters: dict[str, float])[source]¶

Bases: object

Parameters:: parameters (dict[str, float])

copy()[source]¶

merge(other)[source]¶

to_dict()[source]¶

class arborize.definitions.ModelDefinition(use_defaults=False)[source]¶

Bases: Definition[CableType, CableProperties, Ion, Mechanism, Synapse]

cable_properties_class[source]¶: alias of CableProperties

cable_type_class[source]¶: alias of CableType

ion_class[source]¶: alias of Ion

mechanism_class[source]¶: alias of Mechanism

synapse_class[source]¶: alias of Synapse

class arborize.definitions.ModelDefinitionDict[source]¶

Bases: TypedDict

cable_types: dict[str, CableTypeDict]¶

synapse_types: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], dict[str, float] | ExpandedSynapseDict]¶

class arborize.definitions.S¶

Type variable for synapses.

alias of TypeVar(‘S’, bound=Synapse)

class arborize.definitions.Synapse(parameters, mech_id: str | tuple[str] | tuple[str, str] | tuple[str, str, str])[source]¶

Bases: Mechanism

Parameters:: mech_id (tuple[str] | tuple[str, str] | tuple[str, str, str])

copy()[source]¶

mech_id: tuple[str] | tuple[str, str] | tuple[str, str, str]¶

class arborize.definitions.default_ions_dict(ion_class, *args, **kwargs)[source]¶: Bases: dict

arborize.definitions.define_model(template: ModelDefinition, definition: ModelDefinitionDict, /, use_defaults: bool = False) → ModelDefinition[source]¶
arborize.definitions.define_model(definition: ModelDefinitionDict, /, use_defaults: bool = False) → ModelDefinition

arborize.definitions.is_mech_id(mech_id)[source]¶

class arborize.definitions.mechdict[source]¶: Bases: dict

Parameters:: mech_id (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
Return type:: tuple[str] | tuple[str, str] | tuple[str, str, str]

arborize.exceptions module¶

exception arborize.exceptions.ArborizeError(*args, **kwargs)¶

Bases: DetailedException

ArborizeError exception

exception arborize.exceptions.ArborizeWarning[source]¶: Bases: Warning

exception arborize.exceptions.ConstructionError(*args, **kwargs)¶

Bases: SchematicError

ConstructionError exception

exception arborize.exceptions.FrozenError(*args, **kwargs)¶

Bases: SchematicError

FrozenError exception

exception arborize.exceptions.ModelDefinitionError(*args, **kwargs)¶

Bases: ArborizeError

ModelDefinitionError exception

exception arborize.exceptions.ModelError(*args, **kwargs)¶

Bases: ArborizeError

ModelError exception

exception arborize.exceptions.SchematicError(*args, **kwargs)¶

Bases: ArborizeError

SchematicError exception

exception arborize.exceptions.TransmitterError(*args, **kwargs)¶

Bases: ModelError

TransmitterError exception

exception arborize.exceptions.UnconnectedPointInSpaceWarning[source]¶: Bases: ArborizeWarning

exception arborize.exceptions.UnknownLocationError(*args, **kwargs)¶

Bases: ModelError

UnknownLocationError exception

exception arborize.exceptions.UnknownSynapseError(*args, **kwargs)¶

Bases: ModelError

UnknownSynapseError exception

arborize.parameter module¶

class arborize.parameter.CableParameter(prop: str, value: float)[source]¶

Bases: Parameter

Parameters:

prop (str)
value (float)

set_cable_params(cable)[source]¶

class arborize.parameter.IonParameter(ion: str, prop: str, value: float)[source]¶

Bases: Parameter

Parameters:

ion (str)
prop (str)
value (float)

class arborize.parameter.MechParameter[source]¶: Bases: Parameter

class arborize.parameter.Parameter[source]¶: Bases: object

arborize.schematic module¶

class arborize.schematic.Branch[source]¶

Bases: object

children: list[Branch]¶

parent: Branch | None¶

points: list[Point]¶

class arborize.schematic.CableBranch[source]¶

Bases: Branch

append(loc, coords, radius, labels)[source]¶

children: list[CableBranch]¶

parent: CableBranch | None¶

class arborize.schematic.Point(loc, branch: UnitBranch, coords, radius)[source]¶

Bases: object

Parameters:: branch (UnitBranch)

class arborize.schematic.Schematic(name=None)[source]¶

Bases: object

A schematic is an intermediate object that associates parameter definitions to points in space. You can define locations (3d coords + radius) and tag them with labels, or set parameters directly on the locations. You can pass a schematic to a Builder, which will freeze the schematic (no changes can be made anymore) and create a simulator specific instance of the model.

Schematics create a user-facing layer of “virtual branches”, which is the network graph of the created locations. However, NEURON does not support the resolution that arbor does, so an underlying layer of “true branches” is created. In NEURON, a map is kept on the model between the locations on the virtual branches and the locations on the true branches, so that we can arbitrarily split up true branches into smaller pieces to achieve the resolution we need.

create_empty()[source]¶: Create an empty branch.

create_location(location: tuple[int, int], coords: tuple[float, float, float], radius: float, labels: list[str], endpoint: tuple[int, int] | None = None)[source]¶

Add a new location to the schematic. A location is a tuple of the branch id and point-on-branch id. Locations must be appended in ascending order.

Parameters:

location (tuple[int, int]) – The location tuple with branch id and point id.
coords (tuple[float, float, float]) – The 3 coordinates of the point.
radius (float) – The radius of the branch at the point.
labels (list[str]) – The list of labels for the point.
endpoint (tuple[int, int] | None) – Optional endpoint of the previous branch to connect the location to.

Returns:

create_name()[source]¶: Generate the next unique name for an instance of this model.

property definition¶: Definition of the model, contains the definition of the parameters for the cables, mechanisms, and synapses of this model.

freeze()[source]¶

Freeze the schematic.

Most mutating operations will no longer be permitted.

get_cable_types()[source]¶

get_compound_cable_types()[source]¶

get_synapse_types()[source]¶

property name¶

Base name for all the instances of this model.

Suffixed unique names for each instance can be obtained by calling create_name.

set_next_id(id: int)[source]¶

Parameters:: id (int)

set_param(location: tuple[int, int] | tuple[tuple[int, int], tuple[int, int]] | str, param: Parameter)[source]¶

Parameters:

location (tuple[int, int] | tuple[tuple[int, int], tuple[int, int]] | str)
param (Parameter)

class arborize.schematic.UnitBranch[source]¶

Bases: Branch

append(point)[source]¶

children: list[UnitBranch]¶

definition: CableType¶

labels: list[str]¶

parent: UnitBranch | None¶

arborize.schematic.throw_frozen()[source]¶

arborize.synapse module¶

class arborize.synapse.Synapse(cell, section, point_process_name, attributes=None, variant=None, type=None, source=None)[source]¶

Bases: object

presynaptic(section, x=0.5, **kwargs)[source]¶

record()[source]¶

stimulate(*args, **kwargs)[source]¶

arborize._util module¶

class arborize._util.Assert[source]¶

Bases: object

assert_()[source]¶

class arborize._util.Copy[source]¶

Bases: object

copy()[source]¶

class arborize._util.Iterable[source]¶

Bases: object

arborize._util.MechId = str | tuple[str] | tuple[str, str] | tuple[str, str, str]¶

Type alias for mechanism identifiers.

Can be either: - A simple string identifier, e.g., “hh” - A MechIdTuple with 1 to 3 strings for hierarchical naming.

This type supports flexible representation of mechanism IDs.

arborize._util.MechIdTuple = tuple[str] | tuple[str, str] | tuple[str, str, str]¶

Type alias for mechanism identifiers represented as tuples.

Can be a tuple with 1 to 3 strings, e.g.: - (“hh”,) - (“mod”, “hh”) - (“region”, “mod”, “hh”)

This allows hierarchical or detailed identification of mechanisms.

class arborize._util.Merge[source]¶

Bases: object

merge(other)[source]¶

arborize._util.get_arclengths(pts: Iterable[Point]) → ndarray[Any, dtype[float64]][source]¶

Compute normalized cumulative arclengths from a sequence of points.

Parameters:: pts (Iterable[Point]) – Iterable of Point objects with a coords attribute representing coordinates.
Returns:: Normalized cumulative arclengths as a NumPy array.
Return type:: numpy.ndarray

arborize._util.get_location_name(pts: Iterable[Point]) → str[source]¶

Parameters:: pts (Iterable[Point])
Return type:: str

arborize._util.is_empty_constraint(value)[source]¶

Module contents¶

Write descriptions for NEURON cell models in an Arbor-like manner for both the Arbor and NEURON brain simulation engines.

class arborize.CableProperties(Ra: float = None, cm: float = None)[source]¶

Bases: Copy, Merge, Assert, Iterable

Parameters:

Ra (float)
cm (float)

Ra: float = None¶

cm: float = None¶: Axial resistivity in ohm/cm.

to_dict() → dict[source]¶

Return type:: dict

class arborize.CableType(cable_property_class=<class 'arborize.definitions.CableProperties'>)[source]¶

Bases: object

add_ion(key: str, ion: Ion)[source]¶

Parameters:

key (str)
ion (Ion)

add_mech(mech_id: str | tuple[str] | tuple[str, str] | tuple[str, str, str], mech: Mechanism)[source]¶

Parameters:

mech_id (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
mech (Mechanism)

add_synapse(label: str | tuple[str] | tuple[str, str] | tuple[str, str, str], synapse: Synapse)[source]¶

Parameters:

label (str | tuple[str] | tuple[str, str] | tuple[str, str, str])
synapse (Synapse)

Parameters:

defs (Iterable[CableType])
synapses (dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Synapse])
use_defaults (bool)

Return type:

CableType

assert_()[source]¶

cable: CableProperties¶

copy()[source]¶

classmethod default(ion_class=<class 'arborize.definitions.Ion'>)[source]¶

ions: dict[str, Ion]¶

mechs: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Mechanism]¶

merge(def_right: CableType)[source]¶

Parameters:: def_right (CableType)

set(param: Parameter)[source]¶

Parameters:: param (Parameter)

synapses: dict[str | tuple[str] | tuple[str, str] | tuple[str, str, str], Synapse]¶

to_dict()[source]¶

class arborize.Ion(rev_pot: float = None, int_con: float = None, ext_con: float = None)[source]¶

Bases: Copy, Merge, Assert, Iterable

Parameters:

rev_pot (float)
int_con (float)
ext_con (float)

ext_con: float = None¶

int_con: float = None¶

rev_pot: float = None¶

to_dict() → dict[source]¶

Return type:: dict

class arborize.Mechanism(parameters: dict[str, float])[source]¶

Bases: object

Parameters:: parameters (dict[str, float])

copy()[source]¶

merge(other)[source]¶

to_dict()[source]¶

class arborize.ModelDefinition(use_defaults=False)[source]¶

Bases: Definition[CableType, CableProperties, Ion, Mechanism, Synapse]

cable_properties_class[source]¶: alias of CableProperties

cable_type_class[source]¶: alias of CableType

ion_class[source]¶: alias of Ion

mechanism_class[source]¶: alias of Mechanism

synapse_class[source]¶: alias of Synapse

arborize.arbor_build(schematic: Schematic)[source]¶

Parameters:: schematic (Schematic)

arborize.bluepyopt_build(schematic: Schematic)[source]¶

Parameters:: schematic (Schematic)

arborize.bsb_schematic(morphology: bsb.morphologies.Morphology, definitions: Definition | None = None) → Schematic[source]¶

Generate a schematic from a bsb.Morphology object.

Parameters:

morphology (bsb.morphologies.Morphology) – A bsb.Morphology instance.
definitions (arborize.definitions.Definition) – Optional Definition instance.

Returns:

A schematic representation.

Return type:

arborize.schematic.Schematic

arborize.define_constraints(constraints: ConstraintsDefinitionDict, tolerance=None, use_defaults=False) → ConstraintsDefinition[source]¶

Create a ConstraintsDefinition instance from a dictionary of constraints, applying an optional global tolerance and default values.

Parameters:

constraints (ConstraintsDefinitionDict) – Dictionary specifying constraint values structured as ConstraintsDefinitionDict.
tolerance (float or None) – Optional tolerance to apply to all parameter constraints (e.g., 0.1 means ±10%), defaults to None.
use_defaults (bool) – Whether to fill in missing constraint values with defaults, defaults to False.

Returns:

A fully constructed ConstraintsDefinition instance with all values wrapped in Constraint objects and tolerance applied.

Return type:

ConstraintsDefinition

arborize.define_model(templ_or_def, def_dict=None, /, use_defaults=False) → ModelDefinition[source]¶

Return type:: ModelDefinition

arborize.file_schematic(file_like: str | os.PathLike | ~typing.TextIO, definitions: Definition | None = None, fname: str = None, *, name=None, morphio_options: ~morphio._morphio.Option = <Option.no_modifier: 0>) → Schematic[source]¶

Parameters:

file_like (str | os.PathLike | TextIO)
definitions (Definition | None)
fname (str)
morphio_options (Option)

Return type:

Schematic

arborize.is_mech_id(mech_id)[source]¶

arborize.neuron_build(schematic: Schematic)[source]¶

Parameters:: schematic (Schematic)