CLI

The simulator can run from a terminal as well as through the Python API. After installing snnlab, use either entry point:

python -m snnlab.sim --help
snnsim --help

Both call the same implementation. In a project managed by uv, prefix commands with uv run. All execution commands require an explicit --out-dir.

Commands and executorsCopy Anchor Link

python -m snnlab.sim sim --help
python -m snnlab.sim train --help
python -m snnlab.sim dump-weights --help

The CLI defaults to --executor legacy, unlike the ExecutionSpec library API, which defaults to graph execution. Use --executor graph --bundle network.bundle for networks authored with snnlab.lang. Graph execution requires exactly one input source: --input-file, --event-file, --poisson-protocol or --dataset-file. The available source flags depend on the command: generated Poisson and sparse event inputs are available on sim; train accepts dense replay or dataset snapshots.

Complete graph simulationCopy Anchor Link

Save this as build_network.py in your working directory. It compiles the same small excitatory network used in Quickstart and writes a bundle for the CLI:

from snnlab import lang

net = lang.Network("cli-example", dt=0.1 * lang.ms)
inputs = net.input(
    "inputs", shape=("time", "batch", 4), signal_type="spikes", unit="spike"
)
cells = net.population("E", size=16, neuron=lang.COBA_LIF(tau_mem=20 * lang.ms))
net.connect(
    inputs,
    cells.excitatory,
    name="input_to_E",
    synapse=lang.AMPA(tau=2 * lang.ms),
    weight=lang.Uniform(0.1, 0.5),
    constraint=lang.NonNegative(),
)
net.output("spikes", cells.spikes)
net.expose(inputs, name="input_spikes")
net.expose(cells.voltage, name="e_voltage")
lang.compile(net, target="tools/snnsim").write("network.bundle")

Compile it, then generate 300 ms of input spikes at 80 Hz for one presentation:

python build_network.py
python -m snnlab.sim sim \
  --executor graph --bundle network.bundle \
  --poisson-protocol fixed-rate --input-rate 80 \
  --t-ms 300 --n-batch 1 --seed 17 --device cpu \
  --out-dir runs/poisson

The bundle supplies the timestep, topology and input dimensions. --t-ms sets duration in milliseconds; it must align with the bundle timestep. --input-rate is in Hz. For a categorical rate protocol, replace the protocol/rate flags with --poisson-protocol categorical-rate --input-rates 5 25 80; one listed rate is selected independently for each presentation. CLI Poisson generation requires exactly one declared spike input.

Graph runs write the following files, including after training:

Inspect the simulation output:

import numpy as np

with np.load("runs/poisson/outputs.npz", allow_pickle=False) as outputs:
    spikes = outputs["spikes"]
    print(spikes.shape)  # (3000, 1, 16): time, batch, cells
    print(int(spikes.sum()))

Graph execution saves arrays and metrics; it does not automatically produce figures. Use snnlab.viz to plot them.

Replay and dataset inputsCopy Anchor Link

For the bundle above, create a binary replay array and run it:

import numpy as np

spikes = np.zeros((100, 1, 4), dtype=np.float32)
spikes[::10, 0, 0] = 1
np.savez("inputs.npz", inputs=spikes)

python -m snnlab.sim sim \
  --executor graph --bundle network.bundle --input-file inputs.npz \
  --device cpu --seed 17 --out-dir runs/replay

NPZ keys must match declared input IDs and cover every input exactly once. A NPY array can bind a graph with one input. Dense replay determines its own step and batch counts; the bundle supplies the timestep. The example runs for 10 ms. Sparse replay uses --event-file events.npz; see the event binding contract for coordinate rules.

Dataset snapshots use --dataset-file snapshot.npz together with --dataset-encoder rate-poisson, prebinned-spikes or event-bin. Supply --input-dataset-id and --input-split for provenance. Use --dataset-input-id to select the declared input; it is inferred only for a graph with one input. Feature and label keys default to features and labels; override them with --dataset-feature-key and --dataset-label-key. These commands consume local snapshots and do not download a dataset. See DatasetSnapshotBinding for shapes and encoder requirements.

Graph training and checkpointsCopy Anchor Link

Training requires a bundle with an authenticated training recipe, such as one compiled in the Training example. The simulation-only bundle above has no recipe. Given a training bundle, dense inputs and integer class targets, run:

python -m snnlab.sim train \
  --executor graph --bundle classifier.bundle \
  --input-file train-inputs.npz --target-file train-targets.npz \
  --epochs 3 --batch-size 32 --input-shuffle --seed 17 --device cpu \
  --save-final-checkpoint runs/train/final.checkpoint \
  --save-selected-checkpoint runs/train/selected.checkpoint \
  --out-dir runs/train

