Skip to content

docs: rework README with quickstart, architecture diagram and task showcase #23

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
mxj711 merged 1 commit into from
Sep 8, 2026
Merged

docs: rework README with quickstart, architecture diagram and task showcase #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@
*.npz filter=lfs diff=lfs merge=lfs -text
docs/source/_static/data/performance/*.json filter=lfs diff=lfs merge=lfs -text
docs/source/_static/images/performance/*.svg filter=lfs diff=lfs merge=lfs -text
*.gif filter=lfs diff=lfs merge=lfs -text
4 changes: 2 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ MotrixLab 是构建在 MotrixSim 仿真后端之上的强化学习框架，提

## Workspace 结构

项目使用 UV workspace，包含十个 package：
项目使用 UV workspace，包含九个 package：

- `motrix_env_core`：backend 无关的环境框架（不依赖任何 simulator）
- `motrix_env_motrixsim`：MotrixSim 仿真后端（SimBackend、scene compiler、renderer、torch frontend）
Expand Down Expand Up @@ -96,7 +96,7 @@ Python 方法，由 manager 运行时契约定义（`wiki/design/manager/runtime

### 版本与依赖一致性

- 所有 workspace package（见上文 Workspace 结构，共十个）的 `pyproject.toml` 中 `version` 字段必须保持一致。
- 所有 workspace package（见上文 Workspace 结构，共九个）的 `pyproject.toml` 中 `version` 字段必须保持一致。
- MotrixSim 相关依赖版本必须在使用该依赖的 workspace package 之间保持一致。
- 关键第三方依赖使用精确版本锁定（`===`）；新增或升级依赖时同步更新 `uv.lock`。

Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ uv sync --all-packages --extra skrl-jax # Linux only
uv sync --all-packages --extra rslrl
```

The workspace contains ten packages. Package-local changes should use the
The workspace contains nine packages. Package-local changes should use the
smallest required extra; changes involving the simulator, built-in assets, or
training integrations should be tested with the corresponding package and
extra enabled.
Expand Down Expand Up @@ -267,6 +267,6 @@ fork](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/crea
and [secure use of GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions).

All source files should retain the Apache-2.0 SPDX header used by this
repository. Keep the ten workspace package versions synchronized when making a
repository. Keep the nine workspace package versions synchronized when making a
release, and update `THIRD_PARTY_NOTICES.md` whenever a dependency or bundled
asset changes.
181 changes: 100 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,154 +1,173 @@
**Language**: [English](README.md) | [简体中文](README.zh-CN.md)

<div align="center">

# MotrixLab

![GitHub License](https://img.shields.io/github/license/Motphys/MotrixLab)
[![GitHub License](https://img.shields.io/github/license/Motphys/MotrixLab)](LICENSE)
![Python Version](https://img.shields.io/badge/python-3.10-blue)
[![Release](https://img.shields.io/github/v/release/Motphys/MotrixLab?include_prereleases)](https://github.com/Motphys/MotrixLab/releases)
[![Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://motrixlab.readthedocs.io)

**Train robot policies in simulation, then deploy them to real hardware.**

<img src="docs/source/_static/images/microduck-walk.gif" alt="Microduck robots walking in MotrixRender after training with MotrixLab" width="720">

_Microduck locomotion policies trained with MotrixLab, rendered in MotrixRender — [watch the HD video](https://github.com/user-attachments/assets/4bcf3122-f135-44cb-a966-d2d8e84479da)._

`MotrixLab` is a reinforcement learning framework based on the [MotrixSim](https://github.com/Motphys/motrixsim-docs) simulation engine, designed specifically for robot simulation and training. This project provides a complete reinforcement learning development platform that integrates multiple simulation environments and training frameworks.
**📖 Documentation**: [简体中文](https://motrixlab.readthedocs.io/zh-cn/stable/) | [English](https://motrixlab.readthedocs.io/en/stable/)

## Project Overview
</div>

The project is divided into ten workspace packages:
## Contents

- **motrix_deploy** (`motrix-deploy`): Framework-independent artifact, backend, policy, control-loop, registry, and CLI
- **motrix_deploy_mujoco** (`motrix-deploy-mujoco`): MuJoCo deployment backend plugin
- **motrix_deploy_unitree** (`motrix-deploy-unitree`): Unitree SDK2 DDS hardware backend plugin
- **motrix_deploy_tasks** (`motrix-deploy-tasks`): Concrete versioned deployment tasks and executable bootstrap
- **motrix_env_core** (`motrix-env-core`): Environment base classes, configuration, registry, scene construction, NumPy runtime, and rendering. It contains no built-in tasks or robot assets
- **motrix_env_motrixsim** (`motrix-env-motrixsim`): Live MotrixSim backend, renderer, and torch frontend
- **motrix_env_mujoco** (`motrix-env-mujoco`): Compile-only MuJoCo scene backend
- **motrix_envs** (`motrix-envs`): Built-in environments, models, data, and environment-to-deployment-profile compilers
- **motrix_rl** (`motrix-rl`): RL-framework integration built against `motrix-env-core`, with SKRL, RSLRL, and FastSAC support
- [What is MotrixLab?](#what-is-motrixlab)
- [Key Features](#key-features)
- [Quick Start](#-quick-start)
- [Task Environments](#-task-environments)
- [Built-in Robot Models](#-built-in-robot-models)
- [What's Inside](#-whats-inside)
- [Contributing](#-contributing)
- [Contact](#-contact)

> Documentation: https://motrixlab.readthedocs.io
## What is MotrixLab?

**MotrixLab** is an open-source reinforcement learning framework for robot training, built on the high-performance [MotrixSim](https://github.com/Motphys/motrixsim-docs) physics engine. Define an environment once, train it with thousands of parallel environment instances using SKRL, RSL-RL, or the built-in FastSAC, and deploy the resulting policy to MuJoCo or Unitree hardware — all through a single command-line interface.

<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/source/_static/images/architecture-dark.svg">
<img src="docs/source/_static/images/architecture-light.svg" alt="MotrixLab architecture: define an environment once, train it with SKRL, RSL-RL or FastSAC on thousands of parallel MotrixSim environments, then deploy the same policy artifact to MuJoCo or Unitree hardware" width="720">
</picture>
</div>

## Key Features

- **Unified Interface**: Provides a concise and unified reinforcement learning training and evaluation interface
- **Multi-framework Support**: Supports SKRL (JAX/PyTorch), RSLRL (PyTorch), and the built-in FastSAC implementation
- **Rich Environments**: Includes various robot simulation environments such as basic control, locomotion, and manipulation tasks
- **High-performance Simulation**: Built on MotrixSim's high-performance physics simulation engine
- **Sim-to-Real Deployment**: The same policy code deploys via the deploy CLI — Sim2Sim to MuJoCo, Sim2Real to real hardware
- **High-precision, High-performance Simulation**: Built on [MotrixSim](https://motrixsim.readthedocs.io/), a high-precision, high-performance physics engine
- **Visual Training**: Supports real-time rendering and training process visualization

## 🚀 Quick Start

> The following examples use the Python project management tool: [UV](https://docs.astral.sh/uv/)
>
> Before starting, please [install](https://docs.astral.sh/uv/getting-started/installation/) this tool.
### Prerequisites

| Requirement | Notes |
| --- | --- |
| Python **3.10.x** | The workspace pins `==3.10.*` |
| [uv](https://docs.astral.sh/uv/) | Python project and dependency manager — [installation guide](https://docs.astral.sh/uv/getting-started/installation/) |
| [Git LFS](https://git-lfs.com) | Robot meshes, motion data, and videos are tracked by LFS |
| OS | Linux x86_64 or Windows x86_64; the JAX training backend is Linux-only |

### Clone Repository
### 1. Clone the repository

```bash
git clone https://github.com/Motphys/MotrixLab

cd MotrixLab

git lfs pull
```

### Install Dependencies

Install all dependencies:
### 2. Install dependencies

```bash
uv sync --all-packages --all-groups --all-extras
uv sync --all-packages
```

For an external project that only needs the environment framework, install `motrix-env-core`. Install
`motrix-envs` when the built-in MotrixLab tasks and assets are also required.

SKRL framework supports JAX(Flax) or PyTorch as training backends. You can also choose to install only one training backend based on your hardware environment:
This installs all workspace packages together with **PyTorch**, the default training backend used by the built-in FastSAC. Third-party frameworks such as SKRL and RSLRL are optional extras.

Install JAX as training backend (Linux only):
### 3. Train your first policy

```bash
uv sync --all-packages --extra skrl-jax
uv run scripts/train.py task=microduck-walk-flat/motrix.fastsac play=true
```

Install PyTorch as training backend:
While training, the built-in dashboard shows live run progress, episode statistics, throughput, rewards, and system health:

```bash
uv sync --all-packages --extra skrl-torch
```
<p align="center">
<img src="docs/source/_static/images/train-console.png" alt="MotrixLab training dashboard for the microduck-walk-flat fastsac task" width="720">
</p>

Install RSLRL framework (PyTorch backend only):
Training runs thousands of parallel environment instances; when it finishes, the trained policy is loaded and played in the viewer automatically. Checkpoints and TensorBoard logs are saved under `runs/microduck-walk-flat/`; watch the curves with:

```bash
uv sync --all-packages --extra rslrl
uv run tensorboard --logdir runs/microduck-walk-flat
```

### Development Checks
Training finishes in minutes: mean return and episode length typically converge after about 4,000 iterations:

[`dprint-py`](https://pypi.org/project/dprint-py/) is included in the development dependencies. Install
[`prek`](https://github.com/j178/prek), enable the Git pre-commit hook, and run all configured checks:
<p align="center">
<img src="docs/source/_static/images/microduck-training-curves.png" alt="TensorBoard curves of a microduck-walk-flat training run: mean return and episode length converge after about 4,000 iterations" width="720">
</p>

```bash
uv tool install prek==0.5.2
prek install
prek run --all-files
```
### 4. Replay the trained policy

Run dprint directly through uv when needed:
Replay the latest trained policy without retraining (for example, after stopping training early with Ctrl+C):

```bash
uv run dprint fmt
uv run scripts/play.py env=microduck-walk-flat
```

## 🎯 Usage Guide
A trained microduck policy replayed in the viewer:

### Environment Visualization
https://github.com/user-attachments/assets/4bcf3122-f135-44cb-a966-d2d8e84479da

View environments without executing training:
## 🌍 Task Environments

```bash
uv run scripts/view.py env=cartpole
```
MotrixLab ships 50+ built-in simulation environments spanning basic control, quadruped and humanoid locomotion, whole-body motion tracking, and manipulation. The main categories:

View a built-in robot in a static standard scene:
| Preview | Category | Example environments |
| --- | --- | --- |
| <img src="docs/source/_static/images/poster/go2-walk-rough.jpg" alt="go2-walk-rough" width="240"> | Quadruped velocity tracking | `go2-walk-flat` · `go2-walk-rough` · `go1-walk-rough` · `anymalc-walk-flat` |
| <img src="docs/source/_static/images/poster/g1-walk-flat.jpg" alt="g1-walk-flat" width="240"> | Humanoid velocity tracking | `g1-walk-flat` · `k1-walk-rough` · `dex-evt-walk-flat` · `microduck-walk-flat` |
| <img src="docs/source/_static/images/poster/g1-wbt-dance.jpg" alt="g1-wbt-dance" width="240"> | Whole-body tracking (WBT) | `g1-wbt-dance` · `k1-wbt-freekick` · `g1-29dof-wbt-largebox` |

```bash
uv run scripts/view.py robot=g1-29dof
uv run scripts/view.py env=go2-walk-rough
```

Available built-in robot names are `dex-evt`, `g1-29dof`, `go1`, `go2`, and `k1`.

### Model Training

Train the default Cartpole SKRL task:

```bash
uv run scripts/train.py task=cartpole/skrl.ppo
```
See the [full environment gallery](https://motrixlab.readthedocs.io/en/latest/user_guide/envs/index.html) for all registered environments and their supported training algorithms.

Train with RSLRL framework:
## 🤖 Built-in Robot Models

```bash
uv run scripts/train.py task=cartpole/rslrl.ppo
```
Seven reusable robot models are registered out of the box and can be combined into any scene or task:

Override runtime settings and algorithm parameters directly through Hydra:
| Screenshot | Registry name | Type | DoF |
| --- | --- | --- | --- |
| <img src="docs/source/_static/images/robots/anymal_c.png" alt="anymal_c" width="180"> | `anymal_c` | Quadruped | 12 |
| <img src="docs/source/_static/images/robots/dex-evt.png" alt="dex-evt" width="180"> | `dex-evt` | Humanoid | 23 |
| <img src="docs/source/_static/images/robots/g1-29dof.png" alt="g1-29dof" width="180"> | `g1-29dof` | Humanoid | 29 |
| <img src="docs/source/_static/images/robots/go1.png" alt="go1" width="180"> | `go1` | Quadruped | 12 |
| <img src="docs/source/_static/images/robots/go2.png" alt="go2" width="180"> | `go2` | Quadruped | 12 |
| <img src="docs/source/_static/images/robots/k1.png" alt="k1" width="180"> | `k1` | Humanoid | 22 |
| <img src="docs/source/_static/images/robots/microduck.png" alt="microduck" width="180"> | `microduck` | Humanoid | 14 |

```bash
uv run scripts/train.py task=cartpole/skrl.ppo num_envs=64 algo.agent.learning_rate=1e-3
uv run scripts/train.py task=cartpole/skrl.ppo logging.interval=20 checkpoint.interval=100
uv run scripts/view.py robot=go2
```

Training results are saved in the `runs/{env-name}/` directory.
See [Supported Robots](https://motrixlab.readthedocs.io/en/latest/user_guide/robots.html) for configuration details and how to add your own model.

View training data through TensorBoard:
## 🏗️ What's Inside

```bash
uv run tensorboard --logdir runs/{env-name}
```
MotrixLab is a [uv](https://docs.astral.sh/uv/) workspace of nine packages:

### Model Inference
| Package | PyPI name | Description |
| --- | --- | --- |
| **motrix_deploy** | `motrix-deploy` | Framework-independent artifact, backend, policy, control-loop, registry, and CLI |
| **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo deployment backend plugin |
| **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS hardware backend plugin |
| **motrix_deploy_tasks** | `motrix-deploy-tasks` | Concrete versioned deployment tasks and executable bootstrap |
| **motrix_env_core** | `motrix-env-core` | Environment base classes, configuration, registry, scene construction, NumPy runtime, and rendering. It contains no built-in tasks or robot assets |
| **motrix_env_motrixsim** | `motrix-env-motrixsim` | Live MotrixSim backend, renderer, and torch frontend |
| **motrix_env_mujoco** | `motrix-env-mujoco` | Compile-only MuJoCo scene backend |
| **motrix_envs** | `motrix-envs` | Built-in environments, models, data, and environment-to-deployment-profile compilers |
| **motrix_rl** | `motrix-rl` | RL-framework integration built against `motrix-env-core`, with SKRL, RSLRL, and FastSAC support |

```bash
uv run scripts/play.py env=cartpole
```
## 🤝 Contributing

For more usage methods, please refer to the [User Documentation](https://motrixlab.readthedocs.io)
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development environment setup, branch and commit conventions, and the configured checks (`prek`, `ruff`, `dprint`, `mypy`).

## 📬 Contact

Expand Down
Loading
Loading