UniLab Documentation¶
UniLab
Configure task semantics once. Run robot RL across physics backends.
Python >=3.10,<3.14 Hydra + Manager API Cross-backend contract uv workflow
UniLab turns task semantics into reusable configuration: assemble manager terms, select a physics backend, and run the same train/eval workflow on the hardware available to you. Use this landing page to install, run a first demo, follow it with a smoke job, choose an algorithm or backend, or jump into deployment and extension docs. For project fit and alternatives, read Why UniLab?.
Why UniLab¶
Compose actions, observations, rewards, terminations, events, commands, and curricula from manager terms in Hydra owner YAML. Common task variants need no new environment class.
Move between current and future physics adapters with CLI flags such as
--task go2_joystick_flat --sim motrix; the CLI composes the matching owner
YAML under src/unilab/conf/.
The task contract connects CPU-parallel and external-worker simulation to accelerator learners, so the experiment can grow with the hardware available to you.
Quick Install And Smoke Run¶
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/unilabsim/UniLab.git
cd UniLab
uv sync --extra motrix
uv run demo dance
uv run train --algo ppo --task go2_joystick_flat --sim motrix \
algo.max_iterations=1 algo.num_envs=16 training.no_play=true
For the full README-style walkthrough, see Quick Demo. For platform-specific setup, see Installation.
Start where you are¶
Set up uv, sync dependencies, and pick the platform profile that matches your
machine.
Run a pre-trained demo first, then move to PPO training, evaluation, playback, or checkpoint resume.
Select a backend through task owner YAMLs and read its installation and capability requirements.
Compare PPO, APPO, SAC, TD3, and FlashSAC entrypoints.
Follow sim-to-real checklists or use the sim-to-sim docs to swap MuJoCo and Motrix.
Read the env, backend, runner, registry, and task-owner contracts before adding tasks, backends, algorithms, or terrain.
Architecture Snapshot¶
flowchart LR
cli["uv run train/eval<br/>--algo --task --sim"] --> owner["Task owner YAML<br/>src/unilab/conf/*/task/..."]
cli --> script["Thin script routing<br/>src/unilab/scripts/train_*.py"]
owner --> registry["Registry bootstrap<br/>src/unilab/base/registry.py"]
registry --> env["NpEnv contract<br/>obs dict + info dict"]
env --> backend["SimBackend<br/>unisim-core adapters"]
env --> factory["EnvFactory contract"]
factory --> runtime["Runner / IPC<br/>unilab-rl async runtime"]
runtime --> learner["Learner<br/>PPO / APPO / SAC / TD3"]
The load-bearing contracts are documented in Developer Guide; backend support evidence is summarized in Simulation Backends.
Hardware And Algorithm Coverage¶
This snapshot only lists coverage backed by checked-in scripts, owner YAMLs, and the generated support-matrix evidence grades. The repository currently has no committed benchmark manifest or separate recommendation metadata.
Robot / task family |
Algorithm paths with repo evidence |
Backend evidence |
|---|---|---|
Go1 joystick |
PPO, APPO, TD3 |
PPO has tested MuJoCo and Motrix rows. APPO has tested MuJoCo rows and Motrix registered rows. TD3 has a Motrix owner YAML for |
Go2 joystick |
PPO, FlashSAC, TD3 |
PPO has tested MuJoCo and Motrix rows. FlashSAC has MuJoCo owner YAMLs for |
Go2W joystick |
PPO |
PPO owner YAMLs exist for MuJoCo and Motrix flat/rough variants under |
G1 locomotion / tracking |
PPO, APPO, SAC, TD3 |
PPO, APPO, and SAC include committed MuJoCo and Motrix owner YAMLs for G1 tasks; TD3 has a |
Allegro in-hand |
PPO, APPO |
PPO and APPO have committed MuJoCo and Motrix owner YAMLs for Allegro in-hand tasks. |