These filenames stand for prepared training data: input NPZ keys match graph input IDs, target NPZ keys match recipe target IDs, and each target has one integer label per sample. A target NPY is accepted when the recipe has one target. Alternatively, use a dataset snapshot with --dataset-target-id instead of separate input/target files.

The bundle recipe controls the graph optimizer, learning rate and trainable parameters; legacy flags such as --lr do not replace that recipe. Positive --epochs enables minibatch iteration. With graph execution, --epochs 0 performs one full-batch update; the legacy executor uses zero epochs as a probe without training. The selected checkpoint uses the lowest update loss.

Resume graph training by adding --load-weights runs/train/final.checkpoint and increasing the requested total epoch count. Keep the bundle, training data, seed and iteration settings compatible with the checkpoint. Load trained parameters for simulation with:

python -m snnlab.sim sim \
  --executor graph --bundle classifier.bundle \
  --input-file test-inputs.npz --load-weights runs/train/final.checkpoint \
  --device cpu --seed 17 --out-dir runs/inference

Graph simulation loads parameters without restoring the optimizer or training iterator. It does not require --infer, and does not automatically compute legacy test-set accuracy. See checkpoint compatibility.

Graph controlsCopy Anchor Link

Projection scaling and interventions apply to sim and use exact graph IDs. The source bundle is not rewritten. See inference options and runtime continuation for validation rules.

Legacy workflowsCopy Anchor Link

The legacy executor constructs predefined models from flags. A small synthetic-input simulation needs no bundle:

python -m snnlab.sim sim --executor legacy --model ping \
  --n-in 4 --n-hidden 16 --n-inh 4 --n-batch 1 \
  --input synthetic-spikes --input-rate 80 --t-ms 10 \
  --seed 17 --out-dir runs/legacy-sim

Legacy dataset training, evaluation and weight export use the following workflow. MNIST training can download data, so the first run needs network access:

python -m snnlab.sim train --executor legacy --model ping --dataset mnist \
  --n-hidden 16 --epochs 1 --max-samples 64 --batch-size 16 \
  --lr 0.0001 --seed 17 --out-dir runs/legacy-train

python -m snnlab.sim sim --executor legacy --infer \
  --load-config runs/legacy-train/config.json \
  --load-weights runs/legacy-train/weights.pth \
  --max-samples 64 --out-dir runs/legacy-inference

python -m snnlab.sim dump-weights --executor legacy \
  --load-config runs/legacy-train/config.json \
  --load-weights runs/legacy-train/weights.pth \
  --out-dir runs/legacy-weights

Explicit CLI flags override values from --load-config. Legacy runs save config.json, run.sh, output.log and mode-specific artifacts: the synthetic probe above saves metrics.json, snapshot simulations save recording.npz, training saves weights and metrics, test-set inference saves metrics.json, and weight export saves weights_dump.npz. These differ from the graph artifact format. Choose separate output directories to keep runs distinct; legacy --wipe-dir deletes an existing output directory before running.

Complete argument referenceCopy Anchor Link

The tables below cover every argument accepted by the three subcommand parsers, including negative boolean forms. Commands lists where a flag is accepted; the behaviour column notes narrower execution paths. Defaults are parser defaults before loading a bundle or saved configuration. Boolean defaults describe the underlying setting, including on rows for negative forms. Unset means no explicit override; model or dataset defaults may then apply. Flags with multiple values take space-separated values.

Graph-only flags are listed separately at the end so their presence in legacy command help does not imply legacy support.

Network and timingCopy Anchor Link

ReadoutCopy Anchor Link

Neuron dynamicsCopy Anchor Link

Input and driveCopy Anchor Link

Synthetic-drive controls apply to synthetic simulation paths. Dataset selectors choose simulation samples; legacy training loads its dataset independently of --input. See the command column for parser availability.

Weight initialization and learningCopy Anchor Link

Simulation and inferenceCopy Anchor Link

Skip-load, perturbation, inhibitory replay and weight-scaling flags configure loaded-weight inference. Recording mode selects snapshot channels; recording-start-step trims retained probe rasters without shortening the simulation. Transition flags require a compatible legacy bundle simulation.

TrainingCopy Anchor Link

Output and executionCopy Anchor Link

Graph-only arguments accepted by the parserCopy Anchor Link

These flags configure graph execution and have no supported legacy effect. Runtime-state, event, dataset-file, Poisson-protocol, projection-scale, intervention and timestep flags are explicitly rejected when supplied to the legacy executor; other graph fields may be parsed but ignored. Use --executor graph and the contracts above.