🧬 GeneLab

An Isaac Lab–style API for RL & robotics research — powered by Genesis.

Familiar registries, manager-based MDP configs, and a Typer CLI, with Genesis as a lightweight simulation backend — no USD/Kit, no vendor lock-in.

中文 · Documentation · Examples

---

✨ Highlights

• Isaac Lab–shaped API — registered robots / environments / tasks, with manager-based actions, observations, rewards, events, and terminations.
• Genesis backend — fast and lightweight; no USD/Kit, no NVIDIA lock-in.
• Three RL backends — rsl_rl, skrl, and stable_baselines3, dispatched by agent-config type.
• Batteries-included CLI — train / play / eval / export / benchmark, with multi-seed and multi-GPU support.
• Asset zoo — Franka, Unitree G1 / Go1 / H1, ANYmal-C, UR10e, cartpole … fetched on demand.
• Extensible — downstream projects register their own robots, envs, and tasks through a clean extension API.

🚀 Quickstart

uv sync --extra torch-cu128          # pick the torch extra for your CUDA (see below)
source .venv/bin/activate            # Windows: .venv\Scripts\activate
genelab cache                        # create local sim / plot cache dirs
genelab list tasks                   # see what's registered
genelab train GeneLab-Inverted-Pendulum-v0 --max_iterations 150
genelab play  GeneLab-Inverted-Pendulum-v0 --vis

uv sync builds the project venv and installs GeneLab + the deps pinned by uv.lock. The docs use a bare genelab (and bare python), not uv run genelab. uv run re-syncs the environment before every command, and because the torch-* extras are mutually exclusive and outside the default sync set, each uv run uninstalls and reinstalls torch and rewrites the extra you picked. Activate .venv once (as above), or — if you'd rather not activate — prefix one-off commands with uv run --no-sync to skip that re-sync.

📦 Installation

Requirements: Python ≥ 3.12 and uv.

Pick exactly one torch-* extra — they are mutually exclusive:

Extra	Hardware target
torch-cpu	CPU-only or non-NVIDIA development machines
torch-cu126	NVIDIA, CUDA 12.6 driver
torch-cu128	NVIDIA, CUDA 12.8 driver
torch-cu130	NVIDIA, CUDA 13.0 driver

uv sync --extra torch-cpu        # one of the above

PyTorch ≥ 2.8 required. Genesis emits a 'torch<2.8.0' is not supported warning on older builds and may break at runtime. All torch-* extras pin torch>=2.8.0, so uv sync pulls a compatible wheel automatically. PyTorch publishes 2.8+ wheels only on the cpu / cu126 / cu128 / cu130 indices (older cu118 / cu121 / cu124 are intentionally not offered). Refresh an older torch already in the env with uv sync --reinstall-package torch --extra torch-cuXXX.

🖥️ CLI

genelab --help
genelab list robots          # registered robots
genelab list envs            # registered environments
genelab list tasks           # registered tasks
genelab info  <task>         # task detail + overridable cfg paths
genelab train <task> …       # train (backend chosen by the task's agent cfg)
genelab play  <task> …       # rollout: --agent zero | random | trained
genelab eval  <task> <ckpt>  # deterministic eval → eval.json
genelab export <task> <ckpt> # export policy → TorchScript / ONNX

🧩 Core API

• genelab.registry — registries, registration helpers, and extension loading.
• genelab.configs — reusable dataclass configs, including ManagerBasedEnvCfg and TaskCfg.
• genelab.lab — public API facade for registry and manager-based environment primitives.
• genelab.envs, genelab.robots, genelab.tasks — thin core namespaces for registry helpers.
• genelab.actuator, genelab.entity, genelab.scene, genelab.sensor, genelab.terrains, genelab.rl — extension namespaces for robotics research code.
• genelab.asset_zoo — bundled example robots (g1, go1, anymal-c, franka, cartpole, …). Fetch via the ROBOTS registry (ROBOTS.get("g1")()) or import directly (from genelab.asset_zoo import UnitreeG1Cfg).

Downstream projects live in their own Python packages and register robots, environments, and tasks through GeneLab's registry and extension hooks. Scaffold a fresh one:

genelab project new my_robot_project

The minimal template lives at examples/external_project/.

✅ Verification

python -c "import genelab, genesis; print(genelab.__version__, genesis.__version__)"
python -c "from genelab.lab import ManagerBasedEnvCfg; print(ManagerBasedEnvCfg.__name__)"
pytest
ruff check && ruff format --check
pyright

After syncing a torch-* extra, verify the selected PyTorch build:

python -c "import torch; print(torch.__version__, torch.version.cuda)"

🛠️ Troubleshooting

GPU sits idle / training is unexpectedly slow

SimulationCfg.gpu defaults to False (CPU backend). With the CPU backend the physics steps on the CPU while the policy/tensors sit on the GPU — the GPU stays near-idle and training can be ~50–100× slower (contact-heavy tasks like Unitree G1 are hit hardest). Set gpu=True in your task's SimulationCfg. If nvidia-smi shows your training GPU near 0 % during steps, this is almost always why. See docs/best-practices/reference-runs for details.

Hopper GPUs (H100 / H200, SM 90)

Genesis ships precompiled Quadrants kernel fatbins that omit SM 90 for the graph_do_while dispatch path, so any task aborts during scene build with:

RuntimeError: Failed to load graph_do_while condition kernel fatbin (CUDA error 200).
This SM (90) may not be included in the fatbin

Disable graph dispatch:

export QD_GRAPH=0                     # for the session
QD_GRAPH=0 genelab train …     # or for a single command

Note: QD_GRAPH=0 disables CUDA-graph batching and noticeably slows contact-heavy sims — prefer a non-Hopper GPU (Ada / Ampere) for heavy locomotion training.

Viewer won't render on Wayland (--vis): makeCurrent() failed / eglError: 3000

On a Wayland session the Genesis viewer's Qt QOpenGLWidget can fail to activate its EGL context against the compositor, so --vis opens a window that never draws and floods the terminal with:

QWaylandGLContext::makeCurrent: eglError: 3000
QOpenGLWidget: Failed to make context current
qt.qpa.backingstore: composeAndFlush: makeCurrent() failed

(eglError: 3000 is actually EGL_SUCCESS — EGL reports no error code, the context activation just fails; this is the well-known Qt-OpenGL-on-Wayland context-sharing issue.) Force Qt onto XWayland (the X11 backend), which has stable GLX/EGL behavior:

export QT_QPA_PLATFORM=xcb                          # for the session
QT_QPA_PLATFORM=xcb genelab play <task> --vis       # or for a single command

If it still fails, also disable Qt auto-scaling (QT_AUTO_SCREEN_SCALE_FACTOR=0), or on a hybrid-GPU laptop pin the discrete GPU (__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia). The unrelated QFont::fromString and dubious mass lines in the same output are harmless and can be ignored.

📚 Citation

If you use GeneLab in your research, please cite it. GitHub renders a Cite this repository button from CITATION.cff; or use the BibTeX below:

@software{zhang_genelab,
  author  = {Zhang, Chenhao},
  title   = {{GeneLab: An Isaac Lab--style API for RL \& robotics research on Genesis}},
  url     = {https://github.com/KraHsu/GeneLab},
  version = {0.3.0},
  license = {Apache-2.0}
}

---

_{Documentation · Examples · built on Genesis}