# warplab/isaac-auv-env architecture

> Architecture diagram of the GitHub repository warplab/isaac-auv-env, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/warplab/isaac-auv-env
- Repository: https://github.com/warplab/isaac-auv-env

## Overview

##### Project Type and Purpose
- Type: Research-grade reinforcement-learning (RL) simulation environment and training framework.
- Purpose: Provide a Gym-style environment (WarpAUV) atop Omniverse IsaacSim/IsaacLab, run PPO training, evaluate policies, and manage assets/configurations.

##### File Structure
- Top level:
– agents/         ← RL algorithm configuration (rsl_rl_ppo_cfg.py)
– custom_workflows/ ← CLI entry points for train/eval/plot
– warpauv_env.py  ← Gym-style environment wrapper
– rigid_body_hydrodynamics.py, thruster_dynamics.py ← custom physics submodules
– assets/warpauv.py ← AUV USD asset configuration
– data/warpauv/   ← USD meshes and configuration YAML
– weights/        ← Saved model checkpoints
- External dependencies:
– IsaacSim v4.5.0 + IsaacLab v2.2.0 (Omniverse GPU simulation engine)
– Gym, PyTorch (implied by .pt), NVIDIA RL utilities

##### Extract Key Architecture Notes from the README
- The simulation engine (IsaacSim) is decoupled via IsaacLab workflows.
- Training is driven by a CLI script (`scripts/reinforcement_learning/rsl_rl/train.py`).
- The environment exposes gym spaces (obs/action/state) and loads the USD asset.

##### Main Components
A. Reinforcement-Learning Agent
– Config (agents/rsl_rl_ppo_cfg.py)
– PPO algorithm (PyTorch)
– Checkpoint storage (weights/)
B. Gym-Style Environment Wrapper (`warpauv_env.py`)
– Defines observation_space, action_space, step/reset
– Integrates physics and thruster modules
C. Physics Submodules
– rigid_body_hydrodynamics.py
– thruster_dynamics.py
D. Asset Loader (`assets/warpauv.py`)
– Reads USD model from data/warpauv/warpauv.usd
– Configures RigidBodyProperties, Articulation props
E. IsaacSim/IsaacLab Simulation Engine
– External service
– Runs the real-time physics & rendering loop
F. CLI Workflows (`custom_workflows/`)
– train.py → kicks off agent + env + simulation
– play*.py, play_eval*.py → evaluation and data collection
– plot_metrics.py → post-training visualization
G. Data/Configuration
– USD meshes (instanceable_meshes.usd)
– config.yaml for asset parameters

##### Relationships & Data Flows
- Agent → [action] → Environment
- Environment → [step] → IsaacSim Engine
- IsaacSim Engine → [physics/render] → Physics Submodules & USD assets
- IsaacSim Engine → [obs, reward, done] → Environment → Agent
- Agent → [policy update] → Agent (self-contained training loop)
- Training/Eval CLI → orchestrates Agent + Environment instantiation
- Plot workflow → consumes metrics log output

