# abmorobotics/rlroverlab architecture

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

- Interactive diagram: https://gitdiagram.com/abmorobotics/rlroverlab
- Repository: https://github.com/abmorobotics/rlroverlab

## Overview

##### Project type and purpose
- RLRoverLab is an open-source Reinforcement Learning (RL) suite that integrates NVIDIA’s Isaac Sim & Isaac Lab to simulate and train autonomous planetary rovers.
- It provides task-specific environments (navigation & manipulation), assets (robots & terrains), and RL pipelines (entrypoints + example scripts) in a modular, extensible framework.

##### File structure
- Top-level directories:
- docker – container definitions, entrypoint scripts, ROS2 & simulation config
- docs – static site source (mdBook) for installation, development, examples
- examples – Python scripts demonstrating demos, training, inference, ROS integration
- rover_envs – core Python package subdivided into:
· assets (USD robots, terrains, textures)
· entrypoints (CLI wrappers to launch specific envs)
· envs (navigation & manipulation implementations, each with MDP config + SKRL agents)
· mdp (generic RL abstractions: actions, observations, rewards, terminations, recorders)
· utils (config loading, logging utilities, ROS2 publishers/subscribers)
- setup.py / pyproject.toml – package configuration for installation
- download_usd.py – utility to fetch USD assets externally

##### Extract architecture hints from the README
- Emphasizes Isaac Sim/Isaac Lab integration, extensibility for new tasks/robots.

##### Main components
a. Container & Orchestration layer
- Docker engine & docker-compose.yaml
- Environment variables (.env, .env.ros2)
- Entry point scripts (run.sh, run_ros.sh, stop.sh)
b. Simulation layer
- Isaac Sim / Isaac Lab (inside Docker container)
- USD assets loader (download_usd.py + rover_envs/assets)
- DDS middleware (CycloneDDS / FastDDS configured under docker/.ros)
c. RL framework & environment definitions
- rover_envs package
– envs/navigation & manipulation (MDP + SKRL configs + agent models)
– mdp abstractions (actions, observations, rewards, terminations, recorders)
– utils (config management, logging, ROS2 pub/sub interfaces)
- Entrypoint Python scripts (ManagerBasedRLEnv.py, rover_env.py, train.py, eval.py)
- Examples layer demonstrates usage scenarios
d. External services & interfaces
- ROS2 topics for real-time data exchange (publishers/subscribers under utils/ros2)
- Optional external storage for pretrained policies (policies/*.pt)
- Documentation site (docs/) – static site generator

##### Relationships & data flows
- Docker Compose sets up the Isaac Sim container with ROS2 DDS and mounts USD assets.
- The entrypoint script inside Docker invokes a Python CLI module in rover_envs/entrypoints.
- The CLI module initializes the Isaac Sim environment by loading USD scenes (assets → simulation), sets up environment wrappers from rover_envs/envs.
- The MDP layer (rover_envs/mdp) exchanges observations and rewards with the simulation, issues actions via the Isaac Sim API or ROS2 topics.
- The RL algorithm (SKRL agents configured in rover_envs/envs/*/learning/skrl) processes observations and outputs actions.
- Recorders capture trajectories and metrics (rover_envs/mdp/recorders).
- Optionally, ROS2 nodes publish sensor data and subscribe to control commands for external visualization or control loops.
- Example scripts orchestrate full pipelines: create scene → train agent → evaluate using pretrained models.

