diff --git a/.gitattributes b/.gitattributes index 7929c85..91148a6 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 1e2a289..c9973e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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） @@ -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`。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a216f3..bf24d77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. @@ -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. diff --git a/README.md b/README.md index 6d61a27..fda0ef2 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,173 @@ **Language**: [English](README.md) | [简体中文](README.zh-CN.md) +
+ # 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.** + +Microduck robots walking in MotrixRender after training with MotrixLab + +_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 +
-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. + +
+ + + 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 + +
## 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 -``` +

+ MotrixLab training dashboard for the microduck-walk-flat fastsac task +

-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: +

+ TensorBoard curves of a microduck-walk-flat training run: mean return and episode length converge after about 4,000 iterations +

-```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 | +| --- | --- | --- | +| go2-walk-rough | Quadruped velocity tracking | `go2-walk-flat` · `go2-walk-rough` · `go1-walk-rough` · `anymalc-walk-flat` | +| g1-walk-flat | Humanoid velocity tracking | `g1-walk-flat` · `k1-walk-rough` · `dex-evt-walk-flat` · `microduck-walk-flat` | +| g1-wbt-dance | 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 | +| --- | --- | --- | --- | +| anymal_c | `anymal_c` | Quadruped | 12 | +| dex-evt | `dex-evt` | Humanoid | 23 | +| g1-29dof | `g1-29dof` | Humanoid | 29 | +| go1 | `go1` | Quadruped | 12 | +| go2 | `go2` | Quadruped | 12 | +| k1 | `k1` | Humanoid | 22 | +| microduck | `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 diff --git a/README.zh-CN.md b/README.zh-CN.md index 46aac42..72db638 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,154 +1,173 @@ **语言**: [English](README.md) | [简体中文](README.zh-CN.md) +
+ # 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) + +**在仿真中训练机器人策略，并部署到真实硬件。** + +使用 MotrixLab 训练的 microduck 机器人在 MotrixRender 中行走 + +_使用 MotrixLab 训练的 microduck 行走策略，由 MotrixRender 实时渲染 — [观看高清视频](https://github.com/user-attachments/assets/4bcf3122-f135-44cb-a966-d2d8e84479da)。_ -`MotrixLab` 是一个基于 [MotrixSim](https://github.com/Motphys/motrixsim-docs) 仿真引擎的强化学习框架，专为机器人仿真和训练设计。该项目提供了一个完整的强化学习开发平台，集成了多种仿真环境和训练框架。 +**📖 用户文档**: [简体中文](https://motrixlab.readthedocs.io/zh-cn/stable/) | [English](https://motrixlab.readthedocs.io/en/stable/) -## 项目概述 +
-该项目由十个 workspace package 组成： +## 目录 -- **motrix_deploy**（`motrix-deploy`）：独立于训练框架的 artifact、backend、policy、控制循环、registry 与 CLI -- **motrix_deploy_mujoco**（`motrix-deploy-mujoco`）：MuJoCo 部署 backend plugin -- **motrix_deploy_unitree**（`motrix-deploy-unitree`）：Unitree SDK2 DDS 硬件 backend plugin -- **motrix_deploy_tasks**（`motrix-deploy-tasks`）：具体的带版本部署任务实现与可执行入口 bootstrap -- **motrix_env_core**（`motrix-env-core`）：环境基类、配置、registry、场景构建、NumPy runtime 与渲染能力，不包含任何内置任务和机器人资产 -- **motrix_env_motrixsim**（`motrix-env-motrixsim`）：MotrixSim 实时仿真 backend、renderer 与 torch frontend -- **motrix_env_mujoco**（`motrix-env-mujoco`）：仅负责编译场景的 MuJoCo backend -- **motrix_envs**（`motrix-envs`）：内置环境、模型、数据及环境到部署 profile 的编译实现 -- **motrix_rl**（`motrix-rl`）：基于 `motrix-env-core` 的 RL 框架集成，支持 SKRL、RSLRL 和 FastSAC +- [MotrixLab 是什么？](#motrixlab-是什么) +- [主要特性](#主要特性) +- [快速开始](#-快速开始) +- [任务环境](#-任务环境) +- [内置机器人模型](#-内置机器人模型) +- [项目组成](#-项目组成) +- [参与贡献](#-参与贡献) +- [联系方式](#-联系方式) -> 文档地址：https://motrixlab.readthedocs.io +## MotrixLab 是什么？ + +**MotrixLab** 是一个开源的机器人强化学习训练框架，构建于高性能的 [MotrixSim](https://github.com/Motphys/motrixsim-docs) 物理引擎之上。环境只需定义一次，即可通过 SKRL、RSLRL 或内置的 FastSAC 使用数千个并行环境实例进行训练，训练得到的策略可部署到 MuJoCo 或 Unitree 硬件 —— 全程只需一个命令行接口。 + +
+ + + MotrixLab 架构：环境只需定义一次，即可用 SKRL、RSL-RL 或 FastSAC 在数千个并行 MotrixSim 环境上训练，同一策略产物可部署到 MuJoCo 或 Unitree 硬件 + +
## 主要特性 - **统一接口**: 提供简洁统一的强化学习训练和评估接口 - **多框架支持**: 支持 SKRL（JAX/PyTorch）、RSLRL（PyTorch）和内置 FastSAC 实现 - **丰富环境**: 包含基础控制、运动、操作等多种机器人仿真环境 -- **高性能仿真**: 基于 MotrixSim 的高性能物理仿真引擎 +- **Sim-to-Real 部署**: 同一套策略代码，通过部署 CLI Sim2Sim 到 MuJoCo 仿真、Sim2Real 到真实硬件 +- **高精度高性能仿真**: 基于 [MotrixSim](https://motrixsim.readthedocs.io/) 高精度、高性能物理仿真引擎 - **可视化训练**: 支持实时渲染和训练过程可视化 ## 🚀 快速开始 -> 以下示例使用了 Python 项目管理工具：[UV](https://docs.astral.sh/uv/) -> -> 在开始之前，请先[安装](https://docs.astral.sh/uv/getting-started/installation/)该工具。 +### 前置条件 + +| 要求 | 说明 | +| --- | --- | +| Python **3.10.x** | workspace 锁定 `==3.10.*` | +| [uv](https://docs.astral.sh/uv/) | Python 项目与依赖管理工具 — [安装指南](https://docs.astral.sh/uv/getting-started/installation/) | +| [Git LFS](https://git-lfs.com) | 机器人网格、运动数据与视频由 LFS 管理 | +| 操作系统 | Linux x86_64 或 Windows x86_64；JAX 训练后端仅支持 Linux | -### 克隆仓库 +### 1. 克隆仓库 ```bash git clone https://github.com/Motphys/MotrixLab - cd MotrixLab - git lfs pull ``` -### 安装依赖 - -安装全部依赖： +### 2. 安装依赖 ```bash -uv sync --all-packages --all-groups --all-extras +uv sync --all-packages ``` -外部项目如果只需要环境 framework，可单独安装 `motrix-env-core`；需要 MotrixLab 内置任务和资产时再安装 -`motrix-envs`。 - -SKRL 框架支持 JAX(Flax)或 PyTorch 作为训练后端，您也可以根据自己的设备环境，选择只安装其中一种训练后端： +该命令会安装全部 workspace package，以及内置 FastSAC 所需的默认训练后端 **PyTorch**。SKRL、RSLRL 等第三方训练框架为可选 extras。 -安装 JAX 作为训练后端（仅支持 Linux 平台）： +### 3. 训练第一个策略 ```bash -uv sync --all-packages --extra skrl-jax +uv run scripts/train.py task=microduck-walk-flat/motrix.fastsac play=true ``` -安装 PyTorch 作为训练后端： +训练过程中，内置面板会实时显示运行进度、回合统计、吞吐、奖励与系统健康状态： -```bash -uv sync --all-packages --extra skrl-torch -``` +

