# nely-epfl/flygym architecture

> Architecture diagram of the GitHub repository nely-epfl/flygym, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nely-epfl/flygym
- Repository: https://github.com/nely-epfl/flygym

## Overview

FlyGym is a Python digital-twin and simulation library for embodied fly sensorimotor control. Users compose a fly model and world, run CPU or GPU simulations, and obtain sensory and mechanosensory observations; controllers or learning environments can use those observations to drive actions. The graph includes model composition, simulation and sensing, optional Warp acceleration, and the documented demo workflows. Some subsystem implementations were not sampled, so uncertain connections are omitted; README-described capabilities without a clearly supported source path are represented at the package level.

Main entry points: [`src/flygym/simulation.py`](https://github.com/nely-epfl/flygym/blob/main/src/flygym/simulation.py) (Simulation runtime), [`src/flygym/compose/fly/base_fly.py`](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/base_fly.py) (Base fly model), [`src/flygym/compose/world/base_world.py`](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/world/base_world.py) (World composition), [`src/flygym_demo/complex_terrain/hybrid_controller.py`](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/hybrid_controller.py) (Hybrid controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Fly and world models"]
  node_anatomy["Fly anatomy<br/>[anatomy.py]"]
  node_pose["Kinematic poses<br/>[pose.py]"]
  node_fly_base["Base fly model<br/>[base_fly.py]"]
  node_fly_neuro["NeuroMechFly<br/>[neuromechfly.py]"]
  node_fly_body["FlyBody model<br/>[flybody.py]"]
  node_fly_muscle["Musculoskeletal fly<br/>[musculoskeletal.py]"]
  node_world_base["World composition<br/>[base_world.py]"]
  node_world_terrain["Terrain worlds<br/>[complex_terrain.py]"]
  node_physics["Contact physics<br/>[physics.py]"]
end

subgraph group_runtime["Simulation and sensing"]
  node_simulation["Simulation runtime<br/>[simulation.py]"]
  node_rendering["Rendering and viewer<br/>[rendering.py]"]
  node_retina["Retina vision<br/>[retina.py]"]
  node_olfaction["Olfactory inputs"]
  node_mechanosense["Mechanosensory feedback<br/>[simulation.py]"]
end

subgraph group_warp["Warp backend"]
  node_warp_sim["Warp simulation<br/>[simulation.py]"]
  node_warp_render["Warp rendering<br/>[rendering.py]"]
end

subgraph group_control["Locomotion demos"]
  node_terrain_common["Locomotion setup<br/>[common.py]"]
  node_preprogrammed["Step patterns<br/>[preprogrammed.py]"]
  node_cpg["CPG controller<br/>[cpg_controller.py]"]
  node_hybrid["Hybrid controller"]
end

subgraph group_learning["Imitation learning"]
  node_mocap["Motion capture data<br/>[data.py]"]
  node_imitation_env["Imitation environment<br/>[env.py]"]
  node_training["Imitation training<br/>[train.py]"]
end

node_user(("Library user"))

node_user -->|"runs"| node_simulation
node_user -->|"composes scene"| node_world_base
node_fly_base -->|"uses anatomy"| node_anatomy
node_fly_base -->|"uses poses"| node_pose
node_fly_base -.->|"configures contacts"| node_physics
node_fly_neuro -.->|"specializes"| node_fly_base
node_fly_body -->|"extends model"| node_fly_base
node_fly_muscle -.->|"specializes"| node_fly_base
node_world_base -->|"accepts fly"| node_fly_neuro
node_world_terrain -.->|"specializes"| node_world_base
node_simulation -->|"compiles world"| node_world_base
node_simulation -->|"renders frames"| node_rendering
node_simulation -->|"gets vision"| node_retina
node_simulation -->|"reads contacts"| node_mechanosense
node_simulation -.->|"provides inputs"| node_olfaction
node_user -->|"runs GPU mode"| node_warp_sim
node_warp_render -->|"reuses rendering"| node_rendering
node_terrain_common -->|"uses joint types"| node_anatomy
node_terrain_common -->|"sets actions"| node_simulation
node_cpg -->|"maps oscillator state"| node_preprogrammed
node_hybrid -->|"advances network"| node_cpg
node_hybrid -->|"uses step patterns"| node_preprogrammed
node_hybrid -->|"reads observations"| node_simulation
node_imitation_env -->|"steps simulation"| node_simulation
node_imitation_env -->|"loads reference data"| node_mocap
node_training -->|"trains policy"| node_imitation_env
node_training -->|"uses dataset"| node_mocap

click node_anatomy "https://github.com/nely-epfl/flygym/blob/main/src/flygym/anatomy.py"
click node_pose "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/pose.py"
click node_fly_base "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/base_fly.py"
click node_fly_neuro "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/neuromechfly.py"
click node_fly_body "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/flybody.py"
click node_fly_muscle "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/musculoskeletal.py"
click node_world_base "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/world/base_world.py"
click node_world_terrain "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/world/complex_terrain.py"
click node_physics "https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/physics.py"
click node_simulation "https://github.com/nely-epfl/flygym/blob/main/src/flygym/simulation.py"
click node_rendering "https://github.com/nely-epfl/flygym/blob/main/src/flygym/rendering.py"
click node_retina "https://github.com/nely-epfl/flygym/blob/main/src/flygym/vision/retina.py"
click node_olfaction "https://github.com/nely-epfl/flygym/tree/main/src/flygym"
click node_mechanosense "https://github.com/nely-epfl/flygym/blob/main/src/flygym/simulation.py"
click node_warp_sim "https://github.com/nely-epfl/flygym/blob/main/src/flygym/warp/simulation.py"
click node_warp_render "https://github.com/nely-epfl/flygym/blob/main/src/flygym/warp/rendering.py"
click node_terrain_common "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/common.py"
click node_preprogrammed "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/preprogrammed.py"
click node_cpg "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/cpg_controller.py"
click node_hybrid "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/hybrid_controller.py"
click node_mocap "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/data.py"
click node_imitation_env "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/env.py"
click node_training "https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/train.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_anatomy,node_pose,node_fly_base,node_fly_neuro,node_fly_body,node_fly_muscle,node_world_base,node_world_terrain,node_physics,node_user toneBlue
class node_simulation,node_rendering,node_retina,node_olfaction,node_mechanosense toneAmber
class node_warp_sim,node_warp_render toneMint
class node_terrain_common,node_preprogrammed,node_cpg,node_hybrid toneRose
class node_mocap,node_imitation_env,node_training toneIndigo
```

## Components

### Fly and world models

- [Fly anatomy](https://github.com/nely-epfl/flygym/blob/main/src/flygym/anatomy.py): `src/flygym/anatomy.py`
- [Kinematic poses](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/pose.py): `src/flygym/compose/pose.py`
- [Base fly model](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/base_fly.py): `src/flygym/compose/fly/base_fly.py`
- [NeuroMechFly](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/neuromechfly.py): `src/flygym/compose/fly/neuromechfly.py`
- [FlyBody model](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/flybody.py): `src/flygym/compose/fly/flybody.py`
- [Musculoskeletal fly](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/fly/musculoskeletal.py): `src/flygym/compose/fly/musculoskeletal.py`
- [World composition](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/world/base_world.py): `src/flygym/compose/world/base_world.py`
- [Terrain worlds](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/world/complex_terrain.py): `src/flygym/compose/world/complex_terrain.py`
- [Contact physics](https://github.com/nely-epfl/flygym/blob/main/src/flygym/compose/physics.py): `src/flygym/compose/physics.py`

### Simulation and sensing

- [Simulation runtime](https://github.com/nely-epfl/flygym/blob/main/src/flygym/simulation.py): `src/flygym/simulation.py`
- [Rendering and viewer](https://github.com/nely-epfl/flygym/blob/main/src/flygym/rendering.py): `src/flygym/rendering.py`
- [Retina vision](https://github.com/nely-epfl/flygym/blob/main/src/flygym/vision/retina.py): `src/flygym/vision/retina.py`
- [Olfactory inputs](https://github.com/nely-epfl/flygym/tree/main/src/flygym): `src/flygym`
- [Mechanosensory feedback](https://github.com/nely-epfl/flygym/blob/main/src/flygym/simulation.py): `src/flygym/simulation.py`

### Warp backend

- [Warp simulation](https://github.com/nely-epfl/flygym/blob/main/src/flygym/warp/simulation.py): `src/flygym/warp/simulation.py`
- [Warp rendering](https://github.com/nely-epfl/flygym/blob/main/src/flygym/warp/rendering.py): `src/flygym/warp/rendering.py`

### Locomotion demos

- [Locomotion setup](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/common.py): `src/flygym_demo/complex_terrain/common.py`
- [Step patterns](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/preprogrammed.py): `src/flygym_demo/complex_terrain/preprogrammed.py`
- [CPG controller](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/cpg_controller.py): `src/flygym_demo/complex_terrain/cpg_controller.py`
- [Hybrid controller](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/complex_terrain/hybrid_controller.py): `src/flygym_demo/complex_terrain/hybrid_controller.py`

### Imitation learning

- [Motion capture data](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/data.py): `src/flygym_demo/muscle_imitation/data.py`
- [Imitation environment](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/env.py): `src/flygym_demo/muscle_imitation/env.py`
- [Imitation training](https://github.com/nely-epfl/flygym/blob/main/src/flygym_demo/muscle_imitation/train.py): `src/flygym_demo/muscle_imitation/train.py`

### Other components

- **Library user**

## Connections

- Library user → Simulation runtime: runs
- Library user → World composition: composes scene
- Base fly model → Fly anatomy: uses anatomy (evidence: `src/flygym/compose/fly/base_fly.py`)
- Base fly model → Kinematic poses: uses poses (evidence: `src/flygym/compose/fly/base_fly.py`)
- Base fly model → Contact physics: configures contacts
- NeuroMechFly → Base fly model: specializes
- FlyBody model → Base fly model: extends model (evidence: `src/flygym/compose/fly/flybody.py`)
- Musculoskeletal fly → Base fly model: specializes
- World composition → NeuroMechFly: accepts fly (evidence: `src/flygym/compose/world/base_world.py`)
- Terrain worlds → World composition: specializes
- Simulation runtime → World composition: compiles world (evidence: `src/flygym/simulation.py`)
- Simulation runtime → Rendering and viewer: renders frames (evidence: `src/flygym/simulation.py`)
- Simulation runtime → Retina vision: gets vision (evidence: `src/flygym/simulation.py`)
- Simulation runtime → Mechanosensory feedback: reads contacts (evidence: `src/flygym/simulation.py`)
- Simulation runtime → Olfactory inputs: provides inputs (evidence: `src/flygym/simulation.py`)
- Library user → Warp simulation: runs GPU mode
- Warp rendering → Rendering and viewer: reuses rendering (evidence: `src/flygym/warp/rendering.py`)
- Locomotion setup → Fly anatomy: uses joint types (evidence: `src/flygym_demo/complex_terrain/common.py`)
- Locomotion setup → Simulation runtime: sets actions (evidence: `src/flygym_demo/complex_terrain/common.py`)
- CPG controller → Step patterns: maps oscillator state (evidence: `src/flygym_demo/complex_terrain/cpg_controller.py`)
- Hybrid controller → CPG controller: advances network (evidence: `src/flygym_demo/complex_terrain/hybrid_controller.py`)
- Hybrid controller → Step patterns: uses step patterns (evidence: `src/flygym_demo/complex_terrain/hybrid_controller.py`)
- Hybrid controller → Simulation runtime: reads observations (evidence: `src/flygym_demo/complex_terrain/hybrid_controller.py`)
- Imitation environment → Simulation runtime: steps simulation (evidence: `src/flygym_demo/muscle_imitation/env.py`)
- Imitation environment → Motion capture data: loads reference data (evidence: `src/flygym_demo/muscle_imitation/env.py`)
- Imitation training → Imitation environment: trains policy (evidence: `src/flygym_demo/muscle_imitation/train.py`)
- Imitation training → Motion capture data: uses dataset (evidence: `src/flygym_demo/muscle_imitation/train.py`)
