MaleCNS Virtual Fly

A Drosophila brain simulator that runs the whole Traced universe of the released male CNS connectome — 165,122 neurons and every one of the 25,563,197 edges between them — inside a physical fly body, in closed loop, on one GPU.

That universe is 165,122 of the 166,700 bodies the MaleCNS paper annotates: the runtime graph is the subgraph induced by annotation status Traced, a decision recorded in ADR-2026-002. Widening it to Traced+Assign+Anchor would add 2,443 bodies (1.48%) and 60,281 edges (0.24%).

It is not a recovered copy of the imaged fly, a complete biological emulation, or a digital twin. What it is, and the evidence behind every number on this page, is set out in What is and is not claimed.

Twelve flies, twelve connectomes, one scene

Twelve full NeuroMechFly bodies in one MuJoCo scene, scattered at random over a 30 mm disc and aimed at random. Each fly executes its own copy of that whole graph every 15 ms coupling interval, over one shared connectivity allocation with independent membrane, adaptation, spike-counter and noise state. Food spheres and pillars are geoms with real contact pairs, and the bodies share one solver step, so an object stops a fly through the physics rather than through a rule. Flies do not collide with each other — FlyGym gives every fly geom contype 0 and this world writes no fly-fly contact pair, so two bodies pass through one another. What couples them is vision: each fly enters the others' encoders as a sphere of one declared radius.

That vision is analytic, not optical. The encoder is handed each object's exact position and radius and computes a bearing and an angular size from them; there are no camera pixels, no ray casting, no occlusion, no colour and no texture anywhere in the loop.

Nothing steers them but two descending population rates read out of their own network.

Onset is on a timer and the video says so: every fly stands still for 1.5 s by construction and then needs its drive held above threshold for 150 ms, so all twelve start walking at 1.665 s. The timer decides when. What the stimulus decides is whether — the control below never leaves the standing state at all.

Watch the full 1:38 video (1920x1080, 19 MB). What it measured, against the identical-seed stimulus-absent control:

Eleven of twelve ended against a food sphere and the twelfth against a pillar. They were stopped by the object, they did not decide to stop: the decoder has no transition out of its locomoting state, so a blocked fly keeps being commanded forward. "Within 1 mm" is a two-dimensional thorax-centre distance minus the object radius, not MuJoCo contact telemetry. The last row is the one to be careful about, and the video says so on screen: a standing body drifts forward along its own axis, and headings are bounded so that food lies inside the encoder's mapped visual field, so the control leans the same way. Closing distance to food is not the discriminator. Ending against an object is — 12 of 12 against 0 of 12.

This is one seed and one arena — the third arena, designed after measuring two that failed, with starting headings bounded so that food falls inside the encoder's mapped field. There is no multi-seed matrix, and no acceptance contract scores any of it.

Two properties are checked rather than asserted, because the swarm reuses the frozen DEMO-01 network and reimplements its per-fly actuation. One fly driven through SwarmWorld and through Demo01VisualBody under an identical command sequence agree to 0.0 on every one of 133 qpos components; the multi-object encoder reproduces the frozen single-cue encoder to 1.1e-13 Hz on rates spanning 1 to 400 Hz. Both are in tests/test_swarm3d.py.

Operator handoff: docs/showcase/SWARM3D.md. Decision record: ADR-2026-023, which also records the two arenas that were built, measured and discarded first — each one exposed a property of the frozen visual route that no previous experiment had tested.

How it works

MaleCNS v1.0 (CC-BY)          165,122 neurons, 25,563,197 edges, checksum-locked
        |
   transmitter sign           per-neuron; unresolved signs are zeroed, not guessed
        |
   sparse graph build         hashed arrays, verified on every load
        |
   GeNN / CUDA                one connectivity allocation, N independent neuron states
        |    ^
 retinotopic |    | two descending population rates
 lamina      |    |
 encoder     |    v
        MuJoCo + NeuroMechFly 133 qpos / 132 DOF, 42 actuated, contacts solved

The full frame chain, including the causal queues that keep the body one interval behind the neural engine, is in docs/architecture.md.

