# Python Pbr Validation

> 使用 Python WBC+PBR+DOB 验证脚本跑仿真，复现 0.2mm 末端精度。触发关键词：python 验证、pbr 仿真、pbr+dob、末端误差、旧版配置、3380c899、复现.

- Skill: `frankjie09/python-pbr-validation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add frankjie09/python-pbr-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frankjie09/python-pbr-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: FrankJIE09 (https://skillmd.com/u/frankjie09)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/frankjie09/python-pbr-validation

---


# Python PBR+DOB 末端精度验证

## 背景

Python 侧 `mujoco_wbc_validation.py` 在 `pbr_torque` + DOB 模式下可达 **< 1mm 末端误差**。此精度依赖 YAML 中正确的 PBR/DOB 增益（来自旧版调优参数，最早在 `3380c899` commit 中成型）。

**不要修改 `mujoco_wbc_validation.py` 和 `wbc_validation_config.yaml` 本身**。本 skill 通过临时替换配置来复现结果。

## 复现步骤

### 1. 使用正确的 YAML 配置

Python 验证脚本在 `wbc_validation_config.yaml` 的 `pbr:` 段中读取 PBR 参数。要复现 < 1mm 精度，关键参数如下：

```yaml
pbr:
  # 分组增益（手臂用较小增益，躯干用大增益）
  Lambda_arm: [3.0, 3.0, 3.0, 3.0, 2.0, 1.5, 1.2]
  K_arm:      [3.5, 3.5, 3.5, 3.0, 1.5, 1.25, 1.0]
  rho_arm:    [0.12, 0.15, 0.12, 0.12, 0.06, 0.05, 0.04]
  Lambda_arm_R: [3.0, 3.0, 3.0, 3.0, 2.0, 1.5, 1.2]
  K_arm_R:      [3.5, 3.5, 3.5, 3.0, 1.5, 1.25, 1.0]
  rho_arm_R:    [0.12, 0.15, 0.12, 0.12, 0.06, 0.05, 0.04]
  Lambda_trunk: [15.0, 15.0, 15.0, 15.0]
  K_trunk:      [30.0, 30.0, 30.0, 30.0]
  rho_trunk:    [0.12, 0.12, 0.12, 0.10]
  sat_eps: 0.004
  gear_ratio: [50, 50, 50, 50, 50, 50, 50,
               50, 50, 50, 50, 50, 50, 50,
               100, 100, 100, 100]
  dob_enabled: true
  dob_alpha: 0.15
  dob_Ki: 3.0
  dob_int_max: 120.0
  tau_motor_max: [3, 3, 3, 3, 3, 3, 3,
                  3, 3, 3, 3, 3, 3, 3,
                  5, 5, 5, 5]
```

首次运行时，`apply_mode` 也需设为 `pbr_torque`，`sim_duration` 需 **>= 1000.0**（DOB 积分需要长时间收敛）。

### 2. 运行仿真

```bash
# 进入 Docker
docker exec -it agent_dev_nvidia bash
source /tmp/wbc_venv/bin/activate
cd /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation

# 清除之前保存的 DOB 状态（保证从零开始）
rm -f wbc_validation_config_dob_state.npz

# 运行（headless 跑 10s 足够看到收敛）
python3 mujoco_wbc_validation.py --headless --duration 10
```

### 3. 带 GUI 运行

```bash
python3 mujoco_wbc_validation.py --duration 10
```

注意：Python 的 MuJoCo viewer 在 Docker 内可能 segfault（GLFW 依赖问题），此时回退到 `--headless`。

### 4. 预期结果

| 时间 | 末端误差（实测） |
|:---:|:---:|
| t=3s | ~150mm（PBR 鲁棒项开始压缩误差） |
| t=5s | ~30mm（DOB 积分开始积累补偿） |
| t=7s | **< 1mm** ✅ |
| t=10s | **< 0.5mm** ✅ |

DOB 积分值应在稳态时稳定，躯干 Trunk2 的 dob_int 约 +45 Nm（补偿重力缺口）。

## 关键参数说明

- **手臂 K=3.5, Lambda=3.0**: 较小的增益防止远臂端（J5-J7）力矩过冲
- **躯干 K=30, Lambda=15**: 大减速比（N=100）需要大增益克服摩擦和重力
- **rho=0.04~0.15**: 鲁棒项幅度较小，主要靠 DOB 补偿，rho 只是防止发散
- **tau_motor_max**: 手臂 3Nm/躯干 5Nm 电机端限幅，防止肘关节力矩爆炸
- **dob_Ki=3.0, dob_int_max=120**: 快速积分跟踪效率损失，但限幅防止躯干振荡

## 与 C++ 对比

| 对比项 | Python（旧版调优参数） | C++（当前 uniform K=8） |
|:---|:---:|:---:|
| 手臂 K | **3.5** | 8.0 |
| 躯干 K | **30.0** | 8.0 |
| 稳态误差 | **< 0.5mm** | ~189mm |
| use_regressor | true | false |

C++ 当前因 `use_regressor: false`（性能优化关掉了完整回归器）且 K 值 uniform，稳态误差远高于 Python 调优版。

## 故障排查

- **DOB 积分打到饱和 ±120Nm 不下降** → `dob_alpha` 太小或 `dob_Ki` 太大
- **仿真初期就爆炸** → 检查 `sim_dt=0.001`, `dt=0.005`，减小 `ddq_max`
- **DOB 恢复后误差仍大** → 删除 `wbc_validation_config_dob_state.npz` 重新跑
- **segfault** → Python MuJoCo viewer 在 Docker 内不支持，加 `--headless`