DD022: Environmental Modeling and Stimulus Delivery¶
- Status: Proposed (Phase 2)
- Author: OpenWorm Core Team
- Date: 2026-02-19
- Supersedes: None
- Related: DD003 (Body Physics — boundary particles), DD019 (Touch Response — tap stimulus), DD017 (Hybrid ML — learned sensory)
TL;DR¶
The worm doesn't live in a void — it crawls on agar, swims in liquid, navigates chemical gradients, seeks preferred temperatures, and eats bacteria. This DD specifies how to model substrates (agar stiffness, liquid viscosity, soil mechanics), deliver stimuli (NaCl gradients, temperature ramps, tap impulses), and represent food (OP50 bacterial particles in pharyngeal lumen). Success: reproduce chemotaxis (CI index >0.5) and thermotaxis (navigate to cultivation temp) on simulated gradients.
Quick Action Reference¶
| Question | Answer |
|---|---|
| Phase | Phase 2 |
| Layer | Environment — see Phase Roadmap |
| What does this produce? | Substrate models (agar stiffness, liquid viscosity, soil), chemical/thermal gradient fields, geometric obstacles, bacterial lawn particle system |
| Success metric | Chemotaxis on NaCl gradient (CI chemotaxis index >0.5), thermotaxis to cultivation temp (±2°C), tap withdrawal on agar vs. liquid (latency difference reproduced) |
| Repository | openworm/sibernetic (substrate mechanics) + openworm/c302 (stimulus coupling to sensory neurons) — issues labeled dd022 |
| Config toggle | environment.substrate: "agar", environment.chemical_gradient: true, environment.food_particles: true in openworm.yml |
| Build & test | docker compose run quick-test --config chemotaxis (worm navigates gradient?), docker compose run validate (CI index validation) |
| Visualize | DD014 environment/substrate/ layer (agar surface heatmap), environment/gradients/ (chemical/thermal field visualization), environment/food/ (bacterial particles) |
| CI gate | Behavioral validation (chemotaxis, thermotaxis) blocks merge; substrate mechanics must not destabilize body physics |
| --- |
Mission Alignment¶
OpenWorm Mission: "Creating the world's first virtual organism."
DD022 serves this by: An organism doesn't exist in isolation — it interacts with its environment. Chemotaxis (navigating toward food), thermotaxis (seeking optimal temperature), and mechanosensation (detecting surfaces) are core C. elegans behaviors that require environmental context. Without gradients and substrates, the worm can't exhibit naturalistic behavior.
Core Principle: "Building in the physics... because it matters."
DD022 delivers: Physical substrates (agar = viscoelastic solid, liquid = low-Reynolds-number fluid, soil = granular medium) with realistic mechanical properties, enabling validation against environment-dependent behaviors.
Goal & Success Criteria¶
| Criterion | Target | DD010 Tier |
|---|---|---|
| Primary: Chemotaxis behavior | CI (chemotaxis index) >0.5 on NaCl gradient (Iino & Yoshida 2009) | Tier 3 (blocking) |
| Primary: Thermotaxis behavior | Navigate to cultivation temperature (20°C) within ±2°C on thermal gradient | Tier 3 (blocking) |
| Secondary: Substrate-dependent locomotion | Crawling speed on agar vs. swimming speed in liquid matches experimental ratio (~2:1) | Tier 3 (blocking) |
| Tertiary: Tap withdrawal latency | Tap on agar (firm) vs. tap in liquid (soft) produces different reversal latencies | Tier 1 (non-blocking) |
Before: Worm exists in an infinite, featureless void. No substrate, no gradients, no food. Cannot exhibit naturalistic navigation behaviors.
After: Worm crawls on agar (or swims in liquid, or burrows in soil), senses chemical/thermal gradients via DD019/DD017 sensory transduction, navigates toward attractants (food, optimal temperature), avoids repellents.
Deliverables¶
| Artifact | Path | Format | Example |
|---|---|---|---|
| Agar substrate model | sibernetic/substrates/agar.cpp |
C++ (viscoelastic solid) | Young's modulus 3-10 kPa, Poisson ratio 0.45 |
| Liquid substrate model | sibernetic/substrates/liquid.cpp |
C++ (Navier-Stokes) | Viscosity 1e-3 Pa·s (water), Re ~0.01 |
| Chemical gradient field | sibernetic/stimuli/chemical_gradient.py |
Python | NaCl diffusion, concentration vs. position |
| Thermal gradient field | sibernetic/stimuli/thermal_gradient.py |
Python | Linear or radial temperature profile |
| Food particle system | sibernetic/food/bacterial_particles.cpp |
C++ (SPH particles) | OP50 bacteria as deformable particles in lumen |
| Geometric obstacles | sibernetic/obstacles/*.obj |
OBJ meshes | Pillars, channels, barriers for boundary conditions |
| Environment config | openworm.yml environment section |
YAML | substrate, gradients, food, obstacles |
| Chemotaxis trajectory (viewer) | OME-Zarr: environment/chemotaxis_path/ |
Shape (n_timesteps, 2) | (x, y) centroid on gradient |
| Gradient fields (viewer) | OME-Zarr: environment/gradients/ |
Shape (n_x, n_y, n_fields) | Concentration or temperature per spatial bin |
Repository & Issues¶
| Item | Value |
|---|---|
| Primary repository | openworm/sibernetic (environment is part of the physics engine) |
| Secondary repository | openworm/c302 (stimulus coupling to sensory neurons) |
| Issue label | dd022, environment |
| Related DDs | DD003 (Body Physics), DD019 (Touch Response) |
How to Build & Test¶
Prerequisites¶
- Sibernetic (DD003) running in Docker (DD013)
- c302 neural model (DD001) for sensory neuron stimulus coupling
- Stimulus configuration files (chemical gradient profiles, thermal profiles) — included in Docker image or generated at build time
Getting Started (Environment Setup)¶
This DD builds on the Sibernetic body physics framework (DD003). If you have already completed DD003 Getting Started, you are ready for the steps below.
If starting fresh, follow DD003 Getting Started first to clone the Sibernetic repository and install dependencies (including OpenCL), then return here.
Path A — Docker (recommended for newcomers):
cd OpenWorm
docker compose build
Then skip to Step-by-step below. The Docker image includes Sibernetic, substrate models, and gradient field solvers.
Path B — Native (for development):
Complete DD003 native setup (includes OpenCL platform notes for Linux/macOS/Windows), then:
# Install Python dependencies for gradient field solvers
cd sibernetic
pip install -r requirements-env.txt # numpy, scipy for diffusion/thermal solvers
# Generate steady-state gradient fields for chemotaxis/thermotaxis assays
python stimuli/chemical_gradient.py --output data/gradients/nacl_default.npy # [TO BE CREATED]
python stimuli/thermal_gradient.py --output data/gradients/thermal_default.npy # [TO BE CREATED]
Sensory neuron coupling (required for closed-loop behavior): Environmental stimuli must reach sensory neurons via the c302 neural model. Complete DD001 Getting Started to set up c302 and PyOpenWorm/OWMeta, which provide the sensory neuron wiring (AWC for chemotaxis, AFD for thermotaxis, ALM/PLM for mechanosensation).
Step-by-step¶
- Configure environment: Set environment parameters in
openworm.yml(temperature, chemical gradients)environment: substrate: "agar" chemical_gradient: true food_particles: false - Run simulation:
docker compose run quick-test --config chemotaxiswith stimulus delivery enabled - Verify stimulus delivery: Confirm stimulus reaches sensory neurons at correct timing and magnitude
- Green light: Chemotaxis gradient produces measurable neural response in AWC neurons; CI index >0.5 on standard NaCl assay
- Detailed test scripts:
[TO BE CREATED]
Technical Approach¶
Component 1: Substrate Mechanics (Agar vs. Liquid vs. Soil)¶
Agar (most common experimental substrate):
- Viscoelastic solid (not purely elastic, not purely viscous)
- Young's modulus: 3-10 kPa (depends on agarose concentration, typically 2%)
- Poisson ratio: 0.45 (nearly incompressible)
- DD003 boundary particles model agar as fixed constraints; extend to deformable substrate
Liquid (swimming experiments):
- Newtonian fluid (same Navier-Stokes as DD003 pseudocoelom)
- Viscosity: 1e-3 Pa·s (water) to 1e-2 Pa·s (M9 buffer)
- No solid substrate → worm swims, different gait (higher frequency, lower amplitude)
Soil (naturalistic environment):
- Granular medium (sand, decomposed organic matter)
- Modeled as additional SPH particles or DEM (discrete element method)
- Phase 5+ work (complex, low priority)
Component 2: Chemical Gradient Delivery¶
For chemotaxis experiments (ASEL/ASER neurons respond to NaCl):
Diffusion equation in 2D (agar surface):
∂C/∂t = D ∇²C
- D = diffusion coefficient (~1e-5 cm²/s for small molecules in agar)
- Boundary conditions: Source (high concentration) at one end, sink (low) at other
- Steady-state: Linear or exponential gradient
Simplified implementation:
- Pre-compute steady-state gradient field (no time evolution during simulation)
- Lookup concentration at worm's (x, y) position each timestep
- Feed to DD019/DD017 chemosensory transduction model
Closed-Loop Sensorimotor Interaction for Chemotaxis¶
The defining feature of naturalistic chemotaxis is the closed-loop interaction between sensation and movement. Zhao et al. (2024) demonstrated this with their MetaWorm model, achieving zigzag navigation toward food attractors that matches experimentally observed trajectories (Pierce-Shimomura et al. 1999).
Closed-loop cycle (each simulation timestep):
- Body position (DD003) provides the worm's current location in the environment
- Local concentration (DD022 gradient field) sampled at the worm's head position
- Temporal derivative
dC/dt = (C(t) - C(t-dt)) / dtcomputed — this implements the biased random walk strategy where the worm responds to concentration changes, not absolute levels - Sensory neuron activation (DD001/DD017):
dC/dtconverted to current injection on chemosensory neurons (AWC for odors, ASEL/ASER for salt) - Neural circuit computation (DD001): sensory input propagates through interneurons to motor neurons
- Motor output (DD002): motor neuron calcium drives muscle contraction
- Body movement (DD003): muscles deform the body, propelling it through the environment
- Return to step 1
Key biological insight: Sensory activation uses the temporal derivative dC/dt, not the absolute concentration C(t). This is because C. elegans employs a biased random walk strategy: it extends forward runs when moving up-gradient (positive dC/dt) and initiates turns/reversals when moving down-gradient (negative dC/dt) (Pierce-Shimomura et al. 1999).
OpenWorm's approach differs from Zhao et al. in a critical way: they used a linear readout layer from motor neuron membrane potentials to muscle activations (treating the neural circuit as a 'reservoir computer'). OpenWorm instead uses biophysical neuromuscular junction synapses (DD002), producing a fully mechanistic chain from sensation to movement with no learned components in the motor pathway.
Validation target: The simulated worm's trajectory in a chemical gradient should exhibit the characteristic zigzag pattern toward the food source, with a chemotaxis index (CI) > 0.5 on a standard NaCl gradient assay (Iino & Yoshida 2009).
Component 3: Thermal Gradient Delivery¶
For thermotaxis experiments (AFD neuron responds to temperature):
Similar to chemical gradient but for temperature:
- Cultivation temperature (20°C) at one end, 15°C or 25°C at other
- Linear or radial gradient
- Feed to DD017 Component 4 learned thermosensory model
Component 4: Food Particles (OP50 Bacteria)¶
For pharyngeal pumping + feeding behavior:
- Bacteria modeled as small deformable SPH particles (~1 µm diameter)
- Delivered to pharyngeal lumen via pumping (DD007)
- Grinder crushes bacteria (future: mechanical food processing)
Phase 3 work (not required for basic pumping frequency validation).
Alternatives Considered¶
1. Ignore Environment (Worm in Void)¶
Rejected: Cannot model naturalistic behaviors (chemotaxis, thermotaxis, food seeking) without environmental context. The worm's sensory system evolved to detect gradients — testing it requires gradients.
2. Simplified: Boundary Conditions Only (No Substrate Mechanics)¶
Description: Keep boundary particles fixed (current DD003), just add chemical/thermal fields.
Partially adopted: For Phase 2-3, this is the pragmatic approach. Substrate mechanics (agar deformability) can be deferred to Phase 5+.
Quality Criteria¶
- Chemotaxis reproduction: Simulated worm on NaCl gradient produces CI (chemotaxis index) >0.5 (Iino & Yoshida 2009 experimental data).
- Thermotaxis reproduction: Worm navigates to 20°C on 15-25°C gradient within ±2°C.
- Substrate-dependent gait: Crawling on agar vs. swimming in liquid produces ~2:1 speed ratio (matches experiments).
- No destabilization: Adding environment must not break DD003 body physics (no particle escape, no NaN).
Boundaries (Explicitly Out of Scope)¶
- Multi-worm environments: Social aggregation, pheromone communication. Single-worm only.
- Complex geometries: Microfluidic mazes, 3D terrains. Flat gradients for Phase 2-3.
- Food consumption dynamics: Bacterial digestion, nutrient absorption. Food particles are visual only (Phase 3).
- Soil microbial ecology: Bacteria, fungi, nematode predators. Simple soil mechanics only (Phase 5+).
Integration Contract¶
Inputs¶
| Input | Source DD | Variable | Format |
|---|---|---|---|
| Worm body position | DD003 | Centroid (x, y) from SPH particles | Computed from body/ OME-Zarr |
| Sensory neuron positions | DD001 / DD008 | Per-neuron (x, y, z) | Static coordinates |
Outputs¶
| Output | Consumer DD | Variable | Format |
|---|---|---|---|
| Local chemical concentration | DD017 Component 4 (chemosensory) | Concentration at worm position | Scalar (mM) |
| Local temperature | DD017 Component 4 (thermosensory) | Temperature at worm position | Scalar (°C) |
| Substrate reaction force | DD003 | Boundary particle forces | SPH force vectors |
Context & Background¶
C. elegans lives in soil and responds to multiple environmental stimuli: mechanical touch, chemical gradients (food attractants, repellents), temperature gradients, and osmotic changes. The environment model must deliver these stimuli to the correct sensory neurons with biologically realistic spatial and temporal profiles.
Chemotaxis is the best-studied navigational behavior: the worm uses a biased random walk strategy, extending forward runs when moving up a concentration gradient and initiating turns when moving down-gradient (Pierce-Shimomura et al. 1999). Thermotaxis follows a similar strategy, with the AFD neuron detecting temperature relative to cultivation temperature. Mechanosensation — the detection of substrate properties and external touch — is mediated by dedicated touch receptor neurons (Goodman 2006).
Without an environment model, the virtual worm exists in a featureless void and cannot exhibit any of these naturalistic behaviors. This DD provides the environmental context that makes sensory-driven behavior possible.
References¶
- Iino Y, Yoshida K (2009). "Parallel use of two behavioral mechanisms for chemotaxis in Caenorhabditis elegans." J Neurosci 29:5370-5380. NaCl chemotaxis assay — chemotaxis index (CI) metric and experimental benchmarks.
- Pierce-Shimomura JT, Morse TM, Lockery SR (1999). "The fundamental role of pirouettes in Caenorhabditis elegans chemotaxis." J Neurosci 19:9557-9569. Biased random walk strategy — temporal derivative of concentration drives run/pirouette decisions.
- Zhao M, Wang N, Jiang X, et al. (2024). "An integrative data-driven model simulating C. elegans brain, body and environment interactions." Nature Computational Science 4(12):978-990. MetaWorm model — closed-loop chemotaxis demonstration with zigzag trajectories matching experimental observations.
- Approved by: Pending
- Implementation Status: Proposed (Phase 2)
-
Next Actions:
-
Write detailed substrate mechanics spec (agar viscoelasticity parameters)
- Implement steady-state gradient solver (chemical, thermal)
- Test with DD019 closed-loop touch + chemotaxis
- Validate against Iino & Yoshida 2009 chemotaxis data