Network Simulation Engine

Module: sc_neurocore.network (re-exported from sc_neurocore.network.__init__) Source: src/sc_neurocore/network/ — 12 files, 4065 LOC Status (v3.14.0): core orchestrator + Population/Projection/topology/monitors fully wired; Rust network dispatch and MPI per-rank Rust dispatch are implemented, with Python fallback when the engine wheel is absent; MPIRunner has 12 mocked-mpi4py tests; topology/projection compute paths are still pure-Python (no Rust path yet).

This page covers the simulation engine — the declarative Network container, populations of neurons, sparse Projection connectivity (with delays + STDP), connectivity generators, spike/state/rate monitors, stimulus sources, the multi-backend dispatcher (auto/python/rust/mpi), and the LIF-network Verilog exporter. Two specialised circuit models that ship in the same directory will be documented on their own pages once written (planned: api/cortical_column.md, api/gamma_oscillation.md); both are flagged in §14.1 below for fidelity violations.

1. Overview

The simulation engine is declarative: you instantiate populations and projections, hand them to a Network, and call .run(duration, dt). The network registers each object by type (Population, Projection, SpikeMonitor, StateMonitor, RateMonitor, TimedArray, PoissonInput, StepCurrent) and runs the appropriate per-step pipeline:

each timestep t:
  for each population: zero its current accumulator
  apply stimuli → currents
  apply projections (CSR matvec + delay) → currents
  for each population: step neurons, record spikes
  update plasticity (STDP) on projections that have it
  optional: Fisher Information Metric self-observation feedback

Network.run selects one of three backends:

• 'python' — the pure-Python loop above
• 'rust' — delegates to sc_neurocore_engine.NetworkRunner (PyO3) when every population's model_name is in NetworkRunner.supported_models() and there are no stimuli and no plasticity
• 'mpi' — partitions populations round-robin across MPI ranks and exchanges spikes via Allgatherv

'auto' (default) picks 'rust' when its preconditions hold, otherwise falls back to 'python'.

2. Public Surface

The module re-exports 18 public symbols from sc_neurocore.network.__init__:

The submodule cortical_column exports CorticalColumn; the submodule gamma_oscillation exports PINGCircuit. Both are documented separately.

3. Network — orchestrator

3.1 Constructor

Network(*objects, seed: int = 42, fim_lambda: float = 0.0)

Accepts any number of Population, Projection, monitor or stimulus objects positionally. Each is registered into the corresponding internal list by isinstance dispatch; unknown types raise TypeError.

fim_lambda enables a Fisher Information Metric self-observation feedback (_apply_fim, network.py:249): each timestep the per-source weight is pulled toward the population mean of its source spike vector by λ_fim · (activity_i − μ) / N. The mechanism is derived from scpn-quantum-control NB26-28 (FIM alone synchronises at K=0, λ ≥ 8, increases Φ by 73 %, and is topology-universal). Set to 0.0 (default) to disable.

3.2 run

def run(
    duration: float,
    dt: float = 0.001,
    progress: bool = False,
    backend: str = "auto",
    spike_gating: bool = False,
) -> None

• duration is in seconds; dt is the timestep in seconds. n_steps is int(round(duration/dt)).
• backend ∈ {"auto", "python", "rust", "mpi"}. "rust" raises if the engine wheel is not importable; "auto" silently falls back to Python.
• spike_gating (Python backend only) skips neurons with zero input current whose voltage is within 1 % of resting potential. Useful for sparse networks where most neurons are silent.

The Python loop (_run_python, network.py:165) is the reference implementation; the Rust loop (_run_rust, network.py:123) round-trips populations and projections through NetworkRunner.add_population / add_projection, runs n_steps, then decodes packed spike events (u64 = neuron_id<<32 | timestep) back into Python SpikeMonitor records.

3.3 Rust dispatch criteria (_can_use_rust)

Network._can_use_rust (line 80) returns True only when:

1. len(self.stimuli) == 0 — no TimedArray/PoissonInput/StepCurrent in this network.
2. The Rust engine import succeeded (_get_rust_engine() is not False).
3. Every pop.model_name (or its *Neuron-stripped form) is in NetworkRunner.supported_models().
4. No projection has a non-empty plasticity field.

When any of these fails and backend="auto", the network falls back to Python without warning. Pass backend="python" explicitly when you need deterministic dispatch.

3.4 Backend matrix

4. Population — vectorised neurons

Population(model: type | str, n: int,
           params: dict | None = None,
           label: str | None = None)

model may be a class or a string name resolved through sc_neurocore.neurons.models (lazy registry of 130 lazy-loaded classes — see api/neurons.md). The constructor instantiates n independent neuron objects with identical parameters and exposes:

• population.neurons — list[NeuronProtocol] of length n
• population.voltages — read-only np.ndarray view (kept in sync via _sync_voltages)
• population.step_all(currents, spike_gating=False) — returns binary spike vector np.ndarray[int8] of length n
• population.reset_all() — calls reset() or reset_state() on each neuron
• population.get_states() — collects all per-neuron state variables into arrays (uses get_state(), __dataclass_fields__, or falls back to ["v"])
• population.set_voltages(arr) — sync voltages from an external source (used by the Rust round-trip)

Populations are hashable by identity (id(pop)); the Network keeps pop_to_currents keyed by id(pop) so two Population objects with identical parameters are still independent.

4.1 Spike gating

When spike_gating=True, step_all skips neurons that have no input current and sit within 1 % of their resting potential. This makes per-step compute roughly proportional to the active neuron count, which matters for sparse networks where most neurons are silent for most of the simulation. The skipped neurons do not advance — when the population is queried later, their voltages are stale until they receive input again. Models that track sub-threshold leak via internal calls to step() lose that leak during skipped steps.

