# open-x-humanoid/tienkung-lab architecture

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

- Interactive diagram: https://gitdiagram.com/open-x-humanoid/tienkung-lab
- Repository: https://github.com/open-x-humanoid/tienkung-lab

## Overview

1. **Repository shape**
   - The repo is split into two major codebases: `legged_lab`, which defines the TienKung robot task, simulation assets, sensors, and scripts; and `rsl_rl`, a vendored reinforcement-learning library used for PPO/AMP training and rollout management.
   - The overall architecture is an IsaacLab-based robotics control stack, not a general application stack.

2. **Core domain: TienKung locomotion**
   - The main task domain lives under `legged_lab/envs/tienkung`.
   - It defines separate task configurations for `walk`, `run`, and sensor-augmented variants like `walk_with_sensor` and `run_with_sensor`.
   - These configs feed into a common environment implementation in `legged_lab/envs/tienkung/tienkung_env.py`.

3. **Environment framework**
   - `legged_lab/envs/base` provides reusable environment abstractions and configuration classes.
   - This is the boundary where task-specific settings are layered on top of IsaacLab-compatible base environment behavior.
   - The task registry in `legged_lab/utils/task_registry.py` likely connects CLI task names to the correct environment/config pair.

4. **Robot assets and simulation representations**
   - Robot geometry and simulation assets are stored under `legged_lab/assets/tienkung2_lite`.
   - The same robot is represented in multiple formats: STL meshes, URDF, MJCF, and USD.
   - This is important architecturally because the repo supports both IsaacLab simulation and MuJoCo sim-to-sim evaluation, so asset conversion is part of the project structure.

5. **Motion data pipeline**
   - Motion data is a first-class input to the system.
   - The repo distinguishes two dataset roles under `legged_lab/envs/tienkung/datasets`:
     - `motion_visualization`: used to replay or inspect motions.
     - `motion_amp_expert`: used as expert demonstrations for AMP-style learning.
   - The README shows a two-step conversion flow from GMR/SMPLX retargeting output into visualization data, then into AMP expert data.

6. **Training and imitation-learning loop**
   - Training is driven by `legged_lab/scripts/train.py`.
   - The learning setup combines reinforcement learning with AMP-style motion imitation; the README explicitly mentions AMP rewards plus periodic gait rewards.
   - The actual RL algorithms and buffers come from the bundled `rsl_rl` package, especially `amp_ppo.py`, `ppo.py`, `rollout_storage.py`, and the AMP-related modules.

7. **Policy execution and evaluation**
   - `legged_lab/scripts/play.py` runs a trained policy in IsaacLab.
   - `legged_lab/scripts/play_amp_animation.py` is used to visualize motion playback and sensor-augmented playback, which acts as a debugging and dataset validation path.
   - `legged_lab/scripts/sim2sim.py` evaluates exported policies in MuJoCo, forming a separate runtime boundary from IsaacLab.

8. **Sensors and perceptual extensions**
   - The repo includes sensor packages under `legged_lab/sensors`, with camera and lidar support.
   - Camera support includes device-specific configs such as D455 depth and Luxonis OAK-D, plus a tiled camera abstraction.
   - These sensor modules are optional extensions used by the `*_with_sensor` tasks, indicating the architecture supports both proprioceptive-only and perceptive control paths.

9. **Terrain and environment geometry**
   - Terrain-related logic lives under `legged_lab/terrains`.
   - The ray-caster modules suggest environment sensing and/or terrain interaction are implemented with explicit geometric queries.
   - This subsystem is likely shared by locomotion tasks that need obstacle awareness or local terrain perception.

10. **Reward and control shaping**
   - `legged_lab/mdp/rewards.py` is the main place where task reward terms are defined.
   - In practice, this is where locomotion objectives such as gait periodicity, tracking, stability, and AMP-related penalties/rewards are composed.
   - This subsystem sits between raw simulation state and the learning algorithm.

11. **Bundled RL library boundary**
   - `rsl_rl` is a self-contained reinforcement learning library included in the repo rather than consumed as a pure external dependency.
   - It provides reusable algorithm implementations, actor-critic models, recurrent variants, AMP-specific training runner support, motion loaders, and logging utilities.
   - This boundary matters because the project’s training stack is split between task-specific robotics code and generic RL infrastructure.

