NeLy-EPFL/flygym

FlyGym – A high‑performance digital twin of Drosophila

What it is – FlyGym is a Python library that implements NeuroMechFly v2, a physics‑based, fully‑embodied model of an adult fruit fly. It lets researchers simulate a fly that can see, smell, walk on complex terrain, and interact with objects, providing a test‑bed for sensorimotor control experiments.

Key capabilities

• Biomechanical fidelity – The body is built from a micro‑CT scan of a real female fly, with detailed segment geometry (including antennae).
• Vision simulation – Compound eyes are modeled as a hexagonal lattice of ommatidia, delivering realistic retinal images.
• Olfaction – Odor receptors on antennae and maxillary palps receive chemically‑scaled inputs computed from the simulated environment.
• Hierarchical CNS control – Users can attach a two‑part controller (brain‑level decision making + VNC‑level motor control) that communicates via descending and ascending signals.
• Leg adhesion – Specialized adhesive structures are simulated, with a simple on/off switch to emulate the fly’s ability to stick to vertical surfaces.
• Mechanosensory feedback – Joint angles, actuator forces, contact forces and custom joint‑site positions are exposed for closed‑loop control.

Performance upgrades (FlyGym 2.x)

• ~10× faster on CPU (≈2× real‑time)
• ~300× faster on GPU via Warp/MJWarp (≈60× real‑time)
• New interactive viewer and streamlined scene‑composition workflow.
• Simpler dependency stack.

Getting started

1. Install the package following the instructions on the documentation site.
2. Run the tutorials linked from the same site to learn how to build environments, attach controllers, and retrieve sensory data.
3. For legacy code, use the migrated flygym‑gymnasium repository (Gymnasium‑compatible API).

Resources

• Full docs: https://neuromechfly.org/
• Paper (Nature Methods, 2024): https://www.nature.com/articles/s41592-024-02497-y.epdf
• Discussion board: https://github.com/NeLy-EPFL/flygym/discussions

Who it’s for – Researchers in neuroscience, robotics, and AI who need a realistic, fast, and programmable platform to test embodied sensorimotor algorithms, reinforcement‑learning agents, or neuro‑biological hypotheses.