Skip to content

Release dev → main: README polish + project author metadata (#170) #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KraHsu merged 3 commits into from
May 27, 2026
Merged

Release dev → main: README polish + project author metadata (#170) #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1b8207a
docs(readme): polish layout — centered header, badges, highlights, qu…
KraHsu May 27, 2026
4ed567a
docs(readme): polish Chinese README to match; add project authors/mai…
KraHsu May 27, 2026
456f4b8
Merge pull request #170 from KraHsu/docs/readme-polish
KraHsu May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 101 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,139 +1,167 @@
# GeneLab
<div align="center">

[中文](docs/README_CN.md)|EN
# 🧬 GeneLab

GeneLab is an Isaac Lab-inspired API for RL and robotics research powered by
[Genesis](https://github.com/Genesis-Embodied-AI/Genesis). It keeps the familiar shape of registered
robots, environments, tasks, manager-based MDP configuration, and CLI dispatch, while using Genesis
as the simulation backend.
**An Isaac Lab–style API for RL & robotics research — powered by [Genesis](https://github.com/Genesis-Embodied-AI/Genesis).**

- [Documentation](https://krahsu.github.io/GeneLab/) — full guides, CLI reference, concepts,
and auto-generated API docs. Bilingual (English default, 中文 at `/zh/`).
- [Examples](examples/README.md) — bundled tasks, demo scripts, config overrides, and downstream
project integration.
Familiar registries, manager-based MDP configs, and a Typer CLI, with Genesis as a
lightweight simulation backend — no USD/Kit, no vendor lock-in.

## Goals
[![CI](https://github.com/KraHsu/GeneLab/actions/workflows/ci.yml/badge.svg)](https://github.com/KraHsu/GeneLab/actions/workflows/ci.yml)
[![Docs](https://github.com/KraHsu/GeneLab/actions/workflows/docs.yml/badge.svg)](https://krahsu.github.io/GeneLab/)
![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)
![Genesis](https://img.shields.io/badge/sim-Genesis-FF6F00)
![uv](https://img.shields.io/badge/deps-uv-DE5FE9)

- Small registries for robots, environments, and tasks.
- Core API layers separated from example assets and demo scripts.
- Manager-style config hooks for actions, observations, rewards, events, and terminations.
- Explicit, easy-to-extend Genesis backend integration.
- A stable package layout and CLI for downstream robotics projects.
[**中文**](docs/README_CN.md) · [**Documentation**](https://krahsu.github.io/GeneLab/) · [**Examples**](examples/README.md)

## Requirements
</div>

- Python 3.12 or newer.
- [uv](https://docs.astral.sh/uv/) for dependency management.
---

## Setup
## ✨ Highlights

From the repository root:
- **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

```bash
uv sync
uv run genelab --help
uv sync --extra torch-cu128 # pick the torch extra for your CUDA (see below)
uv run genelab cache # create local sim / plot cache dirs
uv run genelab list tasks # see what's registered
uv run genelab train GeneLab-Inverted-Pendulum-v0 --max_iterations 150
uv run genelab play GeneLab-Inverted-Pendulum-v0 --vis
```

`uv sync` creates the project virtual environment, installs GeneLab from this checkout, and installs
the dependencies pinned by `uv.lock`. `uv run ...` runs commands inside that environment. A bare
`genelab` command works only after `.venv` is activated or GeneLab is installed into the active
Python environment.
> `uv sync` builds the project venv and installs GeneLab + the deps pinned by `uv.lock`.
> `uv run …` runs inside that venv; a bare `genelab` command works only after activating `.venv`.

## 📦 Installation

Pick exactly one `torch-*` extra — they are **mutually exclusive**:
Requirements: **Python ≥ 3.12** and [**uv**](https://docs.astral.sh/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. |
|---|---|
| `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 |

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

> **PyTorch version requirement.** Genesis requires `torch>=2.8.0` — older builds emit a
> `'torch<2.8.0' is not supported` warning at import time and may break Genesis runtime
> assumptions. All `torch-*` extras pin `torch>=2.8.0`, so `uv sync` will pull a compatible
> wheel automatically. PyTorch only publishes 2.8+ wheels on the `cpu`, `cu126`, `cu128`, and
> `cu130` indices; older CUDA flavours (`cu118` / `cu121` / `cu124`) are intentionally not
> offered as extras. An older `torch` already in the environment can be refreshed with
> **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`.

Create project-local cache folders used by Genesis/Quadrants and Matplotlib:

```bash
uv run genelab cache
```

## CLI
## 🖥️ CLI

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

## Core API
## 🧩 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`,
and `genelab.rl` — extension namespaces for robotics research code.
- `genelab.asset_zoo` — bundled example robots (`g1`, `go1`, `anymal-c`, `franka`, `cartpole`).
Not part of the core facade: fetch via the `ROBOTS` registry (`ROBOTS.get("g1")()`) or import
the config directly (`from genelab.asset_zoo import UnitreeG1Cfg`).
`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. The minimal template lives at
[`examples/external_project/`](examples/external_project/README.md); a fresh scaffold is
generated with:
tasks through GeneLab's registry and extension hooks. Scaffold a fresh one:

```bash
uv run genelab project new my_robot_project
```

## Verification
The minimal template lives at [`examples/external_project/`](examples/external_project/README.md).

## ✅ Verification

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

After syncing one of the `torch-*` extras, verify the selected PyTorch build:
After syncing a `torch-*` extra, verify the selected PyTorch build:

```bash
uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
```

## Troubleshooting
## 🛠️ Troubleshooting

### Hopper GPUs (H100 / H200, SM 90)
<details>
<summary><b>GPU sits idle / training is unexpectedly slow</b></summary>

Genesis ships precompiled Quadrants kernel fatbins that do not include SM 90 for
the `graph_do_while` graph dispatch path. Launching any task on an H100 or H200
aborts during scene build with:
<br>

`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`](docs/best-practices/reference-runs.en.md) for details.

</details>

<details>
<summary><b>Hopper GPUs (H100 / H200, SM 90)</b></summary>

<br>

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 the graph dispatch with `QD_GRAPH=0`:
Disable graph dispatch:

```bash
QD_GRAPH=0 uv run genelab train ...
export QD_GRAPH=0 # for the session
QD_GRAPH=0 uv run genelab train … # or for a single command
```

Or export it for the session:
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.

```bash
export QD_GRAPH=0
```
</details>

---

<div align="center">
<sub><a href="https://krahsu.github.io/GeneLab/">Documentation</a> · <a href="examples/README.md">Examples</a> · built on <a href="https://github.com/Genesis-Embodied-AI/Genesis">Genesis</a></sub>
</div>
Loading