DD003: Muscle Model Architecture and Calcium-Force Coupling¶
- Status: Accepted
- Author: OpenWorm Core Team (based on Boyle & Cohen 2008)
- Date: 2026-02-14
- Supersedes: None
- Related: DD002 (Neural Circuit), DD001 (Body Physics)
TL;DR¶
The muscle model uses Hodgkin-Huxley muscle cells with Ca²⁺-to-force coupling, bridging the neural voltage domain (mV, milliseconds) to the Sibernetic body physics domain (forces, mechanical strain). 95 body wall muscles in 4 quadrants convert intracellular calcium concentration to a linear activation coefficient [0, 1] consumed by Sibernetic. Success: forward speed and body bend amplitude within ±15% of Schafer lab experimental data.
Quick Action Reference¶
| Question | Answer |
|---|---|
| Phase | Phase 0 |
| Layer | Core Architecture — see Phase Roadmap |
| What does this produce? | GenericMuscleCell NeuroML template (95 body wall muscles), muscle [Ca²⁺]→activation coupling via sibernetic_c302.py |
| Success metric | DD010 Tier 3: forward speed and body bend amplitude within ±15% of baseline |
| Repository | openworm/c302 (muscle templates) + openworm/sibernetic (coupling script) — issues labeled dd003 |
| Config toggle | muscle.enabled: true / muscle.calcium_coupling: true in openworm.yml |
| Build & test | docker compose run quick-test (activation in [0,1]?), docker compose run validate (Tier 3 kinematics) |
| Visualize | DD012 muscle/activation/ layer — 95 muscles with [0,1] activation heatmap, warm colormap |
| CI gate | Tier 3 kinematic validation blocks merge |
| --- |
Goal & Success Criteria¶
| Criterion | Target | DD010 Tier |
|---|---|---|
| Primary: Forward speed | Within ±15% of Schafer lab WCON baseline | Tier 3 (blocking) |
| Primary: Body bend amplitude | Within ±15% of Schafer lab WCON baseline | Tier 3 (blocking) |
| Secondary: Muscle activation range | All activations in [0, 1], peak > 0.3 during neural drive | Quick-test (blocking per-PR) |
| Tertiary: Calcium decay dynamics | Decay time constant ~12 ms, consistent with Boyle & Cohen 2008 | Tier 1 (non-blocking) |
Before: No electrophysiological muscle model — neurons could not drive body physics through a biophysically realistic pathway.
After: 95 body wall muscles receive motor neuron input via NMJ synapses, depolarize via HH channels, accumulate intracellular calcium, and produce a [0, 1] activation coefficient that Sibernetic converts to contractile force.
Deliverables¶
| Artifact | Path (relative to repo) | Format | Example |
|---|---|---|---|
| Generic muscle cell template | openworm/c302 — c302/c302_Muscles.py |
Python → NeuroML 2 XML | GenericMuscleCell with 4 channels (muscle-specific densities) |
| Muscle list (95 cells) | CElegansNeuroML/CElegans/generatedNeuroML2/muscles.csv |
CSV | muscle_id, quadrant, row_number, anterior_position, synaptic_partners |
| Coupling script | openworm/sibernetic — sibernetic_c302.py |
Python | Reads muscle [Ca²⁺]ᵢ, writes activation to Sibernetic |
| Muscle activation time series (viewer) | OME-Zarr: muscle/activation/, shape (n_timesteps, 95) |
OME-Zarr | dimensionless [0, 1] per muscle per timestep |
| Muscle calcium time series (viewer) | OME-Zarr: muscle/calcium/, shape (n_timesteps, 95) |
OME-Zarr | mol/cm³ per muscle per timestep |
Repository & Issues¶
| Item | Value |
|---|---|
| Repository (templates) | openworm/c302 |
| Repository (coupling) | openworm/sibernetic |
| Issue label | dd003 |
| Milestone | Muscle Model Architecture |
| Branch convention | dd003/description (e.g., dd003/tune-nmj-conductance) |
| Example PR title | DD003: Adjust muscle conductance densities for locomotion fidelity |
How to Build & Test¶
Prerequisites¶
Getting Started (Environment Setup)¶
The muscle model lives in the same c302 repository as the neural circuit (DD002). If you already set up DD002, you're ready — skip to Step 1 below.
Clone the repositories:
git clone https://github.com/openworm/c302.git
git clone https://github.com/openworm/sibernetic.git # for coupled simulation
git clone https://github.com/openworm/OpenWorm.git # for docker compose
Path A — Docker (recommended for newcomers):
cd OpenWorm
docker compose build
Then skip to Step 6 below (docker compose run quick-test).
Path B — Native Python:
cd c302
pip install -e . # installs c302 + dependencies
pip install pyneuroml neuron # NeuroML tools + NEURON simulator
You also need jNeuroML (jnml) on your PATH (requires Java). Steps 1–5 below use the native path. Steps 6–7 use Docker.
Step-by-step¶
# Step 1: Generate muscle network
cd c302/
python CElegans.py C1Muscles
# Step 2: Validate NeuroML syntax
jnml -validate LEMS_c302_C1_Muscles.xml
# Step 3: Run simulation
jnml LEMS_c302_C1_Muscles.xml -nogui
# Step 4: Check muscle activation outputs
python scripts/plot_muscle_activation.py LEMS_c302_C1_Muscles_muscles.dat
# [TO BE CREATED] if not present — GitHub issue: openworm/c302#TBD
# Step 5: Verify activation ranges and calcium dynamics
python scripts/validate_muscle_calcium.py
# [TO BE CREATED] if not present — GitHub issue: openworm/c302#TBD
# Step 6: Quick test via Docker (must pass before PR)
docker compose run quick-test
# Green light: output plots show muscle activation in [0, 1] range
# Green light: peak activation during neural drive > 0.3
# Step 7: Full validation via Docker (must pass before merge)
docker compose run validate
# Green light: Tier 3 kinematic metrics within ±15% of baseline
# Green light: forward speed and body bend amplitude specifically checked
Scripts that may not exist yet¶
| Script | Status | Tracking |
|---|---|---|
scripts/plot_muscle_activation.py |
[TO BE CREATED] if not present |
openworm/c302#TBD |
scripts/validate_muscle_calcium.py |
[TO BE CREATED] if not present |
openworm/c302#TBD |
Green light criteria¶
- Muscle activation range: [0, 1]
- Peak activation during neural drive: >0.5 (>0.3 minimum)
- Calcium decay time constant: ~12 ms
- No negative voltages below -60 mV, no positive voltages above +20 mV
- Tier 3 kinematic metrics within ±15% of baseline
How to Visualize¶
DD012 viewer layer: muscle/activation/ — 95 body wall muscles with [0, 1] activation heatmap, warm colormap.
| Viewer Feature | Specification |
|---|---|
| Layer | muscle/activation/ |
| Color mode | Warm colormap: 0 (blue/cool) → 1 (red/hot) representing activation coefficient |
| Data source | OME-Zarr: muscle/activation/ shape (n_timesteps, 95), muscle/calcium/ shape (n_timesteps, 95) |
| What you should SEE | 95 body wall muscles arranged in 4 quadrants (MDR, MVR, MVL, MDL). During forward locomotion, dorsal and ventral muscles should activate in alternating waves propagating anterior-to-posterior. Activation values should range [0, 1] with smooth transitions (no flickering or binary on/off). |
| Trace view | Clicking a muscle shows its calcium concentration and activation coefficient time series. Calcium decay should be ~12 ms. |
Technical Approach¶
Muscle Cells Use the Same Hodgkin-Huxley Framework as Neurons¶
Muscles are modeled as single-compartment conductance-based cells using the same ion channel types (leak, K_slow, K_fast, Ca_boyle) with muscle-specific conductance densities tuned to produce slower, sustained depolarizations rather than sharp action potentials.
Muscle conductance densities (from Boyle & Cohen 2008):
| Channel | Muscle g_max | E_rev | Notes |
|---|---|---|---|
| Leak | 5e-7 S/cm² | -50 mV | 100x smaller than neurons → slower dynamics |
| K_slow | 0.0006 S/cm² | -60 mV | 5000x smaller than neurons |
| K_fast | 0.0001 S/cm² | -60 mV | 711x smaller than neurons |
| Ca_boyle | 0.0007 S/cm² | +40 mV | ~4300x smaller than neurons |
Membrane properties:
- Specific capacitance: 1 µF/cm²
- Cell diameter: larger than neurons (varies by muscle, ~5-10 µm)
- Initial voltage: -45 mV
Calcium-to-Force Coupling (The Bridge to Sibernetic)¶
Intracellular calcium concentration ([Ca²⁺]ᵢ) is the coupling variable between the electrophysiological model (NeuroML/NEURON) and the body physics model (Sibernetic/SPH).
Calcium dynamics:
d[Ca]/dt = -rho * I_Ca - [Ca]/tau_Ca
- rho = 0.000238 mol/(C·cm)
- tau_Ca = 11.5943 ms
Activation coefficient (linear scaling):
activation = min(1.0, [Ca²⁺]ᵢ / [Ca²⁺]_max)
- [Ca²⁺]_max = 4e-7 mol (maximum calcium for full contraction)
Force generation:
F_muscle = activation * max_muscle_force
- max_muscle_force = 4000 (Sibernetic units)
This linear scaling is a simplification. Real muscle involves crossbridge dynamics (actin-myosin binding), cooperative activation, length-tension relationships, and force-velocity curves. But Boyle & Cohen (2008) showed that "Caenorhabditis elegans body wall muscles are simple actuators" -- they behave as direct transducers of calcium to force without complex mechanical nonlinearities.
Neural-to-Muscle Coupling¶
Neurons communicate to muscles via neuromuscular junctions (NMJs) modeled as excitatory chemical synapses:
- Neuron releases synaptic current proportional to presynaptic voltage (graded release)
- Muscle receives depolarizing current
- Muscle voltage rises → Ca channels open → [Ca²⁺]ᵢ increases → contraction
Critical parameter: NMJ conductance is higher than neuron-neuron synapses to produce strong muscle depolarization. Typical values: 0.5-1.0 nS (vs. 0.09 nS for inter-neuron synapses).
Alternatives Considered¶
1. Hill-Type Muscle Model with Crossbridge Dynamics¶
Description: Explicitly model actin-myosin binding, ADP/ATP cycling, length-tension curves, force-velocity relationships.
Rejected because:
- Boyle & Cohen (2008) demonstrated that simple linear activation is sufficient to reproduce C. elegans locomotion
- Adds significant computational cost (6+ additional state variables per muscle)
- Lacks experimental data to parameterize crossbridge kinetics in C. elegans muscles
- Violates YAGNI (You Aren't Gonna Need It) principle
When to reconsider: If simulations fail to reproduce detailed muscle mechanics (e.g., tetanic contraction during egg-laying, rapid twitches during defecation, isometric force-length relationships).
2. Direct Neural Activation Without Electrophysiology¶
Description: Skip the muscle HH model entirely. Let neurons directly control Sibernetic particle forces.
Rejected because:
- Throws away the biophysical realism that is OpenWorm's core strength
- Loses the voltage-to-calcium-to-force causal chain, making the model less interpretable
- Cannot capture muscle dynamics like refractory periods, fatigue, or calcium-dependent force modulation
3. FitzHugh-Nagumo Simplified Excitable Dynamics¶
Description: Use a 2-variable reduced model (V, recovery variable) instead of full HH.
Rejected because:
- FHN does not explicitly model calcium, which is the critical coupling variable to Sibernetic
- Parameters are abstract (not directly tied to conductances and ion channels)
- Loses the modularity of being able to add/remove specific channels
Quality Criteria¶
A contribution to the muscle model MUST:
-
Preserve the Calcium Interface: The output of the muscle model to Sibernetic is [Ca²⁺]ᵢ. Any change must maintain this interface or provide a migration path for Sibernetic.
-
Validate Against Movement Data: Changes must not degrade kinematic validation scores. The Boyle & Cohen parameter set has been validated against real worm movement via open-worm-analysis-toolbox.
-
NeuroML 2 Compliance: Muscle cell definitions must be valid NeuroML 2.
-
Biophysical Units: Conductances in S/cm² or mS/cm², voltages in mV, time constants in ms, calcium in mol or mM.
-
Muscle-Neuron Distinction: Muscle conductance densities are 10-1000x smaller than neuron densities. Do not copy neuron parameters to muscles.
Testing Procedure (Quick Reference)¶
# Generate muscle network
cd c302/
python CElegans.py C1Muscles
# Run simulation
jnml LEMS_c302_C1_Muscles.xml -nogui
# Check muscle activation outputs
python scripts/plot_muscle_activation.py LEMS_c302_C1_Muscles_muscles.dat
# Verify activation ranges are [0, 1] and follow calcium dynamics
python scripts/validate_muscle_calcium.py
Expected results:
- Muscle activation range: [0, 1]
- Peak activation during neural drive: >0.5
- Calcium decay time constant: ~12 ms
- No negative voltages below -60 mV, no positive voltages above +20 mV
Validation Methodology (Twitch → Curves → Round-Trip)¶
Muscle-model changes affect three interlocking validation targets: a single muscle's twitch dynamics (calcium pulse → force pulse shape), the steady-state force-velocity and force-length curves, and the round-trip through Sibernetic body physics (a single quadrant activation must bend the worm in the expected direction with the expected curvature). Each target has a workflow; each follows the cross-tier Validation Workflow Pattern (predict → reference → inspect → refine → implement → tune → render → compare).
Level 1 — Twitch Dynamics (Calcium → Force Pulse)¶
When to apply: any change to the calcium-to-force coupling formula, the muscle cell HH parameters, or the time constants in the activation dynamics.
Reference: Boyle & Cohen 2008 — single-muscle twitch traces showing the calcium-to-force temporal coupling. Specific values: peak twitch force ~2.7 × 10⁻⁹ N (experimentally observed range 1.4–9.6 × 10⁻⁹ N); twitch rise time ~10 ms; decay time constant ~12 ms; activation range [0, 1].
8-phase instantiation:
| Phase | Per-muscle activity |
|---|---|
| 1. Predict | From the HH calcium dynamics (tau_decay, max_ca) + the activation formula (e.g., act = ca / (K_M + ca)), predict the twitch shape: rise time, peak amplitude, decay time. |
| 2. Reference | Pull the Boyle & Cohen 2008 twitch trace from the curated dataset directory. Cite version: data/boyle_cohen_2008_v*/twitch_trace.csv. |
| 3. Inspect | Measure reference twitch: rise time, peak, decay τ. Note that experimental peak forces span ~7× (1.4–9.6 nN); typical "good fit" sits near 2.7 nN. |
| 4. Refine | Update target values with measured ones; flag if your prediction missed by more than 30% on any (likely a wrong assumption in the coupling formula). |
| 5. Implement | Update muscle NeuroML cell template; verify jnml -validate passes. |
| 6. Tune | Grid search over max_ca, K_M, time constants. Do NOT hand-sweep. Save log. |
| 7. Render | Overlay model twitch vs. reference twitch; mark rise, peak, decay markers. Commit PNG. |
| 8. Compare | Per-feature pass/fail: rise time ±20%, peak ±30%, decay τ ±20%. Commit table + plot + tuning log. |
Level 2 — Steady-State Force-Velocity and Force-Length Curves¶
When to apply: when the muscle model gains a contractile-dynamics component (Hill-type element, crossbridge dynamics) or when validating the steady-state behavior of the current simplified model under sustained activation.
Reference: classical Hill 1938 force-velocity relationship; Gordon, Huxley & Julian 1966 force-length relationship. C. elegans-specific muscle mechanical data is sparse; the worm-specific reference is the implicit force-output range required to produce Schafer-lab locomotion kinematics under Boyle & Cohen 2008's parameter set.
8-phase instantiation:
| Phase | Per-curve activity |
|---|---|
| 1. Predict | From the muscle model's parameters, predict the force as a function of shortening velocity and the force as a function of length. Cite the underlying assumptions (linear vs. Hill hyperbolic, sarcomere length range). |
| 2. Reference | Hill 1938 / Gordon-Huxley-Julian 1966 generic curves; the C. elegans-implied force range derived from Boyle & Cohen 2008's matched-kinematics fit. |
| 3. Inspect | Plot the reference curves with their parameter sets (v_max, a/F_0 for Hill, sarcomere optimal length range for force-length). |
| 4. Refine | Update target curves; if the worm-specific reference is implied rather than direct, note this explicitly — pass/fail thresholds will be wider (±50% acceptable). |
| 5. Implement | Add the contractile-dynamics component to the muscle cell or muscle-to-force coupling formula. |
| 6. Tune | Fit Hill parameters or force-length coefficients via grid search or scipy least-squares. |
| 7. Render | Overlay model curves on reference; mark v_max, F_0, optimal length. Commit PNGs. |
| 8. Compare | Curve-shape match (R² > 0.7); peak values within ±50% of reference. Commit table + plots + fit log. |
Note: If you are NOT adding a contractile-dynamics component (i.e., using Boyle & Cohen 2008's simplified calcium-proportional formula), Level 2 is not required. The simplified model is validated indirectly via Level 3 (round-trip kinematics).
Level 3 — Round-Trip with Sibernetic (Quadrant Activation → Body Bend)¶
When to apply: any change to the muscle model that could shift its force output. Even formula-internal changes that "should be force-conserving" must be checked at this level — the body is a closed loop with elastic recovery, so any phase or amplitude shift propagates into kinematics.
Reference: the canonical body-bend test — activate one muscle quadrant (e.g., dorsal-left) and observe whether the body bends in the expected direction with the expected curvature. The detailed Schafer-lab kinematic match is Tier 3 in DD010.
This level uses the DD001 §Validation Methodology tooling — dump_metal_trajectory.py, side-by-side rendering, SGD tuning — with the muscle activation as the input driver. The change being validated is the muscle model; Sibernetic is the simulator; the body-bend shape is the reference.
8-phase summary:
- Predict body bend curvature from quadrant activation pattern + Sibernetic elastic bond stiffness.
- Reference = a known-good baseline body-bend trajectory from before the muscle change (or, for new builds, from the OpenCL gold standard with Boyle & Cohen 2008 parameters).
- Inspect baseline curvature, time-to-peak-bend, recovery time constant.
- Refine targets.
- Implement muscle change.
- Tune any free parameters using gradient-free SGD or grid search (muscle ODE not yet differentiable per DD013).
- Render side-by-side worm-body MP4: baseline vs. post-change.
- Compare curvature, time-to-peak, recovery τ within ±15% (matches Tier 3 thresholds).
Key cross-DD dependency: since the body substrate is differentiable end-to-end (DD001 §Differentiability), the muscle activation → elastic-bond-stiffness modulation path is included in the differentiable pipeline. This means once the muscle-side ODE is also differentiable, joint muscle-and-body parameter fitting via SGD becomes possible.
Mind-of-a-Worm PR Review Checklist (Muscle-Model-Specific)¶
When reviewing a DD003 PR, MoaW must verify:
| # | Check | Pass condition |
|---|---|---|
| 1 | Level identified | The PR clearly states which level(s) of validation it touches: twitch, curves, or round-trip. |
| 2 | Boyle & Cohen 2008 reference cited | PR cites the specific dataset version and notes how the change relates to the validated parameter set. |
| 3 | Twitch trace overlay | For Level 1 changes, model-vs-reference twitch trace PNG committed. |
| 4 | Force-velocity / force-length curves | For Level 2 changes (only if contractile dynamics added), curve overlay PNGs + Hill/Gordon-Huxley-Julian fits committed. |
| 5 | Body-bend round-trip MP4 | For Level 3 changes, side-by-side body-bend video committed under docs/. |
| 6 | NeuroML validates | jnml -validate passes. |
| 7 | Tuning log if parameters changed | Grid search or NSGA-II convergence log committed; no hand-sweeping. |
| 8 | Activation range [0,1] preserved | plot_muscle_activation.py output shows activation in range, no negative values. |
| 9 | Calcium interface preserved | The output to Sibernetic is still [Ca²⁺]ᵢ per the Integration Contract, or a migration path is provided. |
| 10 | Tier 3 regression check | open-worm-analysis-toolbox confirms no degradation in the 5 kinematic metrics. |
Common Gotchas (Muscle-Model-Specific)¶
- Copying neuron HH parameters to muscle. Muscle conductance densities are 10–1000× smaller than neuron densities. Calcium dynamics also differ (slower). Per Quality Criterion 5, this is a recurring landmine.
- Skipping Level 3 for "internal" changes. A formula change that's mathematically force-conserving on paper often shifts phase or amplitude in practice. Always run the body-bend round-trip.
- Targeting "right answer" instead of "right range." The experimentally observed peak twitch force spans 1.4–9.6 nN — a 7× range. Demanding a specific value within that range is over-tuning. Pick the value that best matches the round-trip kinematics, not an arbitrary mid-point.
- Breaking the calcium interface without a migration plan. Sibernetic reads
[Ca²⁺]ᵢas the muscle activation source. If the formula changes such that a different variable becomes the activation source, thesibernetic_c302.pycoupling script must change in lockstep (and that change goes through DD001 review). - Treating muscle ODE as if it were already differentiable. It isn't (yet). Joint SGD over muscle + body parameters requires the muscle side to also be differentiable — currently future work per DD013. For now, use gradient-free tuning for the muscle and let SGD handle the body side only.
Boundaries (Explicitly Out of Scope)¶
This Design Document Does NOT Cover:¶
-
Pharyngeal muscles: Modeled separately (see DD007: Pharyngeal System). Pharyngeal muscle is nonstriated and functionally distinct from body wall muscle.
-
Specialized muscles (vulval, uterine, anal, intestinal): Future work. These may require different channel complements or calcium-to-force relationships.
-
Muscle cell geometry: Currently single-compartment. Multicompartmental muscle with spindle morphology is future work.
-
Developmental changes: Muscle properties change during development (L1 vs. adult). Phase 6 work.
-
Myosin isoform diversity: C. elegans expresses multiple myosin heavy chain genes. Current model uses generic contractility.
Context & Background¶
C. elegans body wall muscles enable locomotion by generating contractile forces that deform the elastic body against the fluid-filled pseudocoelom. The worm has 95 body wall muscles arranged in 4 quadrants (MDR, MVR, MVL, MDL) of 24 rows each, extending along the anterior-posterior axis. These muscles are excitable membranes innervated by motor neurons.
The coupling challenge: neurons operate in the voltage domain (mV, milliseconds), body physics operates in the force domain (Newtons, mechanical strain). The muscle model bridges these domains.
Implementation References¶
Muscle Cell Template¶
# c302/c302_Muscles.py
def create_generic_muscle_cell():
muscle_cell = NeuroMLCell(id="GenericMuscleCell")
muscle_cell.add_channel("leak_chan", density="5e-7 S_per_cm2")
muscle_cell.add_channel("k_slow_chan", density="0.0006 S_per_cm2")
muscle_cell.add_channel("k_fast_chan", density="0.0001 S_per_cm2")
muscle_cell.add_channel("ca_boyle_chan", density="0.0007 S_per_cm2")
muscle_cell.C = 1.0 # uF_per_cm2
muscle_cell.v_init = -45 # mV
return muscle_cell
Muscle List (95 Cells)¶
CElegansNeuroML/CElegans/generatedNeuroML2/muscles.csv
Each muscle row: muscle_id, quadrant (MDR/MVR/MVL/MDL), row_number (1-24), anterior_position, synaptic_partners
Coupling to Sibernetic¶
The c302_Sibernetic integration script:
- Reads muscle [Ca²⁺]ᵢ time series from NEURON simulation
- Converts to activation coefficients via
activation = min(1, ca/max_ca) - Writes to Sibernetic-readable muscle activation file
- Sibernetic reads and applies forces to elastic particle connections representing each muscle
Migration Path¶
If Detailed Crossbridge Mechanics Become Necessary:¶
- Create a new Level D cell type with crossbridge state variables (attached, detached, power stroke, etc.).
- Implement as a LEMS ComponentType extension rather than modifying the base GenericMuscleCell.
- Provide [Ca²⁺]ᵢ → force mapping that preserves the Sibernetic interface.
- Validate against isometric force recordings if such data become available for C. elegans.
If Muscle-Type Diversity Is Required (Phase 3):¶
See DD007 (Pharyngeal System) for an example of creating a distinct muscle cell type. The general pattern:
- Create a new LEMS cell template (e.g.,
PharyngealMuscleCell) - Adjust channel densities based on transcriptomic or electrophysiological data
- Adjust calcium-to-force parameters if pharyngeal contraction dynamics differ
- Validate against tissue-specific behavior (pumping rate, not crawling)
Known Issues and Future Work¶
Issue 1: Single Muscle Compartment¶
Real C. elegans body wall muscles are spindle-shaped with ~60 µm length. Voltage may not be uniform along the length. Multicompartmental muscle models (Level D equivalent for muscle) would require:
- Morphological reconstructions (EM data exists but not yet digitized in cable-equation-compatible format)
- Axial resistance parameters
- Increased compute cost (24 compartments/muscle × 95 muscles = 2,280 compartments)
When to address: If single-compartment fails to reproduce localized muscle responses or wave propagation.
Issue 2: Lack of Direct Muscle Electrophysiology¶
Most validation is indirect (via movement). Direct patch-clamp recordings from C. elegans muscle are rare. We validate via the emergent behavior (crawling), not the muscle voltage directly.
When to address: If muscle-specific electrophysiology data become available, recalibrate conductance densities.
Issue 3: MVL24 Muscle Does Not Exist¶
The simulation includes MVL24 for symmetry (4 quadrants × 24 rows = 96 muscles), but the real worm has only 95 (MVL24 is absent). This is a minor biological inaccuracy preserved for code simplicity.
Fix: Set MVL24 conductances to zero or remove from the simulation. Low priority.
References¶
-
Boyle JH, Cohen N (2008). "Caenorhabditis elegans body wall muscles are simple actuators." Biosystems 94:170-181. Source of muscle conductance densities and calcium-to-force coupling.
-
Goodman MB, Hall DH, Avery L, Bhatt R (1998). "Active currents regulate sensitivity and dynamic range in C. elegans neurons." Neuron 20:763-772. Evidence for graded potentials in the nervous system that drives these muscles.
-
Cook SJ et al. (2019). "Whole-animal connectomes of both Caenorhabditis elegans sexes." Nature 571:63-71. NMJ connectivity (which motor neurons innervate which muscles).
Integration Contract¶
Inputs / Outputs¶
Inputs (What This Subsystem Consumes)
| Input | Source DD | Variable | Format | Units |
|---|---|---|---|---|
| Motor neuron synaptic current | DD002 (via NMJ graded synapses) | I_syn on each muscle cell |
NeuroML synapse coupling (within same LEMS simulation) | nA |
| Motor neuron identity | DD002 connectome | NMJ adjacency (which neurons innervate which muscles) | ConnectomeToolbox | neuron-muscle pairs |
Outputs (What This Subsystem Produces)
| Output | Consumer DD | Variable | Format | Units | Timestep |
|---|---|---|---|---|---|
| Muscle [Ca²⁺]ᵢ | DD001 (Sibernetic) | ca_internal per muscle |
Read by sibernetic_c302.py from NEURON state |
mol/cm³ | dt_coupling (0.005 ms) |
| Muscle activation coefficient | DD001 (Sibernetic) | activation = min(1.0, [Ca²⁺]ᵢ / 4e-7) |
Computed in sibernetic_c302.py, written to Sibernetic muscle activation input |
dimensionless [0, 1] | dt_coupling |
| Muscle activation time series (for viewer) | DD012 (visualization) | Per-muscle activation over all timesteps | OME-Zarr: muscle/activation/, shape (n_timesteps, 95) |
dimensionless [0, 1] | output_interval |
| Muscle calcium time series (for viewer) | DD012 (visualization) | Per-muscle [Ca²⁺] over all timesteps | OME-Zarr: muscle/calcium/, shape (n_timesteps, 95) |
mol/cm³ | output_interval |
Repository & Packaging¶
| Item | Value |
|---|---|
| Repository (templates) | openworm/c302 (muscle cells are NeuroML templates within c302) |
| Repository (coupling) | openworm/sibernetic (sibernetic_c302.py) |
| Docker stage | Same as DD002 (neural stage) |
versions.lock key |
No separate pin — muscles are part of the c302 package |
| Build dependencies | Same as DD002 (NEURON 8.2.6, pyNeuroML) |
Configuration¶
openworm.yml section:
muscle:
enabled: true # Requires neural.enabled
calcium_coupling: true # Ca²⁺ → force pipeline
max_muscle_force: 4000 # Sibernetic force units
max_ca: 4e-7 # mol; calcium for full contraction
| Key | Default | Valid Range | Description |
|---|---|---|---|
muscle.enabled |
true |
true/false |
Enable muscle simulation (requires neural.enabled) |
muscle.calcium_coupling |
true |
true/false |
Enable Ca²⁺ → force coupling pipeline |
muscle.max_muscle_force |
4000 |
Positive float | Maximum muscle force in Sibernetic units |
muscle.max_ca |
4e-7 |
Positive float (mol) | Calcium concentration for full contraction (activation = 1.0) |
How to Test (Contributor Workflow)¶
# Per-PR quick test (must pass before submission)
docker compose run quick-test
# Checks: output plots show muscle activation in [0, 1] range
# Checks: peak activation during neural drive > 0.3
# Full validation (must pass before merge to main)
docker compose run validate
# Checks:
# - Tier 3: kinematic metrics within ±15% of baseline
# - Specifically: forward speed and body bend amplitude are most sensitive to muscle changes
Per-PR checklist:
- [ ]
jnml -validatepasses for muscle NeuroML/LEMS files - [ ]
docker compose run quick-testpasses (activation in [0, 1], peak > 0.3) - [ ]
docker compose run validatepasses (Tier 3 kinematics) - [ ] Muscle conductance densities are 10-1000x smaller than neuron densities (no copy-paste from neuron params)
- [ ] Calcium interface to Sibernetic is preserved (variable name, units)
How to Visualize (DD012 Connection)¶
| OME-Zarr Group | Viewer Layer | Color Mapping |
|---|---|---|
muscle/activation/ (n_timesteps, 95) |
Muscle activation heatmap | Warm colormap: 0.0 (blue) → 1.0 (red) |
muscle/calcium/ (n_timesteps, 95) |
Muscle calcium concentration | mol/cm³ colormap |
Coupling Dependencies¶
| I Depend On | DD | What Breaks If They Change |
|---|---|---|
| Neuron→muscle synaptic conductance | DD002 | NMJ weight changes → muscle depolarization amplitude changes |
| c302 HH framework | DD002 | If channel model equations change, muscle dynamics change (same framework) |
| Depends On Me | DD | What Breaks If I Change |
|---|---|---|
| Body physics forces | DD001 | If calcium→activation mapping changes (max_ca, activation formula), Sibernetic locomotion behavior changes |
| Kinematic validation | DD010 | Muscle force directly determines movement — any change affects Tier 3 |
Note on differentiability downstream: Sibernetic (DD001) is end-to-end differentiable on the native Metal substrate — the muscle activation → elastic-bond-stiffness modulation path is included in the differentiable pipeline. This means muscle parameters that act through the body (force magnitudes, per-muscle scaling, activation timing) can be tuned via gradient descent against kinematic targets once the muscle-side ODE is also differentiable. See DD002 §Joint Neural ↔ Body Parameter Fitting for the joint-fitting story.
Coupling Bridge Ownership¶
The sibernetic_c302.py coupling script (lives in openworm/sibernetic repo) reads muscle calcium from NEURON and writes activation to Sibernetic. This script is the single point where DD003 output format matters. Changes to:
- Muscle calcium variable name → must update
sibernetic_c302.py - Activation formula → must update
sibernetic_c302.py - Number of muscles (e.g., adding pharyngeal muscles per DD007) → must update muscle mapping in
sibernetic_c302.py
Coordination required: Muscle model maintainer + Body Physics maintainer (DD001) + Integration Maintainer (DD011)
- Approved by: OpenWorm Steering
- Implementation Status: Complete (GenericMuscleCell in c302)
-
Next Actions:
-
Differentiate into muscle-type-specific models using transcriptomics (Phase 3)
- Add pharyngeal muscles (DD007)
- Model specialized muscles (vulval, uterine, enteric) as needed