GarageFly: model limitations

GarageFly couples a connectome-derived network model to a physics-simulated fly body. It is a tool for asking how signals propagate through a wiring diagram when you drive specific sensory neurons, and what a simple read-out of descending neurons does to a simulated body. It is not a brain upload, and it is not a model of consciousness, sentience, experience, or "what the fly hears". When this document says the fly "listens to Creed", it means that particle-velocity envelopes computed from an audio file set the Poisson firing rates of the neurons FlyWire annotates as Johnston's organ neurons.

Every parameter carries one of five provenance tags. They are stored in each run's metadata under provenance:

1. What is taken directly from data (connectome)

• 138,639 neurons and 15,091,983 connections (≥5 synapses each) from the FlyWire FAFB v783 adult female brain (Dorkenwald et al. 2024), in the preprocessed form used by Shiu et al. 2024.
• Synapse signs come from machine-learned neurotransmitter predictions (Eckstein et al. 2024): ACh is excitatory; GABA and glutamate are inhibitory. Glutamate is excitatory at some fly synapses (e.g. NMDA-type receptors at the neuromuscular junction and in some central circuits), so a subset of signs is wrong. Dopamine, serotonin and octopamine are treated as whatever sign Shiu et al. assigned. Their modulatory actions are not modelled.
• Cell identities: every sensory input population and descending-neuron output is selected by FlyWire annotation (Schlegel et al. 2024), never by a hand-picked ID.
• Synaptic weight = synapse count × w_syn. Synapse size, location on the dendrite, receptor type, and plasticity are ignored.

2. The neuron model (literature + arbitrary)

• A leaky integrate-and-fire model with identical parameters for every neuron (Shiu et al. 2024). Real fly neurons differ enormously. Many (including some JO neurons, photoreceptors and many local interneurons) use graded potentials rather than spikes.
• No gap junctions. Electrical synapses are common in the fly (e.g. the giant fiber circuit, JO-A neurons) but are absent from the connectome data we use.
• No neuromodulation, no plasticity, no adaptation (apart from the explicit JO adaptation described below), and no internal state: hunger, arousal and circadian phase are not represented.
• No spontaneous activity. Without input the network is silent. We add a constant depolarising bias (decoder.tonic_bias_mv, arbitrary) to the forward-walking DNs (DNp09, oDN1) so the fly walks at all. This bias is the single largest arbitrary intervention in the model. Through DN-DN connectivity it also recruits DNa02_R, which gives the fly a consistent rightward turning bias in every condition, including silence. That comes from the connectome (the right-hemisphere pathway is stronger in the reconstruction) combined with our bias, and it is not a known fly behaviour. Compare conditions against the silent control, never against zero.
• The model was validated by Shiu et al. for a handful of pathways (sugar feeding, grooming, water, bitter). GarageFly's test suite re-checks the sugar-GRN → MN9 result on our PyTorch port. The auditory pathway has not been validated against electrophysiology in this model.
• Left/right asymmetries in responses (e.g. JO-A/B activating the right giant fiber much more than the left) reflect asymmetries in the reconstructed wiring, including proofreading differences. They are not established biology.

3. What is missing from the nervous system

• The ventral nerve cord (VNC) is absent. FlyWire covers the brain only. All leg motor control, local leg reflexes, the CPGs for walking, and the proprioceptive loops live in the VNC. GarageFly replaces it with FlyGym's engineered CPG + rule-based controller, which takes a two-number left/right drive. MANC (male VNC) and BANC (brain + nerve cord, public since 2025) could replace this in future. See ARCHITECTURE.md.
• Proprioceptive and ascending feedback into the brain is not wired up. The body's state reaches the brain only through the sensory transducers below.
• Brain modes. sensory-motor (default) drops the ~86k optic-lobe and visual-projection neurons unless vision is enabled. minimal keeps only neurons within two strong synaptic hops of both the stimulated sensory neurons and the read-out DNs. Both remove recurrent loops that exist in the full brain. full keeps all 138,639 neurons and runs at about half the speed.

4. Sensory transduction

Mechanosensation / audio: the main experiment

What is physical: sound pressure falls off as 1/r from a point source, and air particle velocity (what the arista actually senses) includes the near-field term sqrt(1 + 1/(kr)²). That term matters a lot for bass at garage distances.

