🪱 Quantum Nematode

A closed-loop simulation platform for asking which brain architecture best learns a nematode's behaviours — with the real C. elegans connectome as the focal point of comparison.

A simulated worm senses a continuous 2-D world — chemical gradients, temperature, oxygen, predators, other worms — a pluggable brain turns those senses into motor drive, and learning or evolution shapes the brain across episodes. Twenty-six brain architectures plug into the same loop: feed-forward, recurrent, liquid, attention, spiking, reservoir, quantum, hybrid, GA-evolved, and one constrained to the real 302-neuron C. elegans wiring diagram. Because every brain sees the same environment, reward and statistical protocol, they can be ranked on the same behaviours — and the behaviour they learn can be graded against published C. elegans data.

The project started, and is still named, as a quantum-machine-learning experiment. A 300-session campaign across 11 quantum and hybrid architectures (and their variants) found no quantum advantage on these tasks under controlled attribution (Logbook 008, Logbook 025), so quantum circuits are now one architecture family in the comparison rather than the organising principle. The roadmap records that pivot and everything since.

Each result links to the logbook that holds the evidence. Negative results carry the same weight as positive ones.

• Architecture ranking on the continuous substrate (Logbook 029). On one integrated cell — chemotaxis foraging, predator evasion and thermotaxis all active, klinotaxis sensing, n = 8 paired seeds — the six pre-registered Phase 6 arms rank MLP 89.0 ≫ {CfC 75.8 ≈ Transformer 74.0} > LSTM 60.1 > connectome 52.2 ≫ GA 15.0 (plateau-tail full-clear success %, three tiers separated at Benjamini–Hochberg FDR). A plain MLP wins on all three behaviours.
• The connectome, honestly (Logbook 034, 037). The wild-type C. elegans wiring learns the cell (8/8 seeds converge) but ranks 5th of 6 under PPO weight search — and a degree-preserving rewired-null control is statistically indistinguishable from it (52.8% vs 56.1%, q = 0.77). Under gradient-descent weight search the specific wiring confers no advantage over degree-matched alternatives: a degree-statistics result, not a wiring result, and the motivating hypothesis for Phase 7 — is PPO simply the wrong learning rule for the connectome?
• Real-worm behavioural validation (Logbook 035, 036). The learned worm reproduces both documented C. elegans chemotaxis strategies — klinokinesis (turn rate vs dC/dt; Pierce-Shimomura et al. 1999) and weathervane steering (curving rate vs bearing; Iino & Yoshida 2009; reproduced in direction, not magnitude) — on both the MLP and the connectome arms, with a sensing-ablation control that produces a double dissociation. Thermotaxis validation is partial: the weathervane is reproduced, klinokinesis is absent.
• Working memory is resolvable but not demanded (Logbooks 030, 032, 033). On delayed-match-to-cue and associative-update probes the recurrent and attention arms separate sharply from the memoryless MLP (CfC 0.995 / Transformer 0.978 / LSTM 0.939 vs MLP 0.501; the connectome sits at chance, 0.499). A biologically-grounded area-restricted-search probe returned null: the naturalistic behaviours are reactive-dominated, which is why the memoryless MLP wins the main ranking.
• No quantum advantage on these tasks (Logbook 008, 025). 300+ sessions across 11 quantum and hybrid architectures and their variants on the grid substrate. The best quantum architecture (HybridQuantum, 96.9% pursuit evasion) is matched by its classical ablation (96.3%); a genuinely quantum Z₂-equivariant circuit topped the grid ranking (86.0) but a matched-capacity classical-equivariant network ties it (87.9, ns).
• Evolution and inheritance (Logbooks 012, 013, 021). TPE beats CMA-ES for hyperparameter evolution; Lamarckian weight inheritance passes its pre-registered speed gate (+5.25 generations). Baldwin-effect, predator–prey co-evolution (Red Queen) and transgenerational-memory studies closed with substrate-grounded STOP verdicts, each with a diagnosis.
• Sensing and multi-agent (Logbooks 009, 010, 011). Scalar-only temporal sensing with a GRU reaches oracle-level performance (94% vs 97%); derivative sensing beats oracle gradients on all six large-grid aerotaxis scenarios (+4 to +28pp); food-marking pheromones add +77pp on a single food cluster (a benefit that collapses with multiple clusters) and social feeding +47.8% food under scarcity; alarm and aggregation pheromones are inert.

