Mujoco_WASM/python/mujoco/sysid/README.md

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

给定 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），保证物理一致性且不存在奇异点。

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

示例

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 报告。