gresil 0.1.0-alpha.9

Spiking neural networks in no_std Rust, i16 fixed point, for microcontrollers
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
// SPDX-FileCopyrightText: 2026 philo-the-dendron
// SPDX-License-Identifier: AGPL-3.0-or-later
//! The compare of `tests/traces/`: every file regenerates line for line
//! from `tests/traces/cases.rs`, every header describes its rows, the
//! board case folds to the bench record, the reference vector matches an
//! unbounded-integer neuron model written here, and no file sits in the
//! directory without a case. Part of the test gate
//! (`cargo test --workspace`); alone,
//! `cargo test -p gresil --test traces`.
//!
//! The fixed network is compared here too: `frozen.rs` regenerates line
//! for line from `cases::freeze`; every frozen network, stepped from its
//! arrays, writes its trace file's text through the library's row
//! writer, `gresil::trace::row`; every
//! plasticity-off case, converted by `FixedNetwork::try_from`, steps as
//! the std network; and the frozen `feedforward-8` over 10,000 steps
//! folds to the values the board's network arm must print.
//!
//! A trace that moves is red here. A deliberate move is regenerated by
//! `cargo run -p gresil --features unstable-stdp,unstable-freeze --example trace -- write`
//! and committed with a message that says which cases moved and why.

#[path = "traces/cases.rs"]
mod cases;
#[rustfmt::skip]
#[path = "traces/frozen.rs"]
mod frozen;

use cases::{Case, CASES, DIR};
use gresil::lif_neuron::{MEMBRANE_MV_MAX, MEMBRANE_MV_MIN};
use gresil::trace::{row, Kind, Rows};
use gresil::{FixedNetwork, FixedSynapse};

/// The format line's name and version as a reader expects it, checked on
/// every header below; the library's own is private to
/// `gresil::trace`.
const FORMAT: &str = "neuralos-trace v1";

/// The bench record of the firmware's neuron, `evidence/esp32c3-bringup/
/// README.md`: the spike count, the first spike's step, and the wrapping
/// fold `× 31 + step` over the spike steps, both burst arms.
const BOARD_SPIKES: usize = 147;
const BOARD_FIRST_STEP: u32 = 55;
const BOARD_CHECKSUM: u32 = 0x8cd1_e63b;

/// The network arm: the frozen `feedforward-8` stepped `NETWORK_STEPS`
/// steps on its constant drive, not its 150-step trace. The spike count,
/// the first spike's step, and the wrapping fold `× 31 + step`, `× 31 +
/// id` over every spike in step-then-id order: the values the firmware's
/// network arm must print on the board.
const NETWORK_STEPS: u32 = 10_000;
const NETWORK_SPIKES: u32 = 3_377;
const NETWORK_FIRST_STEP: u32 = 5;
const NETWORK_CHECKSUM: u32 = 0x7e70_0ee1;

fn read(case: &Case) -> String {
    let path = cases::path(case);
    std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{}: {e}", path.display()))
}

/// The first line where two texts part: its number, from 1, and the two
/// lines, `<end>` past a text's last line. `None` when the texts are
/// equal.
fn first_difference(have: &str, want: &str) -> Option<(usize, String, String)> {
    if have == want {
        return None;
    }
    let (mut a, mut b) = (have.lines(), want.lines());
    for n in 1.. {
        match (a.next(), b.next()) {
            (None, None) => {
                return Some((n, "<end>".into(), "<end>; the line endings differ".into()));
            }
            (x, y) if x != y => {
                return Some((n, x.unwrap_or("<end>").into(), y.unwrap_or("<end>").into()));
            }
            _ => {}
        }
    }
    unreachable!("the texts differ, so some line does")
}

/// One parsed row. The time is the `u64` the writer prints, as wide as the
/// networks' clock.
struct Row {
    step: u32,
    time_us: u64,
    ids: Vec<u16>,
    membranes: Vec<i16>,
}

