Source code for dendritic_modeling.networks.architectures.excitation_inhibition.dendritic.compartment_perturbation

"""Additive perturbations of branch-layer compartments for causal analyses.

A :class:`CompartmentPerturbation` set on a
:class:`~dendritic_modeling.networks.architectures.excitation_inhibition.dendritic.branch_layer.DendriticBranchLayer`
(``set_compartment_perturbation`` or ``perturb_compartments``) adds its
offset to the layer's compartments during the layer's own forward pass, in one
coordinate, so the perturbed layer runs once:

``output``
    added to the layer's output after its activation: the signal its parent,
    or the readout, receives.
``voltage``
    added to the pre-activation voltage, so the activation's slope applies.
``current``
    an injected current added to the numerator of the shunting voltage
    equation, ``V = (N + J) / (D + epsilon)``, so the layer's total
    conductance ``D`` attenuates it. Shunting layers only.

The offset must broadcast to the layer's output, ``[batch, compartments]``,
without changing its shape, and must match its device and dtype; compartments
left unperturbed get zeros. A perturbation changes no parameter or buffer.
With signal rounding, voltage and current offsets are rounded with the
voltage, and output offsets are added to the rounded output.

Gradients of a loss with respect to a zero offset that requires gradients are
the exact errors of the compartments in that coordinate, as autograd computes
them: gradient hooks of the model (training-mode gradient scaling, or a core's
``soma_broadcast`` credit) change them in the same way as parameter gradients.

Perturbations act only in ``DendriticBranchLayer.forward``. Paths that would
not apply them raise while one is set: stateful and recurrent currents,
voltages computed from given currents, a ``DendriNet.forward_levels``
intervention on the same level, and a current perturbation under a branch
rule override that does not read the shunting numerator.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Optional

import torch

COORDINATES = ("output", "voltage", "current")


[docs] @dataclass(frozen=True, eq=False) class CompartmentPerturbation: """An additive offset for one branch layer's compartments in one coordinate.""" offset: torch.Tensor coordinate: str = "output" def __post_init__(self) -> None: if not isinstance(self.offset, torch.Tensor): raise TypeError( f"the perturbation offset must be a tensor, got {type(self.offset).__name__}" ) if self.coordinate not in COORDINATES: raise ValueError( f"unknown perturbation coordinate {self.coordinate!r}; " f"use one of {', '.join(COORDINATES)}" ) def add_to(self, value: torch.Tensor) -> torch.Tensor: """``value`` plus the offset, after checking that the offset fits it.""" offset = self.offset if offset.device != value.device: raise ValueError( f"the {self.coordinate} perturbation is on {offset.device}, the " f"layer computes on {value.device}" ) if offset.dtype != value.dtype: raise ValueError( f"the {self.coordinate} perturbation has dtype {offset.dtype}, the " f"layer computes in {value.dtype}" ) try: shape = torch.broadcast_shapes(offset.shape, value.shape) except RuntimeError: shape = None if shape != value.shape: raise ValueError( f"a {self.coordinate} perturbation of shape {tuple(offset.shape)} " f"does not broadcast to the layer's {tuple(value.shape)}" ) return value + offset
def active_compartment_perturbation(owner: Any) -> Optional[CompartmentPerturbation]: """The perturbation a forward pass of ``owner`` applies, or ``None``.""" perturbation = getattr(owner, "_compartment_perturbation", None) if perturbation is None or isinstance(perturbation, CompartmentPerturbation): return perturbation raise TypeError( "compartment perturbations are applied with perturb_compartments(...) or " "DendriticBranchLayer.set_compartment_perturbation(...), not by setting " "_compartment_perturbation" ) __all__ = ["COORDINATES", "CompartmentPerturbation", "active_compartment_perturbation"]