Source code for dendritic_modeling.networks.benchmarks.parameter_budget

"""Auditable fixed-support model families for parameter-budget experiments.

The dendritic arms instantiate the production ``ConfigurableEINetwork``.  All
arms include a counted affine readout and the same information-preserving input
encoding.  No dense candidate bank, dynamic rewiring, or dormant budget-filling
parameter is introduced.  ``width`` always means exposed hidden outputs/somas.
"""

from __future__ import annotations

import hashlib
import math
from copy import deepcopy
from numbers import Integral, Real
from typing import Any

import torch
from torch import nn

from dendritic_modeling.networks.activations import ActivationFactory
from dendritic_modeling.networks.architectures.excitation_inhibition.dendritic.blocklinear import (
    BlockLinear,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.dendritic.dendrinet import (
    DendriNet,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.ei_network import (
    ConfigurableEINetwork,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.synapse.indexed_sparse import (
    IndexedSparseLinear,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.synapse.kernels import (
    normalize_indexed_projection_backend,
)

FAMILIES = (
    "dense",
    "sparse",
    "dendritic_signed",
    "dendritic_additive",
    "dendritic_shunting",
    "grouped_gated",
)
_DEFAULTS = {
    "width": 32,
    "branch_factors": [2],
    "contacts_e": 4,
    "contacts_i": 0,
    "network_depth": 1,
    "seed": 0,
    "activation": "relu",
    "input_encoding": "signed_split",
    "clip_contacts": False,
    "initialization": "fan_in",
    "projection_backend": "eager",
}


def _integer(value: Any, name: str, minimum: int = 1) -> int:
    if isinstance(value, bool) or not isinstance(value, Integral) or value < minimum:
        raise ValueError(f"{name} must be an integer >= {minimum}")
    return int(value)


def _normalize_readout(readout: Any, output_dim: int) -> dict:
    """Validate opt-in signed allocation; omitted seeds retain inheritance."""
    if not isinstance(readout, dict):
        raise ValueError("readout must be a dict")
    kind = readout.get("kind")
    if not isinstance(kind, str) or kind not in {"dense", "indexed", "low_rank"}:
        raise ValueError("readout.kind must be dense, indexed, or low_rank")
    allowed = {"kind", "bias", "init_std", "parameter_seed"}
    if kind == "indexed":
        allowed |= {"topk", "topology_seed", "projection_backend"}
    elif kind == "low_rank":
        allowed.add("rank")
    unknown = set(readout) - allowed
    if unknown:
        raise ValueError(f"Unknown readout keys for {kind}: {sorted(unknown)}")
    result = {"bias": True, "init_std": 0.02, **deepcopy(readout)}
    if not isinstance(result["bias"], bool):
        raise ValueError("readout.bias must be a bool")
    std = result["init_std"]
    if (
        isinstance(std, bool)
        or not isinstance(std, Real)
        or not math.isfinite(std)
        or std <= 0
    ):
        raise ValueError("readout.init_std must be finite and > 0")
    result["init_std"] = float(std)
    for name in ("parameter_seed", "topology_seed"):
        if name in result:
            result[name] = _integer(result[name], f"readout.{name}", 0)
    if kind == "indexed":
        result["topk"] = _integer(result.get("topk"), "readout.topk")
        backend = result.get("projection_backend", "eager")
        if not isinstance(backend, str):
            raise ValueError("readout.projection_backend must be a string")
        result["projection_backend"] = normalize_indexed_projection_backend(backend)
    elif kind == "low_rank":
        result["rank"] = _integer(result.get("rank"), "readout.rank")
        if result["rank"] > output_dim:
            raise ValueError("readout.rank must be <= output_dim")
    return result


def _normalize_spec(spec: dict) -> dict:
    if not isinstance(spec, dict):
        raise TypeError("model spec must be a dict")
    allowed = set(_DEFAULTS) | {
        "family",
        "input_dim",
        "output_dim",
        "topology_seed",
        "readout",
        "activation_init",
    }
    unknown = set(spec) - allowed
    if unknown:
        raise ValueError(f"Unknown model spec keys: {sorted(unknown)}")
    result = {**deepcopy(_DEFAULTS), **deepcopy(spec)}
    if result.get("family") not in FAMILIES:
        raise ValueError(f"family must be one of {FAMILIES}")
    for name in ("input_dim", "output_dim", "width", "network_depth", "contacts_e"):
        result[name] = _integer(result.get(name), name)
    result["contacts_i"] = _integer(result["contacts_i"], "contacts_i", 0)
    result["seed"] = _integer(result["seed"], "seed", 0)
    result["topology_seed"] = _integer(
        result.get("topology_seed", result["seed"]), "topology_seed", 0
    )
    if not isinstance(result["branch_factors"], (list, tuple)):
        raise ValueError("branch_factors must be a sequence")
    result["branch_factors"] = [
        _integer(value, "branch factor") for value in result["branch_factors"]
    ]
    if not isinstance(result["activation"], str) or result["activation"] not in {
        "relu",
        "softplus",
        "sigmoid",
        "param_relu",
        "param_tanh",
    }:
        raise ValueError(
            "activation must be relu, softplus, sigmoid, param_relu, or param_tanh"
        )
    learned_gate = result["activation"] in {"param_relu", "param_tanh"}
    if learned_gate:
        result["activation_init"] = _normalize_activation_init(
            result.get("activation_init"), result["activation"]
        )
    elif "activation_init" in result:
        raise ValueError("activation_init requires param_relu or param_tanh")
    if result["initialization"] not in {"fan_in", "legacy_xavier"}:
        raise ValueError("initialization must be fan_in or legacy_xavier")
    if not isinstance(result["projection_backend"], str):
        raise ValueError("projection_backend must be a string")
    result["projection_backend"] = normalize_indexed_projection_backend(
        result["projection_backend"]
    )
    if result["family"] == "dense" and result["projection_backend"] != "eager":
        raise ValueError(
            "dense has no indexed projections; projection_backend must be eager"
        )
    if result["input_encoding"] not in {"signed_split", "nonnegative", "raw"}:
        raise ValueError("input_encoding must be signed_split, nonnegative, or raw")
    if result["input_encoding"] == "raw" and result["family"] in {
        "dendritic_additive",
        "dendritic_shunting",
    }:
        raise ValueError(
            "Positive E/I families require signed_split or nonnegative inputs; "
            "input_encoding='raw' is not a valid conductance-input contract"
        )
    if not isinstance(result["clip_contacts"], bool):
        raise ValueError("clip_contacts must be a bool")
    if result["family"] == "dendritic_signed" and result["contacts_i"]:
        raise ValueError("dendritic_signed has no I bank; set contacts_i=0")
    if "readout" in result:
        result["readout"] = _normalize_readout(result["readout"], result["output_dim"])
    return result


def _normalize_activation_init(settings: Any, activation: str) -> dict:
    """Require declared, fixed production gate initialization without calibration."""
    if not isinstance(settings, dict) or set(settings) != {"gain", "threshold"}:
        raise ValueError("activation_init must declare exactly gain and threshold")
    result = {}
    for name, value in settings.items():
        if (
            isinstance(value, bool)
            or not isinstance(value, Real)
            or not math.isfinite(value)
        ):
            raise ValueError(f"activation_init.{name} must be a finite real number")
        result[name] = float(value)
    if result["gain"] <= 0:
        raise ValueError("activation_init.gain must be > 0")
    # ParametricReLU.initialize clamps smaller gains. Reject them rather than
    # let production initialization silently differ from conventional controls.
    if activation == "param_relu" and result["gain"] < 1e-8:
        raise ValueError("param_relu activation_init.gain must be >= 1e-8")
    return result


def _activation(
    name: str, output_dim: int, initialization: dict | None = None
) -> nn.Module:
    gain, threshold = 1.5, 0.5
    if initialization is not None:
        gain, threshold = initialization["gain"], initialization["threshold"]
    return ActivationFactory.create(
        name, output_dim=output_dim, init_m=gain, init_b=threshold
    )


def _compartments(branch_factors: list[int]) -> int:
    sites, level = 1, 1
    for factor in branch_factors:
        level *= factor
        sites += level
    return sites


def _contacts(requested: int, available: int, spec: dict) -> int:
    if requested > available and not spec["clip_contacts"]:
        raise ValueError(
            f"Requested {requested} contacts per output but only {available} "
            "sources are available; choose a feasible width/contact count or "
            "explicitly set clip_contacts=true."
        )
    return min(requested, available)


class _InputEncoding(nn.Module):
    def __init__(self, input_dim: int, kind: str):
        super().__init__()
        self.input_dim, self.kind = input_dim, kind

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        if x.ndim != 2 or x.shape[-1] != self.input_dim:
            raise ValueError(f"Expected [batch, {self.input_dim}] inputs")
        if self.kind == "signed_split":
            return torch.cat((x.relu(), (-x).relu()), dim=-1)
        if self.kind == "raw":
            return x
        if bool((x < 0).any()):
            raise ValueError("input_encoding='nonnegative' received negative input")
        return x


class _SparseAffine(nn.Module):
    """Signed, fixed-index production projection plus an ordinary affine bias."""

    def __init__(
        self,
        input_dim: int,
        output_dim: int,
        contacts: int,
        seed: int,
        initialization: str,
        *,
        gate_projection: bool = False,
        projection_backend: str = "eager",
    ):
        super().__init__()
        fan_in = initialization == "fan_in"
        self.projection = IndexedSparseLinear(
            input_dim,
            output_dim,
            contacts,
            param_space="linear",
            weight_transform="identity",
            init_method="kaiming_normal" if fan_in else "xavier_normal",
            # Value projections use ReLU gain sqrt(2); sigmoid-gate logits
            # use gain 1. Both depend on contact fan-in, never output width.
            init_gain=1.0 / math.sqrt(2.0) if fan_in and gate_projection else 1.0,
            seed=seed,
            projection_backend=projection_backend,
        )
        self.bias = nn.Parameter(torch.zeros(output_dim))

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        return self.projection(x) + self.bias


class _IndexedAffineReadout(nn.Module):
    """Signed production output projection with a counted optional affine bias."""

    def __init__(self, projection: IndexedSparseLinear, *, bias: bool):
        super().__init__()
        if (
            not isinstance(projection, IndexedSparseLinear)
            or projection.weight_transform != "identity"
        ):
            raise ValueError(
                "Indexed affine readout requires a signed indexed projection"
            )
        self.projection = projection
        self.bias = (
            nn.Parameter(projection.pre_w.new_zeros(projection.out_features))
            if bias
            else None
        )

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        output = self.projection(x)
        return output if self.bias is None else output + self.bias


def _build_readout(spec: dict) -> nn.Module:
    # Keep the historical call and RNG sequence unchanged when not opted in.
    if "readout" not in spec:
        return nn.Linear(spec["width"], spec["output_dim"])

    from dendritic_modeling.networks.utils.readouts import make_signed_readout

    readout = spec["readout"]
    indexed = readout["kind"] == "indexed"
    with torch.random.fork_rng(devices=[]):
        torch.random.default_generator.manual_seed(
            readout.get("parameter_seed", spec["seed"])
        )
        projection = make_signed_readout(
            spec["width"],
            spec["output_dim"],
            rank=readout.get("rank"),
            topk=readout.get("topk"),
            bias=False if indexed else readout["bias"],
            init_std=readout["init_std"],
            seed=readout.get("topology_seed", spec["topology_seed"]),
            projection_backend=readout.get("projection_backend", "eager"),
        )
        if indexed:
            # The factory's sparse initializer otherwise ignores init_std.
            # Match the signed normal per-stored-weight policy of its dense
            # and low-rank paths, while retaining its fixed support and kernel.
            nn.init.normal_(projection.pre_w, mean=0.0, std=readout["init_std"])
            return _IndexedAffineReadout(projection, bias=readout["bias"])
        return projection


class _GroupedGated(nn.Module):
    """Generic sparse gated subunits, group RMS normalization, and learned sum.

    This conventional comparator has no dendritic circuit dynamics. Each soma
    group contains as many parallel sites as the dendritic nonsomatic-site
    inventory (one for a flat morphology). Both sparse projections, biases,
    branch-combination weights, and output bias are counted. It is a bundled
    grouping/gating/normalization control, not an exact shunting equivalent.
    """

    def __init__(
        self,
        input_dim: int,
        width: int,
        groups: int,
        contacts_e: int,
        contacts_i: int,
        activation: str,
        seed: int,
        initialization: str,
        *,
        projection_backend: str = "eager",
        activation_init: dict | None = None,
    ):
        super().__init__()
        sites = width * groups
        self.width, self.groups = width, groups
        self.value = _SparseAffine(
            input_dim,
            sites,
            contacts_e,
            seed,
            initialization,
            projection_backend=projection_backend,
        )
        self.gate = _SparseAffine(
            input_dim,
            sites,
            contacts_i,
            seed + 1,
            initialization,
            gate_projection=True,
            projection_backend=projection_backend,
        )
        self.activation = _activation(activation, sites, activation_init)
        self.combine = nn.Parameter(torch.empty(width, groups))
        nn.init.normal_(self.combine, std=groups**-0.5)
        self.bias = nn.Parameter(torch.zeros(width))
        self.output_activation = _activation(activation, width, activation_init)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        branches = self.activation(self.value(x)) * torch.sigmoid(self.gate(x))
        branches = branches.reshape(x.shape[0], self.width, self.groups)
        # Include a unit reference so singleton groups remain amplitude-sensitive.
        branches = branches * torch.rsqrt(
            1.0 + branches.square().mean(-1, keepdim=True)
        )
        return self.output_activation((branches * self.combine).sum(-1) + self.bias)


def _dendritic_config(spec: dict, contacts_e: int, contacts_i: int, seed: int) -> dict:
    signed = spec["family"] == "dendritic_signed"
    activation_init = spec.get("activation_init", {"gain": 1.5, "threshold": 0.5})
    return {
        # These scaling controls include signed synapses and shared E/I
        # feature streams; they make no biological-neuron declaration.
        "biological_neuron": False,
        "architecture": {
            "excitatory_layer_sizes": [spec["width"]],
            "inhibitory_layer_sizes": [],
            "excitatory_branch_factors": spec["branch_factors"],
            "inhibitory_branch_factors": spec["branch_factors"],
        },
        "connectivity": {
            "ee_synapses_per_branch_per_layer": [contacts_e],
            "ei_synapses_per_branch_per_layer": [0],
            "ie_synapses_per_branch_per_layer": [contacts_i],
            "ii_synapses_per_branch_per_layer": [0],
        },
        "transfer": {"independent_pathways": False, "output_activation": None},
        "morphology": {
            "somatic_synapses": not bool(spec["branch_factors"]),
            "use_shunting": spec["family"] == "dendritic_shunting",
            "weight_transform": "identity" if signed else "softplus",
            "dbl_init_method": "analytical_expectation",
        },
        "sparsity": {
            "type": "indexed",
            "init_method": (
                "kaiming_normal"
                if spec["initialization"] == "fan_in"
                else "xavier_normal"
            ),
            "indexed": {"seed": seed, "projection_backend": spec["projection_backend"]},
        },
        "reactivation": {
            "enabled": True,
            "type": spec["activation"],
            # Fixed applies explicit m/b to learned gates at every branch and
            # soma. Historical parameter-free gates ignore these same values.
            "init_m": activation_init["gain"],
            "init_b": activation_init["threshold"],
            "init_policy": "fixed",
        },
        "blocklinear": {"efficient": True},
        "implementation": {"adaptive_initialization": False, "print_hooks": False},
    }


def _initialize_signed_dendritic_fan_in(module: nn.Module) -> dict[str, int]:
    """Reset production signed-final-init using actual contacts/children fan-in.

    The production identity-weight initializer reapplies Xavier after the
    projection constructors. Only existing signed parameters are reset here;
    circuit dynamics, support, and positive-conductance initialization remain
    those of the production modules.
    """
    fan_ins = {}
    for name, child in module.named_modules():
        if (
            isinstance(child, IndexedSparseLinear)
            and child.weight_transform == "identity"
        ):
            nn.init.kaiming_normal_(child.pre_w)
            fan_ins[name + ".pre_w"] = child.K
        elif isinstance(child, BlockLinear) and child.weight_transform == "identity":
            nn.init.kaiming_normal_(child.log_weight)
            fan_ins[name + ".log_weight"] = child.block_size
    return fan_ins


class _ScalingModel(nn.Module):
    def __init__(self, spec: dict):
        super().__init__()
        self.scaling_spec = deepcopy(spec)
        self.encoding = _InputEncoding(spec["input_dim"], spec["input_encoding"])
        encoded_dim = spec["input_dim"] * (
            2 if spec["input_encoding"] == "signed_split" else 1
        )
        self.encoded_input_dim = encoded_dim
        self.layer_receipts: list[dict] = []
        layers: list[nn.Module] = []
        input_dim = encoded_dim
        family, width = spec["family"], spec["width"]
        for index in range(spec["network_depth"]):
            support_seed = spec["topology_seed"] + index * 104729
            receipt = {"layer": index, "input_dim": input_dim, "output_dim": width}
            if family == "dense":
                affine = nn.Linear(input_dim, width)
                if spec["initialization"] == "fan_in":
                    nn.init.kaiming_normal_(affine.weight)
                    nn.init.zeros_(affine.bias)
                layer = nn.Sequential(
                    affine,
                    _activation(spec["activation"], width, spec.get("activation_init")),
                )
                receipt.update({"contacts_e": input_dim, "contacts_i": 0})
            elif family == "sparse":
                contacts = _contacts(
                    spec["contacts_e"] + spec["contacts_i"], input_dim, spec
                )
                layer = nn.Sequential(
                    _SparseAffine(
                        input_dim,
                        width,
                        contacts,
                        support_seed,
                        spec["initialization"],
                        projection_backend=spec["projection_backend"],
                    ),
                    _activation(spec["activation"], width, spec.get("activation_init")),
                )
                receipt.update({"contacts_e": contacts, "contacts_i": 0})
            else:
                contacts_e = _contacts(spec["contacts_e"], input_dim, spec)
                contacts_i = _contacts(spec["contacts_i"], input_dim, spec)
                if family == "grouped_gated":
                    # A zero I count does not remove the generic gate; it reuses
                    # the declared value fan-in, with its full cost recorded.
                    contacts_i = contacts_i or contacts_e
                    groups = max(1, _compartments(spec["branch_factors"]) - 1)
                    layer = _GroupedGated(
                        input_dim,
                        width,
                        groups,
                        contacts_e,
                        contacts_i,
                        spec["activation"],
                        support_seed,
                        spec["initialization"],
                        projection_backend=spec["projection_backend"],
                        activation_init=spec.get("activation_init"),
                    )
                    receipt["parallel_groups"] = groups
                else:
                    config = _dendritic_config(
                        spec, contacts_e, contacts_i, support_seed
                    )
                    layer = ConfigurableEINetwork(config=config, input_dim=input_dim)
                    receipt["production_config"] = config
                    if (
                        family == "dendritic_signed"
                        and spec["initialization"] == "fan_in"
                    ):
                        receipt["final_signed_parameter_fan_ins"] = (
                            _initialize_signed_dendritic_fan_in(layer)
                        )
                    elif family in {"dendritic_additive", "dendritic_shunting"}:
                        receipt["final_positive_initialization"] = (
                            "production_analytical_expectation"
                        )
                receipt.update({"contacts_e": contacts_e, "contacts_i": contacts_i})
            layers.append(layer)
            self.layer_receipts.append(receipt)
            input_dim = width
        self.hidden = nn.Sequential(*layers)
        self.readout = _build_readout(spec)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        return self.readout(self.hidden(self.encoding(x)))


def build_model(spec: dict) -> nn.Module:
    """Instantiate a seeded whole model without perturbing the caller's RNG.

    ``seed`` controls initial parameters; ``topology_seed`` defaults to it and
    controls static support. Defaults use a common signed-split input encoding
    and ReLU at every hidden point/branch. Native-input point controls may opt
    into ``input_encoding='raw'``; raw input is also supported by signed trees
    and generic grouped gates. Supported activations are nonnegative
    so successive positive-conductance layers receive valid inputs. Models are
    created on CPU; callers select device/dtype explicitly afterward.

    Learned ``param_relu`` and ``param_tanh`` gates require an explicit
    ``activation_init={"gain": m, "threshold": b}``. The positive gain is m,
    not its stored logarithm: gates evaluate m*relu(V-b) or
    (tanh(m*(V-b))+1)/2. Both log(m) and b are learned and counted at every
    hidden gate, including dendritic somas. Conventional controls use the same
    production activation classes and settings. Initialization is fixed with
    no implicit calibration; the caller must choose a threshold appropriate
    to its voltage regime. For param_relu, gain must be >=1e-8 to avoid the
    production initializer's floor. Omitted options preserve historical specs,
    state, and reports. Gate choices do not promise matched initial body weights.

    ``initialization='fan_in'`` uses the registered production Kaiming-normal
    sparse initializer, whose preweight variance is 2/K rather than 2/(K+width).
    Signed dendritic projections and child couplings are reset after production
    initialization using contacts/children as their row fan-in.
    Dense hidden values use the same fan-in rule; grouped gate logits use gain
    one. With no ``readout`` field, the affine readout retains ordinary PyTorch
    fan-in initialization and the exact historical state/RNG sequence.
    Positive weights retain the production analytical initializer, which
    overwrites their constructor weights, and the softplus transform.
    This removes a width confound, not all differences
    in conditioning across morphologies or integration rules. The archival
    ``legacy_xavier`` option reproduces this harness's original initialization.

    ``projection_backend`` selects the production indexed-projection backend,
    defaulting to ``eager``. It applies to every sparse value/gate/E/I bank;
    dense models accept only the default. Explicit accelerator backends are
    constructed on CPU but require a supported device at forward time. Backend
    changes preserve parameters and support, not floating-point reduction order.

    An optional ``readout`` dict selects signed production output allocation:
    ``kind='dense'``, ``kind='indexed', topk=K``, or ``kind='low_rank', rank=r``.
    All default to a counted affine bias and normal initialization with
    ``init_std=0.02`` per stored weight (per factor for low rank). Thus explicit
    dense initialization differs from the legacy omitted-field path. No
    activation is inserted between low-rank factors. Optional ``parameter_seed``
    isolates readout initialization from hidden-layer RNG consumption; if
    omitted it inherits ``seed``. Indexed readouts additionally accept
    ``topology_seed`` (inherits the core topology seed) and ``projection_backend``
    (defaults to eager independently of core backend). Their fixed indices are
    stored buffers, never learned candidate weights. Readout topk/rank are
    never clipped by ``clip_contacts``.
    """
    resolved = _normalize_spec(spec)
    with torch.random.fork_rng(devices=[]):
        torch.random.default_generator.manual_seed(resolved["seed"])
        return _ScalingModel(resolved)


def _dendrinet_inventory(model: nn.Module) -> dict | None:
    """Inspect actual production populations; never infer counts from a label.

    Depth zero is the soma, whereas ``forward_index`` runs from leaves to the
    soma. A contact means a stored indexed synaptic weight, not a dense masked
    candidate. Parameter roles form an exclusive partition of the whole model;
    a tied parameter with multiple roles is counted once under ``shared``.
    Registered buffers are reported separately from learned parameters and may
    include mutable runtime state, so they are not all called fixed topology.
    """
    dendrinets = [
        (name, module)
        for name, module in model.named_modules()
        if isinstance(module, DendriNet)
    ]
    if not dendrinets:
        return None

    role_names = (
        "excitatory_synapses",
        "inhibitory_synapses",
        "recurrent_synapses",
        "child_couplings",
        "reactivation",
        "readout",
        "shared",
        "other",
    )
    roles: dict[int, set[str]] = {}

    def assign_role(module: nn.Module | None, role: str) -> None:
        if module is not None:
            for parameter in module.parameters():
                roles.setdefault(id(parameter), set()).add(role)

    def parameter_count(module: nn.Module | None) -> int:
        return 0 if module is None else sum(p.numel() for p in module.parameters())

    def bank_receipt(bank: nn.Module | None) -> dict | None:
        if bank is None:
            return None
        result = {
            "module_type": type(bank).__name__,
            "total_parameters": parameter_count(bank),
            "input_dim": int(bank.in_features),
            "output_dim": int(bank.out_features),
            "weight_transform": getattr(bank, "weight_transform", None),
        }
        if isinstance(bank, IndexedSparseLinear):
            indices = bank.connection_indices.detach().cpu().contiguous()
            result.update(
                {
                    "contacts_per_compartment": int(bank.K),
                    "stored_contacts": int(bank.pre_w.numel()),
                    "connection_indices_shape": list(indices.shape),
                    "connection_indices_bytes": indices.numel()
                    * indices.element_size(),
                    "connection_indices_sha256": hashlib.sha256(
                        indices.numpy().tobytes()
                    ).hexdigest(),
                    "support_policy": "static_indexed",
                }
            )
        return result

    populations = []
    for name, dendrinet in dendrinets:
        depths = []
        for forward_index, branch in enumerate(dendrinet.branch_layers):
            excitation = getattr(branch, "branch_excitation", None)
            inhibition = getattr(branch, "branch_inhibition", None)
            coupling = getattr(branch, "branches_to_output", None)
            gate = getattr(branch, "reactivation", None)
            assign_role(excitation, "excitatory_synapses")
            assign_role(inhibition, "inhibitory_synapses")
            assign_role(coupling, "child_couplings")
            assign_role(gate, "reactivation")
            for recurrent_name in ("branch_recurrent", "branch_rec_inhibition"):
                assign_role(getattr(branch, recurrent_name, None), "recurrent_synapses")
            excitation_receipt = bank_receipt(excitation)
            inhibition_receipt = bank_receipt(inhibition)
            depths.append(
                {
                    "module_name": f"{name}.branch_layers.{forward_index}",
                    "forward_index": forward_index,
                    "depth_from_soma": int(branch.layer_idx),
                    "is_soma": branch.layer_idx == 0,
                    "compartment_count": int(branch.n_branches),
                    "compartments_per_soma": branch.n_branches // dendrinet.n_soma,
                    "contacts_e_per_compartment": (
                        excitation_receipt.get("contacts_per_compartment")
                        if excitation_receipt is not None
                        else 0
                    ),
                    "contacts_i_per_compartment": (
                        inhibition_receipt.get("contacts_per_compartment")
                        if inhibition_receipt is not None
                        else 0
                    ),
                    "input_banks": {
                        "excitatory": excitation_receipt,
                        "inhibitory": inhibition_receipt,
                    },
                    "input_synapse_parameters": parameter_count(excitation)
                    + parameter_count(inhibition),
                    "children_per_compartment": (
                        int(coupling.block_size) if coupling is not None else 0
                    ),
                    "child_coupling_parameters": parameter_count(coupling),
                    "gate_enabled": bool(branch.reactivate),
                    "gate_type": type(gate).__name__ if gate is not None else None,
                    "gate_parameters": parameter_count(gate),
                    "integration": "shunting" if branch.use_shunting else "additive",
                    "additive_mode": branch.additive_mode,
                    "weight_transform": branch.weight_transform,
                    "total_parameters": parameter_count(branch),
                }
            )
        contacted_depths = [
            d["depth_from_soma"] for d in depths if d["input_synapse_parameters"] > 0
        ]
        expected_nonsomatic = list(range(dendrinet.n_branch_layers, 0, -1))
        if contacted_depths == [0]:
            placement = "soma_only"
        elif contacted_depths == expected_nonsomatic and expected_nonsomatic:
            placement = "all_nonsomatic_depths"
        elif contacted_depths == [*expected_nonsomatic, 0]:
            placement = "all_depths_including_soma"
        else:
            placement = "explicit_contacted_depths"
        populations.append(
            {
                "module_name": name,
                "module_type": f"{type(dendrinet).__module__}.{type(dendrinet).__name__}",
                "n_soma": int(dendrinet.n_soma),
                "branch_factors": list(dendrinet.branch_factors),
                "internal_branch_depth": int(dendrinet.n_branch_layers),
                "compartment_count": sum(d["compartment_count"] for d in depths),
                "contact_placement": placement,
                "contacted_depths_from_soma": contacted_depths,
                "total_parameters": parameter_count(dendrinet),
                "depths": depths,
            }
        )

    if isinstance(model, _ScalingModel):
        assign_role(model.readout, "readout")
    partition = dict.fromkeys(role_names, 0)
    trainable_partition = dict.fromkeys(role_names, 0)
    parameter_roles = {}
    for name, parameter in model.named_parameters():
        candidates = roles.get(id(parameter), set())
        role = (
            next(iter(candidates))
            if len(candidates) == 1
            else ("shared" if candidates else "other")
        )
        partition[role] += parameter.numel()
        if parameter.requires_grad:
            trainable_partition[role] += parameter.numel()
        parameter_roles[name] = role

    buffers = []
    for name, buffer in model.named_buffers():
        owner_name, _, local_name = name.rpartition(".")
        owner = model.get_submodule(owner_name) if owner_name else model
        buffers.append(
            {
                "name": name,
                "shape": list(buffer.shape),
                "dtype": str(buffer.dtype),
                "numel": buffer.numel(),
                "bytes": buffer.numel() * buffer.element_size(),
                "persistent": local_name not in owner._non_persistent_buffers_set,
            }
        )
    somas = sum(p["n_soma"] for p in populations)
    compartments = sum(p["compartment_count"] for p in populations)
    return {
        "schema_version": 1,
        "population_count": len(populations),
        "total_somas": somas,
        "total_compartments": compartments,
        "total_nonsomatic_compartments": compartments - somas,
        "parameter_partition": partition,
        "trainable_parameter_partition": trainable_partition,
        "parameter_roles": parameter_roles,
        "registered_buffer_inventory": buffers,
        "populations": populations,
        "interpretation": (
            "Observed registered architecture and storage, not effective function "
            "dimension or active nonlinear-region count. Configured ReLU gates "
            "can act linearly on nonnegative branch voltages."
        ),
    }


[docs] def model_report(model: nn.Module) -> dict: """Count unique registered scalars and storage, including the affine head.""" parameters = list(model.parameters()) buffers = list(model.buffers()) topology = hashlib.sha256() topology_bytes = 0 for name, buffer in model.named_buffers(): if not buffer.is_floating_point() and not buffer.is_complex(): topology.update(name.encode()) topology.update(str(tuple(buffer.shape)).encode()) topology.update(buffer.detach().cpu().contiguous().numpy().tobytes()) topology_bytes += buffer.numel() * buffer.element_size() report = { "total_parameters": sum(p.numel() for p in parameters), "trainable_parameters": sum(p.numel() for p in parameters if p.requires_grad), "parameter_bytes": sum(p.numel() * p.element_size() for p in parameters), "buffer_bytes": sum(b.numel() * b.element_size() for b in buffers), "topology_bytes": topology_bytes, "topology_sha256": topology.hexdigest(), "parameter_shapes": { name: list(p.shape) for name, p in model.named_parameters() }, "indexed_projection_backends": { name: { "requested": module.projection_backend, "resolved": module._last_resolved_projection_backend, "device": ( str(module._last_projection_device) if module._last_projection_device is not None else None ), } for name, module in model.named_modules() if isinstance(module, IndexedSparseLinear) }, } dendrinet_inventory = _dendrinet_inventory(model) if dendrinet_inventory is not None: report["dendrinet_inventory"] = dendrinet_inventory if isinstance(model, _ScalingModel): spec = deepcopy(model.scaling_spec) report.update( { "resolved_spec": spec, "family": spec["family"], "input_encoding": spec["input_encoding"], "initialization": spec["initialization"], "projection_backend": spec["projection_backend"], "encoded_input_dim": model.encoded_input_dim, "hidden_parameters": sum(p.numel() for p in model.hidden.parameters()), "readout_parameters": sum( p.numel() for p in model.readout.parameters() ), "layer_receipts": deepcopy(model.layer_receipts), "support_policy": ( "static_indexed" if spec["family"] != "dense" else "dense" ), "compartments_per_soma": ( _compartments(spec["branch_factors"]) if spec["family"].startswith("dendritic_") else None ), } ) if "readout" in spec: readout = deepcopy(spec["readout"]) readout_inventory = model_report(model.readout) readout["parameter_seed"] = readout.get("parameter_seed", spec["seed"]) referenced_columns = spec["width"] if readout["kind"] == "indexed": readout["topology_seed"] = readout.get( "topology_seed", spec["topology_seed"] ) referenced_columns = int( model.readout.projection.connection_indices.unique().numel() ) readout.update( { "factory": "networks.utils.readouts.make_signed_readout", "weight_transform": "identity", "initialization": "normal_per_stored_weight", "input_dim": spec["width"], "output_dim": spec["output_dim"], "total_parameters": report["readout_parameters"], "parameter_bytes": readout_inventory["parameter_bytes"], "buffer_bytes": readout_inventory["buffer_bytes"], "topology_bytes": readout_inventory["topology_bytes"], "topology_sha256": readout_inventory["topology_sha256"], "referenced_input_columns": referenced_columns, "unreferenced_input_columns": spec["width"] - referenced_columns, "support_policy": ( "static_indexed" if readout["kind"] == "indexed" else "dense" ), "learned_factors": 2 if readout["kind"] == "low_rank" else 1, } ) report["readout"] = readout if readout["kind"] == "indexed": report["support_policy"] = "static_indexed" return report
[docs] def match_parameter_budget( spec: dict, target_parameters: int, tolerance: float = 0.02 ) -> tuple[dict, dict]: """Find the nearest feasible integer width by counted monotone search. All fields other than width remain fixed. A match is accepted only when the instantiated *whole-model* count differs from target by at most tolerance. Failure is explicit; neither extra inert weights nor an over-budget-only convention is used. Matching does not equalize compute or activation memory. """ target = _integer(target_parameters, "target_parameters") if ( isinstance(tolerance, bool) or not math.isfinite(tolerance) or not 0 <= tolerance < 1 ): raise ValueError("tolerance must be finite and in [0, 1)") resolved = _normalize_spec(spec) minimum_width = 1 if resolved["network_depth"] > 1 and not resolved["clip_contacts"]: if resolved["family"] == "sparse": minimum_width = resolved["contacts_e"] + resolved["contacts_i"] elif resolved["family"] != "dense": minimum_width = max(resolved["contacts_e"], resolved["contacts_i"]) readout = resolved.get("readout", {}) minimum_width = max(minimum_width, readout.get("topk", 1), readout.get("rank", 1)) cache: dict[int, dict] = {} def count(width: int) -> int: if width not in cache: candidate = {**resolved, "width": width} cache[width] = model_report(build_model(candidate)) return cache[width]["total_parameters"] low = minimum_width low_count = count(low) high = low if low_count < target: high = max(low + 1, resolved["width"]) while count(high) < target: low = high high *= 2 while high - low > 1: middle = (low + high) // 2 if count(middle) < target: low = middle else: high = middle best = min( {low, high}, key=lambda width: (abs(count(width) - target), count(width)) ) report = cache[best] error = abs(report["total_parameters"] - target) / target if error > tolerance: raise ValueError( f"No width matches target_parameters={target} within tolerance={tolerance:g}; " f"nearest feasible width={best} has {report['total_parameters']} parameters " f"(relative error={error:.6g})." ) report.update( { "target_parameters": target, "budget_tolerance": float(tolerance), "budget_relative_error": error, "budget_matched": True, } ) return deepcopy(report["resolved_spec"]), report
__all__ = ["FAMILIES", "build_model", "match_parameter_budget", "model_report"]