fn rows(text: &str) -> Vec<Row> {
    text.lines()
        .skip(1)
        .map(|line| {
            let fields: Vec<&str> = line.split(" | ").collect();
            assert_eq!(fields.len(), 3, "three bar-separated fields: {line:?}");
            let mut head = fields[0].split(' ');
            let mut num = |what: &str| -> u64 {
                head.next()
                    .and_then(|s| s.parse().ok())
                    .unwrap_or_else(|| panic!("{what} in {line:?}"))
            };
            let step = u32::try_from(num("step")).expect("a step fits u32");
            let time_us = num("time_us");
            assert!(head.next().is_none(), "step and time only: {line:?}");
            let ids = fields[1]
                .split_whitespace()
                .map(|s| s.parse().unwrap_or_else(|_| panic!("id in {line:?}")))
                .collect();
            let membranes = fields[2]
                .split_whitespace()
                .map(|s| s.parse().unwrap_or_else(|_| panic!("membrane in {line:?}")))
                .collect();
            Row {
                step,
                time_us,
                ids,
                membranes,
            }
        })
        .collect()
}

/// A header field's value, `key=value`.
fn field<'a>(header: &'a str, key: &str) -> &'a str {
    header
        .split(' ')
        .find_map(|kv| kv.strip_prefix(key).and_then(|v| v.strip_prefix('=')))
        .unwrap_or_else(|| panic!("{key}= in {header:?}"))
}

/// The case a frozen module was written from, by name.
fn case_named(name: &str) -> &'static Case {
    CASES
        .iter()
        .find(|c| c.name == name)
        .unwrap_or_else(|| panic!("frozen module {name} has no case"))
}

#[test]
fn every_case_regenerates_line_for_line() {
    for case in CASES {
        if let Some((n, have, want)) = first_difference(&read(case), &cases::render(case)) {
            panic!(
                "trace {} moved at line {n}:\n  file: {have}\n  code: {want}\nA deliberate move is \
                 regenerated by `cargo run -p gresil --features \
                 unstable-stdp,unstable-freeze --example trace -- write`, committed with the why.",
                case.name
            );
        }
    }
}

#[test]
fn every_header_describes_its_rows() {
    for case in CASES {
        let text = read(case);
        let header = text.lines().next().expect("a header");
        assert!(
            header.starts_with(&format!("# {FORMAT} case={} ", case.name)),
            "{header:?}"
        );
        let n: usize = field(header, "n").parse().expect("n");
        let dt_us: u32 = field(header, "dt_us").parse().expect("dt_us");
        let steps: u32 = field(header, "steps").parse().expect("steps");
        assert_eq!(steps, case.steps, "{}", case.name);
        let rows = rows(&text);
        match case.rows {
            Rows::All => {
                assert_eq!(field(header, "rows"), "all", "{}", case.name);
                assert_eq!(
                    rows.len(),
                    steps as usize,
                    "{}: one row per step",
                    case.name
                );
                assert!(
                    rows.iter().enumerate().all(|(i, r)| r.step as usize == i),
                    "{}: steps in order from 0",
                    case.name
                );
            }
            Rows::Spikes => {
                assert_eq!(field(header, "rows"), "spikes", "{}", case.name);
                assert!(
                    rows.iter().all(|r| !r.ids.is_empty() && r.step < steps),
                    "{}: every row is a spiking step inside the run",
                    case.name
                );
                assert!(
                    rows.windows(2).all(|w| w[0].step < w[1].step),
                    "{}: steps ascend",
                    case.name
                );
            }
        }
        for r in &rows {
            assert_eq!(
                r.time_us,
                u64::from(r.step) * u64::from(dt_us),
                "{}: time is step × dt",
                case.name
            );
            assert_eq!(
                r.membranes.len(),
                n,
                "{}: one membrane per neuron",
                case.name
            );
            assert!(
                r.ids.windows(2).all(|w| w[0] < w[1]) && r.ids.iter().all(|&id| (id as usize) < n),
                "{}: ids ascend and index a neuron",
                case.name
            );
        }
    }
}

#[test]
fn the_board_case_folds_to_the_bench_record() {
    let case = CASES
        .iter()
        .find(|c| c.name == "one-neuron-board")
        .expect("the board case");
    let rows = rows(&read(case));
    assert!(
        rows.iter().all(|r| r.ids == [0]),
        "every row is a spike of the one neuron"
    );
    assert_eq!(rows.len(), BOARD_SPIKES, "spike count");
    assert_eq!(rows[0].step, BOARD_FIRST_STEP, "first spike step");
    let checksum = rows
        .iter()
        .fold(0u32, |acc, r| acc.wrapping_mul(31).wrapping_add(r.step));
    assert_eq!(checksum, BOARD_CHECKSUM, "the fold of the spike steps");
}

