Under the hood

The spike-run command line

Run a circuit file or score it on a level from a terminal, with the same loop, seeds and rules as the game's Check button.


spike-run is a small program that ships with the game and is built with the engine. It does two jobs. It can run any circuit file for a number of milliseconds and print the spikes. And it can score a circuit on a level, headless (with no window), exactly as the game does. The game's Check button runs it for you in the background. See the core loop.

In the release zip it sits next to the game. From a source build it is build/engine/spike-run, and a copy goes to godot/bin when you build the extension.

Mode 1: run a circuitLink to this section

spike-run circuit.json 1000 [--threads n]

This loads circuit.json, runs 1000 ms of model time, and prints one JSON line per spike on standard output:

{"neuron":0,"t":5.800000,"step":58}

neuron is the circuit-level cell index (0 to N-1 over the populations in file order), t is the time in ms, and step is the NEST time stamp in steps (here 0.1 ms each). Lines are sorted by step and then by cell. A summary line goes to standard error, so standard output holds spikes only:

spike-run: t=100.000 ms spikes=16 checksum=76468ca69ef4ff71 dropped=0

The checksum is a hash of every spike, used by the tests to check that a run is reproducible. A file made by the golden-trace tests (with a circuit field) also runs.

Development options for this mode, for people who build their own circuits and tasks:

OptionWhat it does
--threads nNEST threads. The default is 1.
--sample LISTPrint a JSON line of values at regular times instead of spikes. Items are comma-separated: V_m@0 (a state variable of cell 0), out:name (the value of a rate_value output), cnt:name (an output spike count), mod:name (a neuromodulator level).
--every msThe sampling interval for --sample. Default 10 ms.
--set t_ms:channel=valueSet an input channel to a value at that model time. Can be repeated.
--phase neuron[:I]Print the fixed points and onset type of a two-variable cell (the phase-plane numbers behind the Theory wing's dynamics levels), then run.

Example: spike-run c.json 1000 --sample V_m@0,out:rate --every 10 --set 300:cur=5.

spike-run --list-tasks prints every level id, one per line, in campaign order. This build lists 78.

Mode 2: score a circuit on a levelLink to this section

spike-run --task <id> [--circuit file.json] [--seed n | --seeds 1,2,3]
          [--lesion pre>post*k]... [--mode guided|standard|researcher]
          [--variant id] [--require any|all] [--circuits-dir dir]
          [--threads n] [--quick] [--jobs n] [--circuit-seed(s) ...]
OptionWhat it does
--task idThe level to run, for example reflex or m_threshold. Required.
--circuit fileThe circuit to score. Without it, the level's reference circuit is used.
--seed n or --seeds 1,2,3The world seeds. The default is seed 1. Each seed gives a different random world (touch times, noise) and also reseeds the circuit.
--circuit-seed n or --circuit-seeds a,b,cPin the circuit seed instead of the reseed. Give one value for all seeds, or one per seed. The game uses this so the instant check scores the very circuit you watched.
--modeDifficulty mode: guided, standard (the default) or researcher. See modes.
--variant idA challenge variant of the level, such as half_neurons.
--lesion pre>post*kScale the weight of every projection from group pre to group post by k. k of 0 (or leaving out *k) deletes it. Repeatable. A warning on standard error says if nothing matched.
--require any or allSet the exit status from the result (below).
--quickRun the level's short "quick" episode, the one Check uses, instead of the full episode.
--jobs nRun seeds in parallel child processes. The default is the number of cores; 1 runs in-process.
--circuits-dir dirWhere to look for reference circuits. Otherwise $SPIKE_CIRCUITS_DIR, then a circuits or godot/circuits folder in the working directory or up to six folders above it, then the same from the program's own folder.
--threads nNEST threads.

The seed rule. The circuit seed that a run uses is 1000 * seed + the circuit's own seed. A circuit with seed 7 run on seed 1 reports circuit_seed 1007. This is the same rule as the game's Test x5, which is why a score from the command line agrees with the game.

What it printsLink to this section

One JSON object on standard output:

FieldMeaning
circuit, mode, quickWhat was run.
n, passes, mean_valueNumber of seeds, how many passed, and the mean score.
runsOne entry per seed (below).

Each entry of runs has seed, circuit_seed, duration_ms, value (the score, 0 to 100), passed, verdict (a plain sentence about what the circuit did), parts (the numbers behind the score, named for the level), metrics, neurons, spikes, rate_hz_per_neuron (the energy number behind the third star) and hints.

Warning: The hints list holds all three tiers, including the partial recipe of tier 3, whatever the mode. The game only reveals them one at a time. If you want to play a level without spoilers, do not read this field. The text carries no numbers by rule, but tier 3 still describes the wiring.

Exit statusLink to this section

CodeMeaning
0Success.
1The circuit failed to load or the run failed.
2Usage error: unknown option, unknown task, missing circuit, unreadable file.
3The --require condition failed: any means at least one seed must pass, all means every seed must pass.

CI and the smoke test use --require any to check that every level's reference circuit passes.

ExamplesLink to this section

Score the reference circuit of a level on three seeds and require all to pass:

spike-run --task reflex --seeds 1,2,3 --require all

Score your own circuit in Researcher mode, in quick form:

spike-run --task m_threshold --circuit mine.json --mode researcher --seeds 1,2,3,4,5 --quick

Try a lesion: cut the connection from group SN to group MN on a copy of a circuit and see what the verdict says:

spike-run --task reflex --circuit mine.json --lesion SN>MN

This is the same idea as the game's lesion lab, without the table.

From the gameLink to this section

In Godot, SpikeTask.score_headless_async(circuit_json, seeds, mode, variant, circuit_seed) starts a child spike-run in a worker thread and returns a job number. If the program cannot be found or started it returns 0 and a warning lists the places searched. score_headless_quick_async runs the quick episode. The game polls the job each frame. A release build must keep spike-run next to the extension or Check cannot work. The circuit travels in a private temporary file that is deleted afterwards, and headless_cancel(job) kills the child process.

Use your circuit in Python, building from source, architecture, make it yours.

Something wrong or missing? Edit this page on GitHub (source) or open an issue.