+ microduck-walk-flat motrix.fastsac 任务的 MotrixLab 训练面板 +

-安装 RSLRL 框架（仅支持 PyTorch 后端）： +训练会启动数千个并行环境实例；训练结束后会自动加载策略并在查看器中回放。checkpoint 与 TensorBoard 日志保存在 `runs/microduck-walk-flat/` 目录下，通过以下命令查看训练曲线： ```bash -uv sync --all-packages --extra rslrl +uv run tensorboard --logdir runs/microduck-walk-flat ``` -### 开发检查 +microduck 的训练数分钟内即可完成：平均回报与回合长度通常在约 4,000 次迭代后收敛： -开发依赖已包含 [`dprint-py`](https://pypi.org/project/dprint-py/)。安装 -[`prek`](https://github.com/j178/prek)、启用 Git pre-commit hook，并运行所有已配置的检查： +

+ microduck-walk-flat 训练的 TensorBoard 曲线：平均回报与回合长度在约 4,000 次迭代后收敛 +

-```bash -uv tool install prek==0.5.2 -prek install -prek run --all-files -``` +### 4. 回放训练好的策略 -需要单独运行 dprint 时，通过 uv 执行： +无需重新训练即可回放最近一次训练得到的策略（例如提前 Ctrl+C 中断训练之后）： ```bash -uv run dprint fmt +uv run scripts/play.py env=microduck-walk-flat ``` -## 🎯 使用指南 +训练好的 microduck 策略在查看器中的回放效果： -### 环境可视化 +https://github.com/user-attachments/assets/4bcf3122-f135-44cb-a966-d2d8e84479da -查看环境而不执行训练： +## 🌍 任务环境 -```bash -uv run scripts/view.py env=cartpole -``` +MotrixLab 内置 50+ 个仿真环境，覆盖基础控制、四足、人形、全身动作跟踪、操作等类别。主要类别如下： -在静态标准场景中查看内置机器人： +| 预览图 | 类别 | 示例环境 | +| --- | --- | --- | +| go2-walk-rough | 四足速度跟踪 | `go2-walk-flat` · `go2-walk-rough` · `go1-walk-rough` · `anymalc-walk-flat` | +| g1-walk-flat | 人形速度跟踪 | `g1-walk-flat` · `k1-walk-rough` · `dex-evt-walk-flat` · `microduck-walk-flat` | +| g1-wbt-dance | 全身动作跟踪（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 ``` -可用的内置机器人名称包括 `dex-evt`、`g1-29dof`、`go1`、`go2` 和 `k1`。 - -### 训练模型 - -使用默认的 Cartpole SKRL 任务训练： - -```bash -uv run scripts/train.py task=cartpole/skrl.ppo -``` +完整环境列表与各环境支持的训练算法见[环境总览](https://motrixlab.readthedocs.io/zh-cn/latest/user_guide/envs/index.html)。 -使用 RSLRL 框架训练： +## 🤖 内置机器人模型 -```bash -uv run scripts/train.py task=cartpole/rslrl.ppo -``` +通过 robot registry 内置 7 个可复用机器人模型，可与任意场景和任务组合： -通过 Hydra 直接覆盖运行参数和算法参数： +| 截图 | Registry 名称 | 类型 | 自由度 | +| --- | --- | --- | --- | +| anymal_c | `anymal_c` | 四足机器人 | 12 | +| dex-evt | `dex-evt` | 人形机器人 | 23 | +| g1-29dof | `g1-29dof` | 人形机器人 | 29 | +| go1 | `go1` | 四足机器人 | 12 | +| go2 | `go2` | 四足机器人 | 12 | +| k1 | `k1` | 人形机器人 | 22 | +| microduck | `microduck` | 人形机器人 | 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 ``` -训练结果会保存在 `runs/{env-name}/` 目录下。 +机器人配置细节与自定义新模型的方法见[支持的机器人](https://motrixlab.readthedocs.io/zh-cn/latest/user_guide/robots.html)。 -通过 TensorBoard 查看训练数据： +## 🏗️ 项目组成 -```bash -uv run tensorboard --logdir runs/{env-name} -``` +MotrixLab 是一个由九个 package 组成的 [uv](https://docs.astral.sh/uv/) workspace： -### 模型推理 +| Package | PyPI 名称 | 说明 | +| --- | --- | --- | +| **motrix_deploy** | `motrix-deploy` | 独立于训练框架的 artifact、backend、policy、控制循环、registry 与 CLI | +| **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo 部署 backend plugin | +| **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS 硬件 backend plugin | +| **motrix_deploy_tasks** | `motrix-deploy-tasks` | 具体的带版本部署任务实现与可执行入口 bootstrap | +| **motrix_env_core** | `motrix-env-core` | 环境基类、配置、registry、场景构建、NumPy runtime 与渲染能力，不包含任何内置任务和机器人资产 | +| **motrix_env_motrixsim** | `motrix-env-motrixsim` | MotrixSim 实时仿真 backend、renderer 与 torch frontend | +| **motrix_env_mujoco** | `motrix-env-mujoco` | 仅负责编译场景的 MuJoCo backend | +| **motrix_envs** | `motrix-envs` | 内置环境、模型、数据及环境到部署 profile 的编译实现 | +| **motrix_rl** | `motrix-rl` | 基于 `motrix-env-core` 的 RL 框架集成，支持 SKRL、RSLRL 和 FastSAC | -```bash -uv run scripts/play.py env=cartpole -``` +## 🤝 参与贡献 -更多使用方式请参考[用户文档](https://motrixlab.readthedocs.io) +欢迎参与贡献！开发环境搭建、分支与提交规范、以及仓库配置的检查工具（`prek`、`ruff`、`dprint`、`mypy`）请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 📬 联系方式 diff --git a/docs/source/_static/images/architecture-dark.svg b/docs/source/_static/images/architecture-dark.svg new file mode 100644 index 0000000..85612d1 --- /dev/null +++ b/docs/source/_static/images/architecture-dark.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + One CLI, end to end:  train  ·  play  ·  view  ·  export  ·  deploy + + + DEFINE ONCE + TRAIN FAST + DEPLOY ANYWHERE + + + + Environment definition + + ▸Observations & actions + ▸Rewards & terminations + ▸Scene, robot & assets + ▸One shared config schema + + BUILT-IN LIBRARY + + Basic control + + Locomotion + + Manipulation + + Whole-body tracking + + + + SKRL + + JAX · PyTorch + + + RSL-RL + + PyTorch + + + FastSAC + + built-in ★ + + + Thousands of parallel environments + on MotrixSim + + + + policy artifact + .onnx / .pt + + + + MuJoCo + simulation replay + + SIM + + + Unitree + real hardware · DDS + + REAL + + + + more hardware + on the roadmap + + + + + + + + + + + + + + + One definition, every framework + + + Minutes to converge, not hours + + + From sim to real, one artifact + diff --git a/docs/source/_static/images/architecture-light.svg b/docs/source/_static/images/architecture-light.svg new file mode 100644 index 0000000..9aea7c8 --- /dev/null +++ b/docs/source/_static/images/architecture-light.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + One CLI, end to end:  train  ·  play  ·  view  ·  export  ·  deploy + + + DEFINE ONCE + TRAIN FAST + DEPLOY ANYWHERE + + + + Environment definition + + ▸Observations & actions + ▸Rewards & terminations + ▸Scene, robot & assets + ▸One shared config schema + + BUILT-IN LIBRARY + + Basic control + + Locomotion + + Manipulation + + Whole-body tracking + + + + SKRL + + JAX · PyTorch + + + RSL-RL + + PyTorch + + + FastSAC + + built-in ★ + + + Thousands of parallel environments + on MotrixSim + + + + policy artifact + .onnx / .pt + + + + MuJoCo + simulation replay + + SIM + + + Unitree + real hardware · DDS + + REAL + + + + more hardware + on the roadmap + + + + + + + + + + + + + + + One definition, every framework + + + Minutes to converge, not hours + + + From sim to real, one artifact + diff --git a/docs/source/_static/images/microduck-training-curves.png b/docs/source/_static/images/microduck-training-curves.png new file mode 100644 index 0000000..b682d49 --- /dev/null +++ b/docs/source/_static/images/microduck-training-curves.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:10d117976d6a131a416d8ac34610ea0278996262bc1adf88cba5e52d755fe999 +size 72359 diff --git a/docs/source/_static/images/microduck-walk.gif b/docs/source/_static/images/microduck-walk.gif new file mode 100644 index 0000000..57e171c --- /dev/null +++ b/docs/source/_static/images/microduck-walk.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ce7ac578ac164229e669e7351ca87bebf3935a68993ebec280191a912e6d230d +size 5759289 diff --git a/docs/source/_static/images/train-console.png b/docs/source/_static/images/train-console.png new file mode 100644 index 0000000..bd2eb87 --- /dev/null +++ b/docs/source/_static/images/train-console.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74d03422c67b62e68002e34ff3a0b8844fd82fcd4e8fb62f23d40cdc3abf4ae1 +size 39922 diff --git a/docs/source/_static/videos/microduck-walk.mp4 b/docs/source/_static/videos/microduck-walk.mp4 new file mode 100644 index 0000000..0cb248d --- /dev/null +++ b/docs/source/_static/videos/microduck-walk.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e38fff19a52577c8f437e9c4d389c50fcec0be77eb125a432e2923aef35c2bb6 +size 1585145 diff --git a/motrix_rl/pyproject.toml b/motrix_rl/pyproject.toml index 8480a3c..0e1b75a 100644 --- a/motrix_rl/pyproject.toml +++ b/motrix_rl/pyproject.toml @@ -21,13 +21,13 @@ dependencies = [ "numpy>=1.26", "omegaconf>=2.3,<2.4", "nvidia-ml-py>=13.610.43", + # Default training backend; also required by scripts/view.py. Resolved + # from the pytorch-cu128 index via the workspace root tool.uv.sources. + "torch==2.7.0", ] [project.optional-dependencies] -onnx = [ - "onnx==1.20.1", - "onnxruntime==1.23.2", -] +onnx = ["onnx==1.20.1", "onnxruntime==1.23.2"] skrl-jax = [ "skrl>=2.1,<2.2; sys_platform == 'linux'", "jax[cuda12]==0.4.34; sys_platform == 'linux'", diff --git a/scripts/view.py b/scripts/view.py index 1eaa837..053ea7f 100644 --- a/scripts/view.py +++ b/scripts/view.py @@ -2,12 +2,12 @@ # SPDX-License-Identifier: Apache-2.0 import time +from typing import TYPE_CHECKING import gymnasium as gym import hydra import motrixsim as mtx import numpy as np -import torch from motrixsim.render import RenderApp, RenderClosedError, RenderSettings from omegaconf import DictConfig @@ -19,11 +19,13 @@ from motrix_env_core.config.scene import RobotCfg, SystemCameraCfg from motrix_env_core.renderer import RenderConfig, create_renderer from motrix_env_motrixsim.compiler import build_scene_model -from motrix_env_motrixsim.torch_env import TorchEnv from motrix_envs.config.scene import StandardSceneCfg, StandardSceneObjsCfg from motrix_rl.cli import to_typed_config from motrix_rl.config import ViewConfig +if TYPE_CHECKING: + from motrix_env_motrixsim.torch_env import TorchEnv + DEFAULT_ENV_NAME = "cartpole" ROBOT_VIEW_FPS = 60 @@ -137,7 +139,9 @@ def _run_robot(robot_cfg: RobotCfg, sim: str | None = None) -> None: raise ValueError(f"Unsupported robot view sim {backend!r}; expected 'motrixsim' or 'mujoco'") -def _run_torch(env: TorchEnv): +def _run_torch(env: "TorchEnv"): + import torch + renderer = create_renderer(env, RenderConfig()) env.init_state() env_dt = env.cfg.ctrl_dt @@ -157,6 +161,13 @@ def _run_torch(env: TorchEnv): time.sleep(sleep_dt) +def _torch_frontend_missing(env_name: str) -> ModuleNotFoundError: + return ModuleNotFoundError( + f"Environment '{env_name}' uses the torch frontend, but PyTorch is not installed; install torch " + f"(for example `uv sync --all-packages`) or view a NumPy-frontend environment such as '{DEFAULT_ENV_NAME}'" + ) + + def run(cfg: ViewConfig) -> None: if cfg.env is not None and cfg.robot is not None: raise ValueError("env and robot are mutually exclusive; set only one") @@ -167,11 +178,27 @@ def run(cfg: ViewConfig) -> None: _run_robot(registry.make_robot_config(cfg.robot), cfg.sim) return - env = registry.make(cfg.env or DEFAULT_ENV_NAME, num_envs=cfg.num_envs) + env_name = cfg.env or DEFAULT_ENV_NAME + try: + env = registry.make(env_name, num_envs=cfg.num_envs) + except ModuleNotFoundError as exc: + # Torch-frontend environments import torch when their factory resolves the env class. + if exc.name == "torch": + raise _torch_frontend_missing(env_name) from exc + raise if isinstance(env, ArrayEnv): _run_np(env) - elif isinstance(env, TorchEnv): + return + + try: + from motrix_env_motrixsim.torch_env import TorchEnv + except ModuleNotFoundError as exc: + if exc.name == "torch": + raise _torch_frontend_missing(env_name) from exc + raise + + if isinstance(env, TorchEnv): _run_torch(env) else: raise TypeError(f"Unsupported environment type '{type(env).__name__}'.") diff --git a/uv.lock b/uv.lock index 8809e2b..5847447 100644 --- a/uv.lock +++ b/uv.lock @@ -1094,6 +1094,8 @@ dependencies = [ { name = "omegaconf" }, { name = "python-abc" }, { name = "rich" }, + { name = "torch", version = "2.7.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux' and sys_platform != 'win32'" }, + { name = "torch", version = "2.7.0+cu128", source = { registry = "https://download.pytorch.org/whl/cu128" }, marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ] [package.optional-dependencies] @@ -1154,6 +1156,8 @@ requires-dist = [ { name = "skrl", marker = "sys_platform == 'linux' and extra == 'skrl-jax'", specifier = ">=2.1,<2.2" }, { name = "skrl", marker = "extra == 'skrl-torch'", specifier = ">=2.1,<2.2" }, { name = "tensorflow", marker = "sys_platform == 'linux' and extra == 'skrl-jax'", specifier = "==2.20.0" }, + { name = "torch", marker = "sys_platform != 'linux' and sys_platform != 'win32'", specifier = "==2.7.0" }, + { name = "torch", marker = "sys_platform == 'linux' or sys_platform == 'win32'", specifier = "==2.7.0", index = "https://download.pytorch.org/whl/cu128" }, { name = "torch", marker = "(sys_platform == 'linux' and extra == 'rslrl') or (sys_platform == 'win32' and extra == 'rslrl')", specifier = "==2.7.0", index = "https://download.pytorch.org/whl/cu128" }, { name = "torch", marker = "(sys_platform == 'linux' and extra == 'skrl-torch') or (sys_platform == 'win32' and extra == 'skrl-torch')", specifier = "==2.7.0", index = "https://download.pytorch.org/whl/cu128" }, { name = "torch", marker = "sys_platform != 'linux' and sys_platform != 'win32' and extra == 'rslrl'", specifier = "==2.7.0" },