12. **Utilities, CLI, and logging**
   - `legged_lab/utils` contains CLI argument handling, keyboard utilities, scene helpers, and environment setup helpers.
   - The `rsl_rl` utilities include integrations for logging backends such as Weights & Biases and Neptune.
   - These pieces are not the core control logic, but they connect training/evaluation workflows to user interaction and experiment tracking.

13. **External dependencies and runtime constraints**
   - The architecture depends materially on IsaacSim 4.5.0 and IsaacLab 2.1.0, runs on Python 3.10/Linux, and uses MuJoCo for sim-to-sim validation.
   - The README also references GMR for motion retargeting, which is upstream of the training pipeline.
   - `Exported_policy/walk.pt` shows that trained policies are treated as deployable artifacts separate from the source code.

14. **End-to-end flow**
   - The typical pipeline is: retarget motion data externally, convert it into repo-specific motion files, visualize and validate the motion, train an AMP+RL policy in IsaacLab, export the learned policy, then evaluate it either in IsaacLab playback or MuJoCo sim-to-sim.
   - Real-robot deployment is outside this repo, but the README makes clear that the learned policy is intended to transfer to hardware via a separate deployment repository.

Main entry points: [`legged_lab/envs/tienkung/tienkung_env.py`](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/tienkung_env.py) (TienKung env), [`legged_lab/utils/task_registry.py`](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/utils/task_registry.py) (Task registry), [`rsl_rl/rsl_rl/runners`](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/runners) (Runner), [`legged_lab/assets/tienkung2_lite`](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/assets/tienkung2_lite) (Robot assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_legged_lab["legged_lab"]
  node_asset_robot[("Robot assets<br/>USD/URDF/MJCF/meshes")]
  node_asset_usd["USD model<br/>IsaacLab asset<br/>[tienkung2_lite.usd]"]
  node_env_base["Base env<br/>environment base"]
  node_tienkung_env["TienKung env<br/>task env<br/>[tienkung_env.py]"]
  node_walk_cfg["Walk cfg<br/>task config<br/>[walk_cfg.py]"]
  node_run_cfg["Run cfg<br/>task config<br/>[run_cfg.py]"]
  node_walk_sensor_cfg["Walk sensor<br/>task config"]
  node_run_sensor_cfg["Run sensor<br/>task config"]
  node_task_registry["Task registry<br/>CLI routing<br/>[task_registry.py]"]
  node_reward_terms["Rewards<br/>MDP shaping<br/>[rewards.py]"]
  node_datasets[("Motion data<br/>AMP datasets")]
  node_sensor_stack["Sensors<br/>camera/lidar"]
  node_terrains["Terrains<br/>terrain sensing"]
  node_train_script["Train<br/>entrypoint<br/>[train.py]"]
  node_play_script["Play<br/>entrypoint<br/>[play.py]"]
  node_amp_animation["AMP replay<br/>entrypoint"]
  node_sim2sim["Sim2sim<br/>MuJoCo eval<br/>[sim2sim.py]"]
end

subgraph group_rsl_rl["rsl_rl"]
  node_rl_algorithms["Algorithms<br/>PPO/AMP"]
  node_rl_runner["Runner"]
  node_rl_storage[("Storage<br/>rollout buffer")]
  node_rl_modules["Models<br/>policy modules"]
  node_rl_utils["RL utils<br/>motion/logging utils"]
end

node_task_registry -->|"selects"| node_walk_cfg
node_task_registry -->|"selects"| node_run_cfg
node_task_registry -->|"selects"| node_walk_sensor_cfg
node_task_registry -->|"selects"| node_run_sensor_cfg
node_walk_cfg -->|"configures"| node_tienkung_env
node_run_cfg -->|"configures"| node_tienkung_env
node_walk_sensor_cfg -->|"configures"| node_tienkung_env
node_run_sensor_cfg -->|"configures"| node_tienkung_env
node_tienkung_env -->|"extends"| node_env_base
node_tienkung_env -->|"uses"| node_reward_terms
node_tienkung_env -->|"loads"| node_datasets
node_tienkung_env -->|"optionally uses"| node_sensor_stack
node_tienkung_env -->|"samples"| node_terrains
node_tienkung_env -->|"instantiates"| node_asset_robot
node_asset_robot -->|"includes"| node_asset_usd
node_train_script -->|"resolves"| node_task_registry
node_train_script -->|"starts"| node_rl_runner
node_rl_runner -->|"drives"| node_rl_algorithms
node_rl_runner -->|"stores"| node_rl_storage
node_rl_algorithms -->|"uses"| node_rl_modules
node_rl_runner -->|"logs"| node_rl_utils
node_play_script -->|"loads"| node_task_registry
node_play_script -->|"runs"| node_tienkung_env
node_amp_animation -->|"replays"| node_datasets
node_amp_animation -->|"visualizes"| node_sensor_stack
node_sim2sim -->|"evaluates"| node_asset_robot
node_sim2sim -->|"loads"| node_rl_utils

click node_asset_robot "https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/assets/tienkung2_lite"
click node_asset_usd "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/assets/tienkung2_lite/usd/tienkung2_lite.usd"
click node_env_base "https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/envs/base"
click node_tienkung_env "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/tienkung_env.py"
click node_walk_cfg "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/walk_cfg.py"
click node_run_cfg "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/run_cfg.py"
click node_walk_sensor_cfg "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/walk_with_sensor_cfg.py"
click node_run_sensor_cfg "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/run_with_sensor_cfg.py"
click node_task_registry "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/utils/task_registry.py"
click node_reward_terms "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/mdp/rewards.py"
click node_datasets "https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/envs/tienkung/datasets"
click node_sensor_stack "https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/sensors"
click node_terrains "https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/terrains"
click node_train_script "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/train.py"
click node_play_script "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/play.py"
click node_amp_animation "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/play_amp_animation.py"
click node_sim2sim "https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/sim2sim.py"
click node_rl_algorithms "https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/algorithms"
click node_rl_runner "https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/runners"
click node_rl_storage "https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/storage"
click node_rl_modules "https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/modules"
click node_rl_utils "https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/utils"

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_asset_robot,node_asset_usd,node_env_base,node_tienkung_env,node_walk_cfg,node_run_cfg,node_walk_sensor_cfg,node_run_sensor_cfg,node_task_registry,node_reward_terms,node_datasets,node_sensor_stack,node_terrains,node_train_script,node_play_script,node_amp_animation,node_sim2sim toneBlue
class node_rl_algorithms,node_rl_runner,node_rl_storage,node_rl_modules,node_rl_utils toneAmber
```

## Components

### legged_lab

Task-specific robotics stack for TienKung locomotion, assets, sensors, and workflows.

- [Robot assets](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/assets/tienkung2_lite): USD/URDF/MJCF/meshes · TienKung Lite robot represented across simulation formats and geometry sources. · `legged_lab/assets/tienkung2_lite`
- [USD model](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/assets/tienkung2_lite/usd/tienkung2_lite.usd): IsaacLab asset · Canonical IsaacLab robot asset and sensor/physics variants. · `legged_lab/assets/tienkung2_lite/usd/tienkung2_lite.usd`
- [Base env](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/envs/base): environment base · Reusable environment abstractions and configuration layer for IsaacLab-compatible tasks. · `legged_lab/envs/base`
- [TienKung env](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/tienkung_env.py): task env · Common environment implementation shared by walk, run, and sensor variants. · `legged_lab/envs/tienkung/tienkung_env.py`
- [Walk cfg](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/walk_cfg.py): task config · Walking task configuration. · `legged_lab/envs/tienkung/walk_cfg.py`
- [Run cfg](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/run_cfg.py): task config · Running task configuration. · `legged_lab/envs/tienkung/run_cfg.py`
- [Walk sensor](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/walk_with_sensor_cfg.py): task config · Walking task with camera/lidar sensor extensions. · `legged_lab/envs/tienkung/walk_with_sensor_cfg.py`
- [Run sensor](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/envs/tienkung/run_with_sensor_cfg.py): task config · Running task with sensor extensions. · `legged_lab/envs/tienkung/run_with_sensor_cfg.py`
- [Task registry](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/utils/task_registry.py): CLI routing · Maps task names to the correct environment and configuration pair. · `legged_lab/utils/task_registry.py`
- [Rewards](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/mdp/rewards.py): MDP shaping · Locomotion, tracking, stability, periodic gait, and AMP-related reward terms. · `legged_lab/mdp/rewards.py`
- [Motion data](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/envs/tienkung/datasets): AMP datasets · Visualization and expert motion files used by playback and AMP training. · `legged_lab/envs/tienkung/datasets`
- [Sensors](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/sensors): camera/lidar · Optional perceptual extensions for sensor-augmented control paths. · `legged_lab/sensors`
- [Terrains](https://github.com/open-x-humanoid/tienkung-lab/tree/main/legged_lab/terrains): terrain sensing · Terrain generation and ray-caster geometry queries for environment interaction. · `legged_lab/terrains`
- [Train](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/train.py): entrypoint · Training entrypoint for AMP+RL policy learning. · `legged_lab/scripts/train.py`
- [Play](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/play.py): entrypoint · Runs a trained policy in IsaacLab for rollout and inspection. · `legged_lab/scripts/play.py`
- [AMP replay](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/play_amp_animation.py): entrypoint · Motion playback and sensor-augmented visualization path for debugging datasets and policies. · `legged_lab/scripts/play_amp_animation.py`
- [Sim2sim](https://github.com/open-x-humanoid/tienkung-lab/blob/main/legged_lab/scripts/sim2sim.py): MuJoCo eval · Evaluates exported policies in MuJoCo as a separate runtime boundary. · `legged_lab/scripts/sim2sim.py`

### rsl_rl

Bundled reinforcement-learning library used for PPO/AMP training and rollout management.

- [Algorithms](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/algorithms): PPO/AMP · Core PPO, AMP-PPO, and distillation implementations. · `rsl_rl/rsl_rl/algorithms`
- [Runner](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/runners): on-policy runner · Training loop orchestration for on-policy and AMP training. · `rsl_rl/rsl_rl/runners`
- [Storage](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/storage): rollout buffer · Rollout storage and replay buffers used by the training loop. · `rsl_rl/rsl_rl/storage`
- [Models](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/modules): policy modules · Actor-critic, discriminator, normalizer, RND, and student-teacher modules. · `rsl_rl/rsl_rl/modules`
- [RL utils](https://github.com/open-x-humanoid/tienkung-lab/tree/main/rsl_rl/rsl_rl/utils): motion/logging utils · Motion loaders, logging integrations, and helper utilities for training and evaluation. · `rsl_rl/rsl_rl/utils`

## Connections

- Task registry → Walk cfg: selects · Routes walk task name to its configuration.
- Task registry → Run cfg: selects · Routes run task name to its configuration.
- Task registry → Walk sensor: selects · Routes sensor walk task name to its configuration.
- Task registry → Run sensor: selects · Routes sensor run task name to its configuration.
- Walk cfg → TienKung env: configures · Task configuration feeds the shared environment implementation.
- Run cfg → TienKung env: configures · Task configuration feeds the shared environment implementation.
- Walk sensor → TienKung env: configures · Sensor task configuration feeds the shared environment implementation.
- Run sensor → TienKung env: configures · Sensor task configuration feeds the shared environment implementation.
- TienKung env → Base env: extends · Task environment builds on reusable base environment behavior.
- TienKung env → Rewards: uses · Environment computes locomotion and AMP-style reward shaping.
- TienKung env → Motion data: loads · Environment consumes motion visualization and expert AMP data.
- TienKung env → Sensors: optionally uses · Sensor-augmented variants attach perceptual inputs.
- TienKung env → Terrains: samples · Terrain and ray-caster logic provides environment geometry queries.
- TienKung env → Robot assets: instantiates · Environment uses the robot asset package.
- Robot assets → USD model: includes · Robot package contains the IsaacLab USD asset.
- Train → Task registry: resolves · Training entrypoint resolves the configured task.
- Train → Runner: starts · Training delegates loop execution to the RL runner.
- Runner → Algorithms: drives · Runner executes PPO/AMP optimization.
- Runner → Storage: stores · Runner records rollouts and replay data.
- Algorithms → Models: uses · Algorithms depend on policy, discriminator, and auxiliary modules.
- Runner → RL utils: logs · Runner uses motion loaders and experiment logging utilities.
- Play → Task registry: loads · Play entrypoint resolves the policy task.
- Play → TienKung env: runs · Runs trained policy inside the IsaacLab environment.
- AMP replay → Motion data: replays · Visualization entrypoint inspects motion datasets.
- AMP replay → Sensors: visualizes · Also supports sensor-augmented playback.
- Sim2sim → Robot assets: evaluates · MuJoCo sim-to-sim path uses exported robot assets and policy artifacts.
- Sim2sim → RL utils: loads · Uses RL utilities and exported-policy handling for evaluation.
