为 Newton MJWarp 准备资产

为 Newton MJWarp 准备资产#

参见

本页是 isaaclab-preparing-assets-for-newton 智能体技能的权威参考（ 技能源文件 ）。修改本页时，也应更新该技能，使智能体指导保持一致。参见 智能体技能 。

先决条件#

修改资产前，先了解 Isaac Lab 如何选择后端及任务特有预设；见 后端与预设 。本指南为 physics=newton_mjwarp 准备资产和任务。两种后端都能运行资产与任务后，再通过 在 PhysX 和 Newton 之间迁移策略 迁移策略检查点。需要在目标求解器中验证的概念差异见 求解器差异 ；专门的 MJWarp 调参流程见 MJWarp 调优 。

导入多物理后端资产#

Isaac Lab 资产可以同时用于 physics=physx 和 physics=newton_mjwarp 。许多资产编写了 USD Physics 和 PhysX 模式，Newton 会将受支持的属性解析到自身模型中，因此不需要单独制作 Newton 专用副本。请根据功能和模式文档核对每项属性：资产中存在某个 PhysX 属性，并不代表 MJWarp 在步进时会使用它。

对于新的 URDF 或 MJCF 资产，使用 Isaac Lab 导入器创建多物理后端资产。保持 run_asset_transformer 和 run_multi_physics_conversion 启用（两者默认均为 True ），使转换生成中立物理、PhysX 和 MuJoCo payload。当前转换器采用嵌套刚体结构，而非早期的扁平 USD 结构。参见 导入新资产 、 UrdfConverterCfg 和 MjcfConverterCfg 。

区分通用与求解器特有属性#

将通用 USD Physics 属性放入 RigidBodyBaseCfg 、 JointDriveBaseCfg 等求解器通用配置类，将后端专属属性放入对应子类：

  • MJWarp 特有属性使用 MujocoRigidBodyPropertiesCfg 、 MujocoJointDrivePropertiesCfg 和 MujocoCollisionCfg 。

  • 受支持的 Newton 原生碰撞、材质、关节体等属性，使用对应的 Newton*PropertiesCfg 类。

  • PhysX 专属的阻尼、稳定化、求解器迭代、接触面摩擦和柔顺接触属性，保留在对应的 Physx*PropertiesCfg 类中。

配置继承体系和参数到 USD 的对应规则见 模式配置类 。受支持字段请查看 Newton/MuJoCo 模式 API 和 PhysX 模式 API 。某个值存在于 PhysX 资产或导入的 Newton 模型中，并不能证明 MJWarp 会使用它。

检查机械模型#

检查每个动态连杆及与接触相关的物体：

  • 设置正质量 [kg]、质心 [m] 和正定惯量 [kg*m^2]。出现占位惯量警告时，应视为模型问题，并核对惯量与质心的参考坐标系。

  • 只为有意参与碰撞的几何体应用 UsdPhysics.CollisionAPI 。检查近似方式、网格缩放、接触偏移或裕量、材质绑定、恢复系数和自碰撞过滤；外观一致并不意味着碰撞一致。

  • 验证关节体根节点、固定基座表示、固定关节合并、嵌套刚体、关节类型、轴和限制。

  • 确保每个刚体级重力设置都有明确用途。过时的覆盖值可能使任务中的重力与场景重力不同。

匹配碰撞、接触和摩擦行为#

不要直接照搬 PhysX 摩擦参数的数值。先在两个后端验证预期碰撞形状、材质绑定、接触位置、接触数量和夹爪可用法向力。然后检查各形状解析后的 MuJoCo 接触维数 condim ： 1 为无摩擦， 3 增加切向摩擦， 4 增加扭转摩擦， 6 还增加滚动摩擦。选择能表达接触物理的最小模型，并确认导入器和接触路径保留了该设置。