#[test]
fn the_reference_vector_matches_the_neuron_model() {
    // The grid the model clamps to, as the neuron documents it; the
    // crate's constants must agree, loudly, or the oracle is not one.
    const FLOOR_MV: i128 = -100;
    const CEILING_MV: i128 = 50;
    assert_eq!(
        (MEMBRANE_MV_MIN, MEMBRANE_MV_MAX),
        (FLOOR_MV as i16, CEILING_MV as i16)
    );

    let mut seen = 0;
    for case in CASES.iter().filter(|c| matches!(c.kind, Kind::Reference)) {
        seen += 1;
        let cases::Run { net, drive } = (case.build)();
        assert_eq!(
            net.neuron_count(),
            1,
            "{}: the oracle is one neuron",
            case.name
        );
        let n = &net.neurons()[0];
        assert_eq!(n.noise_amplitude_pa(), 0, "{}: no noise term", case.name);
        assert_eq!(n.threshold(), i16::MAX, "{}: no spike term", case.name);
        assert_eq!(net.synapse_count(), 0, "{}: no synaptic term", case.name);

        let text = read(case);
        let header = text.lines().next().expect("a header");
        let dt_us: i128 = field(header, "dt_us").parse().expect("dt_us");
        let s = i128::from(n.voltage_resolution().scale());
        let rest = i128::from(n.resting_potential());
        let r = i128::from(n.resistance_mohm());
        let tau = i128::from(n.tau_membrane_us());
        let mut v = i128::from(n.membrane_potential());

        // The membrane equation with no width limit anywhere: the same
        // arithmetic the neuron documents, in i128, which cannot overflow,
        // with truncating division at the two places the neuron divides.
        for row in rows(&text) {
            assert!(
                row.ids.is_empty(),
                "{}: no spike in a reference vector",
                case.name
            );
            let input = i128::from(drive(row.step)[0]);
            let dt_over_tau = (dt_us * 1000) / tau;
            let leak = rest - v;
            let current = (input * r * s) / 1000;
            let delta = (dt_over_tau * (leak + current)) / 1000;
            v = (v + delta).clamp(FLOOR_MV * s, CEILING_MV * s);
            assert_eq!(
                i128::from(row.membranes[0]),
                v,
                "{} step {}: the neuron and the model part",
                case.name,
                row.step
            );
        }
    }
    assert_eq!(seen, 1, "one reference vector, the neuron");
}

#[test]
fn no_file_without_a_case() {
    let mut orphans: Vec<String> = std::fs::read_dir(DIR)
        .expect("the directory")
        .map(|e| {
            e.expect("an entry")
                .file_name()
                .to_string_lossy()
                .into_owned()
        })
        .filter(|name| name.ends_with(".trace"))
        .filter(|name| !CASES.iter().any(|c| format!("{}.trace", c.name) == *name))
        .collect();
    // Without `unstable-stdp` the `plasticity-on` case does not exist (no
    // build can turn plasticity on), and its file is the one without a case.
    #[cfg(not(feature = "unstable-stdp"))]
    orphans.retain(|name| name != "plasticity-on.trace");
    orphans.sort();
    assert!(orphans.is_empty(), "files without a case: {orphans:?}");
}

#[test]
#[cfg(feature = "unstable-freeze")]
fn the_frozen_file_regenerates_line_for_line() {
    let path = cases::frozen_path();
    let file = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{}: {e}", path.display()));
    if let Some((n, have, want)) = first_difference(&file, &cases::freeze()) {
        panic!(
            "frozen.rs moved at line {n}:\n  file: {have}\n  code: {want}\nIt is regenerated with \
             the traces by `cargo run -p gresil --features unstable-stdp,unstable-freeze \
             --example trace -- write`, committed with the why."
        );
    }
}

