Tutorial: A Heterogeneous Multi-Receptor E/I RSNN¶
This tutorial builds a recurrent network with excitatory and inhibitory
neurons, four receptor channels, receptor-specific synaptic kinetics, Dale's
law, and a trainable sparse connection. The model uses semantic edge metadata:
each edge stores its pre, post, and receptor attributes. The flattened
n_post * n_receptor output layout is derived by SparseConnection for the
PSC implementation; it is not the model's connectivity representation.
This is the recommended starting point for a new heterogeneous model. The
legacy from_hetersynapse constructor remains useful when importing a matrix
produced by older connectome helpers, but new code should normally construct
semantic edges directly.
Model Design¶
We use one neuron population with the excitatory cells first and inhibitory cells second. The receptor channel is the ordered pair of source and target cell types:
| Channel | Source | Target | Sign |
|---|---|---|---|
EE |
E | E | positive |
EI |
E | I | positive |
IE |
I | E | negative |
II |
I | I | negative |
The same semantic connection therefore expresses both cell-type routing and
Dale's law. HeterSynapsePSC maintains a PSC state per receptor channel and
sums the channels back to one current per target neuron before GLIF3 updates
its voltage.
Create Semantic E/I Edges¶
The helper below generates a reproducible random graph without SciPy or a
physically expanded matrix. It returns the edge list, receptor ids, signed
initial weights, and the table used by HeterSynapsePSC.get_psc for inspection.
import pandas as pd
import torch
def make_ei_edges(
n_exc: int,
n_inh: int,
density: float = 0.08,
) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, pd.DataFrame]:
n_neuron = n_exc + n_inh
generator = torch.Generator().manual_seed(11)
connected = torch.rand(n_neuron, n_neuron, generator=generator) < density
connected.fill_diagonal_(False)
pre, post = connected.nonzero(as_tuple=True)
pre_is_exc = pre < n_exc
post_is_exc = post < n_exc
# EE=0, EI=1, IE=2, II=3; output is post-major, then receptor.
receptor = (~pre_is_exc).to(torch.long) * 2 + (~post_is_exc).to(torch.long)
magnitude = 0.08 + 0.04 * torch.rand(pre.numel(), generator=generator)
values = torch.where(pre_is_exc, magnitude, -magnitude)
receptor_index = pd.DataFrame(
{
"receptor_index": [0, 1, 2, 3],
"pre_receptor_type": ["E", "E", "I", "I"],
"post_receptor_type": ["E", "I", "E", "I"],
}
)
return pre, post, receptor, values, receptor_index
n_exc, n_inh = 64, 16
n_neuron = n_exc + n_inh
pre, post, receptor, values, receptor_index = make_ei_edges(n_exc, n_inh)
The receptor ids are aligned with the edge arrays. The connection validates
that each id is in [0, n_receptor) and derives the expanded output index as
post * n_receptor + receptor.
Build the Connection and Heterogeneous PSC¶
Synapse(dale=True) records the sign at construction and keeps each learned
edge on that side of zero after constrain_net. The per-receptor time
constants below are repeated once per post-neuron because the PSC's internal
state is flattened in post-major order:
[post0/receptor0, post0/receptor1, ..., post1/receptor0, ...].
The connection and PSC are built together in the model below, which keeps the edge metadata and receptor index table aligned from construction through training:
from torch import nn
from btorch.models import environ, functional
from btorch.models.rnn import RecurrentNN
class HeterogeneousEIRSNN(nn.Module):
def __init__(self, n_input: int, n_class: int):
super().__init__()
pre, post, receptor, values, receptor_index = make_ei_edges(n_exc, n_inh)
connection = SparseConnection.from_edges(
pre,
post,
n_pre=n_neuron,
n_post=n_neuron,
synapse=Synapse(
receptor=receptor,
n_receptor=len(receptor_index),
dale=True,
),
values=values,
hints=Hints(expected_density=0.02),
)
tau_syn = torch.tensor([5.0, 8.0, 6.0, 10.0]).repeat(n_neuron)
psc = HeterSynapsePSC(
n_neuron=n_neuron,
n_receptor=len(receptor_index),
receptor_type_index=receptor_index,
linear=connection,
base_psc=AlphaPSC,
tau_syn=tau_syn,
step_mode="s",
)
self.input = nn.Linear(n_input, n_neuron)
self.brain = RecurrentNN(
neuron=GLIF3(
n_neuron=n_neuron,
v_threshold=1.0,
v_reset=0.0,
v_rest=0.0,
c_m=1.0,
tau=20.0,
tau_ref=2.0,
step_mode="s",
),
synapse=psc,
step_mode="m",
update_state_names=("neuron.v", "synapse.psc"),
)
self.readout = nn.Linear(n_neuron, n_class)
self.receptor_index = receptor_index
@property
def recurrent_connection(self) -> SparseConnection:
return self.brain.synapse.linear
def forward(self, x: torch.Tensor):
drive = self.input(x)
spikes, states = self.brain(drive)
logits = self.readout(spikes.mean(dim=0))
return logits, spikes, states
model = HeterogeneousEIRSNN(n_input=24, n_class=4)
Train with Dale's Law¶
The training loop is ordinary PyTorch. The additional step is
constrain_net(model) after every optimizer update, which projects Dale
constrained weights back onto their recorded signs.
from btorch.models.constrain import constrain_net
from btorch.models.init import uniform_v_
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)
batch_size, n_step = 16, 40
functional.init_net_state(model, batch_size=batch_size, device=device)
uniform_v_(model.brain.neuron, set_reset_value=True)
optimizer = torch.optim.AdamW(model.parameters(), lr=2e-3)
criterion = nn.CrossEntropyLoss()
for _ in range(10):
inputs = torch.randn(n_step, batch_size, 24, device=device)
targets = torch.randint(0, 4, (batch_size,), device=device)
functional.reset_net(model, batch_size=batch_size)
optimizer.zero_grad(set_to_none=True)
with environ.context(dt=1.0):
logits, spikes, states = model(inputs)
loss = criterion(logits, targets)
loss.backward()
optimizer.step()
constrain_net(model)
If the network is trained with truncated BPTT, call functional.detach_net
between chunks rather than resetting the neuron and PSC memories. Reset only
between independent sequences or batches.
Inspect Receptor Channels and Live Weights¶
The PSC table is kept next to the model because the connection stores integer
receptor ids, not the human-readable DataFrame. get_psc accepts a
(pre_type, post_type) tuple in neuron mode.
psc = model.brain.synapse
ee_current = psc.get_psc(("E", "E"))
ie_current = psc.get_psc(("I", "E"))
all_channels = psc.get_psc() # [..., n_neuron * n_receptor]
conn = model.recurrent_connection
live_weight = conn.weight() # current autograd-aware edge values
edge_snapshot = conn.edge_table() # detached pre/post/receptor/weight snapshot
print(ee_current.shape, ie_current.shape)
print(edge_snapshot["receptor"].unique())
print(conn.n_post, conn.n_receptor, conn.out_features)
The summed psc.psc state has shape [..., n_neuron]; the inner
psc.base_psc.psc and get_psc() expose the flattened receptor channels.
After an optimizer step, call conn.weight() or get_psc() again instead of
holding an old tensor snapshot.
Backend and CUDA Graph Guidance¶
The semantic model is independent of the execution backend. Inspect or compare routes through the connection:
from btorch.sparse import runtime
print(conn.explain())
with runtime.use_backend("aten"):
reference = conn(torch.randn(2, n_neuron, device=device))
On CUDA, an expected_density hint can select a Triton push route for sparse
spike activity. Push accumulation is not bitwise reproducible. Use the pull
route or deterministic algorithms when exact reproducibility is required.
For inference with fixed batch and sequence shapes, construct
RecurrentNN(..., cudagraph=True) and initialize it before capture. This mode
does not support gradient recording. For training, prefer
torch.compile(model) and keep autograd enabled. A weight update refreshes
prepared values; changing edge ids with set_edges_ or loading a different
topology invalidates the captured graph and triggers recapture on the next
cudagraph=True call.
Common Pitfalls¶
- Do not build a new model by multiplying
n_neuronbyn_receptor. That is the lowered tensor layout, not the semantic population size. Synapse.receptoris one integer per stored edge.n_receptoris the number of possible channels, not the number of edges.- For neuron-mode inspection, use
get_psc(("E", "I")); string names are for connection-mode receptor tables. - Per-receptor
tau_synvalues must be repeated in post-major channel order when passed toAlphaPSCthroughHeterSynapsePSC. HeterSynapsePSCneedsfunctional.init_net_statebefore its first call, including when it owns a delay history.from_hetersynapseis an import adapter for physically expanded matrices. Preferfrom_edges(..., Synapse(receptor=..., delay=...))for new code.- Dale constraints are applied after
optimizer.step(), not before the backward pass.