Tune MJWarp

This guide tunes the MuJoCo-Warp (MJWarp) solver after an asset and task can be constructed by the Newton backend. The generated API documentation for NewtonCfg and MJWarpSolverCfg is authoritative for every configuration field and its current default.

Prerequisites

First follow Prepare an Asset for Newton with MJWarp and reproduce one failure with a fixed initial state, seed, and action sequence. Before changing solver settings, check the mechanical model, collision geometry, reset overlap, actuator limits, and unsupported features. A solver setting cannot correct an invalid asset or controller.

Use maintained task configurations as evidence for a similar workload, not as defaults to copy. For example, compare the small Cartpole configuration with the contact-rich Allegro Hand configuration. Their values only apply after validating the new task’s reset and contact distribution.

Start from an explicit baseline

Make the selected solver, integration method, timestep, substeps, and diagnostics visible in the task configuration. This is an illustrative baseline; measure and set contact capacity for the task rather than treating omitted or checked-in values as universal.

from isaaclab.sim import SimulationCfg
from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg

solver_cfg = MJWarpSolverCfg(solver="newton", integrator="implicitfast")
newton_cfg = NewtonCfg(
    solver_cfg=solver_cfg,
    num_substeps=1,
    debug_mode=True,
)
sim_cfg = SimulationCfg(dt=1 / 120, physics=newton_cfg)

Record the fixed-state behavior, warnings, contact count, penetration, slip, task metric, and runtime before changing one variable at a time. Turn off debug_mode only after the solver budget has been validated for the full reset, command, and randomization distribution.

Size contact and constraint capacity

nconmax bounds contact points per environment. njmax bounds constraint rows per environment; contacts can consume multiple rows, and joint limits, drives, equality constraints, and mimic constraints also consume rows. Do not derive njmax directly from nconmax.

Increase the relevant capacity when diagnostics show an overflow, contacts disappear in dense states, or behavior changes with object count. Measure the worst case across resets and randomized scenes, add task-specific headroom, and then verify that the same fixed-state result remains stable. Capacity cannot fix incorrect collision geometry, contact material, or convergence.

Choose timestep and substeps

Each solver substep uses SimulationCfg.dt / NewtonCfg.num_substeps. Start with a policy period that the controller can support, then compare a smaller dt or more substeps when high drive stiffness, light objects, impacts, or dense contact cause instability. Substeps do not change the policy period SimulationCfg.dt * env.decimation.

Use the same physical metrics and fixed-state reproduction for every candidate. Do not change policy decimation merely to conceal an unstable physics step.

Validate convergence

Keep NewtonCfg.debug_mode enabled while diagnosing. It reports per-environment solver iteration statistics and warns when an environment reaches the iterations cap. Only after the model, reset, contact path, and capacities are valid should a cap hit or a reproducible metric justify sweeping iterations, ls_iterations, or tolerance.

Sweep one convergence limit at a time and stop when the physical and task metrics plateau. More iterations cannot compensate for bad inertia, penetration at reset, missing collision geometry, unsupported constraints, or excessive drive stiffness.

Tune friction and contact behavior

Validate colliders, contact locations, normal force, material friction, and condim before changing global friction settings. cone selects the MuJoCo friction-cone representation; test an elliptic cone when a physically valid contact model still slips and the additional cost is warranted. impratio changes frictional impedance relative to normal impedance. Treat both settings as a contact-formulation change, and recheck penetration, slip, energy, convergence, task success, and runtime after each change.

Do not use impratio to mask missing contacts, incorrect material friction, insufficient gripper effort, or a controller that opens the grasp. For the underlying contact formulation, see the MuJoCo contact documentation and option reference.

Choose the contact pipeline

Use use_mujoco_contacts=True for the simplest baseline. It selects MuJoCo’s internal collision detection and cannot be combined with collision_cfg.

Set use_mujoco_contacts=False only when the task needs Newton’s collision pipeline, such as for non-convex meshes, SDF or hydroelastic contacts. Configure NewtonCollisionPipelineCfg on NewtonCfg, then size its collision buffers from observed overflow or missing-contact evidence. collision_decimation matters only for this pipeline and when more than one solver substep is used; refresh contacts more often for fast-changing contacts before reducing work for performance.

Optimize only after validation

After the task is stable over its full distribution, measure the cost of each change and retain only work that improves the recorded outcome. Reduce excess capacity, line-search work, collision refresh, substeps, and state synchronization frequency one at a time.

ccd_iterations is a GJK/EPA collision-convergence cap, not a PhysX-style continuous-collision-detection switch. Increase it only for a warning or a reproducible complex-geometry collision failure. Keep update_data_interval=1 until resets, Newton-side state writes, contact reporting, and sensors are verified; a larger interval reduces synchronization work but can expose stale data. save_to_mjcf, use_mujoco_cpu, and disable_contacts are diagnostic tools, not production tuning targets.

The diagnose-first order is: validate the model and fixed reproduction; choose timestep and substeps; size capacities; validate convergence; tune contact behavior and the contact pipeline; then optimize measured costs.