• Actively developed research software, single maintainer. Phases 0–6a of the roadmap are complete (Phase 6a synthesis). Next is Phase 7: biologically-plausible plasticity (STDP and neuromodulator-gated three-factor rules) on the connectome, and cross-species transfer to P. pacificus using the Cook et al. 2025 connectome. Phase 6b (NEAT topology search) is deferred behind environment vectorisation.
• Evidence discipline. Every experiment series is a numbered logbook with its hypothesis, method, results and decision, plus the configs, seeds and artifacts needed to reproduce it. Phase 5's pilots (Logbooks 012–018) ran n ≥ 4 seeds against pre-declared decision gates; from Logbook 019 comparisons use paired-seed Wilcoxon tests with bootstrap CIs, and the Phase 6 rankings (025 onward) add BH-FDR correction at n = 8. Earlier logbooks report session-level results. Negative results and STOP verdicts are first-class. Changes go through OpenSpec proposals under openspec/.
• Engineering. Python 3.13 only; 4,000+ tests in four tiers (unit, slow integration, CLI smoke, nightly end-to-end benchmarks); Pyright-typed and Ruff-linted (select = ALL). Tagged releases are on GitHub Releases and summarised in CHANGELOG.md; internals change between them.

uv manages the environment; Git LFS stores weights, checkpoints and connectome data. A fresh clone fetches only the connectome data the code needs (~4 MB); the ~620 MB of curated logbook artifacts stay as LFS pointers until you ask for them with git lfs pull --include='artifacts/**'.

# macOS
brew install uv git-lfs
# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh && sudo apt-get install git-lfs

git lfs install
git clone https://github.com/SyntheticBrains/nematode.git
cd nematode
uv sync --extra cpu --extra torch --extra pixel

# Watch an MLP-PPO worm learn klinotaxis foraging on the continuous-2D substrate
uv run ./scripts/run_simulation.py \
  --config configs/scenarios/foraging/mlpppo_small_continuous2d_fick_adaptive_klinotaxis.yml \
  --theme pixel_continuous --runs 50 --seed 1

# The same session headless (fastest): prints a summary, writes CSVs and plots to exports/<session-id>/
uv run ./scripts/run_simulation.py \
  --config configs/scenarios/foraging/mlpppo_small_continuous2d_fick_adaptive_klinotaxis.yml \
  --theme headless --runs 200 --seed 1

Each --config is a self-contained YAML scenario — the brain and its hyperparameters, the environment, the sensing mode and the reward. The 260+ scenarios under configs/scenarios/ are named {brain}_{size}[_{variant}]_{sensing}.yml.

More to try:

# The connectome-constrained brain on the three-behaviour cell used for the Phase 6 ranking
uv run ./scripts/run_simulation.py --config configs/scenarios/foraging_predator_thermal/connectomeppo_small_continuous2d_combined_klinotaxis.yml --theme headless --runs 500 --seed 1

# Five worms with social feeding and pheromones (grid substrate, Pygame)
uv run ./scripts/run_simulation.py --config configs/scenarios/multi_agent_foraging/mlpppo_medium_5agents_full_social_oracle.yml --theme pixel --runs 10

# A variational quantum circuit on the Aer simulator (add --device qpu --optimize for IBM hardware with Q-CTRL Fire Opal)
uv run ./scripts/run_simulation.py --config configs/scenarios/foraging/qvarcircuit_small_oracle.yml --theme emoji --runs 20

# Evolve a feed-forward network's weights with a genetic algorithm
uv run python scripts/run_evolution.py --config configs/evolution/feedforwardga_foraging_small.yml --algorithm ga --generations 20 --parallel 4

The usage guide covers the full CLI, experiment tracking, evolution and inheritance, the analysis scripts, quantum hardware and the GPU container.