What is approximated: * The speaker is an ideal monopole. There are no room reflections, no speaker directivity, and no bench/substrate vibration. A real fly on a bench next to a speaker would also feel the bench vibrate through its leg chordotonal organs (VNC, not in the model), and that could dominate its response to bass. * Playback level is set by audio.spl_db_at_1m (default 85 dB SPL RMS, arbitrary). The default track_rms calibration makes every condition equally loud, so differences between conditions come from spectral and temporal content, not loudness. * The antenna is a linear 2nd-order resonator (f0 = 300 Hz, literature-approx.; Q = 1.5, arbitrary). The real antenna is active and nonlinear: its best frequency and gain change with level (Göpfert & Robert 2001–2003). That is not modelled. * Directionality is a figure-of-eight cosine gain with axes ±45° from the body axis (literature-approx., Morley et al. 2012). * JO subgroup tuning: JO-A prefers higher and JO-B lower vibration frequencies, and JO-C/E respond to low-frequency or static deflection (Kamikouchi et al. 2009; Yorozu et al. 2009; Matsuo et al. 2014). These are qualitative findings. The Gaussian band weights, half-activation levels, Hill exponent, max rate (150 Hz), spontaneous rate (2 Hz), per-neuron heterogeneity, and JO-A/B adaptation (50%, 200 ms) are all arbitrary. * JO neurons phase-lock to sound cycle by cycle. Here they are Poisson processes whose rate follows a smoothed envelope (5 ms window, 1 ms update), so fine temporal structure such as pulse-song inter-pulse intervals survives only at the envelope level. * JO-F (grooming-related) is not driven by sound. It responds only to the antennal_deflection interface, which nothing drives yet. * Music: the fly has no representation of melody, lyrics, genre, or Creed. Different tracks differ only in their band-envelope time courses within 15–1500 Hz.

Olfaction

• Odor concentration is a static falloff c0 / (1 + (d/d50)²) (arbitrary), not a turbulent plume, and has no wind.
• Odor → glomerulus mappings are a handful of well-established cases (CO₂→V, geosmin→DA2, cVA→DA1, vinegar→DM1/VA2/DM4/DP1m). Response magnitudes are arbitrary. tobacco_smoke is an explicitly arbitrary placeholder profile. It triggers a warning every time it is used. Replace it with DoOR-database responses to measured smoke constituents before drawing any conclusion.
• No pharmacology. An odor source changes only ORN firing rates. Nicotine's action (nicotinic ACh receptor agonism, which is where insecticidal neonicotinoids act) is not represented. Representing it defensibly would require per-neuron nAChR subunit expression, receptor kinetics and dose-response data. None of these are in the model. The framework keeps sensory and pharmacological effects separate: any future pharmacology module must modify neuron or synapse parameters explicitly, and label that provenance.

Beer and cigarettes (garage props)

• The garage contains a beer bottle, an open beer can with a small spill, an ashtray, cigarettes (one "lit", with a glowing ember and a static smoke wisp) and a cigarette pack. By default they are purely decorative. They do not collide with the fly, emit nothing, and cannot influence any result.
• --beer-odor [CONC] turns the bottle mouth into an odor source with the beer profile. --smoke-odor [CONC] does the same at the cigarette ember with the tobacco_smoke profile. Both profiles are arbitrary placeholders (they print a warning), and the concentration field is the same static falloff used for all odors. The smoke wisp is not a plume model.
• No alcohol or nicotine pharmacology exists. Ethanol's effects on fly behaviour (e.g. via GABA-A/NMDA receptors and neuromodulators) and nicotine's action on nicotinic ACh receptors are not represented. The flags change olfactory receptor neuron firing only. The spill is visual only: drinking and taste of beer are not simulated.

Gustation

• Brain GRNs in FlyWire are mostly labellar and pharyngeal, but the body model tastes with its legs. We use "tarsus touching a patch" as a proxy that drives the brain GRN population of that modality (engineering). FlyWire also merges sugar and water GRNs into one annotation.

Vision

• Off by default. When on, FlyGym's ~720 ommatidia per eye are collapsed to per-eye mean luminance and yellow/pale means, which drive all R1-6/R7/R8 of that eye as Poisson processes. There is no retinotopy and no motion. The flyvis connectome-constrained visual model would be the principled replacement.

5. Body and behaviour

