chore: release v0.2.0

docs/source/zh_CN/user_guide/demo/pendulum.md

@@ -0,0 +1,138 @@
+# 单摆训练示例
+
+单摆（Pendulum）是经典的单关节摆起并倒立保持任务，目标是用一个电机扭矩把摆甩起并稳定在倒立位置。
+
+```{video} /_static/videos/pendulum.mp4
+:poster: _static/images/poster/pendulum.jpg
+:nocontrols:
+:autoplay:
+:playsinline:
+:muted:
+:loop:
+:width: 100%
+```
+
+---
+
+## 任务描述
+
+单摆由一段杆体和一个铰接关节组成，关节由单个电机驱动（gear 可配置）。电机施加的扭矩使摆杆在平面内旋转，实现从任意初始角度的摆起、倒立和保持。关节力矩受限于 ctrlrange，通过控制扭矩大小与方向，策略需要完成能量累积（swing-up）并在倒立位置维持平衡，同时抑制角速度带来的震荡。
+
+---
+
+## 动作空间
+
+| 项目     | 详情                            |
+| -------- | ------------------------------- |
+| **类型** | `Box(-1.0, 1.0, (1,), float32)` |
+| **维度** | 1                               |
+
+---
+
+## 观察空间
+
+| 项目     | 详情                            |
+| -------- | ------------------------------- |
+| **类型** | `Box(-inf, inf, (3,), float32)` |
+| **维度** | 3                               |
+
+顺序：`cos(theta), sin(theta), 角速度`。
+
+---
+
+## 奖励设计
+
+-   倒立奖励：鼓励角度围绕 π（倒立）
+-   能量 shaping：能量接近倒立位置
+-   惩罚：`角速度^2`、`ctrl^2`、`(ctrl - prev_ctrl)^2`，抑制震荡与过猛动作
+
+---
+
+## 初始状态
+
+-   角度随机于 `[-pi, pi]`
+-   角速度小噪声（如配置）
+-   控制历史 `prev_ctrl` 初始化为 0
+
+## Episode 终止条件
+
+-   无跌倒终止；仅 NaN 检查
+-   Episode 长度由 `max_episode_seconds` 限制
+
+---
+
+### 1. 环境预览
+
+```bash
+uv run scripts/view.py --env pendulum
+```
+
+### 2. 开始训练
+
+```bash
+# 默认参数训练
+uv run scripts/train.py --env pendulum
+
+# 自定义并行环境数
+uv run scripts/train.py --env pendulum --num-envs 1024
+
+# 开启训练时渲染
+uv run scripts/train.py --env pendulum --render
+```
+
+### 3. 查看训练进度
+
+```bash
+uv run tensorboard --logdir runs/pendulum
+```
+
+### 4. 测试训练结果
+
+```bash
+# 自动寻找最新/最优策略（推荐）
+uv run scripts/play.py --env pendulum
+
+# 手动指定策略文件
+uv run scripts/play.py --env pendulum --policy runs/pendulum/nn/best_policy.pickle
+```
+
+> **提示**：策略默认在 `runs/pendulum/` 下自动发现，可用 `--policy` 手动指定。
+
+---
+
+## 配置参数
+
+### 环境配置（示例）
+
+```python
+@dataclass
+class PendulumEnvCfg(EnvCfg):
+    model_file: str = ".../pendulum.xml"  # MJCF 模型，默认 gear=5
+    max_episode_seconds: float = 20.0
+    sim_dt: float = 0.0125
+    ctrl_dt: float = 0.025
+```
+
+### 训练配置（示例 PPO）
+
+```python
+@rlcfg("pendulum")
+@dataclass
+class PendulumPPO(PPOCfg):
+    seed: int = 42
+    max_env_steps: int = 10_000_000
+    num_envs: int = 1024
+    learning_rate: float = 3e-4
+    rollouts: int = 32
+    learning_epochs: int = 5
+    mini_batches: int = 4
+    policy_hidden_layer_sizes: tuple[int, ...] = (64, 64)
+    value_hidden_layer_sizes: tuple[int, ...] = (64, 64)
+```
+
+---
+
+## 预期训练结果
+
+1. 摆能主动摆起并停留在倒立附近
+2. 倒立处的震荡由角速度与控制变化惩罚抑制