# taehoon-kai/supermimic_vibed architecture

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

- Interactive diagram: https://gitdiagram.com/taehoon-kai/supermimic_vibed
- Repository: https://github.com/taehoon-kai/supermimic_vibed

## Overview

SuperMimic is a humanoid motion-tracking system trained with a learned differentiable world model. Its main workflow loads retargeted G1 reference motions, trains a policy through batched simulation and model-based updates, evaluates saved checkpoints across the clips, then plots scores or renders recorded trajectories. The graph also includes the documented robot-asset conversion path. Relationships are based on the shown excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`supermimic/train.py`](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/train.py) (Training Orchestrator), [`supermimic/env.py`](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/env.py) (Tracking Environment), [`supermimic/motion.py`](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/motion.py) (Motion Library), [`supermimic/evaluate.py`](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/evaluate.py) (Checkpoint Evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_motion["Motion and Robot Assets"]
  node_urdf_convert["URDF Conversion<br/>[urdf_to_mjcf.py]"]
  node_mjcf_convert["USD Conversion<br/>[mjcf_to_usd.py]"]
  node_robot["G1 Articulation<br/>[robot.py]"]
  node_kinematics["Differentiable FK<br/>[kinematics.py]"]
  node_motionlib["Motion Library<br/>[motion.py]"]
end

subgraph group_simulation["Tracking Simulation"]
  node_rotations["Rotation Math<br/>[rotations.py]"]
  node_mdp["Tracking MDP<br/>[mdp.py]"]
  node_environment["Tracking Environment<br/>[env.py]"]
  node_reset_sampling["Reset Sampling<br/>[reset_sampling.py]"]
end

subgraph group_learning["Model-Based Training"]
  node_trainer["Training Orchestrator<br/>[train.py]"]
  node_buffer[("Replay Buffer<br/>[buffer.py]")]
  node_networks["World Model and Policy<br/>[networks.py]"]
end

subgraph group_results["Evaluation and Results"]
  node_evaluator["Checkpoint Evaluation<br/>[evaluate.py]"]
  node_plotter["Score Plotting<br/>[plot.py]"]
  node_renderer["Trajectory Rendering<br/>[render.py]"]
end

node_user(("Experimenter"))
node_clips["Retargeted Motions"]
node_urdf["G1 URDF"]
node_simulator["Isaac Lab / Newton"]
node_eval_results["Evaluation Logs"]
node_trajectory["Recorded Trajectory"]

node_user -->|"starts training"| node_trainer
node_clips -->|"loads clips"| node_motionlib
node_urdf -->|"compiles"| node_urdf_convert
node_urdf_convert -->|"converts model"| node_mjcf_convert
node_mjcf_convert -->|"produces USD asset"| node_robot
node_robot -->|"provides model"| node_kinematics
node_motionlib -->|"computes reference FK"| node_kinematics
node_motionlib -->|"uses rotation math"| node_rotations
node_kinematics -->|"uses rotation math"| node_rotations
node_mdp -->|"uses FK"| node_kinematics
node_mdp -->|"reads reference states"| node_motionlib
node_mdp -->|"uses rotation math"| node_rotations
node_environment -->|"steps physics"| node_simulator
node_environment -->|"configures articulation"| node_robot
node_environment -->|"labels transitions"| node_mdp
node_environment -->|"resets from motions"| node_motionlib
node_environment -->|"updates reset scores"| node_reset_sampling
node_trainer -->|"initializes FK"| node_kinematics
node_trainer -->|"loads library"| node_motionlib
node_trainer -->|"builds MDP"| node_mdp
node_trainer -->|"collects rollouts"| node_environment
node_trainer -->|"stores transitions"| node_buffer
node_trainer -->|"fits and updates"| node_networks
node_evaluator -->|"runs evaluation"| node_environment
node_evaluator -->|"evaluates all clips"| node_motionlib
node_evaluator -->|"loads policy"| node_networks
node_evaluator -->|"writes scores"| node_eval_results
node_evaluator -->|"records rollout"| node_trajectory
node_eval_results -->|"plots scores"| node_plotter
node_trajectory -->|"renders video"| node_renderer
node_user -->|"evaluates checkpoint"| node_evaluator
node_user -->|"requests plot"| node_plotter
node_user -->|"requests render"| node_renderer

click node_urdf_convert "https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/urdf_to_mjcf.py"
click node_mjcf_convert "https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/mjcf_to_usd.py"
click node_robot "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/robot.py"
click node_kinematics "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/kinematics.py"
click node_motionlib "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/motion.py"
click node_rotations "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/rotations.py"
click node_mdp "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/mdp.py"
click node_environment "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/env.py"
click node_reset_sampling "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/reset_sampling.py"
click node_trainer "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/train.py"
click node_buffer "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/buffer.py"
click node_networks "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/networks.py"
click node_evaluator "https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/evaluate.py"
click node_plotter "https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/plot.py"
click node_renderer "https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/render.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_urdf_convert,node_mjcf_convert,node_robot,node_kinematics,node_motionlib toneBlue
class node_rotations,node_mdp,node_environment,node_reset_sampling toneAmber
class node_trainer,node_buffer,node_networks toneMint
class node_evaluator,node_plotter,node_renderer toneRose
class node_user,node_clips,node_urdf,node_simulator,node_eval_results,node_trajectory toneIndigo
```

## Components

### Motion and Robot Assets

- [URDF Conversion](https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/urdf_to_mjcf.py): `tools/urdf_to_mjcf.py`
- [USD Conversion](https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/mjcf_to_usd.py): `tools/mjcf_to_usd.py`
- [G1 Articulation](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/robot.py): `supermimic/robot.py`
- [Differentiable FK](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/kinematics.py): `supermimic/kinematics.py`
- [Motion Library](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/motion.py): `supermimic/motion.py`

### Tracking Simulation

- [Rotation Math](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/rotations.py): `supermimic/rotations.py`
- [Tracking MDP](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/mdp.py): `supermimic/mdp.py`
- [Tracking Environment](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/env.py): `supermimic/env.py`
- [Reset Sampling](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/reset_sampling.py): `supermimic/reset_sampling.py`

### Model-Based Training

- [Training Orchestrator](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/train.py): `supermimic/train.py`
- [Replay Buffer](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/buffer.py): `supermimic/buffer.py`
- [World Model and Policy](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/networks.py): `supermimic/networks.py`

### Evaluation and Results

- [Checkpoint Evaluation](https://github.com/taehoon-kai/supermimic_vibed/blob/main/supermimic/evaluate.py): `supermimic/evaluate.py`
- [Score Plotting](https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/plot.py): `tools/plot.py`
- [Trajectory Rendering](https://github.com/taehoon-kai/supermimic_vibed/blob/main/tools/render.py): `tools/render.py`

### Other components

- **Experimenter**
- **Retargeted Motions**
- **G1 URDF**
- **Isaac Lab / Newton**
- **Evaluation Logs**
- **Recorded Trajectory**

## Connections

- Experimenter → Training Orchestrator: starts training (evidence: `README.md`)
- Retargeted Motions → Motion Library: loads clips (evidence: `README.md`)
- G1 URDF → URDF Conversion: compiles (evidence: `README.md`)
- URDF Conversion → USD Conversion: converts model (evidence: `README.md`)
- USD Conversion → G1 Articulation: produces USD asset (evidence: `README.md`)
- G1 Articulation → Differentiable FK: provides model (evidence: `supermimic/kinematics.py`)
- Motion Library → Differentiable FK: computes reference FK (evidence: `supermimic/motion.py`)
- Motion Library → Rotation Math: uses rotation math (evidence: `supermimic/motion.py`)
- Differentiable FK → Rotation Math: uses rotation math (evidence: `supermimic/kinematics.py`)
- Tracking MDP → Differentiable FK: uses FK (evidence: `supermimic/mdp.py`)
- Tracking MDP → Motion Library: reads reference states (evidence: `supermimic/mdp.py`)
- Tracking MDP → Rotation Math: uses rotation math (evidence: `supermimic/mdp.py`)
- Tracking Environment → Isaac Lab / Newton: steps physics (evidence: `README.md`)
- Tracking Environment → G1 Articulation: configures articulation (evidence: `supermimic/env.py`)
- Tracking Environment → Tracking MDP: labels transitions (evidence: `supermimic/env.py`)
- Tracking Environment → Motion Library: resets from motions (evidence: `supermimic/env.py`)
- Tracking Environment → Reset Sampling: updates reset scores (evidence: `supermimic/env.py`)
- Training Orchestrator → Differentiable FK: initializes FK (evidence: `supermimic/train.py`)
- Training Orchestrator → Motion Library: loads library (evidence: `supermimic/train.py`)
- Training Orchestrator → Tracking MDP: builds MDP (evidence: `supermimic/train.py`)
- Training Orchestrator → Tracking Environment: collects rollouts (evidence: `supermimic/train.py`)
- Training Orchestrator → Replay Buffer: stores transitions (evidence: `supermimic/train.py`)
- Training Orchestrator → World Model and Policy: fits and updates (evidence: `supermimic/train.py`)
- Checkpoint Evaluation → Tracking Environment: runs evaluation (evidence: `supermimic/evaluate.py`)
- Checkpoint Evaluation → Motion Library: evaluates all clips (evidence: `supermimic/evaluate.py`)
- Checkpoint Evaluation → World Model and Policy: loads policy (evidence: `supermimic/evaluate.py`)
- Checkpoint Evaluation → Evaluation Logs: writes scores (evidence: `README.md`)
- Checkpoint Evaluation → Recorded Trajectory: records rollout (evidence: `supermimic/evaluate.py`)
- Evaluation Logs → Score Plotting: plots scores (evidence: `README.md`)
- Recorded Trajectory → Trajectory Rendering: renders video (evidence: `README.md`)
- Experimenter → Checkpoint Evaluation: evaluates checkpoint (evidence: `README.md`)
- Experimenter → Score Plotting: requests plot (evidence: `README.md`)
- Experimenter → Trajectory Rendering: requests render (evidence: `README.md`)