#[test]
fn every_frozen_network_writes_its_trace() {
    let mut replayed = 0;
    macro_rules! replay {
        ($case:ident) => {{
            use frozen::$case as c;
            let case = case_named(&stringify!($case).replace('_', "-"));
            let mut net = FixedNetwork::new(c::NEURONS, c::SYNAPSES, c::DT_US);
            let mut fired = [false; c::N];
            let mut text = format!("{}\n", c::HEADER);
            let mut step = 0u32;
            for &(count, input) in c::DRIVE {
                for _ in 0..count {
                    let time_us = net.time_us();
                    net.step(&input, &mut fired);
                    if !c::SPIKES_ONLY || fired.contains(&true) {
                        row(&mut text, step, time_us, &fired, net.neurons())
                            .expect("a String takes every write");
                    }
                    step += 1;
                }
            }
            assert_eq!(step, c::STEPS, "{}: the drive covers the run", case.name);
            if let Some((n, have, want)) = first_difference(&read(case), &text) {
                panic!(
                    "{}: the frozen network parts from its trace at line {n}:\n  file:  {have}\n  \
                     fixed: {want}",
                    case.name
                );
            }
            replayed += 1;
        }};
    }
    frozen::for_each_frozen!(replay);
    assert!(replayed > 0, "for_each_frozen! reached no module");
}

#[test]
fn every_plasticity_off_case_steps_as_the_std_network() {
    let mut compared = 0;
    macro_rules! compare {
        ($case:ident) => {{
            use frozen::$case as c;
            let case = case_named(&stringify!($case).replace('_', "-"));
            let cases::Run { mut net, drive } = (case.build)();
            let mut fixed = FixedNetwork::<{ c::N }, { c::S }>::try_from(&net)
                .unwrap_or_else(|e| panic!("{}: {e}", case.name));
            // THE EMITTED TEXT, before the first step: this is the only
            // test that holds both sides (the compiled constants and the
            // case that wrote them), so for a field no step reads,
            // `neuron_type`, these two lines are the only pin the text
            // has. Each message names the case: the
            // panic location is the macro's one call site for all of
            // them and says nothing.
            assert_eq!(
                c::NEURONS
                    .iter()
                    .map(|n| format!("{n:?}"))
                    .collect::<Vec<_>>(),
                net.neurons()
                    .iter()
                    .map(|n| format!("{n:?}"))
                    .collect::<Vec<_>>(),
                "{}: the frozen neurons are the case's",
                case.name
            );
            assert_eq!(
                c::SYNAPSES.as_slice(),
                FixedSynapse::from_network(&net).as_slice(),
                "{}: the frozen synapses are the case's",
                case.name
            );
            let mut fired = [false; c::N];
            for step in 0..case.steps {
                let input = drive(step);
                let spikes = net.step(&input).expect("a built case steps");
                let input: [i16; c::N] = input.try_into().expect("one current per neuron");
                fixed.step(&input, &mut fired);
                let want: Vec<usize> = spikes.iter().map(|s| usize::from(s.neuron_id)).collect();
                let got: Vec<usize> = (0..c::N).filter(|&i| fired[i]).collect();
                assert_eq!(got, want, "{} step {step}: the spikes", case.name);
                for (f, s) in fixed.neurons().iter().zip(net.neurons()) {
                    assert_eq!(
                        f.membrane_potential(),
                        s.membrane_potential(),
                        "{} step {step}: neuron {}",
                        case.name,
                        s.id()
                    );
                }
            }
            compared += 1;
        }};
    }
    frozen::for_each_frozen!(compare);
    let off = CASES
        .iter()
        .filter(|c| !(c.build)().net.plasticity_enabled())
        .count();
    assert_eq!(compared, off, "every plasticity-off case is frozen");
}

#[test]
fn the_network_arm_folds_to_its_pin() {
    use frozen::feedforward_8 as c;
    let [(_, input)] = c::DRIVE else {
        panic!("feedforward-8's drive is one run: constant");
    };
    let mut net = FixedNetwork::new(c::NEURONS, c::SYNAPSES, c::DT_US);
    let mut fired = [false; c::N];
    let (mut spikes, mut first_step, mut checksum) = (0u32, None, 0u32);
    for step in 0..NETWORK_STEPS {
        net.step(input, &mut fired);
        for (id, _) in (0u32..).zip(fired).filter(|&(_, f)| f) {
            spikes += 1;
            first_step.get_or_insert(step);
            checksum = checksum
                .wrapping_mul(31)
                .wrapping_add(step)
                .wrapping_mul(31)
                .wrapping_add(id);
        }
    }
    assert_eq!(
        (spikes, first_step, checksum),
        (NETWORK_SPIKES, Some(NETWORK_FIRST_STEP), NETWORK_CHECKSUM),
        "(spike count, first spike step, fold)"
    );
}