1. Sense. The worm reads its world through biologically-motivated channels: chemical concentration (oracle gradients, scalar-only temporal sensing, the temporal derivative dC/dt, or klinotaxis head-sweeps), temperature (AFD-like thermosensation), oxygen (URX/BAG-like aerotaxis), contact and distal predator cues (ASH/ALM/PVD-style mechano- and chemosensation), pheromones and neighbours in multi-agent runs, plus proprioception and a short-term associative memory (STAM) buffer. On the continuous substrate an adaptive, Weber-law chemosensor sits between the field and the brain.
2. Decide. The brain maps the sensory vector to motor drive. On the continuous-2D substrate that is a (speed, turn) command from a tanh-squashed Gaussian head; on the grid it is one of {forward, left, right, stay}. The environment owns the physical scale and integrates the kinematics, so the same brain works in any arena.
3. Act and learn. Moving costs satiety, food restores it, predators damage health, and thermal or oxygen zones range from comfortable to lethal. Reward, satiety and health feed back to the learner — PPO for most arms, REINFORCE, DQN, surrogate-gradient rules for spiking networks — or to an evolutionary outer loop: CMA-ES, genetic algorithms, TPE hyperparameter search, Lamarckian warm-starts across generations, predator–prey co-evolution.
4. Measure. Every run logs success, foods, steps, reward, distance efficiency, survival and comfort; --track-experiment captures the config hash, git state and results for reproducibility; bias-curve analysis grades the worm's own turning behaviour against the C. elegans literature; paired-seed statistics rank the architectures.

Two substrates. The discrete grid (Phases 0–5) is where most historical results live and remains fully supported. The continuous-2D substrate (Phase 6) adds float kinematics, Euclidean geometry, Fick-shaped diffusion fields and the adaptive sensor, and is where the current ranking and the real-worm validation were run. The two are deliberately non-commensurable; results are never mixed across them.

Behaviours. Chemotaxis foraging, predator evasion (stationary traps and pursuit predators), thermotaxis, aerotaxis, multi-agent foraging with pheromones and social feeding, and two engineered working-memory probes (delayed match-to-cue and chemosensory associative update). The Phase 6 ranking runs the first three together on one cell. The biology behind every channel, with references, is in docs/nematode_biology.md.

All 26 architectures self-register through @register_brain and implement one Brain interface, so adding one is a bounded change of at most six files (plugin guide). The full catalogue — one-line descriptions, the role each arm played and which optimiser to use — is in docs/architectures.md.

Phase 6 ranked six of these as pre-registered MUST arms (mlpppo, lstmppo, cfcppo, transformerppo, connectomeppo, feedforwardga). The rest are comparators, ablation controls or closed historical arms whose evidence lives in their logbooks.

Two Pygame renderers — --theme pixel_continuous for the continuous substrate and --theme pixel for the grid, including multi-agent runs — plus terminal themes (ascii, emoji, unicode, colored_ascii, rich, emoji_rich) and headless for batch training. Sprites, overlays and keyboard controls are documented in docs/visualization.md.

Contributions are welcome — CONTRIBUTING.md covers setup, the four test tiers, code style and the pull-request process. Good places to start, aligned with the roadmap:

• Phase 7 plasticity: STDP/Hebbian and neuromodulator-gated three-factor rules on the connectome substrate; receptor-class metadata from CeNGEN.
• Environment vectorisation: the binding constraint on Phase 6b's NEAT topology search.
• Validation arms: a predator/mechanosensation behavioural validation; named-neuron grounding for the connectome brain.
• Docs, tutorials and reproductions: rerun any logbook on your own hardware — a discrepancy is a finding.

Questions and ideas go to Discussions; bugs to Issues; suspected vulnerabilities to the private channel in SECURITY.md.

If you use the platform or its results, please cite it (CITATION.cff):

@software{zaharia_quantum_nematode,
  author  = {Zaharia, Chris Julian},
  title   = {Quantum Nematode: a closed-loop brain-architecture comparison platform on the C. elegans connectome},
  year    = {2026},
  url     = {https://github.com/SyntheticBrains/nematode},
  license = {Apache-2.0}
}

Apache License 2.0 — see LICENSE.

• Connectome data: Cook et al. 2019 (Nature) whole-animal C. elegans connectome, cross-validated against Witvliet et al. 2021 (Nature) — see data/connectome/PROVENANCE.md.
• Behavioural reference data: Pierce-Shimomura et al. 1999, Iino & Yoshida 2009, Luo et al. 2014 and the wider C. elegans literature catalogued in docs/nematode_biology.md.
• Q-CTRL for quantum hardware access and Fire Opal error suppression; Qiskit and the IBM Quantum platform.
• OpenSpec for the spec-driven development framework.
• ncps for the CfC liquid-network implementation, and PyTorch, NumPy, Optuna, pycma, Pydantic, Rich and Pygame.