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)

Implementation Roadmap (By Phase)

Phase 0: Existing Foundation ✅

Milestone: "First Whole-Nervous-System Simulation" (already achieved)

DD Title Status What It Does
DD001 Neural Circuit Architecture ✅ Accepted 302 neurons, HH Level C1, graded synapses
DD002 Muscle Model Architecture ✅ Accepted 95 muscles, Ca²⁺→force coupling
DD003 Body Physics Architecture ✅ Accepted Sibernetic SPH, ~100K particles
DD020 Connectome Data Access ✅ Accepted cect API, Cook2019 default

Infrastructure Bootstrap ⚠️

  • Milestone: "Containerized Stack with Automated Validation"
  • Duration: 4 weeks
  • Status: Proposed — must complete before modeling phases
DD Title What It Delivers
DD013 Simulation Stack Docker, CI/CD, openworm.yml config
DD021 Movement Toolbox Revival Tier 3 validation (8 tasks, 33 hours)
DD012 RFC Process DD template, governance
DD011 Contributor Progression Observer to Senior Contributor (L0-L5)
DD025 Foundation Model Channel Kinetics Predicted ion channel kinetics from sequence (parallel, derisks DD005)

Phase 1: Cell-Type Specialization ⚠️

  • Milestone: "Biologically Distinct Neurons"
  • Duration: 3 months
  • Key: 128 neuron classes from CeNGEN, functional connectivity improves ≥20%
DD Title What Changes
DD005 Cell-Type Specialization 128 distinct neuron classes (not 302 identical)
DD014 Phase 1 Trame Viewer OME-Zarr export, organism + tissue scales
DD010 Tier 2 Functional Connectivity Validate vs. Randi 2023 (r > 0.5)

Phase 2: Slow Modulation + Closed-Loop ⚠️

  • Milestone: "The Worm Can Feel and Modulate"
  • Duration: 3 months
  • Key: 31,479 neuropeptide connections + bidirectional touch response
DD Title What Adds
DD006 Neuropeptides GPCR modulation, seconds timescale
DD019 Touch Response MEC-4 channel, tap withdrawal
DD022 Environment Gradients, substrates, stimuli
DD023 Proprioception Stretch receptors, motor coordination
DD026 Reservoir Computing Validation Tests RC framing: 5 properties × 4 partitions, falsifiable predictions
DD027 Multicompartmental Neurons (PoC) 5 representative neurons, 14 ion channel classes, EM morphologies

Phase 3: Organ Systems ⚠️

  • Milestone: "Multi-Organ Digital Organism"
  • Duration: 6 months
  • Key: Pharynx, intestine, egg-laying, ML acceleration
DD Title What Adds
DD007 Pharyngeal System 63 cells, 3-4 Hz pumping
DD009 Intestinal Oscillator 20 cells, 50s defecation
DD018 Egg-Laying System 28-cell circuit, two-state
DD017 Hybrid ML Differentiable sim, 1000× speedup (Component 3 extracted to DD025)

Phase 4: Complete Organism ⚠️

  • Milestone: "959-Cell Photorealistic Whole Organism"
  • Duration: 6 months
  • Key: All somatic cells, mesh deformation, public web viewer
DD Title What Adds
DD004 Mechanical Cell Identity 959 cells with cell-type mechanics
DD014.2 Mesh Deformation GPU skinning, photorealistic
DD014 Phase 3 WormSim 2.0 Molecular scale, wormsim.openworm.org

All Design Documents (Complete List)

Browse on GitHub

All Design Documents are maintained in this openworm_docs repository. Total: 28 DDs (DD001-DD027 + 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)

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