Motphys/UniLab

UniLab – Contract‑driven infrastructure for robot learning

What it is

An open‑source Python framework that lets you describe robot reinforcement‑learning tasks once (using Hydra YAML configs) and then run them on any supported physics simulator or hardware backend without changing your code.
Provides a SimBackend contract so the same task definition can be executed on MuJoCo, Isaac Gym, Motrix, Newton, Genesis, etc., and on CPUs, GPUs, AMD ROCm, Apple Silicon, Intel XPU, or external‑worker simulation.

Why it matters

Eliminates the need to rewrite environment classes when swapping simulators or hardware.
Keeps the learning algorithm (e.g., SAC, Flash‑SAC) independent from the simulation layer, enabling heterogeneous training pipelines.
Claims 3–10× speed‑up for off‑policy replay‑based training by overlapping data collection with learner updates.

Key Features

Feature	Description
Configuration‑first	Tasks, actions, observations, rewards, curricula, and metrics are assembled from reusable manager terms in a Hydra YAML file – often no Python code is required.
Backend‑agnostic	Any registered simulator implements the public `SimBackend` interface; switch with `--sim` flag.
Device‑agnostic learners	Learners run on CUDA, ROCm, MPS, or Intel XPU while simulation can stay on CPU or remote workers.
Replay‑accelerated off‑policy training	Built‑in SAC/Flash‑SAC pipelines overlap simulation and gradient updates, delivering large end‑to‑end speed gains.
Cross‑platform support	Documented installation paths for Windows, macOS (Apple Silicon), Linux (CUDA, ROCm, XPU).
Support matrix	A curated table shows which task‑backend‑device combos have been verified.
Ecosystem hooks	Downstream robot‑specific repos (MicroDuck RL, EngineAI RL, Unitree RL, etc.) can reuse the same task definitions and contracts.
Extensible RL stack	Algorithms, async runtime, and logging live under `src/unilab/rl/`.

Typical Use‑Cases

Research: Prototype a new locomotion or manipulation task once, then benchmark it across MuJoCo, Isaac Gym, and other simulators.
Sim‑to‑sim transfer: Train in a fast, low‑fidelity simulator and evaluate in a high‑fidelity one without rewriting code.
Heterogeneous clusters: Run many CPU‑only simulation workers that feed data to a GPU‑accelerated learner.
Robotics labs: Share a common task library across multiple robot platforms (e.g., Unitree, MicroDuck) while each team uses its preferred physics engine.

Installation (quick)

# Install the lightweight UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repo and set up the environment
git clone https://github.com/unilabsim/UniLab.git
cd UniLab
make setup   # installs dependencies via uv

The first run will automatically download model checkpoints and assets from Hugging Face.

Quick‑Start Commands

# Run a demo (dance) to verify the installation
uv run demo dance

# Train a flat‑walking task with MuJoCo using SAC
uv run train  --algo sac --task g1_walk_flat --sim mujoco

# Evaluate the trained policy and render with Viser
uv run eval   --algo sac --task g1_walk_flat --sim mujoco --render-mode viser

# Swap simulators without changing the task definition
uv run --extra motrix  eval --algo sac --task g1_walk_flat --sim motrix --render-mode interactive --load-run -1
uv run --extra isaacgym eval --algo sac --task g1_walk_flat --sim isaacgym --load-run -1

All flags (--algo, --task, --sim) are explicit, making experiments reproducible.

Documentation & Learning Resources

Why UniLab? – design rationale and comparison with alternatives: https://unilabsim.github.io/UniLab-doc/en/why_unilab.html
Installation & first demo: https://unilabsim.github.io/UniLab-doc/en/1-getting_started/0-index.html
Training & evaluation guide: https://unilabsim.github.io/UniLab-doc/en/2-user_guide/1-training/0-index.html
Backend support matrix: https://unilabsim.github.io/UniLab-doc/en/5-reference/5-support_matrix.html
Sim‑to‑sim deployment: https://unilabsim.github.io/UniLab-doc/en/3-deployment/2-sim_to_sim/1-backend_swap.html
Developer guide (contributing, extending contracts): https://unilabsim.github.io/UniLab-doc/en/4-developer_guide/0-index.html

Community

WeChat assistant (QR code in the repo) for real‑time help and announcements.
Active GitHub issues and PRs; see the contributing guide for how to add new backends or tasks.
Downstream projects listed in the README showcase real‑world usage.

License & Citation

License: Apache‑2.0 (per LICENSE).
Citation:

@article{jia2026unilab,
  title   = {UniLab: A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms},
  author  = {Jia, Yufei and Cao, Zhanxiang and Yu, Mingrui and ...},
  journal = {arXiv preprint arXiv:2605.30313},
  year    = {2026},
  url     = {https://arxiv.org/abs/2605.30313}
}

Bottom line: UniLab is a genuine, research‑grade toolkit that abstracts robot RL tasks from the underlying physics engine and compute hardware, enabling reproducible experiments and rapid backend swapping. It is well‑documented, actively maintained, and already cited in a CoRL 2026 paper.