单摆训练示例

单摆（Pendulum）是经典的单关节摆起并倒立保持任务，目标是用一个电机扭矩把摆甩起并稳定在倒立位置。

---

任务描述

单摆由一段杆体和一个铰接关节组成，关节由单个电机驱动（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. 环境预览

uv run scripts/view.py --env pendulum

2. 开始训练

# 默认参数训练
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. 查看训练进度

uv run tensorboard --logdir runs/pendulum

4. 测试训练结果

# 自动寻找最新/最优策略（推荐）
uv run scripts/play.py --env pendulum

# 手动指定策略文件
uv run scripts/play.py --env pendulum --policy runs/pendulum/nn/best_policy.pickle

提示：策略默认在 runs/pendulum/ 下自动发现，可用 --policy 手动指定。

---

配置参数

环境配置（示例）

@registry.envcfg("pendulum")
@dataclass
class PendulumEnvCfg(EnvCfg):
    model_file: str = model_file
    max_episode_seconds: float = 10.0
    sim_dt: float = 0.0125
    ctrl_dt: float = 0.025
    angle_bound: float = 8.0
    cosing_bound: float = 0.0
    # reset_noise_scale: float = 0.01

训练配置（示例 PPO）

@rlcfg("pendulum")
@dataclass
class PendulumSkrlPpo(SkrlCfg):
    """Pendulum SKRL configuration with nested structure."""

    def __post_init__(self):
        """Configure nested SKRL runner settings."""
        runner = self.runner

        # Configure model architectures
        runner.models.policy.hiddens = [64, 64]
        runner.models.value.hiddens = [64, 64]

        # Configure PPO agent parameters
        agent = runner.agent
        agent.rollouts = 32
        agent.learning_epochs = 5
        agent.mini_batches = 4
        agent.learning_rate = 3e-4
        # Configure training parameters
        # trainer.timesteps = max_env_steps / num_envs
        runner.trainer.timesteps = 5000

---

预期训练结果

1. 摆能主动摆起并停留在倒立附近

2. 倒立处的震荡由角速度与控制变化惩罚抑制