E3 验证与交付范围#

Learning home · MuJoCo contents

Course text is primarily Chinese, with English terminology and summaries. The original content is preserved.

任务：MuJoCo #4。源码固定在 3.15.0 的 9ea3cdfcae93bf2cc4dc0e1a1627c5a39a1e06e5。本阶段从实际 main 2c0accf0acc92dd56ecbe98b66bd0ca16a0e7ec5 创建 docs/e3-contact-solvers；开始前已确认干净工作树、E1/E2 实际交付文件以及没有未关闭 PR。发布/合入状态由 Git 历史与主审记录确定，不把本地文档写完当成远端发布。

#4 验收映射#

范围

本次交付

边界

B0 动力学补齐、B1 执行链

动力学与流水线：空间/量纲、CRB/RNE、稀疏 M/因子/约束 arena、装配和完整调用顺序

原生 CPU 核心，不外推 MJX/Warp/宿主同名接口

A4/B2 接触

接触模型：过滤、margin/gap、dim/锥、priority/solmix/pair/override、软约束/adhesion

原生刚体软接触主线，flex/IPC 内循环留 E6

B3 数值算法

求解与积分：primal/dual、PGS/CG/Newton、实际停止、warmstart、岛与 NoSlip

同时说明 finite-budget/预条件边界，无速度或精度排名

B4 积分

同篇：五种积分器、有效 metric/shift/隐式行、refsafe、有限差分接口和支持组合

不把线性化稳定性扩大为任意模型/步长正确性

B5 观测

力观测：广义/接触/传感器、force:torque 与 rot:lin 区别、作用侧、frame/参考点、采样和冲量条件

force/torque/touch 语义基础；完整传感/渲染仍 E4，无峰值/冲量实测

练习与原创片段

四篇共 28 道附答案阅读练习；两球–平面 XML 与读数 Python

未编译 MJCF，未执行 forward/step，未声称接触数或支撑力实测

导航与阶段

中英文 README、curriculum、roadmap、source map/manifest；README 正文与顶栏都链接 Sim Atlas

A4/B0–B5 主线交付，A6/B6 等仍保留独立阶段

实际静态检查#

git diff --check
git diff --cached --check
python scripts/check_docs.py
python scripts/check_examples.py

在 Python 3.10.12 与 CI 使用的 Python 3.12.12 下运行文本检查：本地 Markdown 链接通过；全仓 4 个 Python 文件、2 个文档 Python 片段、3 个 XML 文件解析通过。E3 新增 1 个 Python、1 个 XML。它们仅被 AST/ElementTree 解析；没有 import 原生引擎、模型编译、MJCF schema、forward/step、solver、传感器、实验、训练或 benchmark 运行验收。暂存新增文件后的空白检查曾发现 28 道练习使用 Markdown 双空格换行而触发 trailing whitespace；已改为普通分段，重跑 git diff --cached --check 通过。

对 sources.json 中 31 个官方文件，计算 SHA1("blob <byte-count>\0" + bytes) 并对照固定官方 Git 树；全部一致。全仓本引擎 GitHub blob 链接均核对固定 SHA、manifest 收录和存在的行锚；重要声明逐段人工对照实现。文件身份与行号存在只说明引用身份，不能代替相关算法的人工阅读，也不等于审计了整个上游仓库。

本阶段新增引用的官方源文件是 engine_init.c、engine_passive.c、engine_sensor.c、engine_derivative.c、engine_derivative_fd.c、engine_island.c；完整固定链接见source map。公式分开标明连续加速度、冻结接触集合、有效 metric、稳定符号线性化、无 adhesion 与后处理等前提。

源码核对重点及文字差异#

易误判项

直接依据与本课处理

惯量存储/API

mjData.M、mj_fullM：本版下三角 CSR、mj_fullM(model,data,dst)，不用旧 qM 签名

auto Jacobian 的 60 边界

实际 nv>=60；XML 的 up to/over 60 文字有边界差异，按实现说明

margin/gap

两侧求和、exclude 判定：检测 m+g、施力 m，不照搬旧版 max 或 margin−gap

材料组合

priority/solmix/min/max/adhesion：不同参数采用不同规则，pair/override 另走分支

cone 与 solver 独立

mj_isPyramidal只读 cone；computation condim 小节的“由 solver 决定”措辞不能覆盖实际分支

PGS 不是朴素固定次序算法

默认 Nesterov 与固定种子块乱序；不将内部测试开关包装为公开 XML

CG 主分支

Hager–Zhang / 条件 PR+，不沿用旧算法名称

Newton 零轮终止

gap + gradient gate 与 decrement，比官方 warmstart 简述更具体；metric 的预条件实现也单独限定，不外推 bare-M 的严格界

净接触力

contactForce 扣除 adhesion，不把正锥 efc_force 与净界面力混同

接触作用侧与轴

RNE 应用两侧符号、frame 转置，geom[1] 正向、geom[0] 反向；力矩换点另加叉积

积分器实际兼容性

运行时检查，包括 discrete/PGS/flex/sleep/IPC 限制，不以旧支持表补结论

自审、未决项与下一步#

实现者完成本地自审，未声称独立 reviewer 已通过；主 agent 负责集成审查和远端交付。上述暂存空白失败已保留记录并修复；写作自审修正了 Hessian 符号重名，并统一使用仓库的 $$ 数学块。源码与示例均未执行，所以不能以这些检查宣称接触、数值或任务实验通过。

主线没有待查算法身份问题；明确未验证项是实际绑定调用、MJCF schema、数值收敛/稳定性、运行时力与采样。E6 仍需独立研究 flex 弹性、IPC 内循环/隐藏状态与后端能力；E4 仍需完整传感器、渲染与 headless 生命周期。本轮没有新实验或跨引擎封装，也不写入 DexLab 结果表。

复盘后建议下一项 E4：已有 E1 前置，E3 的力语义可为传感器课提供基础；完成后 E5 才具备 E2+E4 前置。E6 也在 E3 交付后具备前置，但仍需主 agent 另行派发。后续实验最终复用 DexLab 的原始版本、配置、采样和工况记录。

Course source · GitHub · License