Kamino 调优

Kamino 是处于测试阶段的 Newton 求解器，通过任务提供的 newton_kamino 预设启用。本指南先定位并测量可复现的问题，再调整求解器设置。各配置字段及其当前默认值，以 KaminoPADMMSolverCfg 和 KaminoDVISolverCfg 的自动生成 API 文档为准。

先决条件

预设的含义见 后端与预设 ，任务中的集成方式见 后端与求解器预设 。请按照 为 Newton MJWarp 准备资产 为 Newton 准备资产。通过任务的 --help 输出或 环境目录 确认任务是否提供 newton_kamino ；不能因为任务支持其他 Newton 预设，就推断它也支持 Kamino。

建立明确的基准配置

训练或性能测试前，先运行一个小规模的可视化冒烟测试：

uv run python scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct --num_envs 4 --viz newton_gl physics=newton_kamino

然后固定初始状态、随机种子、动作序列和重置状态分布。记录这一复现场景中的穿透、滑移、能量、任务指标、收敛诊断结果和运行耗时。每次只调整一项，以便在同一基准下比较所有候选配置。

选择 PADMM 或 DVI

接触密集的任务优先选择 PADMM；活动接触较少的机构可以考虑 DVI。如果 DVI 任务需要显式覆盖 KaminoDynamicsCfg ，应禁用预条件处理；否则不要设置动力学覆盖配置，让 Newton 选择兼容的默认值。

验证重置与状态一致性

调优求解器前，先验证通过 Isaac Lab 资产 API 写入的根状态和关节状态。每次重置后，Kamino 的最大坐标刚体位姿都必须与约化关节状态一致。如果刚体位姿与关节状态不一致，应先检查自定义重置代码、重置时的物体重叠等问题，再调整收敛或稳定化设置。

选择碰撞处理方式并确定容量

在相同的完整重置分布和接触分布下，比较 Kamino 内置检测器与 Newton 碰撞管线。Kamino 求解器上的 use_collision_detector 用于选择内置路径，其参数由 KaminoCollisionDetectorCfg 配置；禁用内置路径时，由 NewtonCollisionPipelineCfg 配置 Newton 路径。仅在观察到容量不足、接触丢失或警告时调整当前路径的容量，具体控制项以这些自动生成的 API 文档为准。增加碰撞容量无法修复无效几何或重置时的穿透。

调整时间步长与子步数

保持策略周期和固定的复现场景不变。只有在模型与重置均已验证后，才比较同一策略周期下更小的仿真时间步长或更多的 num_substeps 。重新检查已记录的物理、收敛、任务和耗时指标；不要仅为掩盖仿真步的不稳定而改变策略时序。

调整收敛与稳定化参数

仅当 PADMM 的收敛失败可复现时，才调整 KaminoPADMMCfg 的迭代与残差控制项。对于 DVI，也应有同类证据后再调整 KaminoDVICfg 的交替迭代次数和容差。只有验证碰撞与重置后，才调整 KaminoConstraintsCfg 的稳定化控制项。增加求解计算量无法修复状态不一致、无效碰撞几何或重置时的重叠。

验证后再优化性能

测量性能前关闭诊断。只保留能改善已记录指标的修改，并根据所选求解器和负载，分别测量稀疏雅可比、CUDA 图、碰撞、子步和迭代的开销。对应的 MJWarp 流程见 MJWarp 调优 ，但它不能替代 Kamino 自身的验证和调优。

先诊断、后调优的顺序是：验证基准、重置状态与碰撞路径；比较时间步长和子步数；排查收敛与稳定化问题；最后优化实测开销。