# carlosferrazza/humanoid-bench architecture

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

- Interactive diagram: https://gitdiagram.com/carlosferrazza/humanoid-bench
- Repository: https://github.com/carlosferrazza/humanoid-bench

## Overview

HumanoidBench provides MuJoCo-based whole-body locomotion and manipulation tasks, alongside several reinforcement-learning training implementations. The user selects a registered task and training method; the resulting workflow interacts with the simulated environment, computes task rewards, and trains or evaluates a policy. The README also documents sensory observations, hierarchical low-level policies, and MJX reaching training. Those capabilities are represented at the documented subsystem level; source excerpts are limited, so uncertain internal wiring is omitted.

Main entry points: [`humanoid_bench/env.py`](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/env.py) (Environment API), [`humanoid_bench/tasks.py`](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/tasks.py) (Task logic), [`dreamerv3/embodied/agents/dreamerv3`](https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/agents/dreamerv3) (DreamerV3), [`tdmpc2/tdmpc2`](https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2) (TD-MPC2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_benchmark["Benchmark environments"]
  node_task_envs["Task environments"]
  node_env_api["Environment API<br/>[env.py]"]
  node_task_wrappers["Task wrappers"]
end

subgraph group_simulation["Simulation and tasks"]
  node_task_logic["Task logic<br/>[tasks.py]"]
  node_robot_models["Robot models<br/>[robots.py]"]
  node_dmc_support["MuJoCo support"]
end

subgraph group_training["Training methods"]
  node_dreamer["DreamerV3"]
  node_tdmpc["TD-MPC2"]
  node_sac["SAC"]
  node_ppo["PPO<br/>[run_sb3_ppo.py]"]
end

subgraph group_runtime["Training runtime"]
  node_dreamer_runner["Dreamer runner"]
  node_replay[("Replay buffer")]
  node_distributed["Distributed services"]
  node_tdmpc_trainer["TD-MPC trainers"]
end

subgraph group_hierarchical["Hierarchical and MJX"]
  node_mjx_ppo["MJX PPO"]
  node_skill_policy["Low-level skills<br/>[env.py]"]
  node_mjx_envs["MJX environments"]
end

node_researcher(("Researcher"))

node_researcher -->|"selects task"| node_task_envs
node_task_envs -->|"provides environment"| node_env_api
node_env_api -->|"steps task"| node_task_logic
node_task_logic -->|"uses robot state"| node_robot_models
node_task_logic -->|"uses simulation support"| node_dmc_support
node_researcher -->|"chooses method"| node_dreamer
node_researcher -->|"chooses method"| node_tdmpc
node_researcher -->|"chooses method"| node_sac
node_researcher -->|"chooses method"| node_ppo
node_dreamer -->|"trains on"| node_env_api
node_tdmpc -->|"trains on"| node_env_api
node_sac -->|"trains on"| node_task_envs
node_ppo -->|"trains on"| node_env_api
node_dreamer -->|"runs through"| node_dreamer_runner
node_dreamer_runner -->|"samples and stores"| node_replay
node_dreamer_runner -.->|"dispatches work"| node_distributed
node_tdmpc -->|"trained by"| node_tdmpc_trainer
node_tdmpc_trainer -->|"wraps tasks"| node_task_wrappers
node_researcher -.->|"configures optional skill"| node_skill_policy
node_researcher -->|"chooses MJX training"| node_mjx_ppo
node_mjx_ppo -->|"trains on"| node_mjx_envs

click node_task_envs "https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/envs"
click node_env_api "https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/env.py"
click node_task_logic "https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/tasks.py"
click node_robot_models "https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/robots.py"
click node_dmc_support "https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/dmc_deps"
click node_dreamer "https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/agents/dreamerv3"
click node_tdmpc "https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2"
click node_sac "https://github.com/carlosferrazza/humanoid-bench/tree/main/jaxrl_m/jaxrl_m"
click node_ppo "https://github.com/carlosferrazza/humanoid-bench/blob/main/ppo/run_sb3_ppo.py"
click node_mjx_ppo "https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/mjx/ppo_continuous_action.py"
click node_dreamer_runner "https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/run"
click node_replay "https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/replay"
click node_distributed "https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/distr"
click node_tdmpc_trainer "https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2/trainer"
click node_task_wrappers "https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2/envs/wrappers"
click node_skill_policy "https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/env.py"
click node_mjx_envs "https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/mjx/envs"

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_task_envs,node_env_api,node_task_wrappers toneBlue
class node_task_logic,node_robot_models,node_dmc_support toneAmber
class node_dreamer,node_tdmpc,node_sac,node_ppo toneMint
class node_dreamer_runner,node_replay,node_distributed,node_tdmpc_trainer toneRose
class node_mjx_ppo,node_skill_policy,node_mjx_envs,node_researcher toneIndigo
```

## Components

### Benchmark environments

- [Task environments](https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/envs): `humanoid_bench/envs`
- [Environment API](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/env.py): `humanoid_bench/env.py`
- [Task wrappers](https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2/envs/wrappers): `tdmpc2/tdmpc2/envs/wrappers`

### Simulation and tasks

- [Task logic](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/tasks.py): `humanoid_bench/tasks.py`
- [Robot models](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/robots.py): `humanoid_bench/robots.py`
- [MuJoCo support](https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/dmc_deps): `humanoid_bench/dmc_deps`

### Training methods

- [DreamerV3](https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/agents/dreamerv3): `dreamerv3/embodied/agents/dreamerv3`
- [TD-MPC2](https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2): `tdmpc2/tdmpc2`
- [SAC](https://github.com/carlosferrazza/humanoid-bench/tree/main/jaxrl_m/jaxrl_m): `jaxrl_m/jaxrl_m`
- [PPO](https://github.com/carlosferrazza/humanoid-bench/blob/main/ppo/run_sb3_ppo.py): `ppo/run_sb3_ppo.py`

### Training runtime

- [Dreamer runner](https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/run): `dreamerv3/embodied/run`
- [Replay buffer](https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/replay): `dreamerv3/embodied/replay`
- [Distributed services](https://github.com/carlosferrazza/humanoid-bench/tree/main/dreamerv3/embodied/distr): `dreamerv3/embodied/distr`
- [TD-MPC trainers](https://github.com/carlosferrazza/humanoid-bench/tree/main/tdmpc2/tdmpc2/trainer): `tdmpc2/tdmpc2/trainer`

### Hierarchical and MJX

- [MJX PPO](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/mjx/ppo_continuous_action.py): `humanoid_bench/mjx/ppo_continuous_action.py`
- [Low-level skills](https://github.com/carlosferrazza/humanoid-bench/blob/main/humanoid_bench/env.py): `humanoid_bench/env.py`
- [MJX environments](https://github.com/carlosferrazza/humanoid-bench/tree/main/humanoid_bench/mjx/envs): `humanoid_bench/mjx/envs`

### Other components

- **Researcher**

## Connections

- Researcher → Task environments: selects task
- Task environments → Environment API: provides environment
- Environment API → Task logic: steps task
- Task logic → Robot models: uses robot state
- Task logic → MuJoCo support: uses simulation support
- Researcher → DreamerV3: chooses method
- Researcher → TD-MPC2: chooses method
- Researcher → SAC: chooses method
- Researcher → PPO: chooses method
- DreamerV3 → Environment API: trains on
- TD-MPC2 → Environment API: trains on
- SAC → Task environments: trains on
- PPO → Environment API: trains on
- DreamerV3 → Dreamer runner: runs through
- Dreamer runner → Replay buffer: samples and stores
- Dreamer runner → Distributed services: dispatches work
- TD-MPC2 → TD-MPC trainers: trained by
- TD-MPC trainers → Task wrappers: wraps tasks
- Researcher → Low-level skills: configures optional skill
- Researcher → MJX PPO: chooses MJX training
- MJX PPO → MJX environments: trains on