The loop is deliberately narrow and every narrowing is declared. Light enters one synapse downstream of the photoreceptors, because all 66,533 photoreceptor output edges are zeroed by the frozen unresolved-sign policy. The gait is a published pattern generator, not the simulated ventral nerve cord. The readout is two numbers. Everything else the body and the connectome could do is inert in this demonstration, and the inventory of what is inert is part of the artifact rather than a footnote.

What is and is not claimed

The project sits at tier V0 Structural on its own V0–V8 ladder. The swarm demonstration awards no tier at all: both the run summary and the render manifest carry validation_tier_awarded: null and evidence_grade: false, because no preregistered biological hypothesis and no acceptance contract exists for a swarm. It demonstrates machinery and validates no biology.

Specifically not claimed, and printed on the video frames rather than hidden here:

• No social behaviour. Flies aggregate because a nearby fly is a large object in the visual field and the network approaches large objects.
• No foraging. Food is a coloured sphere with a radius. The encoder has no colour channel and cannot tell food from a pillar; what separates them is angular size. There is no ingestion, no proboscis extension, no taste channel in this run.
• The walking is engineered. No part of the simulated ventral nerve cord contributes to leg movement.
• The flies are not individuals. Twelve parameterised copies of one specimen, differing in where they start, what they see from there, and their independent noise stream.
• No fly-fly contact and no optical vision, as above: the bodies pass through one another and the encoder reads exact coordinates rather than pixels.
• The controls that would make this a swarm result do not exist yet. There is no flies-invisible arm, no swarm-specific readout ablation, no matched controller-only arm, no activity-matched shuffle, no multi-seed matrix and no equal-angular-size food-versus-pillar preference test. The published run is exact against stimulus-absent, and nothing more.
• Rendering is software rasterisation on the machine that produced these files, and the manifest records it.

The discipline that produces those statements is the point of the project as much as the simulation is: every parameter carries a provenance class (M measured, P population prior, F fitted, E engineering scaffold, I irrecoverable) and an assumption ID in configs/assumptions.json; evidence-grade runs refuse to start from a dirty worktree; and criteria are registered before they are scored. Results that failed are kept — see docs/STATUS.md for the current state, including Track A's 0-of-30 grooming-displacement failure and a withdrawn evidence round.

Quick start

The lightweight reference engine runs before FlyGym, CUDA or the MaleCNS data are installed:

uv python install 3.12
uv sync --python 3.12 --extra data --extra render
uv run flysim run eon-demo --seed 1 --headless
uv run flysim render runs/<run-id>
uv run pytest        # tests needing FlyGym, MuJoCo or CUDA skip

That produces the semantic engineering storyboard, which is also the project's neural-bypass control. It is an E engineering scaffold and its manifest says so.

For anything that executes the real connectome you need the dataset and an NVIDIA GPU:

export FLYSIM_DATA_ROOT=/path/with/room          # dataset + run outputs
flysim data sync --profile starter               # public, no credentials
flysim data validate
flysim data import-aggregate

GeNN is a native CUDA source build rather than a registry package (scripts/install_genn.sh), and the pinned production environment is Linux. On Windows it is reached through WSL2. Full operator documentation, including the dataset profiles, the preregistered matrices and the evidence-bundle path, is in docs/OPERATIONS.md.

Reproduce the swarm video

Recording and rendering are separate by construction: the run records whole-scene qpos once per coupling interval and no frames at all, and the replay path refuses a world that has ever been stepped, so rendering cannot advance a simulation.

PYTHONPATH=src python scripts/run_swarm3d_showcase.py \
    --duration-s 30 --variant exact --variant stimulus-absent --progress
PYTHONPATH=src python scripts/render_swarm3d_showcase.py \
    --run RUN_DIR/exact --control RUN_DIR/stimulus-absent \
    --out artifacts/showcase/swarm3d-v1/swarm3d-showcase.mp4 --progress

