MNESIS

Imported from laurentperrinet/MNESIS (AGENTS.md). Install upstream with npx skills add laurentperrinet/MNESIS. Copyright stays with the author.

AGENTS.md — Developer & AI-Assistant Reference

Project Summary

MNESIS is a recurrent spiking neural network (SNN) with heterogeneous synaptic delays. The repository has two independent, buildable halves:

• src/ — Python source and Jupyter experiment notebooks. Core code lives in two modules (mnesis_boilerplate.py, mnesis_chains.py); the numbered notebooks import from them and are run sequentially.
• tex/ — LaTeX source of the paper (Perrinet26mnesis.tex), a small set of standalone TikZ figures, a bibliography, and the Springer LNCS class/style files.

This file gives rules, commands, and gotchas for agents working in the repository; it is not a place for reference data. The full parameter catalogue, per-experiment results, and notebook inventory live in README.md — point there for "what value / what result", and to the paper (tex/Perrinet26mnesis.pdf) for the camera-ready numbers.

An AI assistant was used to improve the readability of the code, not to create it; these rules guide how that formatting and testing was done.

Architecture Overview

Module Dependency Graph (src/)

notebooks (*.ipynb)
   └── mnesis_chains.py         (HD_SNN, SpikingPattern, StochasticSpikingPattern, load())
         └── mnesis_boilerplate.py    (imports, Params dataclass, utilities, SpikeF1scoreLoss)
               └── snntorch / torch / numpy / matplotlib / ...

