Skip to content

Design Documents

Introduction

Design Documents (DDs) are OpenWorm's technical roadmap from today's 302-neuron simulation to the complete 959-cell digital organism. Each DD specifies one subsystem (neurons, muscles, body physics, pharynx, intestine), ensuring every piece is:

  • Biophysically realistic — grounded in experimental data
  • Causally interpretable — we can trace why behavior emerges
  • Validated — tested against real worm physiology and behavior
  • Composable — subsystems integrate via clean interfaces

Mission Alignment

OpenWorm Mission

"OpenWorm is an open source project dedicated to creating the world's first virtual organism in a computer, a C. elegans nematode."

Design Documents serve this mission by providing the complete architectural blueprint — from ion channels to organism behavior — with quantitative success criteria and experimental validation at every level.

Core Principle: "Worms are soft and squishy. So our model has to be too. We are building in the physics of muscles, soft tissues and fluids. Because it matters."

For the philosophical commitments behind these principles — mechanistic explanation, causal interpretability (Pearl), emergence, and completeness — see Background: Mission & Design Principles. For how OpenWorm compares to similar projects, see Full History.

New to Design Documents?

Implementing or Contributing?

Resources:

  • 📦 GitHub Repo Inventory — All 109 OpenWorm repositories (existing code resources are documented in each DD's "Existing Code Resources" section)

Phase Overview

OpenWorm's roadmap takes the project from today's 302 generic neurons to a complete 959-cell digital organism over ~18 months. The journey is organized into phases that manage scientific risk, build infrastructure first, and validate early. Phase 0 established the core architecture — coupled neural-muscle-body simulation runs and produces movement, though stabilization work remains (see Phase A1). Phases A1 and A2 lay the infrastructure and governance foundation. Phases 1-4 progressively add biological complexity — from cell-type specialization through organ systems to the complete organism.

The key insight behind this phasing: validate the hardest science early. Phase 1's expression→conductance mapping is the highest-risk step. If it fails, we discover it in month 3 (not month 12). Each subsequent phase builds on validated foundations, not assumptions.

Phase Name Duration What It Delivers Key DDs Cells
0 Core Architecture Functional Neural circuit + muscle + body + connectome data — simulation runs, 83 stabilization issues tracked 4 302 neurons + 95 muscles
A1 Core Infrastructure Wks 1-2 docker compose run quick-test, unified data API, validation toolbox, baseline datasets, project dashboard 5 —
A2 Governance & Derisking Wks 3-4 L0-L5 contributor levels + badge taxonomy (DD011), DD proposal/review process (DD012), AI agent registration + task pipeline (DD015), ion channel kinetics predictions derisking Phase 1 (DD025) 4 —
1 Cell-Type Specialization Mo 1-3 128 neuron classes from generic → specialized 4 302 specialized neurons
2 Modulation + Closed-Loop Mo 4-6 Neuropeptides, touch response, proprioception 6 +sensory loop
3 Organ Systems Mo 7-12 Pharynx, intestine, egg-laying, ML hybrid 4 +3 organs
4 Complete Organism Mo 13-18 959 mechanically distinct cells, web viewer 3 959 cells

Why This Order?

  • Phase 0: The foundation is functional — coupled simulation runs and produces movement with 302 neurons, 95 muscles, and SPH body physics. 83 stabilization issues remain (containerization, validation scripts, dependency pinning), most addressed by Phase A1.
  • Phase A1: Can't build/test/validate without containerization (DD013), data access (DD008), and validation toolbox (DD021). These block everything.
  • Phase A2: Doesn't block modeling but enables governance at scale and derisks Phase 1 calibration via foundation model cross-validation (DD025). Runs in parallel with A1.
  • Phase 1: Highest scientific risk (expression→conductance mapping) — test early, fail fast. If it works, we have 128 distinct neuron classes. If it fails, DD025 predictions are the fallback.
  • Phase 2: Closes the sensory loop — the worm can now respond to stimuli (touch, chemicals, temperature) and modulate behavior via neuropeptides.
  • Phase 3: Adds organ systems (pharynx, intestine, egg-laying) that need the closed-loop substrate from Phase 2.
  • Phase 4: Completes the organism — 959 mechanically distinct cells + public web viewer at wormsim.openworm.org.

For detailed milestones, success criteria, datasets, and blocking dependencies, see the Phase Roadmap.

All Design Documents (Complete List)

Browse on GitHub

All Design Documents are maintained in this openworm_docs repository. Total: 29 DDs (DD001-DD028 + DD014.1/DD014.2; DD016 was merged into DD005)

By Topic

Neural Systems: DD001 (architecture), DD005 (specialization), DD006 (neuropeptides), DD007 (pharynx neurons), DD018 (egg-laying HSN/VC), DD019 (touch neurons), DD027 (multicompartmental)

Muscle Systems: DD002 (body wall), DD007 (pharyngeal), DD018 (reproductive)

Body Mechanics: DD003 (SPH), DD004 (cell identity), DD014.2 (mesh deformation), DD019 (strain readout)

Organ Systems: DD007 (pharynx), DD009 (intestine), DD018 (egg-laying)

Sensory Systems: DD019 (touch/MEC-4), DD022 (environment), DD023 (proprioception)

Data & Validation: DD008 (OWMeta), DD010 (4-tier validation), DD020 (connectome/cect), DD021 (movement toolbox), DD024 (validation data acquisition), DD026 (reservoir computing validation)

Infrastructure: DD013 (simulation stack), DD014 (visualization), DD014.1 (visual rendering), DD014.2 (mesh deformation), DD028 (project metrics dashboard)

Governance: DD011 (contributor progression), DD012 (RFC process), DD015 (AI contributors)

Hybrid/Advanced: DD017 (mechanistic-ML hybrid), DD025 (foundation model channel kinetics), DD026 (reservoir computing validation)

Cross-Reference by Topic

Neural Systems

  • Core: DD001 (302-neuron HH architecture, graded synapses, Level C1)
  • Specialization: DD005 (128 neuron classes from CeNGEN scRNA-seq)
  • Modulation: DD006 (31,479 neuropeptide-receptor interactions, GPCR modulation, seconds timescale)
  • Pharynx: DD007 (20 pharyngeal neurons, pumping circuit)
  • Egg-Laying: DD018 (2 HSN serotonergic command neurons, 6 VC cholinergic motor neurons)
  • Touch: DD019 (6 touch receptor neurons: ALM, AVM, PLM; tap withdrawal circuit, MEC-4 channel)
  • Multicompartmental: DD027 (NeuroML2 multicompartmental cable-equation models; spatially resolved synapses)

Muscle Systems

  • Body Wall: DD002 (95 muscles, Ca²⁺→force coupling, Boyle & Cohen 2008 parameters)
  • Pharynx: DD007 (20 pharyngeal muscles, nonstriated, plateau potentials, gap-junction-synchronized)
  • Reproductive: DD018 (16 sex muscles: 8 vulval, 8 uterine; EGL-19/UNC-103 channels)

Body Mechanics

  • Physics Engine: DD003 (Sibernetic SPH, ~100K particles, PCISPH incompressibility, elastic bonds, muscle force injection)
  • Cell Identity: DD004 (per-particle cell IDs from WBbt ontology, 959 somatic cells, cell-type-specific elasticity/adhesion)
  • Mesh Deformation: DD014.2 (GPU skinning, cage-based MVC, PBD collision for Virtual Worm's 688 meshes)
  • Strain Readout: DD019 (cuticle strain from SPH particles for mechanotransduction)

Organ Systems

  • Pharynx: DD007 (63 cells: 20 neurons + 20 muscles + 9 epithelial + 9 marginal + 4 gland + 1 valve; 3-4 Hz pumping)
  • Intestine: DD009 (20 cells, IP3/Ca²⁺ oscillator, defecation motor program 50±10s period)
  • Reproductive: DD018 (28-cell circuit: 2 HSN + 6 VC + 16 sex muscles + 4 uv1 feedback; two-state pattern)

Sensory & Environment

  • Touch: DD019 (MEC-4/MEC-10 DEG/ENaC mechanosensory channel, gentle + harsh touch)
  • Environment: DD022 (substrates, chemical gradients, temperature, food particles)
  • Proprioception: DD023 (stretch receptors, motor coordination)

Data & Validation

  • Connectome: DD020 (cect API v0.2.7, Cook2019 default, 30+ datasets)
  • Data Integration: DD008 (OWMeta semantic RDF graph; Phase 3+ wraps cect)
  • Movement Validation: DD021 (analysis toolbox revival, WCON 1.0, 5 kinematic metrics)
  • Validation Framework: DD010 (4 tiers: electrophysiology, functional connectivity r > 0.5, behavioral ±15%, causal/interventional)
  • Validation Data: DD024 (acquire, format, version-control all experimental datasets)
  • Reservoir Computing: DD026 (tests whether the 302-neuron connectome functions as a reservoir computer — 5 RC properties × 4 neuron partitions, falsifiable predictions)

Infrastructure & Visualization

  • Simulation Stack: DD013 (Docker, openworm.yml, CI/CD, Integration Maintainer role)
  • Visualization: DD014 (OME-Zarr, Trame→Three.js, 3-phase roadmap)
    • DD014.1: Visual Rendering Specification (colors, materials, lighting, 14 mockups)
    • DD014.2: Anatomical Mesh Deformation Pipeline (GPU skinning, ~1.6M vertices)

Governance

  • Contributors: DD011 (L0-L5 progression, badge system)
  • RFC Process: DD012 (DD template, approval workflow, Mind-of-a-Worm enforcement)
  • AI Contributors: DD015 (autonomous agents as L1-L3 contributors)

Hybrid & Advanced

  • Mechanistic-ML: DD017 (differentiable simulation, SPH surrogate, learned sensory transduction)
  • Foundation Model Kinetics: DD025 (protein sequence → ion channel HH parameters, derisks DD005)
  • Reservoir Computing: DD026 (tests RC framing of the connectome — 5 falsifiable predictions across 4 neuron partitions, either confirms or rejects the framework)

Contributing

See the Contributing Guide for:

  • How to use DDs as a contributor or reviewer
  • Design Document lifecycle and status definitions
  • Writing your first DD (7-step guide with template)
  • Examples of excellent DDs
  • Anti-patterns to avoid
  • Frequently asked questions

Additional Resources