# luwudynamics/xgoduck_rl architecture

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

- Interactive diagram: https://gitdiagram.com/luwudynamics/xgoduck_rl
- Repository: https://github.com/luwudynamics/xgoduck_rl

## Overview

XgoDuck RL provides mjlab task configurations and robot models for training and using PPO policies. The main workflow is to select a registered task, train it against the configured robot and environment, then play from a checkpoint or export the policy to ONNX. Task coverage also includes terrain variants and specialized behaviors such as stand-up, ground-pick, sit-stand, ball-kick, and roulade. The README establishes the product workflow; sampled source supports selected MDP, actuator, and robot details, but not every task’s internal wiring.

Main entry points: [`src/mjlab_microduck/tasks`](https://github.com/luwudynamics/xgoduck_rl/tree/main/src/mjlab_microduck/tasks) (Behavior tasks), [`src/mjlab_microduck/train_cli.py`](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/train_cli.py) (Training CLI), [`src/mjlab_microduck/robot/xgoduck_constants.py`](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/robot/xgoduck_constants.py) (XgoDuck config), [`scripts/export.py`](https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/export.py) (ONNX export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tasks["Tasks and MDP"]
  node_task_registry["Task registration<br/>[__init__.py]"]
  node_task_configs["Behavior tasks"]
  node_mdp["MDP functions<br/>[mdp.py]"]
  node_terrain["Terrain generation<br/>[slope_terrain.py]"]
  node_symmetry["Policy symmetry<br/>[symmetry.py]"]
  node_testbench["Testbench tasks"]
end

subgraph group_robot["Robot and actuation"]
  node_robot_cfg["XgoDuck config"]
  node_robot_model["XgoDuck model"]
  node_actuator["BAM actuation<br/>[friction_dr_bam.py]"]
  node_backlash["Backlash modeling<br/>[backlash.py]"]
end

subgraph group_policy["Policy workflow"]
  node_train_cli["Training CLI<br/>[train_cli.py]"]
  node_train_hook["Training hook<br/>[train_hook.py]"]
  node_checkpoint["Model checkpoint"]
  node_play_hook["Checkpoint selection<br/>[play_hook.py]"]
  node_play["Policy playback<br/>[play_latest.py]"]
  node_export["ONNX export<br/>[export.py]"]
end

subgraph group_integrations["Integrations and validation"]
  node_hf_jobs["HF job submission<br/>[hf_jobs.py]"]
  node_sim2real["Sim-to-real checks"]
end

node_user(("Engineer"))
node_ppo["mjlab PPO"]
node_onnx["ONNX policy"]

node_user -->|"selects task"| node_train_cli
node_train_cli -->|"loads tasks"| node_task_registry
node_task_registry -->|"registers"| node_task_configs
node_task_configs -->|"configures terms"| node_mdp
node_task_configs -->|"configures terrain"| node_terrain
node_task_configs -->|"uses symmetry"| node_symmetry
node_task_configs -->|"selects robot"| node_robot_cfg
node_robot_cfg -->|"loads model"| node_robot_model
node_robot_cfg -->|"configures actuator"| node_actuator
node_task_configs -->|"configures backlash"| node_backlash
node_train_cli -->|"dispatches"| node_train_hook
node_train_hook -->|"starts training"| node_ppo
node_ppo -->|"writes checkpoint"| node_checkpoint
node_user -->|"requests playback"| node_play
node_play_hook -->|"selects latest"| node_checkpoint
node_play -->|"loads checkpoint"| node_checkpoint
node_user -->|"requests export"| node_export
node_export -->|"loads checkpoint"| node_checkpoint
node_export -->|"writes policy"| node_onnx
node_train_cli -.->|"submits remotely"| node_hf_jobs
node_user -->|"runs checks"| node_sim2real
node_sim2real -->|"uses task"| node_testbench

click node_task_registry "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/__init__.py"
click node_task_configs "https://github.com/luwudynamics/xgoduck_rl/tree/main/src/mjlab_microduck/tasks"
click node_mdp "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/mdp.py"
click node_terrain "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/slope_terrain.py"
click node_symmetry "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/symmetry.py"
click node_robot_cfg "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/robot/xgoduck_constants.py"
click node_robot_model "https://github.com/luwudynamics/xgoduck_rl/tree/main/src/mjlab_microduck/robot/xgoduck"
click node_actuator "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/actuator/friction_dr_bam.py"
click node_backlash "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/backlash.py"
click node_train_cli "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/train_cli.py"
click node_train_hook "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/train_hook.py"
click node_play_hook "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/play_hook.py"
click node_play "https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/play_latest.py"
click node_export "https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/export.py"
click node_hf_jobs "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/hf_jobs.py"
click node_sim2real "https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/testbench_sim2real.py"
click node_testbench "https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/testbench_env_cfg.py"

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_registry,node_task_configs,node_mdp,node_terrain,node_symmetry,node_testbench toneBlue
class node_robot_cfg,node_robot_model,node_actuator,node_backlash toneAmber
class node_train_cli,node_train_hook,node_checkpoint,node_play_hook,node_play,node_export toneMint
class node_hf_jobs,node_sim2real toneRose
class node_user,node_ppo,node_onnx toneIndigo
```

## Components

### Tasks and MDP

- [Task registration](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/__init__.py): `src/mjlab_microduck/tasks/__init__.py`
- [Behavior tasks](https://github.com/luwudynamics/xgoduck_rl/tree/main/src/mjlab_microduck/tasks): `src/mjlab_microduck/tasks`
- [MDP functions](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/mdp.py): `src/mjlab_microduck/tasks/mdp.py`
- [Terrain generation](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/slope_terrain.py): `src/mjlab_microduck/tasks/slope_terrain.py`
- [Policy symmetry](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/symmetry.py): `src/mjlab_microduck/tasks/symmetry.py`
- [Testbench tasks](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/testbench_env_cfg.py): `src/mjlab_microduck/tasks/testbench_env_cfg.py`

### Robot and actuation

- [XgoDuck config](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/robot/xgoduck_constants.py): `src/mjlab_microduck/robot/xgoduck_constants.py`
- [XgoDuck model](https://github.com/luwudynamics/xgoduck_rl/tree/main/src/mjlab_microduck/robot/xgoduck): `src/mjlab_microduck/robot/xgoduck`
- [BAM actuation](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/actuator/friction_dr_bam.py): `src/mjlab_microduck/actuator/friction_dr_bam.py`
- [Backlash modeling](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/tasks/backlash.py): `src/mjlab_microduck/tasks/backlash.py`

### Policy workflow

- [Training CLI](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/train_cli.py): `src/mjlab_microduck/train_cli.py`
- [Training hook](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/train_hook.py): `src/mjlab_microduck/train_hook.py`
- **Model checkpoint**
- [Checkpoint selection](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/play_hook.py): `src/mjlab_microduck/play_hook.py`
- [Policy playback](https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/play_latest.py): `scripts/play_latest.py`
- [ONNX export](https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/export.py): `scripts/export.py`

### Integrations and validation

- [HF job submission](https://github.com/luwudynamics/xgoduck_rl/blob/main/src/mjlab_microduck/hf_jobs.py): `src/mjlab_microduck/hf_jobs.py`
- [Sim-to-real checks](https://github.com/luwudynamics/xgoduck_rl/blob/main/scripts/testbench_sim2real.py): `scripts/testbench_sim2real.py`

### Other components

- **Engineer**
- **mjlab PPO**
- **ONNX policy**

## Connections

- Engineer → Training CLI: selects task
- Training CLI → Task registration: loads tasks
- Task registration → Behavior tasks: registers
- Behavior tasks → MDP functions: configures terms
- Behavior tasks → Terrain generation: configures terrain
- Behavior tasks → Policy symmetry: uses symmetry
- Behavior tasks → XgoDuck config: selects robot
- XgoDuck config → XgoDuck model: loads model
- XgoDuck config → BAM actuation: configures actuator
- Behavior tasks → Backlash modeling: configures backlash
- Training CLI → Training hook: dispatches
- Training hook → mjlab PPO: starts training
- mjlab PPO → Model checkpoint: writes checkpoint
- Engineer → Policy playback: requests playback
- Checkpoint selection → Model checkpoint: selects latest
- Policy playback → Model checkpoint: loads checkpoint
- Engineer → ONNX export: requests export
- ONNX export → Model checkpoint: loads checkpoint
- ONNX export → ONNX policy: writes policy
- Training CLI → HF job submission: submits remotely
- Engineer → Sim-to-real checks: runs checks
- Sim-to-real checks → Testbench tasks: uses task