Crate neuromod 

neuromod — Spiking neural network primitives

Biologically grounded SNN building blocks for Rust: a topology-neutral SpikingNetwork engine (LIF + Izhikevich banks), generic neuromodulators, classical STDP helpers, and reward-modulated STDP types.

Aimed at SNN / neuroscience readers learning Rust: equations and engine contracts first; idiomatic APIs second.

Requirements

• Rust 1.98.1+ (MSRV; also rust-version in Cargo.toml and rust-toolchain.toml).
• Edition 2024.
• CI-tested platforms: Linux, macOS, and Windows (GitHub Actions matrix).

Syllabus (reading order on docs.rs)

1. This page — engine vs standalone honesty and a quick start.
2. engine — SpikingNetwork and the per-tick SpikingNetwork::step contract.
3. lif / izhikevich — the two banks the engine actually wires.
4. modulators — dopamine / serotonin / acetylcholine / norepinephrine.
5. rm_stdp / hebbian — plasticity: reward-modulated eligibility traces (wired into the engine) and classical Hebbian STDP (standalone).
6. Standalone models (lapicque, gif, fitzhugh_nagumo, hodgkin_huxley) for research use outside the engine.
7. gif_layer — SparseGifHiddenLayer, a structure-of-arrays bank of GIF neurons with deterministic sparse fan-in and batched execution.
8. Evaluation and reproducibility — SpikingNetwork::step_frozen advances runtime dynamics without retaining plasticity changes, while SpikingNetwork::step_with_rng, SpikingNetwork::step_frozen_with_rng, and lif::PoissonEncoder::encode_with_rng inject a caller RNG into the live stochastic paths. See the RNG inventory.

Engine vs standalone models

• SpikingNetwork wires LIF and Izhikevich neuron banks only (with_dimensions(num_lif, num_izh, num_channels)).
• Standalone types (LapicqueNeuron, GifNeuron, FitzHughNagumoNeuron, HodgkinHuxleyNeuron, …) are usable on their own; they are not alternate engine banks.
• Plasticity: SpikingNetwork learns through EligibilityTrace / RmStdpConfig. Each step decays and accumulates one trace per synapse regardless of dopamine; dopamine gates only the trace → weight conversion, so reward can arrive after the coincidence it pays for. Classical Hebbian STDP utilities are separate and unmodulated.
• Held-out evaluation: SpikingNetwork::step_frozen runs the normal dynamics and exposes spikes while preserving weights, traces, adaptive thresholds/decay, persistent modulators, and other plasticity-controlled state. Passing zero dopamine is not a substitute because traces still decay and accumulate.

Reproducibility

The engine and lif::PoissonEncoder draw random numbers for spike encoding. Their thread-local convenience wrappers have *_with_rng variants that take &mut impl rand::Rng; the engine supplies injected variants for both normal (SpikingNetwork::step_with_rng) and frozen (SpikingNetwork::step_frozen_with_rng) stepping. One caller generator can drive a full multi-step run; the engine does not store or serialize it. All other public dynamics (LIF / Izhikevich integration, R-STDP given spike times, standalone neuron models, SparseGifHiddenLayer execution) are deterministic. SparseGifHiddenLayer topology is seeded at construction via SplitMix64, not a live rand stream.

Features

• Topology-neutral, dynamically sized SpikingNetwork
• Neuromodulators: dopamine, serotonin, acetylcholine, norepinephrine
• Reward-modulated STDP over per-synapse eligibility traces
• Frozen held-out evaluation that preserves plasticity-controlled state
• Caller-injected RNG on normal and frozen engine paths (step_with_rng, step_frozen_with_rng)

use neuromod::{NeuroModulators, SpikingNetwork};

let mut network = SpikingNetwork::new();
let stimuli = [0.5f32; 16];
let modulators = NeuroModulators::default();
let output = network.step(&stimuli, &modulators).unwrap();
println!("Neurons that fired: {output:?}");

// Or build dynamically for larger architectures.
let mut large = SpikingNetwork::with_dimensions(518, 5, 518);
let large_input = vec![0.25f32; 518];
let _ = large.step(&large_input, &modulators).unwrap();

Re-exports

pub use engine::ChannelVector;

pub use engine::ModulatorField;

pub use engine::NonFiniteClass;

pub use engine::SpikingNetwork;

pub use engine::StepError;

pub use fitzhugh_nagumo::FitzHughNagumoNeuron;

pub use gif::GifNeuron;

pub use gif::GifParams;

pub use gif_layer::GifLayerError;

pub use gif_layer::SparseGifHiddenLayer;

pub use gif_layer::SparseGifLayerConfig;

pub use gif_layer::SpikeRaster;

pub use hebbian::HebbianIzhikevichNetwork;

pub use hebbian::StdpParams;

pub use hebbian::apply_classical_stdp;

pub use hodgkin_huxley::HodgkinHuxleyNeuron;

pub use hodgkin_huxley::VoltageConvention;

pub use izhikevich::IzhikevichNeuron;

pub use lapicque::LapicqueNeuron;

pub use lif::LifNeuron;

pub use modulators::GenericReward;

pub use modulators::NeuroModulators;

pub use modulators::Observation;

pub use modulators::SignalProfile;

pub use modulators::UnitReward;

pub use modulators::apply_neuromodulation;

pub use rand::SeedableRng;

pub use rm_stdp::EligibilityTrace;

pub use rm_stdp::RmStdpConfig;

Modules

engine

Engine — LIF + Izhikevich SpikingNetwork

fitzhugh_nagumo

FitzHugh-Nagumo neuron model (1961) — the classic 2D relaxation oscillator.

gif

Generalized Integrate-and-Fire (GIF) neuron model.

gif_layer

Sparse Generalized Integrate-and-Fire (GIF) hidden layer.

hebbian

Classical Hebbian learning module.

hodgkin_huxley

Hodgkin-Huxley neuron model (1952) — the biophysical gold standard.

izhikevich

Izhikevich neurons

lapicque

Lapicque (1907) Integrate-and-Fire neuron model — the biological root of all spiking neuron models.

lif

Leaky integrate-and-fire (LIF) neurons

modulators

Neuromodulators and domain-agnostic reward hooks

rm_stdp

R-STDP (Reward-modulated Spike-Timing-Dependent Plasticity) parameters.

Structs

StdRng

A strong, fast (amortized), non-portable RNG

Constants

NUM_INPUT_CHANNELS

Number of input channels supported by default.

Traits

Rng

Trait for infallible random number generators