"""Exact model-resource accounting for confirmatory experiments."""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from dataclasses import asdict, dataclass, fields, is_dataclass
from typing import Any
import torch
from dendritic_modeling.analysis.utils.dendritic_depth import (
soma_relative_dendritic_depth,
)
from dendritic_modeling.analysis.utils.effective_synapses import (
effective_synapse_snapshot,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.dendritic.branch_layer import (
DendriticBranchLayer,
)
from dendritic_modeling.networks.architectures.excitation_inhibition.synapse import (
DenseToSparseLinear,
TopKLinear,
)
_SYNAPSE_PATHWAYS = {
"branch_excitation": "ff_excitatory",
"branch_inhibition": "ff_inhibitory",
"branch_recurrent": "rec_excitatory",
"branch_rec_inhibition": "rec_inhibitory",
}
@dataclass(frozen=True)
class SynapseResourceRecord:
module: str
pathway: str
soma_relative_depth: int
out_features: int
in_features: int
candidate_parameters: int
candidate_slots: int
active_synapses: int
realized_k_min: int
realized_k_max: int
realized_k_mean: float
selection_policy: str
mask_source: str
@dataclass(frozen=True)
class StaticDendriticResourceSummary:
"""Config-derived resources for a regular dendritic population.
This summary is intentionally limited to quantities that are determined
exactly by morphology, pathway input widths, and retained contacts. It
does not infer trainable parameter counts for a particular sparse-layer
implementation; checkpoint-backed analyses should use
:func:`model_resource_summary` for those quantities.
"""
level_compartments_per_soma: tuple[int, ...]
nonsomatic_compartments_per_soma: int
nonsomatic_compartments_total: int
synaptic_compartments_total: int
active_synapses_by_pathway: dict[str, int]
active_synapses_total: int
candidate_slots_by_pathway: dict[str, int]
candidate_synapse_slots_total: int
child_couplings_total: int
reactivation_parameters_total: int
def _resource_integer(value: Any, *, name: str, allow_zero: bool) -> int:
if isinstance(value, bool):
raise TypeError(f"{name} must be an integer, not bool")
try:
parsed = int(value)
except (TypeError, ValueError):
raise TypeError(f"{name} must be an integer, got {value!r}") from None
if parsed != value:
raise ValueError(f"{name} must be an exact integer, got {value!r}")
minimum = 0 if allow_zero else 1
if parsed < minimum:
qualifier = "non-negative" if allow_zero else "positive"
raise ValueError(f"{name} must be {qualifier}, got {parsed}")
return parsed
def dendritic_level_widths(branch_factors: Sequence[int]) -> tuple[int, ...]:
"""Return nonsomatic compartment counts per soma from proximal to distal."""
if isinstance(branch_factors, (str, bytes)):
raise TypeError("branch_factors must be a sequence of positive integers")
factors = tuple(
_resource_integer(value, name=f"branch_factors[{index}]", allow_zero=False)
for index, value in enumerate(branch_factors)
)
if not factors:
raise ValueError("branch_factors must contain at least one dendritic level")
level_widths = []
width = 1
for factor in factors:
width *= factor
level_widths.append(width)
return tuple(level_widths)
def static_dendritic_resource_summary(
*,
branch_factors: Sequence[int],
n_somas: int,
pathway_input_dims: Mapping[str, int],
synapses_per_compartment: Mapping[str, int],
somatic_synapses: bool = False,
reactivation_scalars_per_compartment: int = 2,
reactivation_includes_soma: bool = True,
) -> StaticDendriticResourceSummary:
"""Compute exact config-level resources for one regular population.
``candidate_slots`` counts structurally available input/output pairs, not
necessarily trainable parameters. For standard dense-candidate Top-K the
two counts coincide; indexed and structured implementations can differ.
"""
level_widths = dendritic_level_widths(branch_factors)
soma_count = _resource_integer(n_somas, name="n_somas", allow_zero=False)
reactivation_width = _resource_integer(
reactivation_scalars_per_compartment,
name="reactivation_scalars_per_compartment",
allow_zero=True,
)
input_dims = {
str(pathway): _resource_integer(
value,
name=f"pathway_input_dims[{pathway!r}]",
allow_zero=True,
)
for pathway, value in pathway_input_dims.items()
}
retained = {
str(pathway): _resource_integer(
value,
name=f"synapses_per_compartment[{pathway!r}]",
allow_zero=True,
)
for pathway, value in synapses_per_compartment.items()
}
if not input_dims:
raise ValueError("At least one synaptic pathway must be specified")
if set(input_dims) != set(retained):
raise ValueError(
"pathway_input_dims and synapses_per_compartment must have identical keys"
)
for pathway in sorted(input_dims):
if retained[pathway] > input_dims[pathway]:
raise ValueError(
f"Retained contacts for {pathway!r} exceed its input width: "
f"{retained[pathway]} > {input_dims[pathway]}"
)
nonsomatic_per_soma = sum(level_widths)
nonsomatic_total = nonsomatic_per_soma * soma_count
synaptic_compartments = nonsomatic_total + (
soma_count if bool(somatic_synapses) else 0
)
active_by_pathway = {
pathway: synaptic_compartments * count for pathway, count in retained.items()
}
candidate_by_pathway = {
pathway: synaptic_compartments * input_dims[pathway] for pathway in input_dims
}
reactivation_compartments = nonsomatic_total + (
soma_count if bool(reactivation_includes_soma) else 0
)
return StaticDendriticResourceSummary(
level_compartments_per_soma=level_widths,
nonsomatic_compartments_per_soma=nonsomatic_per_soma,
nonsomatic_compartments_total=nonsomatic_total,
synaptic_compartments_total=synaptic_compartments,
active_synapses_by_pathway=active_by_pathway,
active_synapses_total=sum(active_by_pathway.values()),
candidate_slots_by_pathway=candidate_by_pathway,
candidate_synapse_slots_total=sum(candidate_by_pathway.values()),
child_couplings_total=nonsomatic_total,
reactivation_parameters_total=(reactivation_compartments * reactivation_width),
)
def synapse_resource_records(model: torch.nn.Module) -> list[SynapseResourceRecord]:
"""Return one realized-connectivity record per dendritic pathway."""
records: list[SynapseResourceRecord] = []
seen: set[int] = set()
for branch_name, branch_layer in model.named_modules():
if not isinstance(branch_layer, DendriticBranchLayer):
continue
depth = soma_relative_dendritic_depth(branch_layer)
for attr, pathway in _SYNAPSE_PATHWAYS.items():
synapse = getattr(branch_layer, attr, None)
if synapse is None or id(synapse) in seen:
continue
seen.add(id(synapse))
if type(synapse) in {TopKLinear, DenseToSparseLinear}:
counts = _dense_candidate_topk_resource_counts(synapse)
out_features = int(counts["out_features"])
in_features = int(counts["in_features"])
candidate_slots = int(counts["candidate_slots"])
active_synapses = int(counts["active_synapses"])
realized_k_min = int(counts["realized_k_min"])
realized_k_max = int(counts["realized_k_max"])
realized_k_mean = float(counts["realized_k_mean"])
selection_policy = str(counts["selection_policy"])
mask_source = str(counts["mask_source"])
elif callable(
compact_counts_fn := getattr(
synapse,
"connectivity_resource_counts",
None,
)
):
counts = compact_counts_fn()
out_features = int(counts["out_features"])
in_features = int(counts["in_features"])
candidate_slots = int(counts["candidate_slots"])
active_synapses = int(counts["active_synapses"])
realized_k_min = int(counts["realized_k_min"])
realized_k_max = int(counts["realized_k_max"])
realized_k_mean = float(counts["realized_k_mean"])
selection_policy = str(counts["selection_policy"])
mask_source = str(counts["mask_source"])
else:
snapshot = effective_synapse_snapshot(synapse)
realized_k = snapshot.realized_k.to(dtype=torch.float32)
out_features = int(snapshot.active_mask.shape[0])
in_features = int(snapshot.active_mask.shape[1])
candidate_slots = int(snapshot.candidate_mask.ne(0).sum().item())
active_synapses = int(snapshot.active_mask.ne(0).sum().item())
realized_k_min = int(realized_k.min().item())
realized_k_max = int(realized_k.max().item())
realized_k_mean = float(realized_k.mean().item())
selection_policy = snapshot.selection_policy
mask_source = snapshot.mask_source
records.append(
SynapseResourceRecord(
module=f"{branch_name}.{attr}",
pathway=pathway,
soma_relative_depth=int(depth),
out_features=out_features,
in_features=in_features,
candidate_parameters=int(
sum(parameter.numel() for parameter in synapse.parameters())
),
candidate_slots=candidate_slots,
active_synapses=active_synapses,
realized_k_min=realized_k_min,
realized_k_max=realized_k_max,
realized_k_mean=realized_k_mean,
selection_policy=selection_policy,
mask_source=mask_source,
)
)
return records
def _dense_candidate_topk_resource_counts(
synapse: TopKLinear,
) -> dict[str, int | float | str]:
"""Count deterministic dense-candidate Top-K support without a dense mask."""
if type(synapse) is DenseToSparseLinear:
selected_k = int(synapse.current_k)
selection_policy = "dense_to_sparse"
elif type(synapse) is TopKLinear:
selected_k = int(synapse.K)
selection_policy = "topk"
else: # pragma: no cover - guarded by the caller
raise TypeError(type(synapse))
allowed_mask = synapse.connection_mask
forbidden = synapse._forbidden_input_index_per_output
if allowed_mask.numel() > 0:
allowed_per_output = allowed_mask.count_nonzero(dim=1).to(torch.long)
if forbidden.numel() > 0:
valid = forbidden >= 0
if bool(valid.any()):
rows = torch.arange(synapse.out_features, device=forbidden.device)
forbidden_allowed = allowed_mask[
rows[valid],
forbidden[valid].to(torch.long),
].to(torch.long)
allowed_per_output[valid] -= forbidden_allowed
mask_source = "structured_candidate_mask"
else:
allowed_per_output = torch.full(
(synapse.out_features,),
synapse.in_features,
dtype=torch.long,
device=synapse.pre_w.device,
)
if forbidden.numel() > 0:
allowed_per_output -= (forbidden >= 0).to(
device=allowed_per_output.device,
dtype=torch.long,
)
mask_source = "dense_candidates"
realized = allowed_per_output.clamp(max=selected_k)
return {
"out_features": int(synapse.out_features),
"in_features": int(synapse.in_features),
"candidate_slots": int(allowed_per_output.sum().item()),
"active_synapses": int(realized.sum().item()),
"realized_k_min": int(realized.min().item()),
"realized_k_max": int(realized.max().item()),
"realized_k_mean": float(realized.to(torch.float64).mean().item()),
"selection_policy": selection_policy,
"mask_source": mask_source,
}
def _tensor_tree_numel(value: Any, seen: set[int]) -> int:
if isinstance(value, torch.Tensor):
if id(value) in seen:
return 0
seen.add(id(value))
return int(value.numel())
if is_dataclass(value) and not isinstance(value, type):
return sum(
_tensor_tree_numel(getattr(value, field.name), seen)
for field in fields(value)
)
if isinstance(value, dict):
return sum(_tensor_tree_numel(item, seen) for item in value.values())
if isinstance(value, (list, tuple)):
return sum(_tensor_tree_numel(item, seen) for item in value)
return 0
def persistent_state_scalars(core: torch.nn.Module) -> int:
"""Count recurrent state scalars retained per sample between timesteps."""
init_state = getattr(core, "init_state", None)
if callable(init_state):
state = init_state(
batch_size=1,
device=torch.device("cpu"),
dtype=torch.float32,
)
return _tensor_tree_numel(state, set())
config = getattr(core, "config", None)
cell_type = str(getattr(config, "cell_type", "")).lower()
hidden_dim = int(getattr(config, "hidden_dim", 0) or 0)
num_layers = int(getattr(config, "num_layers", 1) or 1)
if cell_type in {"vanilla", "gru"}:
return hidden_dim * num_layers
if cell_type == "lstm":
return 2 * hidden_dim * num_layers
return 0
[docs]
def topk_parameter_inventory(model: torch.nn.Module) -> dict[str, int]:
"""Count trainable storage versus retained dense-candidate Top-K weights.
Works for conventional affine controls as well as dendritic models. Other
parameter families are counted at their stored size; dynamic indexed or
scheduled sparse policies require their own resource records. This is a
parameter count, not a claim about executable bytes or runtime.
"""
stored = sum(p.numel() for p in model.parameters() if p.requires_grad)
candidate = retained = 0
seen: set[int] = set()
for module in model.modules():
if type(module) is TopKLinear and module.pre_w.requires_grad:
if id(module.pre_w) in seen:
raise ValueError(
"Shared Top-K weights require an explicit support accounting policy"
)
seen.add(id(module.pre_w))
candidate += module.pre_w.numel()
retained += int(
_dense_candidate_topk_resource_counts(module)["active_synapses"]
)
return {
"training_parameters": stored,
"candidate_weights": candidate,
"retained_parameters": stored - candidate + retained,
"buffer_bytes": sum(
value.numel() * value.element_size() for value in model.buffers()
),
}
def model_resource_summary(model: torch.nn.Module) -> dict[str, Any]:
"""Return auditable parameter, connectivity, and state accounting.
Connectivity is counted for the evaluation-mode model, whose stochastic
selectors use their deterministic top-K masks.
"""
core = getattr(model, "core_network", model)
modes = {module: module.training for module in model.modules()}
model.eval()
try:
records = synapse_resource_records(model)
finally:
for module, training in modes.items():
module.training = training
record_provider = getattr(core, "connectivity_resource_records", None)
if callable(record_provider):
provided = record_provider()
if not isinstance(provided, list):
raise TypeError("connectivity_resource_records() must return a list")
records.extend(
(
record
if isinstance(record, SynapseResourceRecord)
else SynapseResourceRecord(**record)
)
for record in provided
)
total_parameters = int(sum(parameter.numel() for parameter in model.parameters()))
trainable_parameters = int(
sum(
parameter.numel()
for parameter in model.parameters()
if parameter.requires_grad
)
)
core_total_parameters = int(
sum(parameter.numel() for parameter in core.parameters())
)
core_trainable_parameters = int(
sum(
parameter.numel()
for parameter in core.parameters()
if parameter.requires_grad
)
)
synapse_candidate_parameters = int(
sum(record.candidate_parameters for record in records)
)
summary = {
"total_parameters": total_parameters,
"trainable_parameters": trainable_parameters,
"core_total_parameters": core_total_parameters,
"core_trainable_parameters": core_trainable_parameters,
"synapse_candidate_parameters": synapse_candidate_parameters,
"non_synaptic_parameters": total_parameters - synapse_candidate_parameters,
"candidate_synapse_slots": int(
sum(record.candidate_slots for record in records)
),
"active_synapses": int(sum(record.active_synapses for record in records)),
"persistent_state_scalars_per_sample": persistent_state_scalars(core),
"synapses": [asdict(record) for record in records],
}
ledger_provider = getattr(core, "resource_ledger", None)
if callable(ledger_provider):
summary["mechanism_ledger"] = ledger_provider()
return summary
__all__ = [
"StaticDendriticResourceSummary",
"SynapseResourceRecord",
"dendritic_level_widths",
"model_resource_summary",
"persistent_state_scalars",
"static_dendritic_resource_summary",
"synapse_resource_records",
"topk_parameter_inventory",
]