Cost, measured: twelve flies at 0.015x biological real time, about 33 minutes of wall clock per variant on one RTX 3060 at 4.2 GB of device memory. That is not the GPU being slow — 30 s of biology at the registered 100 µs neural step is 300,000 timesteps over 165,122 x 12 neuron states, or 594 billion state updates, which would need roughly 1.2 TB/s of memory bandwidth for the neuron state alone against the card's 360 GB/s.

Other demonstrations

Repository map

Green CI does not mean the headline system ran. CI installs neither GeNN, CUDA, FlyGym nor MuJoCo, so it never executes the connectome, the body or the swarm; it runs the pure-Python half and the contracts, at a 53% coverage floor. The GPU work is verified by hand on one machine, and the run manifests are the record of that.

Sources

Everything below was read, downloaded or reused to build this. No dataset here is redistributed by this repository: each is fetched by flysim data sync, checksummed, and recorded in an immutable dataset lock. Licences and redistribution terms, which registry each number landed in, and the sources that were read and rejected, are in docs/REFERENCES.md.

The connectome

MaleCNS v1.0 - HHMI Janelia FlyEM, CC-BY, https://male-cns.janelia.org/download/. 165,122 neurons and 25,563,197 edges across seven checksum-locked flat-connectome tables.

• Sexual dimorphism in the complete Drosophila male central nervous system connectome - 10.1016/j.cell.2026.08.015
• Male gustatory connectome - 10.1016/j.cell.2026.08.016
• Structural and male-female comparison supplement - https://github.com/flyconnectome/2025malecns

What the graph does not say about itself - its reconstruction completion rates, which qualify every structural and functional claim made anywhere in this repository - is section 5 of the literature corpus.

Software this is built on

Papers behind the registered parameters

Fourteen full-text papers were read and every quantitative value extracted with its measurement conditions. A paper appearing here does not mean its value was accepted: the corpus records what was rejected, and one registered value that an independent measurement contradicts.

Behaviour, mapping and cell-type sources

Method and boundary prior art

Used as method or as a limit marker, never as a source of numbers: Effectome (connectome weights as priors for fitted causal effects), FlyVis (visual type sharing and fitting precedent), BrainTrace (scalable fitting, and evidence that background drive matters), inter-individual connectome variability, BANC (female brain-and-cord comparison), the adult mushroom-body connectome, adult muscle motor-unit physiology, femoral chordotonal biomechanics and the DoOR odour-response database.

Flybody and FlyMimic were consulted as whole-body and muscle-level baselines and are not used. That is why wing flapping produces exactly zero lift in this body, and why the project says so instead of implying flight (ADR-2026-017).

Datasets with their own cards

Each carries its source URL, checksum, licence and redistribution status in configs/datasets/:

malecns-v1.0                     the connectome, CC-BY
berg-malecns-2025-supplement     structural and male-female comparison tables
morphology-canaries              skeleton SWCs that detect a silently changed release
shiu-2024-brain-model            Stage 1 regression reference and archived outputs
ozdil-2026-antennal-grooming     grooming supplementary data ...
   ... -trajectory               ... and the replayed joint trajectory
gugel-2023-elife-85443           uEPSC source data, Dryad 10.5061/dryad.v15dv420q
nanami-2024-pn-current-clamp     PN current-clamp recordings ...
   ... -invivo-cellular-pack     ... and the in vivo pack redistributed alongside them
gouwens-wilson-2009-dm1-modeldb  published DM1 passive model, redistribution disabled
stage2-2026-09-09-intake         classification of a staged dataset drop
stage2-reservations-v1           which files, variables and columns are RESERVED and unopened

The last card is load-bearing for the validation discipline: data declared reserved stays unread until a preregistered test opens it, because reading it spends it.

Contributing, licence, citation, security

Setup, the checks CI runs, and the handful of rules that are not style are in CONTRIBUTING.md.

Project code is GPL-2.0-or-later. Dataset and dependency licences remain their own — see THIRD_PARTY_NOTICES.md. Cite the software release and the exact MaleCNS release a run used (CITATION.cff). Credential handling and the dataset lock rules are in SECURITY.md.