# suz-tsinghua/smp architecture

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

- Interactive diagram: https://gitdiagram.com/suz-tsinghua/smp
- Repository: https://github.com/suz-tsinghua/smp

## Overview

SMP ports motion-prior learning and physics-based G1 control to mjlab. Its main workflow converts motion clips into windows and normalization statistics, trains a DDPM denoiser, then reuses a frozen prior as a guidance reward while PPO trains one of four task policies. The graph also shows the shared RL runtime and task-specific command logic. README and sampled source support the principal links; unsampled task internals are represented only where documented or indexed.

Main entry points: [`src/smp/rl/rewards.py`](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/rewards.py) (SMP task reward), [`scripts/pretrain.py`](https://github.com/suz-tsinghua/smp/blob/master/scripts/pretrain.py) (Prior training), [`src/smp/rl/env_cfg.py`](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/env_cfg.py) (Shared environment), [`src/smp/rl/tasks/steering/steering_env_cfg.py`](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/steering_env_cfg.py) (Steering task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Motion data"]
  node_csv["Motion CSVs<br/>[g1_walk.csv]"]
  node_convert["Window conversion<br/>[csv_to_npz.py]"]
  node_windows["Motion windows"]
  node_stats["Normalization stats"]
end

subgraph group_prior["Diffusion prior"]
  node_dataset["Training dataset<br/>[dataset.py]"]
  node_denoiser["Diffusion denoiser<br/>[model.py]"]
  node_scheduler["DDPM scheduler<br/>[scheduler.py]"]
  node_pretrain["Prior training<br/>[pretrain.py]"]
  node_checkpoints["Prior checkpoints<br/>[pretrained_loco.pt]"]
end

subgraph group_runtime["RL runtime"]
  node_train["Policy training<br/>[train.py]"]
  node_sharedcfg["Shared environment<br/>[env_cfg.py]"]
  node_events["Prior initialization<br/>[events.py]"]
  node_features["Feature reconstruction"]
  node_reward["SMP task reward<br/>[rewards.py]"]
  node_rlutils["RL feature buffer<br/>[utils.py]"]
  node_play["Policy playback<br/>[play.py]"]
end

subgraph group_tasks["G1 tasks"]
  node_forward["Forward task<br/>[forward_env_cfg.py]"]
  node_steering["Steering task"]
  node_steercommand["Steering commands<br/>[commands.py]"]
  node_location["Location task"]
  node_loccommand["Location commands<br/>[commands.py]"]
  node_getup["Get-up task<br/>[getup_env_cfg.py]"]
  node_getupterm["Get-up termination<br/>[terminations.py]"]
end

node_user(("Researcher"))

node_user -->|"prepares data"| node_convert
node_csv -->|"converts clips"| node_convert
node_convert -->|"writes windows"| node_windows
node_windows -->|"computes ranges"| node_stats
node_user -->|"trains prior"| node_pretrain
node_windows -.->|"loads windows"| node_dataset
node_pretrain -->|"uses dataset"| node_dataset
node_pretrain -->|"trains model"| node_denoiser
node_pretrain -->|"uses diffusion"| node_scheduler
node_pretrain -->|"uses statistics"| node_stats
node_pretrain -->|"saves prior"| node_checkpoints
node_user -->|"trains policy"| node_train
node_train -->|"runs task config"| node_sharedcfg
node_sharedcfg -->|"registers events"| node_events
node_events -->|"loads prior"| node_checkpoints
node_events -->|"reconstructs state"| node_features
node_reward -->|"updates buffer"| node_rlutils
node_reward -->|"scores features"| node_denoiser
node_reward -->|"adds noise"| node_scheduler
node_user -->|"plays policy"| node_play
node_forward -->|"extends config"| node_sharedcfg
node_steering -->|"extends config"| node_sharedcfg
node_steering -->|"configures command"| node_steercommand
node_location -->|"extends config"| node_sharedcfg
node_location -->|"configures command"| node_loccommand
node_getup -->|"extends config"| node_sharedcfg
node_getup -->|"configures termination"| node_getupterm
node_forward -.->|"uses SMP reward"| node_reward
node_steering -->|"uses SMP reward"| node_reward
node_location -->|"uses SMP reward"| node_reward
node_getup -->|"uses SMP reward"| node_reward

click node_csv "https://github.com/suz-tsinghua/smp/blob/master/datasets/csv/forward/g1_walk.csv"
click node_convert "https://github.com/suz-tsinghua/smp/blob/master/scripts/csv_to_npz.py"
click node_stats "https://github.com/suz-tsinghua/smp/blob/master/scripts/compute_norm_stats.py"
click node_dataset "https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/dataset.py"
click node_denoiser "https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/model.py"
click node_scheduler "https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/scheduler.py"
click node_pretrain "https://github.com/suz-tsinghua/smp/blob/master/scripts/pretrain.py"
click node_checkpoints "https://github.com/suz-tsinghua/smp/blob/master/datasets/pretrain_ckpt/pretrained_loco.pt"
click node_train "https://github.com/suz-tsinghua/smp/blob/master/scripts/train.py"
click node_sharedcfg "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/env_cfg.py"
click node_events "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/events.py"
click node_features "https://github.com/suz-tsinghua/smp/blob/master/src/smp/sampling/feature_to_state.py"
click node_reward "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/rewards.py"
click node_rlutils "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/utils.py"
click node_play "https://github.com/suz-tsinghua/smp/blob/master/scripts/play.py"
click node_forward "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/forward_env_cfg.py"
click node_steering "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/steering_env_cfg.py"
click node_steercommand "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/mdp/commands.py"
click node_location "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/location/location_env_cfg.py"
click node_loccommand "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/location/mdp/commands.py"
click node_getup "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/getup/getup_env_cfg.py"
click node_getupterm "https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/getup/mdp/terminations.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_csv,node_convert,node_windows,node_stats toneBlue
class node_dataset,node_denoiser,node_scheduler,node_pretrain,node_checkpoints toneAmber
class node_train,node_sharedcfg,node_events,node_features,node_reward,node_rlutils,node_play toneMint
class node_forward,node_steering,node_steercommand,node_location,node_loccommand,node_getup,node_getupterm toneRose
class node_user toneIndigo
```

## Components

### Motion data

- [Motion CSVs](https://github.com/suz-tsinghua/smp/blob/master/datasets/csv/forward/g1_walk.csv): `datasets/csv/forward/g1_walk.csv`
- [Window conversion](https://github.com/suz-tsinghua/smp/blob/master/scripts/csv_to_npz.py): `scripts/csv_to_npz.py`
- **Motion windows**
- [Normalization stats](https://github.com/suz-tsinghua/smp/blob/master/scripts/compute_norm_stats.py): `scripts/compute_norm_stats.py`

### Diffusion prior

- [Training dataset](https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/dataset.py): `src/smp/pretrain/dataset.py`
- [Diffusion denoiser](https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/model.py): `src/smp/pretrain/model.py`
- [DDPM scheduler](https://github.com/suz-tsinghua/smp/blob/master/src/smp/pretrain/scheduler.py): `src/smp/pretrain/scheduler.py`
- [Prior training](https://github.com/suz-tsinghua/smp/blob/master/scripts/pretrain.py): `scripts/pretrain.py`
- [Prior checkpoints](https://github.com/suz-tsinghua/smp/blob/master/datasets/pretrain_ckpt/pretrained_loco.pt): `datasets/pretrain_ckpt/pretrained_loco.pt`

### RL runtime

- [Policy training](https://github.com/suz-tsinghua/smp/blob/master/scripts/train.py): `scripts/train.py`
- [Shared environment](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/env_cfg.py): `src/smp/rl/env_cfg.py`
- [Prior initialization](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/events.py): `src/smp/rl/events.py`
- [Feature reconstruction](https://github.com/suz-tsinghua/smp/blob/master/src/smp/sampling/feature_to_state.py): `src/smp/sampling/feature_to_state.py`
- [SMP task reward](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/rewards.py): `src/smp/rl/rewards.py`
- [RL feature buffer](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/utils.py): `src/smp/rl/utils.py`
- [Policy playback](https://github.com/suz-tsinghua/smp/blob/master/scripts/play.py): `scripts/play.py`

### G1 tasks

- [Forward task](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/forward_env_cfg.py): `src/smp/rl/tasks/steering/forward_env_cfg.py`
- [Steering task](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/steering_env_cfg.py): `src/smp/rl/tasks/steering/steering_env_cfg.py`
- [Steering commands](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/steering/mdp/commands.py): `src/smp/rl/tasks/steering/mdp/commands.py`
- [Location task](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/location/location_env_cfg.py): `src/smp/rl/tasks/location/location_env_cfg.py`
- [Location commands](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/location/mdp/commands.py): `src/smp/rl/tasks/location/mdp/commands.py`
- [Get-up task](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/getup/getup_env_cfg.py): `src/smp/rl/tasks/getup/getup_env_cfg.py`
- [Get-up termination](https://github.com/suz-tsinghua/smp/blob/master/src/smp/rl/tasks/getup/mdp/terminations.py): `src/smp/rl/tasks/getup/mdp/terminations.py`

### Other components

- **Researcher**

## Connections

- Researcher → Window conversion: prepares data (evidence: `README.md`)
- Motion CSVs → Window conversion: converts clips (evidence: `README.md`)
- Window conversion → Motion windows: writes windows (evidence: `README.md`)
- Motion windows → Normalization stats: computes ranges (evidence: `README.md`)
- Researcher → Prior training: trains prior (evidence: `README.md`)
- Motion windows → Training dataset: loads windows
- Prior training → Training dataset: uses dataset (evidence: `scripts/pretrain.py`)
- Prior training → Diffusion denoiser: trains model (evidence: `scripts/pretrain.py`)
- Prior training → DDPM scheduler: uses diffusion (evidence: `scripts/pretrain.py`)
- Prior training → Normalization stats: uses statistics
- Prior training → Prior checkpoints: saves prior (evidence: `README.md`)
- Researcher → Policy training: trains policy (evidence: `README.md`)
- Policy training → Shared environment: runs task config (evidence: `README.md`)
- Shared environment → Prior initialization: registers events (evidence: `src/smp/rl/env_cfg.py`)
- Prior initialization → Prior checkpoints: loads prior
- Prior initialization → Feature reconstruction: reconstructs state (evidence: `src/smp/rl/events.py`)
- SMP task reward → RL feature buffer: updates buffer (evidence: `src/smp/rl/rewards.py`)
- SMP task reward → Diffusion denoiser: scores features (evidence: `src/smp/rl/rewards.py`)
- SMP task reward → DDPM scheduler: adds noise (evidence: `src/smp/rl/rewards.py`)
- Researcher → Policy playback: plays policy (evidence: `README.md`)
- Forward task → Shared environment: extends config (evidence: `src/smp/rl/tasks/steering/forward_env_cfg.py`)
- Steering task → Shared environment: extends config (evidence: `src/smp/rl/tasks/steering/steering_env_cfg.py`)
- Steering task → Steering commands: configures command (evidence: `src/smp/rl/tasks/steering/steering_env_cfg.py`)
- Location task → Shared environment: extends config (evidence: `src/smp/rl/tasks/location/location_env_cfg.py`)
- Location task → Location commands: configures command (evidence: `src/smp/rl/tasks/location/location_env_cfg.py`)
- Get-up task → Shared environment: extends config (evidence: `src/smp/rl/tasks/getup/getup_env_cfg.py`)
- Get-up task → Get-up termination: configures termination (evidence: `src/smp/rl/tasks/getup/getup_env_cfg.py`)
- Forward task → SMP task reward: uses SMP reward (evidence: `src/smp/rl/tasks/steering/forward_env_cfg.py`)
- Steering task → SMP task reward: uses SMP reward (evidence: `src/smp/rl/tasks/steering/steering_env_cfg.py`)
- Location task → SMP task reward: uses SMP reward (evidence: `src/smp/rl/tasks/location/location_env_cfg.py`)
- Get-up task → SMP task reward: uses SMP reward (evidence: `src/smp/rl/tasks/getup/getup_env_cfg.py`)
