neuromod 0.4.0

A high-performance Rust SNN library for neuroscience research and pure spiking neural network library featuring LIF, Izhikevich, Hebbian, Nagumo, Lapicque and Hodgkin-Huxley dynamics.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# neuromod

A generalized Rust library for spiking neural networks (SNNs), centered on biologically grounded neuron models, neuromodulation, and plasticity.

`neuromod` is designed to be a reusable core: topology-neutral at initialization, dynamically sizable at runtime, and strict about input shape validation.

## Highlights

- Dynamic network sizing with `SpikingNetwork::with_dimensions(...)`
- Backward-compatible default constructor: `SpikingNetwork::new()`
- Strict step contract: `Result<Vec<usize>, StepError>`
- Neutral initialization (blank synaptic weights; no hardcoded domain topology)
- Canonical neuron models included:
  - Lapicque
  - LIF
  - GIF (Generalized Integrate-and-Fire)
  - Izhikevich
  - FitzHugh-Nagumo
  - Hodgkin-Huxley
- Classical Hebbian STDP utilities and reward-modulated learning components

## Installation

```toml
[dependencies]
neuromod = "0.4.0"
```

## Quick Start

```rust
use neuromod::{NeuroModulators, SpikingNetwork};

fn main() {
    let mut network = SpikingNetwork::new(); // default: 16 LIF, 5 Izh, 16 channels
    let stimuli = [0.5_f32; 16];
    let modulators = NeuroModulators::default();

    let spikes = network.step(&stimuli, &modulators).unwrap();
    println!("Spiking neuron indices: {spikes:?}");
}
```

## Dynamic Dimensions

```rust
use neuromod::{NeuroModulators, SpikingNetwork};

fn main() {
    let mut network = SpikingNetwork::with_dimensions(518, 5, 518);
    let modulators = NeuroModulators::default();
    let stimuli = vec![0.25_f32; 518];

    let spikes = network.step(&stimuli, &modulators).unwrap();
    println!("Spike count: {}", spikes.len());
}
```

## Step Errors (Shape Validation)

`step` validates that `stimuli.len() == num_channels` and returns an error on mismatch.

```rust
use neuromod::{NeuroModulators, SpikingNetwork, StepError};

fn main() {
    let mut network = SpikingNetwork::with_dimensions(32, 4, 32);
    let modulators = NeuroModulators::default();
    let bad_stimuli = vec![0.1_f32; 31];

    match network.step(&bad_stimuli, &modulators) {
        Ok(_) => unreachable!("expected length mismatch"),
        Err(StepError::InputLenMismatch { expected, got }) => {
            println!("InputLenMismatch: expected {expected}, got {got}");
        }
    }
}
```

## Neuromodulators

`NeuroModulators` supports both direct control and signal-derived initialization.

```rust
use neuromod::NeuroModulators;

fn main() {
    // (thermal_signal, power_signal, throughput_signal, timing_signal)
    let mut mods = NeuroModulators::from_signals(75.0, 300.0, 0.05, 2640.0);

    mods.add_reward(0.2);
    mods.add_stress(0.1);
    mods.boost_focus(0.3);
    mods.add_aux_reward(0.4);
    mods.decay();

    println!("dopamine={:.3}, aux={:.3}", mods.dopamine, mods.aux_dopamine);
}
```

## Included Components

- `SpikingNetwork`, `StepError`
- `NeuroModulators`
- Neuron models:
  - `LifNeuron`
  - `GifNeuron`
  - `IzhikevichNeuron`
  - `LapicqueNeuron`
  - `FitzHughNagumoNeuron`
  - `HodgkinHuxleyNeuron`
- Learning/plasticity:
  - `apply_classical_stdp`, `StdpParams`, `HebbianIzhikevichNetwork`
  - `EligibilityTrace`, `RmStdpConfig`

## Examples

Run included examples:

```bash
cargo run --example basic
cargo run --example rstdp_demo
```

## Development

```bash
cargo check
cargo test
cargo bench --no-run
```

## License

GPL-3.0

## Links

- Crates.io: https://crates.io/crates/neuromod
- Docs.rs: https://docs.rs/neuromod
- Repository: https://github.com/Limen-Neural/neuromod