接触模型有效后，再根据实测切向滑移调整材质摩擦。 MujocoCollisionCfg 还提供 priority 、 solmix 、 solref 和 solimp 等逐碰撞体高级覆盖选项，仅在测量证明接触模型需要时使用。请使用 contact_margin 、 contact_gap 和 max_hull_vertices ，不要使用导入器的原始属性。当前全局求解器与接触调参顺序见 MJWarp 调优 。

验证执行器和限制#

检查各关节的驱动力上限、刚度、阻尼、摩擦、电枢惯量、动作缩放和控制周期。电枢惯量只作用于关节坐标，应使用有物理依据的折算电机/传动惯量，或通过受控响应试验确定；不要用它掩盖错误的刚体质量、惯量、单位、重置穿透或接触容量。改变电枢惯量后应重新调整阻尼。通用执行器模型和配置指南见 执行器 。

actuator_velocity_limit 是执行器的物理额定速度，Isaac Lab 可在执行器或任务逻辑、观测、奖励和终止条件中使用它，但 MJWarp 不会将其解析到求解器模型，也不会在步进时施加该限制。 joint_velocity_limit 请求求解器侧硬限幅，Isaac Lab 将其写入 Newton 的 Model.joint_velocity_limit ；MJWarp 丢弃该字段，而 Kamino 会执行它。如果 MJWarp 任务需要速度边界，应在任务或控制逻辑中实现并验证。仿真驱动力限制使用 joint_effort_limit ，显式执行器模型限幅使用 actuator_effort_limit ；两者都应根据电机和齿轮箱确定，不要为整个机器人设置同一个过大值。

运行成对冒烟测试#

训练或迁移前，在两种后端中运行相同的固定任务状态：

uv run --extra isaacsim python scripts/environments/zero_agent.py --task TASK --num_envs 4 --viz none physics=physx
uv run --extra isaacsim python scripts/environments/zero_agent.py --task TASK --num_envs 4 --viz none physics=newton_mjwarp

让每次运行经历多次重置。对同一固定抓取，记录物体位移、接触数量、夹爪驱动力、穿透和成功率。还应检查非有限状态、首步冲量、异常饱和、过大角速度、接触丢失，以及导入器或求解器警告。第一个物理步之前就应排除机器人与物体/支撑面的穿透、不可满足的 mimic 状态和无效随机几何。

考虑求解器差异#

成对冒烟测试后，使用目标求解器的参数处理 求解器差异 所述差异：

  1. 扩大规模前，使用少量但足以验证的环境和可视化器，重新验证接触行为。

  2. 根据实测滑移重新调整材质摩擦；PhysX 接触面摩擦与 MJWarp 接触摩擦不能直接按数值互换。

  3. 根据观察到的反弹和抖动重新调整恢复系数，不要假定 PhysX 场景阈值也适用于 Newton。

  4. 使用固定复现案例对比时间步长和 num_substeps ，尤其是接触密集任务。

  5. PhysX 任务使用 CCD 时，应验证 Newton 的碰撞策略，并按需缩短求解器时间步长；MJWarp 的 ccd_iterations 不是 CCD 开关。

  6. 对于 Kamino，先验证重置状态一致性，再研究约束稳定化或收敛设置。

诊断仅在 Newton 中发生的故障#

使用一个环境、固定种子和重置状态，关闭域随机化，并在两个后端使用相同动作序列，复现首次失败的步。调参前先定位故障：

  1. 初始化或第一步失败时，检查质量、惯量、缩放、重置重叠、拓扑、驱动和不受支持的功能。

  2. 开始接触时失败，检查接触位置和数量、容量警告、裕量、 condim 、摩擦、摩擦锥选择，以及极端质量或惯量比。

  3. 控制期间失败时，检查驱动力和增益限制、动作缩放、 dt 、子步、阻尼、电枢惯量及关节限位冲击。

  4. 密集场景中，对比负载最重环境与逐环境接触/约束容量。

启用 NewtonCfg.debug_mode ，查看迭代上限使用情况。先增大溢出的容量；只有资产、重置、控制器、接触模型和容量均有效后，才改变收敛设置。保留最小固定状态复现案例，记录第一个非有限量，便于逐项对比后续修改。

目录