UniLab

A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms

Languages: English | 简体中文

Train robot RL without a GPU simulation backend. Teaser rendered with MotrixSim.

Start with the Quick Demo below to run the primary training command from this repository. The recommended setup path uses uv; platform-specific notes are in the installation guide. Conda and pip users should still follow the repository uv workflow for now; see the installation guide for the current boundaries.

✨ Highlights

┌───────────────────┐                            ┌─────────────────────────┐
│  CPU Physics Sim  │   Unified Shared Memory    │   GPU Policy Training   │
│   MuJoCo/Motrix   │ ─────────────────────────▶ │     PPO / SAC / TD3     │
│ Multithread Step  │    SharedReplayBuffer      │ CUDA / MPS / ROCm / XPU │
└───────────────────┘                            └─────────────────────────┘

• Heterogeneous RL runtime: CPU-parallel simulation streams transitions through shared memory while policy learning runs on GPU accelerators.
• Two physics backends: MuJoCoUni and MotrixSim are integrated through backend-specific adapters and task owner configs.
• Unified training CLI: uv run train and uv run eval cover PPO, MLX PPO, APPO, SAC, TD3, and FlashSAC; additional HORA and HIM-PPO paths are documented as script-level workflows.
• Config-owned tasks: Hydra owner YAML files select task, reward, backend, and algorithm settings together; backend switching is expressed as task=<task>/<backend>.
• Cross-platform setup paths: The repository tracks Linux CUDA, Linux ROCm, Linux XPU, and Apple Silicon / macOS setup flows.

🚀 Quick Demo

# 0. If uv is not installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# 1. Clone the repository
git clone https://github.com/unilabsim/UniLab.git
cd UniLab

# 2. Install dependencies
# Pick the setup command for your platform.

# Linux CUDA or macOS
make setup-motrix
# Without shell completion setup: uv sync --extra motrix
# If `make` is not installed: uv sync --extra motrix && uv run --no-sync unilab-complete install

# Linux AMD / ROCm
# make sync-rocm

# Linux Intel Arc / iGPU
# make sync-xpu

# 3. Pre-trained checkpoint playback (downloads from Hugging Face on first run)
uv run demo dance

Available demo names: teaser, dance, wallflip, boxtracking, locomani, inhandgrasp. See the Unified CLI page for the full list and flags.

Mainland China users: motions, scenes, and demo checkpoints are pulled from Hugging Face on first run. If huggingface.co is unreachable, point the client at the community mirror before running demo commands:

export HF_ENDPOINT=https://hf-mirror.com

For training and evaluation:

uv run train --algo appo --task go2_joystick_flat --sim motrix

uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1

# Headless Motrix video export for Linux/server runs
uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1 --render-mode record

This routes through the go2_joystick_flat/motrix task owner config and keeps backend selection explicit.

On macOS / MacBook, the UniLab CLI routes Motrix interactive playback through mxpython when needed. Motrix defaults to interactive playback; use --render-mode record for headless video export or --render-mode none to skip playback. Detailed script-level commands are in the Training Guide.

The Go2Arm manipulation-locomotion PPO task also supports Motrix after installing the motrix extra:

uv run train --algo ppo --task go2_arm_manip_loco --sim motrix
uv run eval --algo ppo --task go2_arm_manip_loco --sim motrix --load-run -1

Interactive Notebooks

Prefer a guided, step-by-step experience? Open the notebooks in Jupyter:

• Demo Notebook: local checkpoint playback via uv run demo
• PPO Training Walkthrough: end-to-end guide from config preview to training and playback

Notebooks are designed for local environments with MuJoCo access.

🏃 Example Runs

uv run train --algo sac --task g1_walk_flat --sim mujoco

uv run train --algo sac --task g1_motion_tracking --sim motrix

bash scripts/sharpa_collect_grasps.sh 0.8 0.9 1.0 1.1 1.2 1.3 1.4 1.5
uv run train --algo appo --task sharpa_inhand --sim mujoco --profile hora

uv run train --algo ppo --task go2_arm_manip_loco --sim motrix
uv run eval --algo ppo --task go2_arm_manip_loco --sim motrix --load-run -1

uv run train --algo ppo --task sharpa_inhand --sim mujoco --profile hora

More training commands, script-level entrypoints, resume flow, and W&B details are in the Training Guide.

🎯 Training Entrypoints

Use uv run train for training, uv run eval for checkpoint playback, and uv run demo for the local demo preset. These commands keep algorithm, task, and backend selection explicit.

See Training Guide for the algorithm matrix, log directory layout, Hydra overrides, script-level entrypoints, and demo flags.

📚 Documentation

Use the published UniLab documentation; start at the English documentation index. High-signal entrypoints:

• Getting Started: installation, Docker runtime, dependency setup, and first-run commands
• Training Guide: training, playback, resume flow, Hydra overrides, and W&B
• Simulation Backends: generated MuJoCo / Motrix support matrix
• Development Standard: contracts, layering, and validation boundaries
• ADR Index: accepted architecture decisions

💬 Community

WeChat Group	WeChat Assistant
Scan to join the UniLab WeChat group.	If the group is full, add the assistant and include unilab交流 in your message.

🧾 Citation

UniLab

@article{jia2026unilab,
  title         = {UniLab: A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms},
  author        = {Yufei Jia and Zhanxiang Cao and Mingrui Yu and Heng Zhang and Shenyu Chen and Dixuan Jiang and Meng Li and Xiaofan Li and Yiyang Liu and Junzhe Wu and Zheng Li and XiLin Fang and Tingyu Cui and Shengcheng Fu and Haoyang Li and Anqi Wang and Zifan Wang and Dongjie Zhu and Chenyu Cao and Zhenbiao Huang and Ziang Zheng and Jie Lu and Xin Ma and Zhengyang Wei and Xiang Zhao and Tianyue Zhan and Ye He and Yuxiang Chen and Yizhou Jiang and Yue Li and Haizhou Ge and Yuhang Dong and Fan Jia and Ziheng Zhang and Meng Zhang and Xiwa Deng and Zhixing Chen and Hanyang Shao and Chenxin Dong and Yixuan Li and Yizhi Chen and Bokui Chen and Kaifeng Zhang and Hanqing Cui and Yusen Qin and Ruqi Huang and Lei Han and Tiancai Wang and Xiang Li and Yue Gao and Guyue Zhou},
  journal       = {arXiv preprint arXiv:2605.30313},
  year          = {2026},
  url           = {https://arxiv.org/abs/2605.30313}
}

Physics Backends

@article{jia2026mujocouni,
  title  = {MuJoCoUni: Persistent Batched Runtime Primitives for MuJoCo},
  author = {Jia, Yufei and Wu, Junzhe},
  journal = {arXiv preprint arXiv:2605.24922},
  year   = {2026}
}

@software{motrixsim2026,
  title  = {MotrixSim: A Physics Simulation Engine for Robotics and Embodied AI},
  author = {{Motphys Team}},
  year   = {2026},
  url    = {https://motrixsim.readthedocs.io/},
  note   = {Python binary package}
}