Worm × MNIST

Teach a virtual worm-inspired network to recognize handwritten digits. Draw a number, watch pixels drive its 302-neuron circuit, inspect individual neuron activity, and train your own model—all in one local browser page.

Watch Episode 1 on YouTube · By Jad Tounsi El Azzoiani

This is the standalone MNIST experiment from Worm Lab. It includes a trained checkpoint and ten recorded training epochs, so you can start experimenting immediately.

Start here

Install Python 3.11–3.13 and Git. A CPU is sufficient; no Node.js, GPU, account, or API key is needed.

git clone https://github.com/jadouse5/worm-mnist.git
cd worm-mnist
python3 -m venv .venv

macOS / Linux:

source .venv/bin/activate
python -m pip install -r requirements.txt
python -m wormlab

Windows PowerShell (activation is optional):

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m wormlab

On Windows, use python in place of python3 when creating the environment. Use .\.venv\Scripts\python.exe in place of python for the commands below.

Open http://127.0.0.1:8000. Leave the terminal running; Ctrl+C stops the server.

1. Click Draw, write one digit, then Predict. You can also upload a PNG, JPEG, or WebP.
2. Click an input pixel or neuron to inspect its actual computed activity.
3. Click Replay learning to cycle through the ten recorded training epochs.
4. Step through the activity timeline or enable Show only activity ≥ to see which neurons pass your chosen threshold.

The included model scored 88.79% on the official 10,000-image MNIST test set. Your own handwriting may be harder for it, especially after reduction to 80 input values.

Train your own worm

In a second terminal, activate the same environment, then download the four checksum-verified MNIST files:

python -m wormlab download

The page detects the download automatically. Select 1–1,000 epochs, then click Train & watch. Each click starts a fresh model; it does not resume the selected checkpoint. More epochs may improve validation accuracy, but improvement is not guaranteed.

• Stop training retains completed checkpoints and recordings.
• Pause animation pauses playback only; training continues.
• Next digit tests a validation image with the selected saved checkpoint. It requires the MNIST download.
• Predict and Next digit use a finished run and never update its weights.
• Checkpoint downloads the best model; Run report includes configuration and metrics.

Training uses 55,000 images, validation uses 5,000, and the official 10,000-image test set is evaluated after selecting the best checkpoint by validation accuracy (validation loss breaks ties). The split and random seed are fixed for repeatable experiments. Use validation to choose experiments; repeatedly tuning against the test result would compromise its role as a held-out assessment.

Models, data, and recordings are stored in .wormlab/, which Git ignores. Each training run retains a dataset snapshot and features, so repeated runs consume disk space. Set WORM_LAB_DATA to an absolute path to use another storage location.

What is actually learning?

flowchart LR
    A[28 × 28 grayscale digit] --> B[Fixed area averaging: 10 × 8]
    B --> C[80 values + 3 zeros]
    C --> D[83 sensory inputs]
    D --> E[302-neuron worm circuit · 24 steps]
    E --> F[217 interneuron / motor outputs]
    F --> G[Trainable linear readout · 10 digits]

Loading

The network uses measured C. elegans connectivity from Cook et al. (2019), with 3,709 chemical edges and 1,091 electrical pairs between neurons. Learning changes the strength of existing chemical edges and the final digit readout.

Component	Trainable parameters
Fixed pixel averaging and sensory assignment	0
Chemical connection gains	3,709
Electrical coupling	0
217 → 10 linear readout, including bias	2,180
Total	5,889

There is no learned image encoder or CNN. The worm circuit performs the recurrent processing; a small learned readout converts its final activity into digit scores. Pixel-to-neuron assignment, connection normalization, signs, dynamics, and the readout are engineering choices. Anatomical wiring alone is not a complete biological simulator.

This implementation uses continuous graded activity, not spikes. It is inspired by biological circuits and the broader idea of liquid neural networks, but it does not implement a liquid time-constant (LTC) model. “Teaching a worm numbers” means training this software model to classify digits—not teaching a living worm arithmetic.

Is the animation real?

Neuron brightness and traces come from the model's computed states for the displayed image. The wiring and schematic positions stay fixed because training changes connection strengths, not topology. Different images can activate overlapping neurons.

During training, the server publishes sampled batch updates and saves the final batch of each epoch. The trace is a post-update forward pass for one image from that batch; the displayed batch loss comes from the pre-update batch prediction. Replay animates those saved measurements; it does not run another optimizer step. Moving input dots illustrate input drive. The 20 ms step labels are a display convention, not calibrated biological timing.

Explore the code

File	What to change or inspect
wormlab/model.py	Recurrent neuron dynamics, connectivity, trainable gains, readout
wormlab/mnist.py	Verified MNIST download, fixed pixel mapping, drawn-digit centering
wormlab/worker.py	Optimizer, epoch loop, validation, test metrics, activity recordings
wormlab/app.py	Local API, training jobs, saved-model inference
web/src/observatory.js	Circuit drawing, activity playback, learning curves
web/src/digit-input.js	Drawing pad, uploads, inference
web/data/worm/README.md	Connectome provenance and conversion details

Try changing the number of recurrent steps or freezing chemical gains, then train a fresh run and compare validation results. Keep a copy of the original configuration; changing model code can change the meaning of existing checkpoints.

Tests

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -v

Tests run without downloading MNIST. They check the bundled checkpoint against its recorded activity, gradient flow through the chemical gains, fixed pixel preprocessing, and the offline drawing / replay API.

Troubleshooting

• Port busy: run python -m wormlab --port 8001, then open http://127.0.0.1:8001.
• Train disabled: run python -m wormlab download. Also wait for any active run or inference to finish.
• Poor drawn-digit predictions: use one thick, centered digit. Center digit crops and centers ink; the actual processed image is shown before its 10 × 8 reduction.
• Blank image error: draw a visible digit first. Light-background uploads are automatically inverted.
• Installation fails: check your Python version. PyTorch installation is the largest dependency; internet access is needed for installation and the optional dataset download.
• Stopped mid-run: restart the server. It marks interrupted workers accordingly and retains completed checkpoints.

Sources and license

Application code is MIT licensed. Research data retain their own attribution and terms; see THIRD_PARTY.md.

• Cook SJ et al. (2019), Whole-animal connectomes of both Caenorhabditis elegans sexes; workbooks from WormWiring.
• MNIST by Yann LeCun, Corinna Cortes, and Christopher J. C. Burges; dataset background and download implementation / published hashes.

What should the worm learn next? Leave your challenge on Episode 1, or open an issue with your experiment and results.