##### Architectural patterns & principles
- Modular separation: assets ←→ env definitions ←→ MDP abstractions ←→ RL algorithms ←→ entrypoints
- Clear layering: Containerization → Simulation → Wrapper API → RL layer → External interfaces
- Configuration-driven: YAML / Python configs under rover_envs/envs/*/config facilitate new tasks or robots
- Extensibility: New assets or tasks plug into the same MDP → env → agent pipeline without touching core code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Layer
    subgraph "Deployment Layer"
        direction TB
        DockerCompose["docker-compose.yaml"]:::infra
        DockerEngine["Docker Engine"]:::infra
        EnvFile[".env"]:::infra
        EnvRos[".env.ros2"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DockerfileRos["Dockerfile.ros2"]:::infra
        CycloneDDS["cyclonedds.xml"]:::infra
        FastDDS["fastdds.xml"]:::infra
        EntrypointSh["entrypoint.sh"]:::infra
        RunSh["run.sh"]:::infra
        RunRosSh["run_ros.sh"]:::infra
        StopSh["stop.sh"]:::infra
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        IsaacSim["Isaac Sim / Isaac Lab"]:::sim
        USDLoader["download_usd.py"]:::sim
        Assets["rover_envs/assets"]:::sim
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        subgraph "Entrypoints" 
            ManagerEnv["ManagerBasedRLEnv.py"]:::core
        end
        subgraph "Environments"
            direction TB
            subgraph "Navigation"
                NavCfg["rover_env_cfg.py"]:::core
                NavNoObs["rover_env_no_obstacles_cfg.py"]:::core
                NavEntry1["rover_env.py"]:::core
                NavEntry2["rover_camera_env.py"]:::core
                NavObs["observations.py"]:::core
                NavRew["rewards.py"]:::core
                NavTerm["terminations.py"]:::core
                NavAgents["agents.py"]:::core
            end
            subgraph "Manipulation"
                ManipCfg["manipulation_env_cfg.py"]:::core
                ManipObs["observations.py"]:::core
                ManipRew["rewards.py"]:::core
                ManipTerm["terminations.py"]:::core
            end
        end
        subgraph "MDP Abstractions"
            AckActions["ackermann_actions.py"]:::core
            ActionsCfg["actions_cfg.py"]:::core
            Recorders["recorders.py"]:::core
            RecCfg["recorders_cfg.py"]:::core
        end
        subgraph "Utilities"
            ConfigUtil["config.py"]:::core
            LogUtil["logging_utils.py"]:::core
            ROS2Pub["publishers.py"]:::core
            ROS2Sub["subscribers.py"]:::core
        end
    end

    %% Training & Inference Layer
    subgraph "Examples & Pipelines"
        direction TB
        Demos["01_demos/*.py"]:::examples
        Train["02_train/train.py"]:::examples
        Eval["03_inference_pretrained/eval.py"]:::examples
        ROSExamples["05_ros/*.py"]:::examples
    end

    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        ROS2["ROS2 Topics"]:::external
        Policies["policies/*.pt"]:::external
        Docs["docs/src"]:::external
    end

    %% Connections
    DockerCompose -->|uses| DockerEngine
    EnvFile --> DockerCompose
    EnvRos --> DockerCompose
    DockerEngine -->|build| Dockerfile
    DockerEngine -->|build| DockerfileRos
    DockerEngine -->|config| CycloneDDS
    DockerEngine -->|config| FastDDS
    DockerEngine -->|run| EntrypointSh
    EntrypointSh -->|starts| ManagerEnv

    ManagerEnv -->|initializes| IsaacSim
    USDLoader -->|loads assets| Assets
    Assets -->|mounted into| IsaacSim

    IsaacSim -->|produces Obs| NavObs
    IsaacSim -->|produces Obs| ManipObs
    NavObs -->|input| NavAgents
    NavRew -->|input| NavAgents
    NavAgents -->|actions| IsaacSim
    ManipObs -->|input| ManipRew
    ManipTerm -->|input| ManipRew
    ManipRew -->|actions| IsaacSim

    NavEntry1 -->|wraps| IsaacSim
    NavEntry2 -->|wraps| IsaacSim

    IsaacSim <-->|via DDS| ROS2Pub
    IsaacSim <-->|via DDS| ROS2Sub
    ROS2Pub --> ROS2
    ROS2Sub --> ROS2

    Recorders -->|logs| Policies
    Recorders -->|metrics| Docs

    Demos -->|demonstrate| ManagerEnv
    Train -->|calls| ManagerEnv
    Eval -->|loads| Policies
    ROSExamples -->|uses| ROS2

    %% Click Events
    click DockerCompose "https://github.com/abmorobotics/rlroverlab/blob/main/docker/docker-compose.yaml"
    click EnvFile "https://github.com/abmorobotics/rlroverlab/blob/main/docker/.env"
    click EnvRos "https://github.com/abmorobotics/rlroverlab/blob/main/docker/.env.ros2"
    click Dockerfile "https://github.com/abmorobotics/rlroverlab/tree/main/docker/Dockerfile"
    click DockerfileRos "https://github.com/abmorobotics/rlroverlab/blob/main/docker/Dockerfile.ros2"
    click CycloneDDS "https://github.com/abmorobotics/rlroverlab/blob/main/docker/.ros/cyclonedds.xml"
    click FastDDS "https://github.com/abmorobotics/rlroverlab/blob/main/docker/.ros/fastdds.xml"
    click EntrypointSh "https://github.com/abmorobotics/rlroverlab/blob/main/docker/entrypoint.sh"
    click RunSh "https://github.com/abmorobotics/rlroverlab/blob/main/docker/run.sh"
    click RunRosSh "https://github.com/abmorobotics/rlroverlab/blob/main/docker/run_ros.sh"
    click StopSh "https://github.com/abmorobotics/rlroverlab/blob/main/docker/stop.sh"
    click USDLoader "https://github.com/abmorobotics/rlroverlab/blob/main/download_usd.py"
    click Assets "https://github.com/abmorobotics/rlroverlab/tree/main/rover_envs/assets"
    click ManagerEnv "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/entrypoints/ManagerBasedRLEnv.py"
    click NavCfg "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/rover_env_cfg.py"
    click NavNoObs "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/rover_env_no_obstacles_cfg.py"
    click NavEntry1 "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/entrypoints/rover_env.py"
    click NavEntry2 "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/entrypoints/rover_camera_env.py"
    click NavObs "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/mdp/observations.py"
    click NavRew "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/mdp/rewards.py"
    click NavTerm "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/mdp/terminations.py"
    click NavAgents "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/envs/navigation/learning/skrl/agents.py"
    click AckActions "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/mdp/actions/ackermann_actions.py"
    click ActionsCfg "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/mdp/actions/actions_cfg.py"
    click Recorders "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/mdp/recorders/recorders.py"
    click RecCfg "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/mdp/recorders/recorders_cfg.py"
    click ConfigUtil "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/utils/config.py"
    click LogUtil "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/utils/logging_utils.py"
    click ROS2Pub "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/utils/ros2/publishers.py"
    click ROS2Sub "https://github.com/abmorobotics/rlroverlab/blob/main/rover_envs/utils/ros2/subscribers.py"
    click Demos "https://github.com/abmorobotics/rlroverlab/tree/main/examples/01_demos/"
    click Train "https://github.com/abmorobotics/rlroverlab/blob/main/examples/02_train/train.py"
    click Eval "https://github.com/abmorobotics/rlroverlab/blob/main/examples/03_inference_pretrained/eval.py"
    click ROSExamples "https://github.com/abmorobotics/rlroverlab/tree/main/examples/05_ros/"
    click Docs "https://github.com/abmorobotics/rlroverlab/tree/main/docs/src"

    %% Styles
    classDef infra fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef sim fill:#ffe5cc,stroke:#f90,stroke-width:1px
    classDef core fill:#d5f5d5,stroke:#2d7,stroke-width:1px
    classDef examples fill:#f4e1ff,stroke:#a0a,stroke-width:1px
    classDef external fill:#e5ccff,stroke:#93f,stroke-width:1px
```
