Density

class braincell.mech.Density(class_name, /, *, params=None, name=None, coverage_area_fraction=1.0)

Base class for distributed mechanism declarations.

Density is the shared skeleton for Channel and Ion. It stores the declaration fields (class_name,

params, name, coverage_area_fraction) and implements equality / hashing / immutability, but it is abstract in the sense that category is only set by the concrete subclasses. Attempting to construct Density directly raises TypeError.

Parameters:

• class_name (Any) – Registry key for the concrete runtime class, or a class object whose canonical name the registry already knows (e.g. braincell.ion.PotassiumFixed). A type argument is resolved through braincell.mech.get_registry() at construction time; the stored class_name is always a string.

• params (Any) – Parameter mapping. None (the default) produces an empty Params.

• name (str | None) – Optional instance label. When None, class_name is used as the display label (see instance_name).

• coverage_area_fraction (float) – Fraction in [0, 1] of the target control volume’s lateral area covered by this declaration. Set by the control-volume lowering pipeline (braincell.cv._lower) when a paint region only partially overlaps a CV. Defaults to 1.0.

Raises:

• TypeError – If Density itself is instantiated directly (the concrete subclass determines category), or if class_name is neither a string nor a class, or if name is not a string or None.

• ValueError – If class_name resolves to an empty string, or if coverage_area_fraction is outside [0, 1].

See also

Channel

Concrete subclass for ion channels.

Ion

Concrete subclass for ion species.

category: ClassVar[str] = ''

Category discriminator, set by concrete subclasses to "channel" or "ion". Instances of the abstract base have an empty string.

property identity: tuple[str, str]

Return (instance_name, class_name) for table views.

property instance_name: str

Display label for this declaration.

Returns self.name when set, otherwise self.class_name.

with_coverage(fraction)

Return a copy with a new coverage_area_fraction.

Parameters:

fraction (float) – New fraction, must lie in [0, 1].

Returns:

A new instance of the same concrete subclass. self is unchanged.

Return type:

Density

with_name(name)

Return a copy with a new instance label.

Return type:

Density

with_params(**updates)

Return a copy with updates merged into params.

Parameters:

**updates (Any) – Parameters to add or replace.

Returns:

A new instance of the same concrete subclass. self is unchanged.

Return type:

Density