# 系统辨识工具箱（System Identification Toolbox）

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.png)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/mujoco/sysid/sysid.ipynb)

给定 MuJoCo 模型和采集到的传感器数据，寻找能够使仿真结果与真实物理系统相吻合的模型参数。默认情况下，该库使用带有边界约束（box constraints）的非线性最小二乘法来最小化测量输出与仿真（预测）输出之间的差异。残差可以通过静态或待优化的参数（例如权重和时间延迟）进行调整。

优化器采用基于有限差分雅可比矩阵的高斯-牛顿法（Gauss-Newton）。每次参数摄动都需要一次独立的仿真 rollout（推演）。所有 rollout 均在对 `mujoco.rollout` 的单次批处理调用中跨多线程并行执行。

## 工作流程（Pipeline）

**用户提供：**
- 一个或多个 `ModelSequences`，每个序列将单个 `MjSpec` 与一个或多个测量数据序列打包在一起。所有序列将被联合优化。
- 一个 `ParameterDict`，用于定义带有上下界的可微参数 `Parameter`。
- 用于将 `Parameter` 应用到 `MjSpec` 上的回调函数（可单独或联合应用）。
- （可选）用于覆盖默认残差函数行为的自定义函数（`build_model`、`custom_rollout`、`modify_residual`）。

**框架执行：**
- 将用户代码组合为残差函数（`build_residual_fn`）。
- 通过批量并行 rollout 优化参数（`optimize`）。
- 保存结果并生成交互式 HTML 报告（`save_results`、`default_report`）。

## 可以辨识哪些参数？

您可以优化任何能够以可微方式修改最终残差的参数。常见用例包括：

在 `MjSpec` 上可设置的**物理参数**。MjSpec 中的大多数参数可以通过用户提供的回调函数直接轻松设置：

| 辨识目标 | 对应方法 |
|---|---|
| 接触滑动摩擦力 | `spec.pair("cp").friction[0] = p.value[0]` |
| 关节阻尼 | `spec.joint("j1").damping = p.value[0]` |

对于无法直接简单应用到 MjSpec 的常见系统辨识参数化方式，该库提供了便捷函数：

| 辨识目标 | 对应方法 |
|---|---|
| 刚体质量 | `body_inertia_param(..., InertiaType.Mass)` |
| 刚体质量 + 质心位置 | `body_inertia_param(..., InertiaType.MassIpos)` |
| 完整惯量（10 维） | `body_inertia_param(..., InertiaType.Pseudo)` |
| 执行器 P/D 增益 | `apply_pdgain(spec, "act1", p.value)` |

完整惯量采用伪惯量 Cholesky 参数化（Pseudo-inertia Cholesky Parameterization，[Rucker & Wensing 2022](https://ieeexplore.ieee.org/document/9690029)），保证物理一致性且不存在奇异点。

诸如传感器延迟、增益和偏差等**测量参数**属于测量系统的属性，而非物理模型本身的属性。该库提供了在 rollout 之后将这些校正应用于残差的实用工具。这些功能已完备，但其 API 尚未最终定型。

## 示例

```python
import mujoco
from mujoco import sysid

# 1. 加载模型并定义待辨识参数。
spec = mujoco.MjSpec.from_file("robot.xml")
model = spec.compile()

def set_link1_mass(spec, p):
    spec.body("link1").mass = p.value[0]

params = sysid.ParameterDict()
params.add(sysid.Parameter(
    "link1_mass", nominal=2.0, min_value=0.5, max_value=5.0,
    modifier=set_link1_mass))

# 2. 加载并封装实测数据。
# 数组默认采用 MuJoCo 顺序，否则请传入 names 参数
control = sysid.TimeSeries.from_control_names(times, ctrl_array, model)
measureddata = sysid.TimeSeries.from_names(times, measurement_array, model)
initial_state = sysid.create_initial_state(model, qpos_0, qvel_0)
ms = sysid.ModelSequences("robot", spec, "traj_1", initial_state, control, measureddata)

# 3. 构建残差函数、执行优化并保存结果。
residual_fn = sysid.build_residual_fn(models_sequences=[ms])
opt_params, opt_result = sysid.optimize(initial_params=params, residual_fn=residual_fn)
sysid.save_results("results/", [ms], params, opt_params, opt_result, residual_fn)
```

`default_report` 可生成包含视频、测量对比图、参数表格以及置信区间的交互式 HTML 报告。