Simulation Backends

UniLab exposes backend names through registry/config paths, including mujoco, motrix, mjwarp, drake, isaacgym, genesis, isaacsim, newton, and superdex where an owner is registered. User commands select them with --sim, which routes to the matching task owner YAML; do not switch a run by overriding training.sim_backend alone.

Runtime Prerequisites

  • Install Motrix support with uv sync --extra motrix.

  • IsaacGym and IsaacSim use dedicated external worker runtimes; see their backend pages for installation and runtime requirements.

  • Any run using --sim mujoco, MuJoCo playback, or MuJoCo-only debugging tool still requires a working MuJoCo runtime.

  • Drake uses the external drake-uni package plus a locally built C++ batch extension; see Drake Backend before selecting --sim drake.

  • Newton uses the newton extra (uv sync --extra newton), which shares the MuJoCo 3.11 / MuJoCo-Warp 3.11 / Warp 1.16 line with the mujoco / mjwarp extras and can be combined with them in one environment; see Newton Backend before selecting --sim newton.

  • On macOS, the package CLI routes Motrix interactive playback through mxpython when needed. Direct script calls that open the native Motrix renderer should use uv run mxpython.

OS and GPU Support

Backend

Operating system

GPU

MuJoCo

Linux / macOS / Windows

Not required: CPU physics; offline playback can render on CPU

Motrix

Linux / Windows / Apple Silicon macOS

Not required: CPU physics (Rust runtime)

MJWarp

Linux (validated path)

Required: NVIDIA CUDA with an explicit CUDA process device

Genesis

Linux x86_64

Required: NVIDIA GPU and driver; only the gs.gpu channel is validated

Newton

Linux

Required: NVIDIA GPU and CUDA driver; CPU devices are not a validated channel

IsaacGym

Linux x86_64

Required: NVIDIA GPU and driver; physics runs in a separate Python 3.8 worker

IsaacSim

Linux x86_64

Required: NVIDIA CUDA; native rendering depends on the RTX driver stack; separate Python 3.11 worker

Drake

Linux x86_64 / Apple Silicon macOS (arm64)

Not required: CPU batch physics; Intel macOS has no official Drake binary

Backend device requirements are independent of the learner device: CPU-physics backends (MuJoCo / Motrix / Drake) can still train with the learner on CUDA, ROCm, MPS, or XPU; see the platform profiles in Installation.

Select A Backend

UniLab selects the simulator through the task owner config. For normal usage, choose the task and backend with --task and --sim; off-policy commands keep the algorithm in --algo, not in --task. Do not switch a run by overriding training.sim_backend alone; that field is set by the owner YAML and identifies the composed backend.

Quick Choice

Need

Prefer

Default path or broadest owner coverage

MuJoCo

Native interactive playback through the backend

Motrix

MuJoCo-only tools such as scripts/play_viser.py

MuJoCo

Task owner exists only under src/unilab/conf/.../<task>/mujoco.yaml

MuJoCo

Task owner exists under src/unilab/conf/.../<task>/motrix.yaml and the support matrix marks the combination as tested or configured

Motrix

The support matrix is generated from registry, owner YAML, and tests; use it as the current evidence source: Support Matrix.

uv run train --algo ppo --task go1_joystick_flat --sim mujoco
uv run train --algo ppo --task go1_joystick_flat --sim motrix
uv run train --algo ppo --task g1_walk_flat --sim isaacsim

More combinations:

uv run train --algo ppo --task stewart_balance --sim drake \
  algo.max_iterations=1 algo.num_envs=8 training.no_play=true
uv run train --algo sac --task g1_walk_flat --sim mujoco

Owner YAML locations:

  • PPO / APPO: src/unilab/conf/{ppo,appo}/task/<task>/<backend>.yaml

  • Off-policy (SAC / TD3 / FlashSAC): src/unilab/conf/<algo>/task/<task>/<backend>.yaml

The selected owner YAML sets training.sim_backend as an identity field.

Playback Differences

  • --render-mode auto exports play_video.mp4 on MuJoCo paths.

  • --render-mode auto opens Motrix native interactive rendering on Motrix paths.

  • --render-mode record records without opening an interactive window.

  • --render-mode none disables playback.

uv run eval --algo ppo --task go1_joystick_flat --sim mujoco --load-run -1
uv run eval --algo ppo --task go1_joystick_flat --sim motrix --load-run -1 \
  --render-mode record

Support Evidence

Task/backend/entrypoint support is evidence-graded. See Support Matrix for the support matrix entry and links to the generated source data.

The unisim-core boundary

UniLab’s physics backends are provided by the independent unisim-core distribution, with unisim as the Python namespace. For example:

uv sync --extra mujoco
uv run python -c "import unisim; print(unisim.ADAPTER_SPECS)"

unisim has no dependency on UniLab, Hydra, or training components. MuJoCo, Motrix, Drake, MJWarp, Genesis, IsaacGym, IsaacSim, and Newton use one public contract. Missing proprietary SDKs or GPU workers produce an explicit cold-path diagnostic; no backend silently falls back to another engine.

Backend physics is owned exclusively by unisim-core. UniLab keeps only the owner-layer assembly entry point unilab.base.backend_factory; contracts and adapters are imported from unisim. The former unilab.base.backend implementation and compatibility layer have been removed; do not add backend APIs to UniLab.

Benchmark v1 reserves only BenchmarkCase, BenchmarkResult, and provenance schema. Workloads, timing, comparisons, and performance claims require a separately authorized issue.