# tamastran/mjlab_mpopi architecture

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

- Interactive diagram: https://gitdiagram.com/tamastran/mjlab_mpopi
- Repository: https://github.com/tamastran/mjlab_mpopi

## Overview

mjlab is a GPU-accelerated robotics simulation and reinforcement-learning framework built around MuJoCo Warp. The main workflow is to select a registered task, configure a robot and environment, train or evaluate a policy through the manager-based environment, and observe simulation results. Environment steps coordinate actions, simulation, observations, rewards, events, and episode handling. The tree and README document additional velocity, motion-tracking, and manipulation tasks, plus terrain generation and sensor support. Some links reflect documented framework roles; unsampled implementation details are not expanded.

Main entry points: [`src/mjlab/envs/manager_based_rl_env.py`](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/envs/manager_based_rl_env.py) (Manager-based env), [`src/mjlab/scripts/train.py`](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scripts/train.py) (Train / play CLI), [`src/mjlab/scene/scene.py`](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scene/scene.py) (Scene and entities), [`src/mjlab/rl/runner.py`](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/rl/runner.py) (RL runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Task and policy workflow"]
  node_train["Train / play CLI<br/>[train.py]"]
  node_registry["Task registry<br/>[registry.py]"]
  node_taskcfg["Task configurations"]
end

subgraph group_environment["Environment managers"]
  node_env["Manager-based env"]
  node_actions["Action manager<br/>[action_manager.py]"]
  node_commands["Command manager<br/>[command_manager.py]"]
  node_observations["Observation manager"]
  node_events["Event manager<br/>[event_manager.py]"]
  node_metrics["Rewards and metrics<br/>[metrics_manager.py]"]
  node_recorders["Rollout recording"]
end

subgraph group_simulation["Simulation and scene"]
  node_sim["MuJoCo Warp sim<br/>[sim.py]"]
  node_scene["Scene and entities<br/>[scene.py]"]
  node_entity["Robot entities<br/>[entity.py]"]
  node_actuators["Actuator models"]
end

subgraph group_capabilities["Robotics capabilities"]
  node_terrain["Terrain generation"]
  node_sensors["Sensors and context"]
  node_taskmdp["Task MDP terms"]
  node_viewer["Simulation viewers"]
end

subgraph group_learning["RL runtime"]
  node_runner["RL runner<br/>[runner.py]"]
  node_algorithm["MPOPI algorithm"]
end

node_user(("Engineer"))
node_wandb(("Weights &amp; Biases"))

node_user -->|"starts task"| node_train
node_train -->|"selects task"| node_registry
node_registry -->|"resolves config"| node_taskcfg
node_taskcfg -->|"configures"| node_env
node_env -->|"initializes"| node_scene
node_env -->|"steps physics"| node_sim
node_env -->|"loads manager"| node_actions
node_env -->|"loads manager"| node_commands
node_env -->|"loads manager"| node_observations
node_env -->|"loads manager"| node_events
node_env -->|"loads manager"| node_metrics
node_env -->|"loads manager"| node_recorders
node_scene -->|"contains"| node_entity
node_actions -->|"targets"| node_entity
node_entity -->|"uses"| node_actuators
node_scene -->|"builds from"| node_terrain
node_scene -->|"provides context"| node_sensors
node_observations -->|"evaluates terms"| node_taskmdp
node_commands -->|"updates commands"| node_taskmdp
node_metrics -->|"evaluates terms"| node_taskmdp
node_train -->|"runs training"| node_runner
node_runner -->|"trains on"| node_env
node_runner -->|"uses algorithm"| node_algorithm
node_train -.->|"opens for play"| node_viewer
node_train -.->|"fetches checkpoint"| node_wandb

click node_train "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scripts/train.py"
click node_registry "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/tasks/registry.py"
click node_taskcfg "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/tasks"
click node_env "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/envs/manager_based_rl_env.py"
click node_actions "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/action_manager.py"
click node_commands "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/command_manager.py"
click node_observations "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/observation_manager.py"
click node_events "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/event_manager.py"
click node_metrics "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/metrics_manager.py"
click node_recorders "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/recorder_manager.py"
click node_sim "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/sim/sim.py"
click node_scene "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scene/scene.py"
click node_entity "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/entity/entity.py"
click node_actuators "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/actuator"
click node_terrain "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/terrains"
click node_sensors "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/sensor"
click node_taskmdp "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/tasks"
click node_viewer "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/viewer"
click node_runner "https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/rl/runner.py"
click node_algorithm "https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/rl/mpopi"

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_train,node_registry,node_taskcfg toneBlue
class node_env,node_actions,node_commands,node_observations,node_events,node_metrics,node_recorders toneAmber
class node_sim,node_scene,node_entity,node_actuators toneMint
class node_terrain,node_sensors,node_taskmdp,node_viewer toneRose
class node_runner,node_algorithm,node_user,node_wandb toneIndigo
```

## Components

### Task and policy workflow

- [Train / play CLI](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scripts/train.py): `src/mjlab/scripts/train.py`
- [Task registry](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/tasks/registry.py): `src/mjlab/tasks/registry.py`
- [Task configurations](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/tasks): `src/mjlab/tasks`

### Environment managers

- [Manager-based env](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/envs/manager_based_rl_env.py): `src/mjlab/envs/manager_based_rl_env.py`
- [Action manager](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/action_manager.py): `src/mjlab/managers/action_manager.py`
- [Command manager](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/command_manager.py): `src/mjlab/managers/command_manager.py`
- [Observation manager](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/observation_manager.py): `src/mjlab/managers/observation_manager.py`
- [Event manager](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/event_manager.py): `src/mjlab/managers/event_manager.py`
- [Rewards and metrics](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/metrics_manager.py): `src/mjlab/managers/metrics_manager.py`
- [Rollout recording](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/managers/recorder_manager.py): `src/mjlab/managers/recorder_manager.py`

### Simulation and scene

- [MuJoCo Warp sim](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/sim/sim.py): `src/mjlab/sim/sim.py`
- [Scene and entities](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/scene/scene.py): `src/mjlab/scene/scene.py`
- [Robot entities](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/entity/entity.py): `src/mjlab/entity/entity.py`
- [Actuator models](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/actuator): `src/mjlab/actuator`

### Robotics capabilities

- [Terrain generation](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/terrains): `src/mjlab/terrains`
- [Sensors and context](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/sensor): `src/mjlab/sensor`
- [Task MDP terms](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/tasks): `src/mjlab/tasks`
- [Simulation viewers](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/viewer): `src/mjlab/viewer`

### RL runtime

- [RL runner](https://github.com/tamastran/mjlab_mpopi/blob/main/src/mjlab/rl/runner.py): `src/mjlab/rl/runner.py`
- [MPOPI algorithm](https://github.com/tamastran/mjlab_mpopi/tree/main/src/mjlab/rl/mpopi): `src/mjlab/rl/mpopi`

### Other components

- **Engineer**
- **Weights & Biases**

## Connections

- Engineer → Train / play CLI: starts task
- Train / play CLI → Task registry: selects task
- Task registry → Task configurations: resolves config
- Task configurations → Manager-based env: configures
- Manager-based env → Scene and entities: initializes
- Manager-based env → MuJoCo Warp sim: steps physics
- Manager-based env → Action manager: loads manager
- Manager-based env → Command manager: loads manager
- Manager-based env → Observation manager: loads manager
- Manager-based env → Event manager: loads manager
- Manager-based env → Rewards and metrics: loads manager
- Manager-based env → Rollout recording: loads manager
- Scene and entities → Robot entities: contains
- Action manager → Robot entities: targets
- Robot entities → Actuator models: uses
- Scene and entities → Terrain generation: builds from
- Scene and entities → Sensors and context: provides context
- Observation manager → Task MDP terms: evaluates terms
- Command manager → Task MDP terms: updates commands
- Rewards and metrics → Task MDP terms: evaluates terms
- Train / play CLI → RL runner: runs training
- RL runner → Manager-based env: trains on
- RL runner → MPOPI algorithm: uses algorithm
- Train / play CLI → Simulation viewers: opens for play
- Train / play CLI → Weights & Biases: fetches checkpoint