Prepare an Asset for Newton with MJWarp

Prepare an Asset for Newton with MJWarp#

See also

This page is the source of truth for the isaaclab-preparing-assets-for-newton agent skill (skill source). When you change this page, update the skill so agent guidance stays in sync. See Agent Skills.

Prerequisites#

Understand how Isaac Lab selects a backend and its task-specific preset before changing an asset; see Backends and Presets. This guide prepares an asset and task for physics=newton_mjwarp. After both backends run the asset and task, use Transfer Policies Between PhysX and Newton to transfer a policy checkpoint. For the conceptual differences that require target-solver validation, see Solver Differences; use Tune MJWarp for the focused MJWarp tuning procedure.

Import a multi-physics asset#

Isaac Lab assets can work with both physics=physx and physics=newton_mjwarp. Many assets author USD Physics and PhysX schemas; Newton parses the supported authored properties into its model, so a separate Newton-only copy is not required. Confirm each property against the supported feature and schema documentation: an authored PhysX attribute can be present without MJWarp using it during stepping.

For a new URDF or MJCF asset, use the Isaac Lab importers to create a multi-physics asset. Keep run_asset_transformer and run_multi_physics_conversion enabled (both default to True) so the conversion creates neutral physics, PhysX, and MuJoCo payloads. The current converter uses a nested rigid-body structure rather than the earlier flat USD structure. See Importing a New Asset, UrdfConverterCfg, and MjcfConverterCfg.

Separate common and solver-specific properties#

Put common USD Physics properties in solver-common configuration classes such as RigidBodyBaseCfg and JointDriveBaseCfg. Put backend-only properties in the matching subclasses:

  • Use MujocoRigidBodyPropertiesCfg, MujocoJointDrivePropertiesCfg, and MujocoCollisionCfg for MJWarp-specific properties.

  • Use the matching Newton*PropertiesCfg classes for supported Newton-native collision, material, articulation, and related properties.

  • Keep PhysX-only damping, stabilization, solver-iteration, friction-patch, and compliant-contact properties in the matching Physx*PropertiesCfg classes.

For configuration hierarchy and parameter-to-USD routing, see Schema Configuration Classes. Check the Newton/MuJoCo schema API and PhysX schema API for supported fields. A value present in a PhysX asset or imported Newton model is not proof that MJWarp consumes it.

Audit the mechanical model#

Inspect every dynamic link and contact-relevant object:

  • Author positive mass [kg], center of mass [m], and positive-definite inertia [kg*m^2]. Treat a placeholder inertia warning as a modeling failure, and verify the inertia and center-of-mass frames.

  • Apply UsdPhysics.CollisionAPI only to intentional collision geometry. Check approximation, mesh scale, contact offset or margin, material binding, restitution, and self-collision filters; visual parity is not collision parity.

  • Verify the articulation root, fixed-base representation, fixed-joint merging, nested rigid bodies, joint types, axes, and limits.

  • Make each body-level gravity setting intentional. A stale override can make a task differ from scene gravity.

Match collision, contact, and friction behavior#

Do not copy PhysX friction settings numerically. First verify intended collision shapes, material bindings, contact locations, contact count, and available gripper normal force in both backends. Then inspect the resolved per-shape MuJoCo contact dimensionality, condim: 1 is frictionless, 3 adds tangential friction, 4 adds torsional friction, and 6 also adds rolling friction. Choose the smallest model that represents the contact physics and confirm that the importer and contact path preserve it.

Tune material friction against measured tangential slip only after the contact model is valid. MujocoCollisionCfg also exposes expert per-collider overrides such as priority, solmix, solref, and solimp; use them only with a measured contact-model need. Use contact_margin, contact_gap, and max_hull_vertices instead of raw importer attributes. Follow Tune MJWarp for the current global solver and contact tuning sequence.

Validate actuators and limits#

Audit per-joint effort limits, stiffness, damping, friction, armature, action scale, and control period. Armature applies only to articulated coordinates: use a physically justified reflected motor/transmission inertia or a controlled response test, and do not use it to hide bad body mass, inertia, units, reset penetration, or contact capacity. Retune damping after changing armature. For the general actuator model and configuration guidance, see Actuators.

actuator_velocity_limit is the actuator’s physical rated speed. Isaac Lab can use it in actuator or task logic, observations, rewards, and terminations, but MJWarp does not parse it into the solver model or enforce it while stepping. joint_velocity_limit requests a solver-side hard clamp. Isaac Lab writes it to Newton’s Model.joint_velocity_limit; MJWarp drops that field, while Kamino honors it. When a task needs a speed bound under MJWarp, implement and validate it in task or control logic. Use joint_effort_limit for the simulated effort limit and actuator_effort_limit to clip an explicit actuator model, choosing both from the motor and gearbox rather than using one oversized value for the whole robot.

Run paired smoke tests#

Run the same fixed task state through both backends before training or transfer:

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

Let each run cross multiple resets. Record object displacement, contact count, gripper effort, penetration, and success rate for the same fixed grasp. Also check for non-finite state, first-step impulses, unexpected saturation, excessive angular velocity, contact loss, and importer or solver warnings. Reject robot-object and robot-support penetration, impossible mimic states, and invalid randomized geometry before the first physics step.

Account for solver differences#

After the paired smoke tests, use the target solver’s controls to address the differences described in Solver Differences:

  1. Revalidate contact behavior with the smallest useful environment count and a visualizer before scaling up.

  2. Retune material friction from measured slip; PhysX patch friction and MJWarp contact friction are not numerically interchangeable.

  3. Retune restitution from observed bounce and chatter rather than assuming a PhysX scene threshold applies to Newton.

  4. Compare timestep and num_substeps against the fixed reproduction, especially for contact-heavy tasks.

  5. When a PhysX task used CCD, validate a Newton collision strategy and shorter solver timestep as needed; MJWarp’s ccd_iterations is not a CCD switch.

  6. For Kamino, validate reset-state consistency and only then investigate constraint stabilization or convergence settings.

Diagnose Newton-only failures#

Reproduce the first failing step with one environment, a fixed seed and reset state, no domain randomization, and the same action sequence in both backends. Localize the failure before tuning:

  1. At initialization or the first step, inspect mass, inertia, scale, reset overlap, topology, drives, and unsupported features.

  2. At contact onset, inspect contact locations and counts, capacity warnings, margins, condim, friction, cone choice, and extreme mass or inertia ratios.

  3. Under control, inspect effort and gain limits, action scale, dt, substeps, damping, armature, and joint-limit impacts.

  4. In dense scenes, compare the busiest environment with per-environment contact and constraint capacities.

Enable NewtonCfg.debug_mode to inspect iteration-cap usage. Increase overflowing capacity first; change convergence settings only after the asset, reset, controller, contact model, and capacities are valid. Keep the smallest fixed-state reproduction and record the first non-finite quantity so later changes can be compared one at a time.