Language

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?.

Quick Demo

User guide

Why UniLab¶

Configure tasks without boilerplate

Compose actions, observations, rewards, terminations, events, commands, and curricula from manager terms in Hydra owner YAML. Common task variants need no new environment class.

Backend choice stays in config

Move between current and future physics adapters with CLI flags such as --task go2_joystick_flat --sim mujoco; the CLI composes the matching owner YAML under src/unilab/conf/.

Scale across hardware

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 mujoco
uv run demo dance
uv run train --algo ppo --task go2_joystick_flat --sim mujoco \
  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¶

Install the repo

Set up uv, sync dependencies, and pick the platform profile that matches your machine.

Installation

Run or replay training

Run a pre-trained demo first, then move to PPO training, evaluation, playback, or checkpoint resume.

Quick Demo

Choose a physics backend

Select a backend through task owner YAMLs and read its installation and capability requirements.

Simulation Backends

Pick an algorithm

Compare PPO, APPO, SAC, and FlashSAC entrypoints.

Algorithms

Deploy or switch sims

Follow sim-to-real checklists or use the sim-to-sim docs to swap MuJoCo and Motrix.

Sim-to-Real Overview

Extend safely

Read the env, backend, runner, registry, and task-owner contracts before adding tasks, backends, algorithms, or terrain.

Developer Guide

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["TorchEnv contract<br/>tensor 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"]

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
Go2 joystick	PPO, FlashSAC	PPO has tested MuJoCo and Motrix rows. FlashSAC has MuJoCo owner YAMLs for `go2_joystick_flat`.
G1 reference locomotion / tracking	PPO, APPO, SAC	PPO, APPO, and SAC include committed MuJoCo and Motrix owner YAMLs for retained G1 tasks.

Unitree production task families are maintained in unitree_rl_unilab and are not counted as core repository evidence.