• NeuroMechFly v2 (FlyGym 2.1) body in MuJoCo, legs only (antennae, head, wings and proboscis are rigid). The locomotion controller (CPG + stumbling/retraction rules) is engineered and comes from the FlyGym examples.
• The controller updates every 0.5 ms (MuJoCo integrates at 0.1 ms). Behaviour matched the 0.1 ms controller within 0.1 mm over 1 s in our check (engineering).
• Physics QA. Every run is checked automatically for simulation artifacts: jumps > 1 mm per 10 ms, or thorax height outside 0.5–2.5 mm. In an early version the fly stood on a 1.5 m box geom. MuJoCo's convex collision between that box and the 0.1 mm leg segments occasionally failed and flung the fly. This affected 2 of 26 runs, reproduced identically in silence, and was unrelated to the stimulus. The fly now stands on an analytic plane, as in FlyGym. Those runs were discarded and the whole study was re-run. Reports flag any QA failure, and compare_conditions.py excludes failing runs by default and lists them.
• Grooming ("cleaning") uses measured kinematics. When the decoded grooming command is on (aDN2/DNg11/DNg12 activity), the fly stops walking and replays front-leg joint angles recorded with DeepFly3D from a fly grooming its antennae under optogenetic activation of aDN (NeuroMechFly v1 data, Lobato-Rios et al. 2022). The rhythmic bout (0.1–3.3 s of the recording) is looped seamlessly. Engineering approximations: the source fly was tethered on a ball, so the middle and hind legs hold our standing pose instead of the recorded angles; the same antennal-grooming motion stands in for every grooming DN (DNg11/DNg12 are also linked to head and front-leg grooming); and there are no antennal contact mechanics. The legs sweep to ~0.4 mm (joint centres) from the antennae without touching them, and grooming does not feed back into JO-F.
• Flight is an engineered abstraction. An escape command (giant-fiber rate above threshold) triggers takeoff, a climb to 60 mm, 1 s of cruise at 80 mm/s steered by the DN turn signal, and a controlled landing. Lift and thrust are an external force on the body (velocity controller with gravity compensation), and PD torques stand in for haltere stabilisation. The wings beat visibly (200 Hz, stroke + rotation) but produce no aerodynamic force: MuJoCo cannot resolve flapping-flight aerodynamics without a trained wing controller. The takeoff has no leg-driven jump (the real GF → TTM jump is not modelled). Speed, altitude, duration and the 1 s post-landing refractory period are arbitrary. Real escape flights are faster and longer, but here the fly is kept within ±200 mm of its start so it stays over the bench. The body has no collision with props while airborne (only the legs collide).
• Righting is engineered. A fly upside down for > 0.25 s (e.g. after falling off a prop) rights itself with a short hop-flight. Real flies use coordinated leg and wing movements.
• Proboscis extension is not actuated; MN9 activity is recorded only.
• Consequence for interpretation: because auditory input drives the giant fiber in this model (see §2, left/right asymmetry), loud stimuli can cause frequent escape takeoffs. Whether a real fly would take off in response to music has not been established here. The GF threshold (decoder.escape_threshold_hz) is arbitrary, and the model lacks the gap junctions and biophysics that shape real GF recruitment. Report takeoff results together with a threshold sensitivity analysis.
• The DN → drive decoder (body/decoder.py) uses literature-supported DN roles and arbitrary gains. It reads out about 20 of ~1,300 DNs. Everything the other DNs do is invisible to the body.

6. Timing and numerics

• Brain and physics share a 0.1 ms step. Sensory rates and motor commands update every 1 ms. DN rates are exponentially filtered (τ = 50 ms) before decoding, which adds read-out lag.
• Runs are stochastic (Poisson inputs). Always compare several seeds per condition. scripts/compare_conditions.py applies Mann-Whitney U tests with Benjamini-Hochberg correction across metrics. With few seeds, treat any difference as exploratory.
• Speed on an RTX 3090 + desktop CPU: sensory-motor mode runs ~5–6× slower than real time; full mode is roughly 1.3× slower still. A 120 s experiment takes ~10–12 min.

7. How to read results honestly

Good question: "When Johnston's-organ neurons are driven with the band envelopes of track X at 85 dB, which descending neurons change firing, and does the engineered body walk differently than in the silent control, across N seeds?"

Not a supported question: "Does the fly like Creed?" The model has no affect, preference, or learning, and the answer depends heavily on arbitrary parameters (playback level, JO transfer functions, decoder gains, tonic bias). Parameter-sensitivity sweeps (--set ...) should accompany any claim.