Installation & Quickstart

Install dependencies

Requires Python 3.10+. From the repository root:

pip install -r src/requirements.txt

Core dependencies: torch, snntorch, numpy, scipy, matplotlib, jupyter. The optimisation/scan notebooks additionally use optuna (bundled in src/requirements.txt).

Run the notebooks in order

The notebooks are numbered and designed to be run sequentially. They import shared infrastructure from the Python modules mnesis_boilerplate (imports, device detection, Params dataclass, utilities) and mnesis_chains (HD_SNN class, analytical initialisation). Each notebook saves its outputs (model weights, scan results) to cached_data/ so that downstream notebooks can load them without recomputation. Notebook 99 can orchestrate a full multi-notebook run in one place.

cd src
jupyter notebook

Each notebook opens with its own opt_dict = dict(...) that overrides the global Params defaults for that experiment (a different N_neuron, num_delay, N_pretime, threshold, …). The global defaults in Params are the canonical reference; per-notebook opt_dicts tune the run for the pattern family being studied.

See Experiments & Notebooks for the annotated notebook pipeline.

Debug mode

Set DEBUG > 1 in src/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.

Cached data

Results are saved to cached_data/ (excluded from git via .gitignore), each file prefixed by the current datetag (the batch date, ISO 8601):

File	Written by	Content
{datetag}_init.pth	11	Analytically initialised weights (pseudo-inverse or Hebbian, deconvolved or not)
{datetag}_vanilla.pth	11	Trained model weights after gradient steps, loaded by 13–16
{datetag}_score.npy	13	Sliding-window \(F_1\) trajectory of the sequential retrieval
{datetag}_noise.npz, {datetag}_noise_retrain.npz	14	\(F_1\) versus \(p_\mathrm{flip}\) (fixed weights / fine-tuned), shape (N_scan, N_cv); the fixed-weights file also holds the \(F_1\) of each motif, scores_motif_np of shape (N_scan, N_cv, N_pattern)
{datetag}_trigger_time.npz	15	\(F_1\) versus trigger duration, shape (num_delay, N_cv), and of each motif, scores_motif_np of shape (num_delay, N_cv, N_pattern)
{datetag}_N_neurons.npz	16	\(F_1\) versus number of silenced trigger neurons, shape (N_scan, N_cv), and of each motif, scores_motif_np of shape (N_scan, N_cv, N_pattern)
{datetag}_periodic.pth, {datetag}_periodic_spikes.pth, {datetag}_periodic_spikes_noisy.pth	18	Periodic-memory weights and retrieved rasters (clean / noisy)
{datetag}_periodic-with-noise_N_period={N_period}.npz	18	Periodic-memory robustness: \(F_1\) per period of free replay for each noise level (p_flip, scores_np)
{datetag}_scan_{key}.json (+ .lock)	20	Parameter sweep results (key, i_cv, loss, time per row)
{datetag}_optuna.sqlite3	25	Optuna study (synthetic motifs)

Delete a cached file to force its recomputation; set RECOMPUTE = True at the top of any notebook to invalidate the full cache for that notebook. The scan/optimisation notebooks additionally guard each run with a .lock sentinel file to allow safe incremental resumption: a .lock sentinel is created when a scan starts, each computed parameter value is appended to the JSON (not re-running values already present), and the lock is deleted when done — never delete a .lock out from under a running scan. A scan interrupted mid-run leaves placeholder rows (loss=null, time=0.0) that would otherwise count as computed; mnesis_boilerplate.purge_unfinished_scans() (called at the start of notebook 99) removes them so they are recomputed.

Build the paper

The LaTeX source lives in tex/ and uses fontspec and biblatex, so it must be built with lualatex and biber, from inside tex/. The experiment figures are read from figures/ (generated by the notebooks); the two TikZ schematics are compiled in tex/:

cd tex
lualatex -interaction=nonstopmode tikz_izhikevich.tex
lualatex -interaction=nonstopmode tikz_snntorch.tex
latexmk -pdflua -pdf -interaction=nonstopmode Perrinet26mnesis.tex

Build this documentation

The site is built and deployed by the GitHub Actions workflow .github/workflows/static.yml on every push to main (the Pages source is set to “GitHub Actions” in the repository settings); no generated HTML is committed, as docs/ only holds the sources. To preview it locally:

pip install -r docs/requirements.txt
make -C docs html        # output in docs/_build/html (git-ignored)

make -C docs help lists the available targets (notebooks, html, clean, all). The notebooks are symlinked from src/ into docs/notebooks/ and rendered with their stored outputs (they are not re-executed by the docs build).