# uzh-rpg/agile_narrow_gap_diffsim architecture

> Architecture diagram of the GitHub repository uzh-rpg/agile_narrow_gap_diffsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uzh-rpg/agile_narrow_gap_diffsim
- Repository: https://github.com/uzh-rpg/agile_narrow_gap_diffsim

## Overview

Flightning is a JAX differentiable quadrotor simulator and learning framework for static and moving narrow-gap flight. The main workflow selects a gap and observation mode, trains a BPTT or state-only PPO policy, then loads a checkpoint for rollout evaluation and visualization. The graph preserves the four environment variants, simulation/modeling and sensing layers, policy network, and shared environment utilities. Edges are limited to relationships shown by README statements or the supplied source index; unsampled integration details are omitted.

Main entry points: [`flightning/envs/env_base.py`](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/env_base.py) (Environment API), [`experiments/train_bptt_gap_crossing.py`](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_bptt_gap_crossing.py) (BPTT training), [`experiments/train_ppo_gap_crossing.py`](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_ppo_gap_crossing.py) (PPO training), [`experiments/evaluate.py`](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/evaluate.py) (Checkpoint evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Training and evaluation"]
  node_bptt_train["BPTT training"]
  node_ppo_train["PPO training"]
  node_evaluate["Checkpoint evaluation<br/>[evaluate.py]"]
  node_visualization["Rollout visualization<br/>[visualization.py]"]
  node_configs["Training configuration"]
  node_checkpoints[("Saved checkpoints")]
end

subgraph group_algorithms["Learning algorithms"]
  node_bptt["BPTT optimizer<br/>[bptt.py]"]
  node_ppo["PPO optimizer<br/>[ppo.py]"]
end

subgraph group_environments["Gap environments"]
  node_static_state["Static state task"]
  node_static_vision["Static vision task"]
  node_moving_state["Moving state task"]
  node_moving_vision["Moving vision task"]
  node_env_base["Environment API<br/>[env_base.py]"]
  node_wrappers["Environment wrappers<br/>[wrappers.py]"]
end

subgraph group_simulation["Simulation and sensing"]
  node_quadrotor["Quadrotor dynamics"]
  node_quadrotor_model["Extended quadrotor<br/>[quadrotor_obj.py]"]
  node_world["World geometry<br/>[world_box_obj.py]"]
  node_camera["Double-sphere camera"]
  node_sim_models["Dynamics augmentation"]
end

subgraph group_shared["Policy and shared runtime"]
  node_mlp["MLP policy<br/>[mlp.py]"]
  node_spaces["Action and observation spaces<br/>[spaces.py]"]
  node_pytrees["JAX pytree utilities<br/>[pytrees.py]"]
  node_math["Math utilities<br/>[math.py]"]
  node_random["Randomization utilities<br/>[random.py]"]
end

node_engineer(("Researcher"))

node_engineer -->|"starts training"| node_bptt_train
node_engineer -->|"starts training"| node_ppo_train
node_engineer -->|"requests evaluation"| node_evaluate
node_bptt_train -->|"invokes"| node_bptt
node_ppo_train -->|"invokes"| node_ppo
node_bptt_train -->|"creates task"| node_env_base
node_ppo_train -->|"creates task"| node_env_base
node_bptt_train -->|"uses"| node_wrappers
node_ppo_train -->|"uses"| node_wrappers
node_bptt_train -->|"builds policy"| node_mlp
node_ppo -->|"uses policy"| node_mlp
node_bptt -->|"rolls out"| node_env_base
node_ppo -->|"steps environment"| node_env_base
node_evaluate -->|"loads policy"| node_bptt_train
node_evaluate -->|"loads policy"| node_ppo_train
node_evaluate -->|"renders results"| node_visualization
node_bptt_train -->|"saves checkpoint"| node_checkpoints
node_evaluate -->|"loads checkpoint"| node_checkpoints
node_bptt_train -->|"reads settings"| node_configs
node_ppo_train -->|"reads settings"| node_configs
node_env_base -->|"defines spaces"| node_spaces
node_env_base -->|"uses state trees"| node_pytrees
node_static_state -.->|"implements API"| node_env_base
node_static_vision -.->|"implements API"| node_env_base
node_moving_state -.->|"implements API"| node_env_base
node_moving_vision -.->|"implements API"| node_env_base
node_static_state -->|"uses dynamics"| node_quadrotor
node_moving_state -->|"uses dynamics"| node_quadrotor
node_static_vision -->|"uses sensing"| node_camera
node_moving_vision -->|"uses sensing"| node_camera
node_quadrotor_model -->|"extends dynamics"| node_quadrotor
node_static_state -->|"uses geometry math"| node_math
node_static_state -->|"randomizes starts"| node_random
node_wrappers -->|"wraps"| node_env_base

click node_bptt_train "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_bptt_gap_crossing.py"
click node_ppo_train "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_ppo_gap_crossing.py"
click node_evaluate "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/evaluate.py"
click node_visualization "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/visualization/visualization.py"
click node_bptt "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/algos/bptt.py"
click node_ppo "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/algos/ppo.py"
click node_static_state "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/static_gap_state_env.py"
click node_static_vision "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/static_gap_vision_env.py"
click node_moving_state "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/moving_gap_state_env.py"
click node_moving_vision "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/moving_gap_vision_env.py"
click node_env_base "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/env_base.py"
click node_wrappers "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/wrappers.py"
click node_quadrotor "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/quadrotor_simple_obj.py"
click node_quadrotor_model "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/quadrotor_obj.py"
click node_world "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/world_box_obj.py"
click node_camera "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/sensors/double_sphere_camera.py"
click node_sim_models "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/tree/main/flightning/simulation"
click node_mlp "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/modules/mlp.py"
click node_spaces "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/spaces.py"
click node_pytrees "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/pytrees.py"
click node_math "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/math.py"
click node_random "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/random.py"
click node_configs "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/configs/training_configs.yaml"
click node_checkpoints "https://github.com/uzh-rpg/agile_narrow_gap_diffsim/tree/main/runs"

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_bptt_train,node_ppo_train,node_evaluate,node_visualization,node_configs,node_checkpoints toneBlue
class node_bptt,node_ppo toneAmber
class node_static_state,node_static_vision,node_moving_state,node_moving_vision,node_env_base,node_wrappers toneMint
class node_quadrotor,node_quadrotor_model,node_world,node_camera,node_sim_models toneRose
class node_mlp,node_spaces,node_pytrees,node_math,node_random,node_engineer toneIndigo
```

## Components

### Training and evaluation

- [BPTT training](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_bptt_gap_crossing.py): `experiments/train_bptt_gap_crossing.py`
- [PPO training](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/train_ppo_gap_crossing.py): `experiments/train_ppo_gap_crossing.py`
- [Checkpoint evaluation](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/experiments/evaluate.py): `experiments/evaluate.py`
- [Rollout visualization](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/visualization/visualization.py): `flightning/envs/visualization/visualization.py`
- [Training configuration](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/configs/training_configs.yaml): `configs/training_configs.yaml`
- [Saved checkpoints](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/tree/main/runs): `runs`

### Learning algorithms

- [BPTT optimizer](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/algos/bptt.py): `flightning/algos/bptt.py`
- [PPO optimizer](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/algos/ppo.py): `flightning/algos/ppo.py`

### Gap environments

- [Static state task](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/static_gap_state_env.py): `flightning/envs/static_gap_state_env.py`
- [Static vision task](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/static_gap_vision_env.py): `flightning/envs/static_gap_vision_env.py`
- [Moving state task](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/moving_gap_state_env.py): `flightning/envs/moving_gap_state_env.py`
- [Moving vision task](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/moving_gap_vision_env.py): `flightning/envs/moving_gap_vision_env.py`
- [Environment API](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/env_base.py): `flightning/envs/env_base.py`
- [Environment wrappers](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/envs/wrappers.py): `flightning/envs/wrappers.py`

### Simulation and sensing

- [Quadrotor dynamics](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/quadrotor_simple_obj.py): `flightning/objects/quadrotor_simple_obj.py`
- [Extended quadrotor](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/quadrotor_obj.py): `flightning/objects/quadrotor_obj.py`
- [World geometry](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/objects/world_box_obj.py): `flightning/objects/world_box_obj.py`
- [Double-sphere camera](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/sensors/double_sphere_camera.py): `flightning/sensors/double_sphere_camera.py`
- [Dynamics augmentation](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/tree/main/flightning/simulation): `flightning/simulation`

### Policy and shared runtime

- [MLP policy](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/modules/mlp.py): `flightning/modules/mlp.py`
- [Action and observation spaces](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/spaces.py): `flightning/utils/spaces.py`
- [JAX pytree utilities](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/pytrees.py): `flightning/utils/pytrees.py`
- [Math utilities](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/math.py): `flightning/utils/math.py`
- [Randomization utilities](https://github.com/uzh-rpg/agile_narrow_gap_diffsim/blob/main/flightning/utils/random.py): `flightning/utils/random.py`

### Other components

- **Researcher**

## Connections

- Researcher → BPTT training: starts training (evidence: `README.md`)
- Researcher → PPO training: starts training (evidence: `README.md`)
- Researcher → Checkpoint evaluation: requests evaluation (evidence: `README.md`)
- BPTT training → BPTT optimizer: invokes (evidence: `experiments/train_bptt_gap_crossing.py`)
- PPO training → PPO optimizer: invokes (evidence: `experiments/train_ppo_gap_crossing.py`)
- BPTT training → Environment API: creates task (evidence: `experiments/train_bptt_gap_crossing.py`)
- PPO training → Environment API: creates task (evidence: `experiments/train_ppo_gap_crossing.py`)
- BPTT training → Environment wrappers: uses (evidence: `experiments/train_bptt_gap_crossing.py`)
- PPO training → Environment wrappers: uses (evidence: `experiments/train_ppo_gap_crossing.py`)
- BPTT training → MLP policy: builds policy (evidence: `experiments/train_bptt_gap_crossing.py`)
- PPO optimizer → MLP policy: uses policy (evidence: `flightning/algos/ppo.py`)
- BPTT optimizer → Environment API: rolls out (evidence: `flightning/algos/bptt.py`)
- PPO optimizer → Environment API: steps environment (evidence: `flightning/algos/ppo.py`)
- Checkpoint evaluation → BPTT training: loads policy (evidence: `experiments/evaluate.py`)
- Checkpoint evaluation → PPO training: loads policy (evidence: `experiments/evaluate.py`)
- Checkpoint evaluation → Rollout visualization: renders results (evidence: `experiments/evaluate.py`)
- BPTT training → Saved checkpoints: saves checkpoint (evidence: `README.md`)
- Checkpoint evaluation → Saved checkpoints: loads checkpoint (evidence: `README.md`)
- BPTT training → Training configuration: reads settings (evidence: `README.md`)
- PPO training → Training configuration: reads settings (evidence: `README.md`)
- Environment API → Action and observation spaces: defines spaces (evidence: `flightning/envs/env_base.py`)
- Environment API → JAX pytree utilities: uses state trees (evidence: `flightning/envs/env_base.py`)
- Static state task → Environment API: implements API (evidence: `flightning/envs/static_gap_state_env.py`)
- Static vision task → Environment API: implements API (evidence: `flightning/envs/static_gap_vision_env.py`)
- Moving state task → Environment API: implements API (evidence: `flightning/envs/moving_gap_state_env.py`)
- Moving vision task → Environment API: implements API (evidence: `flightning/envs/moving_gap_vision_env.py`)
- Static state task → Quadrotor dynamics: uses dynamics (evidence: `flightning/envs/static_gap_state_env.py`)
- Moving state task → Quadrotor dynamics: uses dynamics (evidence: `flightning/envs/moving_gap_state_env.py`)
- Static vision task → Double-sphere camera: uses sensing (evidence: `flightning/envs/static_gap_vision_env.py`)
- Moving vision task → Double-sphere camera: uses sensing (evidence: `flightning/envs/moving_gap_vision_env.py`)
- Extended quadrotor → Quadrotor dynamics: extends dynamics (evidence: `flightning/objects/quadrotor_obj.py`)
- Static state task → Math utilities: uses geometry math (evidence: `flightning/envs/static_gap_state_env.py`)
- Static state task → Randomization utilities: randomizes starts (evidence: `flightning/envs/static_gap_state_env.py`)
- Environment wrappers → Environment API: wraps (evidence: `flightning/envs/wrappers.py`)
