chore: release v0.0.1

This commit is contained in:
motphys-developers
2025-11-20 08:57:48 +00:00
commit 5133830b5a
105 changed files with 8789 additions and 0 deletions

View File

@@ -0,0 +1,84 @@
# 快速入门Hello MotrixLab
本教程通过演示一个简单例子 - 加载倒立摆并进行训练,以此来展示 MotrixLab 工作流程:
## 环境预览
我们提供了一个简单的脚本,用于可视化一个环境,而不执行任何训练,这可以帮助您检测系统的环境依赖是否配置正确:
```bash
uv run scripts/view.py --env cartpole
```
这将打开一个可视化窗口,显示倒立摆的物理仿真环境,使用随机动作进行演示。
## 训练模型
开始训练倒立摆平衡任务:
```bash
uv run scripts/train.py --env cartpole
```
训练过程会自动:
1. 根据硬件环境自动选择训练后端JAX 或 PyTorch
2. 创建训练环境
3. 开始 PPO 算法训练
训练结果会保存在 `runs/cartpole/` 目录下,包含:
- 训练检查点checkpoint
- TensorBoard 日志文件
## 可视化训练过程
如果您想要在训练过程中观察模型的学习过程,可以启用可视化渲染:
```bash
uv run scripts/train.py --env cartpole --render
```
### 🎮 交互式渲染控制
> **重要提示**:可视化会显著降低训练速度,建议主要用于调试和演示。
在可视化训练过程中,您可以使用**空格键**来动态控制渲染:
- **开启渲染**:按下空格键开启可视化,观察机器人行为
- **关闭渲染**:再次按下空格键关闭渲染,提升训练速度
- **随时切换**:无需重新启动程序,可以在训练过程中随时切换
这种交互式控制让您可以在需要时观察训练效果,在不需要时享受快速训练。这项功能在运行推断时也能生效。
## 查看训练结果
使用 TensorBoard 查看训练进度:
```bash
uv run tensorboard --logdir runs/cartpole
```
## 测试训练好的模型
训练完成后,使用训练好的策略进行测试:
```bash
# 自动寻找最佳策略测试(推荐)
uv run scripts/play.py --env cartpole
# 手动指定策略文件测试(如果需要特定版本)
uv run scripts/play.py --env cartpole --policy runs/cartpole/YOUR_RESULT_NUMBER/best_agent.pickle
```
> **提示**:系统会自动在 `runs/cartpole/` 目录下寻找最新、最佳的策略文件。通常情况下,使用自动发现功能即可。
## 至此我们完成了整个示例
接下来可以尝试修改参数,观察不同设置下的物理效果,或者尝试其他环境。
## 下一步
- 了解 [基础框架](../tutorial/basic_frame.md)
- 学习 [物理环境配置](../tutorial/physics_environment.md)
- 查看更多 [训练示例](../demo/cartpole.md)

View File

@@ -0,0 +1,57 @@
# 安装环境
## 安装要求
- **Python 版本**{bdg-danger-line}`3.10.*`
| Python 版本 | 支持状态 |
| :---------: | :------: |
| ≤ 3.9 | ❌ |
| 3.10 | ✅ |
| ≥ 3.11 | ❌ |
- **包管理器**{bdg-danger-line}`UV`
[UV 安装参考](https://docs.astral.sh/uv/getting-started/installation/)
- **系统及架构**
- {bdg-danger-line}`Windows(x86_64)`
- {bdg-danger-line}`Linux(x86_64)`
```{note}
各平台支持的功能如下:
| 操作系统 | CPU 仿真 | 交互式查看器 | GPU 仿真 |
| :------: | :------: | :----------: | :------: |
| Linux | ✅ | ✅ | 🛠️ 开发中 |
| Windows | ✅ | ✅ | 🛠️ 开发中 |
```
## 安装方法
### 克隆项目
```bash
git clone https://github.com/Motphys/MotrixLab.git
cd MotrixLab
```
### 安装依赖
使用 UV 安装项目依赖:
```bash
# 安装所有依赖
uv sync --all-packages --all-extras
```
如果只需要安装一种训练后端,可以选择单独安装指定的后端类型:
```bash
# 安装 SKRL JAX (仅支持 Linux 平台)
uv sync --all-packages --extra skrl-jax
# 安装 SKRL PyTorch
uv sync --all-packages --extra skrl-torch
```