# ntnu-arl/aerial_gym_simulator architecture

> Architecture diagram of the GitHub repository ntnu-arl/aerial_gym_simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ntnu-arl/aerial_gym_simulator
- Repository: https://github.com/ntnu-arl/aerial_gym_simulator

## Overview

##### Project Type and Purpose
- Aerial Gym Simulator is an open-source, GPU-accelerated physics simulator for micro aerial vehicles (MAVs).
- Built on NVIDIA Isaac Gym for physics, NVIDIA Warp for custom sensors, and integrates RL frameworks (CleanRL, RL-Games, Sample Factory).
- Provides modular components to define assets, robots, environments, sensors, controllers, tasks, and training pipelines.

##### Core Components
a. Configuration Layer (Python)
- Directories: `aerial_gym/config/{asset,controller,env,robot,sensor,sim,task}_config`.
- Purpose: parameterize every entity via fine-grained Python config classes.

b. Asset & Robot Management
- `aerial_gym/env_manager/asset_loader.py` & `asset_manager.py`
- Loads URDFs, meshes (resources/models, resources/robots) into the simulation.

c. Simulation Builder & Backend
- `aerial_gym/sim/sim_builder.py` constructs Isaac Gym/world objects using configs.
- Isaac Gym backend (C++/CUDA) performs physics integration.

d. Environment Manager & Loop
- `aerial_gym/env_manager/env_manager.py` orchestrates simulation steps:
1) Read states from Isaac Gym
2) Invoke Controllers → motor commands
3) Control allocation → actuator forces
4) Step physics
5) Render sensors (cameras, LiDAR) via NVIDIA Warp kernels
6) Return observations

e. Controllers & Control Allocation
- `aerial_gym/control/controllers/*` implement geometric and dynamic controllers on GPU.
- `control_allocation.py` maps controller outputs to thrust/torque or motor commands.

f. Sensor & Rendering Pipeline
- `aerial_gym/sensors` contains base sensors and Warp-based camera and LiDAR kernels.
- Produces depth, segmentation, point clouds in parallel on GPU.

g. Tasks & Registry
- `aerial_gym/task/*` define RL Gym environments with observation/action spaces.
- `aerial_gym/registry/*_registry.py` auto-registers assets, controllers, envs, robots, sims, tasks.

h. RL Training Frameworks
- `aerial_gym/rl_training/cleanrl` for CleanRL implementations.
- `.../rl_games` and `.../sample_factory` for alternative RL pipelines.
- Example scripts under `aerial_gym/examples` demonstrating usage and training.

i. Sim2Real Pipeline
- `aerial_gym/sim2real` contains VAE models, inference classes, ROS nodes, and utilities to bridge sim-to-real gaps.

j. Utilities & Helpers
- `aerial_gym/utils` for logging, math, curriculum management, mixing matrix, data conversion, etc.

##### Relationships & Data Flow
- User script / Example (top-level)
↓ loads
- Configuration Layer
↓ instructs
- Simulation Builder
↔ Isaac Gym Backend
↔ Asset Manager
↔ Registry
↓ each simulation step
- Environment Manager
├─> Sensors (Warp GPU kernels) → Observations
├─> Controllers (GPU) → Motor commands
└─> Control Allocation → Physics inputs
↻ loop
↓ feeds
- RL Agent (CleanRL / RL-Games / Sample Factory)
↑ actions

- Sim2Real Pipeline taps simulation logs/weights → VAE training → inference modules.

##### Architectural Patterns & Principles
- Modular, plug-and-play classes for each simulation component.
- GPU-parallelized controllers and sensors to scale to thousands of agents.
- Registry-based auto-discovery to extend with new robots, sensors, tasks without modifying core.
- Separation of concerns: config vs. builder vs. manager vs. controllers vs. rendering vs. training.

##### Essential Elements
- Clear labels: e.g., “Isaac Gym Physics Engine,” “Warp Sensor Kernels,” “CleanRL Training Script.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & Registry Layer
    subgraph "Configuration & Registry" 
        direction TB
        Config["Configuration Layer"]:::blue
        Registry["Registry"]:::blue
        Config -->|loads configs into| Registry
    end

    %% Asset & Robot Management
    AssetMgr["Asset & Robot Management"]:::green
    Config -->|provides params| AssetMgr
    AssetMgr -->|loads models| Resources[(URDF/Meshes)]:::gray

    %% Simulation Builder & Isaac Gym
    subgraph "Simulation Core"
        direction TB
        SimBuilder["Simulation Builder"]:::green
        IsaacGym["Isaac Gym Physics Engine"]:::green
        SimBuilder -->|constructs world| IsaacGym
        AssetMgr -->|registers assets| SimBuilder
        Registry -->|provides types| SimBuilder
    end

    %% Environment Manager & Runtime Loop
    subgraph "Runtime Loop" 
        direction TB
        EnvMgr["Environment Manager"]:::orange
        Sensors["Sensors & Rendering"]:::orange
        Controllers["Controllers"]:::orange
        CtrlAlloc["Control Allocation"]:::orange
        IsaacGym -->|state| EnvMgr
        EnvMgr -->|invoke| Controllers
        Controllers -->|commands| CtrlAlloc
        CtrlAlloc -->|forces| IsaacGym
        EnvMgr -->|render| Sensors
        Sensors -->|observations| EnvMgr
    end

    %% RL Training & Sim2Real
    subgraph "Training & Sim2Real"
        direction TB
        RLAgent["RL Training Frameworks"]:::purple
        Sim2Real["Sim2Real Pipeline"]:::purple
        EnvMgr -->|observations| RLAgent
        RLAgent -->|actions| EnvMgr
        IsaacGym -->|logs/weights| Sim2Real
    end

    %% Utilities & Examples
    Utils["Utilities & Helpers"]:::gray
    Examples["Example Scripts"]:::gray
    RLAgent -->|uses utils| Utils
    Examples -->|user entry| Config

    %% Click Events
    click Config "https://github.com/ntnu-arl/aerial_gym_simulator/tree/main/aerial_gym/config/"
    click Registry "https://github.com/ntnu-arl/aerial_gym_simulator/tree/main/aerial_gym/registry/"
    click AssetMgr "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/env_manager/asset_manager.py"
    click Resources "https://github.com/ntnu-arl/aerial_gym_simulator/tree/main/resources/models/"
    click SimBuilder "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/sim/sim_builder.py"
    click EnvMgr "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/env_manager/env_manager.py"
    click Controllers "https://github.com/ntnu-arl/aerial_gym_simulator/tree/main/aerial_gym/control/controllers/"
    click CtrlAlloc "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/control/control_allocation.py"
    click Sensors "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/sensors/base_sensor.py"
    click RLAgent "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/rl_training/cleanrl/ppo_continuous_action.py"
    click Sim2Real "https://github.com/ntnu-arl/aerial_gym_simulator/blob/main/aerial_gym/sim2real/config.py"
    click Utils "https://github.com/ntnu-arl/aerial_gym_simulator/tree/main/aerial_gym/utils/"

    classDef blue fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef green fill:#D5F5E3,stroke:#196F3D,color:#0B5345
    classDef orange fill:#FCF3CF,stroke:#B9770E,color:#7D6608
    classDef purple fill:#E8DAEF,stroke:#6C3483,color:#4A235A
    classDef gray fill:#F2F3F4,stroke:#212F3C,color:#1C2833
```
