chore: release v0.1.0

(cherry picked from commit 82525f882f3924a332d9ce40bf64255d0d14f6a4)
This commit is contained in:
motphys-developers
2026-01-04 04:43:04 +00:00
parent 13cfbce9a7
commit 62011bb24f
390 changed files with 18897 additions and 626 deletions

View File

@@ -0,0 +1,123 @@
# 双关节机械臂控制
双关节机械臂Reacher是 DeepMind Control Suite 中的经典操作任务。其目标是训练一个由两段连杆组成的机械臂通过控制关节力矩使末端执行器fingertip尽可能靠近随机生成的目标点。
```{video} /_static/videos/dm_reacher.mp4
:poster: _static/images/poster/dm_reacher.jpg
:nocontrols:
:autoplay:
:playsinline:
:muted:
:loop:
:width: 100%
```
## 任务描述
Reacher 是一个二维平面内的双关节机械臂控制任务。由两个通过铰链关节hinge连接的连杆组成拥有 2 个受控关节joint0 根部关节、joint1 中间关节),智能体通过向这些关节施加扭矩作为动作,使机械臂末端移动到目标点位置。目标点在每个 episode 初始化时随机采样。
---
## 动作空间Action Space
| 项目 | 详细信息 |
| -------- | ------------------------------- |
| **类型** | `Box(-1.0, 1.0, (2,), float32)` |
| **维度** | 2 |
动作对应如下:
| 序号 | 动作含义(施加在关节的力矩) | 最小值 | 最大值 | 对应 XML 中名称 |
| ---: | ---------------------------- | :----: | :----: | :-------------: |
| 0 | 根部关节驱动扭矩 | -1 | 1 | `joint0` |
| 1 | 中间关节驱动扭矩 | -1 | 1 | `joint1` |
---
## 观察空间
| 项目 | 详细信息 |
| -------- | ------------------------------- |
| **类型** | `Box(-inf, inf, (6,), float32)` |
| **维度** | 6 |
Reacher 环境的观测空间由以下部分组成(按顺序):
| 部分 | 内容说明 | 维度 | 备注 |
| ---------------------- | -------------------- | ---- | ------------ |
| **qpos** | 2 个关节角度 | 2 | 关节位置信息 |
| **fingertip → target** | 末端到目标的向量差值 | 2 | x、y 两维 |
| **qvel** | 2 个关节角速度 | 2 | 关节速度信息 |
| 序号 | 观察量 | 最小值 | 最大值 | XML 名称 | 关节 | 类型 (单位) |
| ---- | ---------------------------- | ------ | ------ | ---------- | ----- | -------------- |
| 0 | 第一个关节角度 | -Inf | Inf | joint0_pos | hinge | 角度 (rad) |
| 1 | 第二个关节角度 | -Inf | Inf | joint1_pos | hinge | 角度 (rad) |
| 2 | fingertip - target 的 x 差值 | -Inf | Inf | NA | slide | 位置 (m) |
| 3 | fingertip - target 的 y 差值 | -Inf | Inf | NA | slide | 位置 (m) |
| 4 | 第一个关节角速度 | -Inf | Inf | joint0_vel | hinge | 角速度 (rad/s) |
| 5 | 第二个关节角速度 | -Inf | Inf | joint1_vel | hinge | 角速度 (rad/s) |
---
## 奖励函数设计
reacher 的奖励函数基于指尖与目标的距离:
```python
# 距离奖励:指尖越接近目标,奖励越高
reward = tolerance(|| fingertip - target ||)
# 其中 tolerance 是一个单调递减函数
# 距离为 0 时奖励最大,距离越大奖励越小
```
---
## 初始状态
初始状态通过随机分布采样:
- **手臂角度**:均匀分布
- **手臂角速度**:小范围随机值
- **目标点位置**:随机一个圆形区域
## Episode 终止条件
- 若观测中出现 `NaN` 值则终止
---
## 使用指南
### 1. 环境预览
```bash
uv run scripts/view.py --env dm-reacher
```
### 2. 开始训练
```bash
uv run scripts/train.py --env dm-reacher
```
### 3. 查看训练进度
```bash
uv run tensorboard --logdir runs/dm-reacher
```
### 4. 测试训练结果
```bash
uv run scripts/play.py --env dm-reacher
```
---
## 预期训练结果
1. 机械臂迅速精准触达目标
2. 末端与目标的平均距离小于 0.01 米
3. 动作平滑,无震荡