Notebooks (src/*.ipynb) are numbered simple → complex, each loading cached artifacts from the previous one. They import from the two modules — they do not carry standalone copies of Params, HD_SNN, etc. Notebooks 01, 05, and 08 (former boilerplate, parameters, generative-model) were refactored into the two modules; any reference to those notebook numbers in old documents is stale.

src/ — Python source code

Install

pip install -r src/requirements.txt     # Python 3.10+; toolchain lives in .venv/

Conventions

• Imports belong at the top of mnesis_boilerplate.py; downstream modules and notebooks re-export via from mnesis_boilerplate import ….
• Notebooks from mnesis_boilerplate import … / from mnesis_chains import …, so they must be run from inside src/ (that is the expected CWD).
• src/mnesis_boilerplate.py Params is the authoritative hyperparameter source.
• .venv/ is git-ignored; do not commit it.
• Figure/sandbox output goes to ../figures/ (relative to src/); on the Jean Zay cluster (USER == "uvb28bo") figure saving is disabled automatically.
• datetag controls the cache-filename prefix — change it to start a new batch (current run: 2026-09-07).
• seed = 2026 (in Params) is fixed for reproducibility.

Debug mode

Set DEBUG > 1 in mnesis_boilerplate.py to shrink the problem: N_neuron, N_pattern, N_time, and num_epochs are divided by DEBUG. Use DEBUG = 1 (the default) only for production/camera-ready runs.

Cache invalidation

Artifacts are cached in cached_data/ (git-ignored). To recompute:

• delete the individual .pth, .json, .npz, or .sqlite3 file, or
• set RECOMPUTE = True at the top of the notebook to invalidate the whole cache.

File-based locking (used by the scan/optimisation notebooks): a .lock sentinel file guards against concurrent runs of the same scan.

1. If RECOMPUTE=True, delete both the data and lock files to force a restart.
2. Load existing results if present.
3. If no lock file exists, create one and start processing.
4. For each parameter value, skip it if already computed; otherwise run the scan and append to the JSON.
5. Delete the lock file when done. This avoids data corruption and allows safe incremental resumption — never delete a .lock out from under a running scan.

Test / compile the Python side

There is no unit-test framework (no pytest/CI). The checks below are the tests; run the fast one first, then a representative notebook, and only the full orchestrator when you need end-to-end verification.

cd src

# 1. Fast: modules import and build cleanly
python -c "import mnesis_boilerplate, mnesis_chains"

# 2. Representative: execute the smallest notebook (set DEBUG > 1 in mnesis_boilerplate.py first)
jupyter nbconvert --to notebook --execute --inplace 10_MNESIS_generative-model.ipynb

# 3. Full pipeline (slow): the orchestrator runs the whole notebook chain
jupyter nbconvert --to notebook --execute --inplace 99_MNESIS_run-all.ipynb

nbconvert exiting without error and writing updated outputs is a green build.

tex/ — LaTeX source code

Files

The main paper resolves experiment figures through \graphicspath{{../figures/}} (Perrinet26mnesis.tex:40): pattern.pdf, target.pdf, retrieval.pdf, the *_score.pdf curves, etc. are generated by the src/ notebooks, not built in tex/. The two TikZ figures are built in tex/. Build everything from inside tex/. Engine is lualatex (fontspec); toolchain: lualatex, latexmk -pdflua, biber.

Test / compile the LaTeX side

Full build (reproduces tex/Perrinet26mnesis.pdf):

cd tex

# 1. Standalone TikZ figures
lualatex -interaction=nonstopmode fig_izhikevich.tex
lualatex -interaction=nonstopmode fig_snntorch.tex

# 2. Experiment figures — must already exist in ../figures/
#    generate them by running the relevant notebooks in src/ (see above), e.g.
cd ../src && jupyter nbconvert --to notebook --execute --inplace 11_MNESIS_learn-synthetic.ipynb && cd ..

# 3. Build the paper (biber handled automatically by latexmk)
cd tex && latexmk -pdflua -pdf -interaction=nonstopmode Perrinet26mnesis.tex

If latexmk refuses ("gave an error in previous invocation"), latexmk -g or run lualatex twice directly. Quick, figure-independent parse check (tolerates missing ../figures/*.pdf):

cd tex && lualatex -interaction=nonstopmode Perrinet26mnesis.tex

A clean run produces tex/Perrinet26mnesis.pdf. (A Missing character: ^^V (U+0016) warning from the dsrom/microtype font is a benign known quirk, not a control character in the sources.) Generated byproducts (.aux, .bbl, .blg, .log, .fls, .fdb_latexmk, .synctex.gz, and the Perrinet26mnesis_copy.tex* scratch copy) are git-ignored — never commit them.

Notebook annotations

Each experiment notebook carries markdown documentation in a standard shape (see notebooks 10–16 for models to follow):

• H1 title (# ...) as the first markdown cell, stating the experiment in one paragraph; end it with the <!-- MNESIS-annotated --> idempotency marker so annotation passes are not applied twice.
• ## Notebook summary with exactly three ### sub-sections: ### Pipeline (numbered stages), ### Main outputs (caches + figures), ### Notes (gotchas; keep known bugs flagged here rather than silently fixing scan cells).
• One ## header per experimental stage (## Parameters, ## Analytic initialisation of the readout, ## Supervised learning of the readout, ## Sweep: ...), with ### for raster legends, evaluation cells and animations. Match the heading style already used in 30/40-series notebooks (## working memory with periodic targets).
• Inline # code comments may be added, but commenting must never change executable code (verify by stripping comments and diffing against HEAD).

Terminology (consistency with the paper):

Raster legend (used by every retrieval notebook): green x = input spikes (spontaneous pad + trigger), open red o = target (hidden from the network after the trigger), blue + = evoked/replayed spikes; red/blue dashed vlines mark N_pretime and N_pretime + num_delay. The paper captions in figure_*.tex use the same colours — keep both sides in sync when changing a plot.

Figures → generating notebook:

Character hygiene: no non-breaking/narrow spaces (U+00A0/U+202F), zero-width characters, curly quotes or non-ASCII hyphens in .py, .ipynb, .tex comments/docstrings — use plain ASCII there (legitimate em/en dashes in README prose are fine). The ^^V (U+0016) lualatex warning is the dsrom font quirk, not a stray character.

Conventions & gotchas

• Parameter drift. As of the reconciliation run 2026-09-07, the paper methods text (β = 0.7, τ ≈ 2.8 steps; ϑ₀ = 0.75, δ = 0.25; p_flip = 0.01; FastSigmoid α = 5; adadelta; η 40→0.4 mLR; dropout 0.6) matches the Params production defaults in mnesis_boilerplate.py. Older documents may still cite camera-ready values (β = 0.8, α = 12, SGD, dropout 0.10); robustness results (Fig. fig:noise) keep their own run's numbers. Do not "autocorrect" code defaults to match stale prose — consult README.md / tex/Perrinet26mnesis.pdf for the exact value a given figure used. Each notebook may also override defaults with its own local opt_dict.
• Bibliography toolchain. The paper and poster .tex files were migrated from natbib/bibtex to biblatex/biber (updates to Perrinet26mnesis.tex and Perrinet26mnesis_poster.tex: replace \usepackage{natbib} with \usepackage[style=numeric, sorting=none]{biblatex} + \addbibresource{mnesis.bib}, and replace \bibliographystyle{plainnat}\bibliography{mnesis} with \addbibresource{mnesis.bib}\printbibliography; bibliography line %!BIB TS-program = bibtex → `%!BIB TS-program = biber). Do not revert these changes.
• The analytical initialisation in HD_SNN.get_W_init is controlled by two flags: do_pinv (default True; False switches to the Hebbian cross-correlation rule) and do_deconv (default True; LIF-membrane deconvolution of the target).
• num_delay must stay odd (convolution symmetry).
• Keep notebooks' shared code in the two modules, not inlined — notebooks are meant to stay import-only.