5. Projection — CSR connectivity + delays + STDP

Projection(
    source: Population,
    target: Population,
    weight: float,
    probability: float = 1.0,
    delay: float | np.ndarray = 0.0,
    topology: str | tuple[np.ndarray, np.ndarray, np.ndarray] = "random",
    plasticity: str | None = None,
    seed: int = 42,
    weight_threshold: float = 0.0,
)

Stores connectivity in CSR (indptr, indices, data). Source spikes propagate via _csr_matvec (no delay) or one of two delayed variants:

• delay = 0.0 — direct CSR matvec, no buffering
• delay = scalar — uniform axonal delay; output goes through a circular buffer of shape (steps, target.n) and is read out one timestep behind
• delay = ndarray of length n_synapses — per-synapse delay; source spike history is stored as a ring buffer of shape (max_delay+1, source.n) and each synapse reads from spike_history[(hist_idx − d_k) % max_delay]

Per-synapse delays implement Hammouamri et al. 2023 (DCLS) and Masquelier's DelRec — learnable synaptic delays in spiking nets.

5.1 weight_threshold pruning

When weight_threshold > 0.0, the matvec skips synapses with |data[k]| ≤ weight_threshold. Useful after sparse pruning to avoid wasted multiplications. The branch is in the inner Python loop (projection.py:47) so the speed-up is real but linear in connection count.

5.2 STDP plasticity

plasticity="stdp" activates trace-based STDP in update_plasticity (projection.py:258):

• Pre/post traces decay with tau (default 20 timesteps), incremented on spike
• LTD on pre-spike: data[k] -= a_minus * post_trace[j]
• LTP on post-spike: data[k] += a_plus * directional_bias * pre_trace[i]
• Weights clipped at 0 (no sign change)

directional_bias scales a_plus per projection. The scpn-quantum-control NB19 measurement of autonomic → cortical asymmetry suggests 1.36 for bottom-up (sensory → higher-order) projections; default 1.0 keeps learning symmetric.

Self-projections (source is target) additionally trigger _enforce_symmetry after each STDP update — W_ij and W_ji are averaged. Required because gradient/STDP updates break W = W^T after ~30 steps (SPO Finding #7); asymmetric coupling hurts synchronisation by +12 % (quantum-control NB24).

6. Topology generators

All generators in topology.py return a (indptr, indices, data) CSR tuple ready to feed into Projection(..., topology=tuple).

6.1 Performance (this workstation, 2026-04-17)

Measured directly by calling each generator and timing with time.perf_counter(). All inputs are deterministic seeds.

small_world and scale_free use Python lists during construction; for n ≥ 10 000 they become noticeably slow and are candidates for the planned Rust path (task #13). grid_topology and ring_topology already vectorise adequately for typical sizes.

7. Stimulus sources

Each stimulus carries a target: Population | None slot that the network populates when adding the stimulus to a population (the convenience pattern is to set stim.target = pop after construction). When target is None, the network broadcasts to populations[0].

PoissonInput owns a np.random.default_rng(seed); runs are deterministic when seeds are pinned. TimedArray and StepCurrent are deterministic by construction.

8. Monitors

8.1 SpikeMonitor

Records (neuron_id, timestep) pairs. Two ingestion paths:

• record(spikes, t) — accepts the binary spike vector emitted by Population.step_all (Python backend)
• record_event(neuron_id, t) — accepts a single decoded event (used by the Rust round-trip, which packs u64 = neuron_id<<32 | timestep for efficient transport)

Read-out helpers:

8.2 StateMonitor

Captures population.get_states() snapshots at each call to snapshot(t). Configure with variables: list[str] (default ["v"]) and an optional record: list[int] to subset recorded neurons.

8.3 RateMonitor

Bins spike counts into fixed-duration windows (bin_ms), then converts to per-neuron mean rate (Hz). The bin-completion check uses steps_per_bin = max(1, int(bin_ms / 1000.0 / dt)), so a 10 ms bin at dt=1 ms flushes every 10 steps.

9. Verilog export

export_verilog(network, output_dir, target="ice40") -> str emits a top-level sc_network_top SystemVerilog module that wires one sc_lif_array instance per population. Each population's parameters are read from the first neuron in pop.neurons (v_threshold, v_reset, tau) and converted to fixed-point by multiplying by 256 (Q8.8). The allowed neuron model whitelist is _LIF_MODELS (17 LIF variants); any non-LIF model raises SCHardwareError.

The exporter writes two files:

• sc_network_top.v — module wrapper with one pop_<i> instance per population
• params.vh — \define POP__SIZE n` per population

each rank r:
  local_pops = {i for i in range(n_pops) if i % size == r}
  for t in range(n_steps):
    propagate local + cross-rank projections into local_currents
    step local populations → local_spikes
    Allgatherv local_spikes → all_spikes
    if r == 0: feed monitors with all_spikes

net = Network(pop, proj, mon, stim, seed=1)
net.run(duration=0.2, dt=0.001, backend="python")

PYTHONPATH=src python3 -m pytest \
    tests/test_network_basic.py \
    tests/test_network_monitors_stimulus.py \
    tests/test_network/test_to_torch_bridge.py \
    tests/test_cortical_column.py \
    tests/test_cortical_column_dynamics.py \
    tests/test_gamma_oscillation.py \
    tests/test_topology.py \
    tests/test_topology_generators.py -q
# 87 passed in 2.26s  (verified 2026-04-17)