##### Architectural Patterns & Design Principles
- Modular layering:
– External engine (IsaacSim) decoupled from Python wrapper
– Physics concerns split into dedicated modules
- Standard RL interfaces: Gym API for compatibility
- Configuration-driven: all hyperparams & asset settings live in code and YAML

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Workflows
    subgraph "CLI Workflows"
        direction TB
        CLI_Train["train.py"]:::compute
        CLI_Play["play.py"]:::compute
        CLI_PlayControls["play_controls.py"]:::compute
        CLI_PlayEval["play_eval.py"]:::compute
        CLI_PlayEvalPos["play_eval_for_publication_pos.py"]:::compute
        CLI_PlayEvalVel["play_eval_for_publication_vel.py"]:::compute
        CLI_PlayPoshold["play_poshold.py"]:::compute
        CLI_Plot["plot_metrics.py"]:::compute
    end

    %% RL Agent
    subgraph "Reinforcement-Learning Agent" 
        direction TB
        AgentCfg["rsl_rl_ppo_cfg.py"]:::compute
        PPO["PPO Algorithm (PyTorch)"]:::compute
    end

    %% Environment
    warpauv_env["warpauv_env.py"]:::compute

    %% Physics Modules
    subgraph "Physics Submodules"
        direction TB
        RigidHydro["rigid_body_hydrodynamics.py"]:::compute
        ThrusterDyn["thruster_dynamics.py"]:::compute
    end

    %% Asset Loader
    AssetLoader["assets/warpauv.py"]:::compute

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        IsaacSim["IsaacSim / IsaacLab"]:::external
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        direction TB
        Weights["weights/"]:::data
        DataFiles["USD & Config Data"]:::data
    end

    %% Data File Details
    USDModel["warpauv.usd"]:::data
    Meshes["instanceable_meshes.usd"]:::data
    ConfigYAML["config.yaml"]:::data

    %% Connections
    CLI_Train -->|"init Agent & Env"| AgentCfg
    CLI_Train --> AgentCfg
    CLI_Train --> warpauv_env

    CLI_Play --> warpauv_env
    CLI_PlayControls --> warpauv_env
    CLI_PlayEval --> warpauv_env
    CLI_PlayEvalPos --> warpauv_env
    CLI_PlayEvalVel --> warpauv_env
    CLI_PlayPoshold --> warpauv_env
    CLI_Plot --> DataFiles

    AgentCfg --> PPO
    PPO -->|"policy update"| PPO
    PPO -->|"action"| warpauv_env

    warpauv_env -->|"step"| IsaacSim
    IsaacSim -->|"physics/render"| RigidHydro
    IsaacSim --> RigidHydro
    IsaacSim --> ThrusterDyn
    IsaacSim --> AssetLoader
    IsaacSim -->|"obs/reward/done"| warpauv_env
    warpauv_env -->|"obs/reward"| PPO

    AssetLoader -->|"loads USD & config"| USDModel
    AssetLoader --> USDModel
    AssetLoader --> Meshes
    AssetLoader --> ConfigYAML

    %% Storage arrows
    PPO -->|"save checkpoints"| Weights
    warpauv_env -->|"reads/writes"| DataFiles

    %% Group Data files under DataFiles
    DataFiles --> USDModel
    DataFiles --> Meshes
    DataFiles --> ConfigYAML

    %% Click Events
    click AgentCfg "https://github.com/warplab/isaac-auv-env/blob/main/agents/rsl_rl_ppo_cfg.py"
    click Weights "https://github.com/warplab/isaac-auv-env/tree/main/weights/"
    click warpauv_env "https://github.com/warplab/isaac-auv-env/blob/main/warpauv_env.py"
    click RigidHydro "https://github.com/warplab/isaac-auv-env/blob/main/rigid_body_hydrodynamics.py"
    click ThrusterDyn "https://github.com/warplab/isaac-auv-env/blob/main/thruster_dynamics.py"
    click AssetLoader "https://github.com/warplab/isaac-auv-env/blob/main/assets/warpauv.py"
    click USDModel "https://github.com/warplab/isaac-auv-env/blob/main/data/warpauv/warpauv.usd"
    click Meshes "https://github.com/warplab/isaac-auv-env/blob/main/data/warpauv/Props/instanceable_meshes.usd"
    click ConfigYAML "https://github.com/warplab/isaac-auv-env/blob/main/data/warpauv/config.yaml"
    click CLI_Train "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play.py"
    click CLI_Play "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play.py"
    click CLI_PlayControls "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play_controls.py"
    click CLI_PlayEval "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play_eval.py"
    click CLI_PlayEvalPos "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play_eval_for_publication_pos.py"
    click CLI_PlayEvalVel "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play_eval_for_publication_vel.py"
    click CLI_PlayPoshold "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/play_poshold.py"
    click CLI_Plot "https://github.com/warplab/isaac-auv-env/blob/main/custom_workflows/plot_metrics.py"

    %% Styles
    classDef compute fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef data fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef external fill:#FFF3E0,stroke:#F57C00,color:#000
```
