SuperDex 是一套面向灵巧操作研究的统一仿真平台，其核心SuperDex Physics是一个"接触优先"的物理引擎：它用隐式时间积分 + 非线性 Newton 求解器处理刚体、软体与多关节机器人，并用网格 SDF（有符号距离场）接触模型精确判定碰撞。本文带你从零理解这套组合拳的原理与关键参数，帮你在调试仿真时少走弯路。

SuperDex 资产制作工具界面：CAD/网格资产被转换为物理引擎可用的模型（含 SDF 碰撞体数据）

一、SuperDex Physics 定位：以接触为核心的仿真引擎

SuperDex 平台由四大模块组成（见 README.md）：

它的口号很直白："purpose-built for tactile manipulation"—— 凡是需要稳定接触与精确感知（如灵巧手抓握、指尖触觉）的场景，都是它的目标战场。而"稳定"二字，正是由下面两大支柱撑起来的。

二、隐式求解器：稳定仿真的第一支柱

2.1 时间积分：为什么默认是 Backward Euler？

每个时间步，引擎先用隐式方法把运动方程离散化。可选的积分方案定义在 integration_params.h：

• Backward Euler（默认，L-稳定）：强阻尼特性，接触类问题最稳
• BDF2 / BDF3：更高阶，但稳定性下降
• DIRK22 / DIRK23 / DIRK33：多阶隐式 Runge-Kutta
• SymplecticDIRK12 / 22：辛方法，适合能量守恒场景

对夹爪抓取、软体堆叠这类"接触密集"任务，L-稳定的 Backward Euler 是安全的选择：步长可以更大而不会发散，这正是新手最关心的"稳定性"来源。

2.2 非线性求解：Newton 方法 + 线搜索的三重保险

隐式离散后每步都要解一个非线性方程组。核心配置集中在 NonLinearSolverParams，它有三层防护设计：

① 求解算法可选（NonLinearSolverType）

• Newton（默认）：二阶收敛，每步组装完整雅可比
• BFGS / SR1（拟 Newton）：用低秩更新近似雅可比，省算力，并按dResidualAssemblyPeriod周期性重算真实雅可比

② 收敛判据与容差

• 默认最多maxIter = 4次非线性迭代，absTol = 1e-3、relTol = 1e-6
• 支持PerActorWeighted模式：按每个 actor 的惯性加权残差范数判断收敛，避免"大物体掩盖小物体"的误差
• 支持 Eisenstat-Walker 自适应内层容差策略（forcing term），让内层线性求解"该松则松、该紧则紧"

③ 防爆机制（这是与常见引擎的差异点）

• explosionControl（默认开启）：残差超过absDivTol或相对relDivTol即触发发散保护，而不是让物体"飞出去"
• PSD 投影：雅可比偏离正半定谱时自动投影修正
• 线搜索（line search）：默认ResidualNorm型，要求每步残差范数下降，步长按lineSearchAlpha = 0.5折半，最多 4 次尝试；另有 Simple/Armijo/Wolfe 等目标函数型判据可选

实际求解入口见 mochi_solve.cpp——场景会先拆分成相互独立的island（动力学岛），每个岛独立求解、并行收敛，这正是大规模场景不拖慢的原因。

2.3 内层线性求解：稀疏迭代求解器矩阵

每次 Newton 迭代内部还要解一个大型稀疏线性系统。LinearSolverParams 提供了相当完整的工具箱：

默认的PerActor 域分解预处理（PreconditionerType）把每个 actor 当作一个子域独立处理，既贴合物理结构又天然适合并行。求解结束后引擎会输出SolverStats收敛统计，配合调试器可以逐帧检查迭代次数与残差曲线。

三、SDF 接触模型：稳定仿真的第二支柱

3.1 什么是网格 SDF（Grid SDF）

传统网格碰撞要么粗糙（包围盒）、要么昂贵（网格-网格求交）。SuperDex 的方案是把碰撞体烘焙成网格 SDF：一个三维体素网格，每个格点存"到最近表面的有符号距离"，场内的采样查询又快又准。烘焙参数定义在 GridSdfParams：

• resolutionDelta（默认 0.25）：最大体素尺寸 = 该系数 × 参考特征尺寸（边长/包围盒等，由resolutionMode指定）。调小提升精度，但内存与生成耗时按 N³ 增长
• boundaryPaddingDist：SDF 网格在包围盒外的扩展距离，默认取接触 penalty 阈值的 5 倍，保证接触带内始终有合法距离值
• minGridResolution（默认 6×6×6）：防止小物体网格过小退化

运行时对应的碰撞体组件是 CSdfCollider，且支持异步烘焙（CSdfColliderPending）——大场景加载时不阻塞主线程。仓库里也有现成的隐式 SDF 形状示例：plane.mochi.json。

3.2 接触判定与响应：penalty 阈值 + 同步/异步模式

接触参数由 ContactParams 控制，核心是penaltyThresholdDefault = 0.001 m：当 SDF 距离进入阈值带，接触罚力开始作用，并带光滑过渡区间避免力突变。

接触更新的时序由 ContactType 决定：

• Sync（推荐）：用当前步双方状态，接触力双向施加，动量守恒更严格
• Async：碰撞方用上一步状态，只向被碰方施力，可与其他计算重叠、更快

此外，场景可以在步进前注册SdfDistances等查询类型，回读每个接触样本点的距离与每节点接触力（见 mochi_physics_topics.dox）——这对触觉仿真和策略奖励设计非常有用。

四、上手建议：如何调出稳定又快的仿真 🎯

结合上面的原理，给你几条实操方向：

1. 先稳后快：保持默认 Backward Euler + Newton + ResidualNorm 线搜索；需要提速时优先调内层线性求解（如放宽relTol、换PreconditionerType），而不是关闭explosionControl
2. 接触抖动时：检查 SDF 的boundaryPaddingDist是否 ≥ penalty 阈值，以及软体/皮肤的penaltyThresholdDefault是否与物体尺度匹配（毫米级指尖建议调小）
3. SDF 精度取舍：默认resolutionDelta = 0.25适合多数场景；小特征（指尖纹理、薄壁）再按需调小，记住 N³ 的成本
4. 收敛诊断：查看SolverStats中每步迭代次数与ConvergenceStatus（Converged/Stopped/Diverged 三级递进），持续 Diverged 说明模型或材料参数有问题
5. 跑通示例再改参数：仓库自带软体鸭子、T 恤落桌面、阻尼扫描等例子，是很好的回归测试基线：
   • example_soft_duck.py
   • example_tshirt_on_plane.py
   • example_damping_sweep.py

五、关键源码导读清单

小结

SuperDex Physics 的稳定仿真 =隐式骨架（Backward Euler 离散 + Newton 非线性迭代 + 线搜索/防爆保护 + 稀疏迭代线性求解）×SDF 皮肤（网格有符号距离场 + 罚函数接触响应）。前者保证"数值不发散"，后者保证"接触算得准"。理解了 NonLinearSolverParams 与 GridSdfParams 这两张参数表，你就掌握了调优 SuperDex 物理仿真的全部钥匙 🔑