MuJoCo Solver

SolverMuJoCo wraps mujoco_warp behind Newton’s standard solver interface. Newton uses compatible-release pins (~=) on both mujoco and mujoco-warp to keep the two version-aligned; see pyproject.toml for the current pins.

Because MuJoCo has its own modeling conventions, many Newton properties are mapped differently or not at all. The sections below describe which Newton concepts the solver supports, how each is mapped to MuJoCo, how state is exchanged at every step, and where each piece of the conversion lives in the source. MuJoCo-specific behavior that has no Newton-core equivalent is exposed through the custom-attribute namespace. A code pointers section at the bottom collects the most useful anchor points.

Note

References to mjModel / mjData fields below (e.g. mjData.contact, mjData.mocap_pos) use the canonical names from MuJoCo’s mjModel and mjData reference. mujoco_warp exposes the same fields on its GPU-resident analogues.

Joint types

Newton type	MuJoCo equivalent	Notes
FREE	mjJNT_FREE	Initial pose taken from body_q.
BALL	mjJNT_BALL	Per-axis actuators mapped via gear.
REVOLUTE	mjJNT_HINGE
PRISMATIC	mjJNT_SLIDE
D6	Up to 3 × mjJNT_SLIDE + 3 × mjJNT_HINGE	Each active linear/angular DOF becomes a separate MuJoCo joint with a _lin or _ang suffix; a numeric index is appended when more than one axis is active in the same group (e.g. _lin0, _lin1).
FIXED	(no joint)	The child body is nested directly under its parent. A fixed joint connecting to the world produces a mocap body, driven via mjData.mocap_pos / mjData.mocap_quat.
DISTANCE	(no joint)	The distance constraint is dropped, but the body bookkeeping is handled like a free body (counted in MuJoCo’s free-body slots).
ROD	unsupported	Not forwarded to MuJoCo.

Joint reference values (ref)

MuJoCo scalar joints (hinge and slide) may carry a reference value (MJCF ref, exposed as the mujoco.dof_ref custom attribute): the authored body poses correspond to qpos = ref, and MuJoCo interprets limits, position-actuator controls, and keyframes as absolute qpos values. Newton has no reference concept — its scalar joint coordinates are relative to the authored pose — so the two conventions are reconciled at the solver boundary:

• In Newton, joint_q, joint limits (joint_limit_lower / joint_limit_upper), and position targets (Control.joint_target_q) are relative to the authored pose. The MJCF importer and MuJoCo-converter USD importer shift authored joint ranges by -ref accordingly. joint_qd is unaffected because ref changes position coordinates only.

• MuJoCo-side quantities keep MuJoCo’s absolute convention: the solver adds ref back when it writes qpos, jnt_range, and position-actuator ctrl, so the compiled MuJoCo model and its runtime observables (qpos, sensors) match the authored MJCF and native MuJoCo exactly.

• Attributes in the mujoco.* custom-attribute namespace (for example dof_springref or authored actuator_ctrlrange) are native MuJoCo data and remain in MuJoCo’s absolute units.

Changing mujoco.dof_ref at runtime (via JOINT_REFERENCE_POSE_PROPERTIES or the broad JOINT_DOF_PROPERTIES) shifts exported qpos0, jnt_range, and position controls with the new reference. Native MuJoCo attributes remain absolute and are not shifted.

Geometry types

Newton type	MuJoCo equivalent	Notes
SPHERE	mjGEOM_SPHERE
CAPSULE	mjGEOM_CAPSULE
CYLINDER	mjGEOM_CYLINDER
BOX	mjGEOM_BOX
ELLIPSOID	mjGEOM_ELLIPSOID
PLANE	mjGEOM_PLANE	Must be attached to a static body (body=-1); attaching to a non-static body raises ValueError at conversion time. Planes are infinite for collision in MuJoCo regardless of size; the configured shape_scale only affects rendering, defaulting to 5 × 5 × 5 when unset.
HFIELD	mjGEOM_HFIELD	Heightfield data is stored normalized to [0, 1] on the Newton Heightfield source and forwarded as-is. The geom origin is shifted by min_z so the lowest point is at the correct world height.
MESH / CONVEX_MESH	mjGEOM_MESH	MuJoCo only supports convex collision meshes. Non-convex meshes are convex-hulled by MuJoCo’s compiler (not by Newton), which changes the collision boundary. The mesh source’s maxhullvert is forwarded.
CONE	mjGEOM_MESH	MuJoCo has no cone primitive, so Newton tessellates the cone into a 32-segment mesh at conversion time. Collision uses that convex polyhedral approximation. Changing shape_scale after construction is unsupported; recreate the solver to resize the cone. Eager shape-property notifications validate cone scales and raise ValueError on changes. This host-side check is skipped during CUDA graph capture and replay: keep cone scales fixed, and call notify_model_changed() with SHAPE_PROPERTIES outside capture to validate any preceding edits.
GAUSSIAN	unsupported	Not present in the MuJoCo geom-type map.

Sites (shapes with the SITE flag) are converted to MuJoCo sites — non-colliding reference frames used for sensor attachment and spatial tendon wrap anchors. Only SPHERE, CAPSULE, CYLINDER, and BOX are MuJoCo-native site geom types; other types silently fall back to SPHERE.

Several Newton collision features — for example non-convex trimesh, SDF-based contacts, and hydroelastic contacts — are not part of the MuJoCo geometry model. They are only available through Newton’s collision pipeline (see Collision pipeline below).

Joint-limit stiffness and damping

joint_limit_ke and joint_limit_kd are force-space gains (for example, N·m/rad and N·m·s/rad for revolute joints). MuJoCo converts solreflimit to an effective limit response using the owning DOF’s dof_invweight0 and the limit impedance parameter dmax = solimplimit[1]:

\[k_\mathrm{eff} = k_\mathrm{stored} / (\mathrm{dof\_invweight0} \cdot (1 - dmax))\]

To keep Newton’s force-space meaning, SolverMuJoCo first scales the direct stiffness/damping pair by factor = dof_invweight0 * (1 - dmax) and then converts that pair to MuJoCo’s positive (timeconst, dampratio) convention:

\[\begin{split}\begin{aligned} k_\mathrm{stored} &= ke \cdot factor \\ b_\mathrm{stored} &= kd \cdot factor \\ \mathrm{timeconst} &= 2 / b_\mathrm{stored} \\ \mathrm{dampratio} &= b_\mathrm{stored} / (2 \sqrt{k_\mathrm{stored}}) \end{aligned}\end{split}\]

The positive convention preserves the same unclamped force-space response as the equivalent direct stiffness/damping pair while allowing MuJoCo’s refsafe timestep clamp to soften limits that are too stiff for the step size. This update runs after MuJoCo has compiled or refreshed dof_invweight0. If joint_limit_ke <= 0 or joint_limit_kd <= 0, the solver restores MuJoCo’s default solreflimit value (0.02, 1.0).

MJCF- or USD-authored solreflimit values are already native MuJoCo parameters, so they are preserved verbatim through the model.mujoco.solreflimit custom attribute and are not rescaled. Neither MJCF import nor USD import through the MuJoCo schema derives generic joint_limit_ke or joint_limit_kd values from solreflimit; those gains retain Newton builder defaults or values supplied by a generic schema. An authored native value wins in SolverMuJoCo, while the generic gains remain available to other solvers. Imported joints that did not author solreflimit keep MuJoCo’s implicit default (0.02, 1.0) until either generic gain is configured or edited, including edits made before constructing the solver, at which point the Newton force-space scaling above is used. model.mujoco.solreflimit_gain_baseline records the generic gains seen at import time so that edits made before construction can be detected.

model.mujoco.solreflimit_mode records how solreflimit should be interpreted: Newton force-space gains, a raw authored MuJoCo value, or an implicit MJCF default. This extra flag is needed because the two-component solreflimit value alone cannot distinguish an unauthored value from an authored native value such as solreflimit="0 0" or USD mjc:solreflimit = [0, 0].

Authored raw solreflimit values are validated during solver construction and eager JOINT_DOF_FORCE_PROPERTIES or JOINT_DOF_PROPERTIES notifications on both backends. CUDA graph capture skips this host validation and leaves it pending until the next eager solref update. Graph replay does not validate values; call notify_model_changed() with either force-update flag outside capture after reassigning raw values to check them. Joint-transform notifications do not validate joint-limit parameters or consume pending validation.

On the MuJoCo Warp backend, runtime joint- and tendon-limit updates are stored in solver.mjw_model.jnt_solref, tendon_solref_lim, and tendon_range per world. The corresponding arrays in the host template solver.mj_model are not updated; inspect the Warp arrays for current values. The MuJoCo CPU backend keeps the host arrays synchronized.

Note

SolverMuJoCo(..., save_to_mjcf=path) is not a fully semantic round-trip for SOLREF_MODE_FORCE_SPACE joints. MJCF only stores solreflimit; it has no field for “use Newton force-space scaling with these gains”. The exporter therefore only writes solreflimit for SOLREF_MODE_RAW joints (where the authored value carries the full intent). joint_limit_ke / joint_limit_kd from the original SOLREF_MODE_FORCE_SPACE / SOLREF_MODE_MJCF_DEFAULT joints will not be preserved; reapply them on the rebuilt model if you need those force-space gains.

Shape-material contact stiffness and damping

shape_material_ke and shape_material_kd are force-space stiffness and damping (N/m and N·s/m), but their realized response depends on the active mapping. On the force-space Newton-contacts path, SolverMuJoCo mixes the two shapes’ gains and scales the pair by 1 - dmax and the sum of the bodies’ translational body_invweight0[..., 0] values before writing per-contact solref. Here dmax = solimp[1]. This inverse-weight scaling is Newton’s implemented force-space contract. For pyramidal contacts with condim > 1, the factor also includes mu**2 * (1 + mu**2) / (impratio * (condim - 1)) to account for the summed pyramid-edge normal response. Here mu is the final sliding friction after contact overrides. Elliptic and frictionless contacts retain the inverse-weight factor alone. The same mapping applies to positive per-contact stiffness and damping overrides; zero per-contact damping retains the critical-damping fallback.

This resting-contact approximation is not the full scalar contact effective mass \((J M^{-1} J^T)^{-1}\) for arbitrary articulated or off-center contacts.

model.mujoco.solref_mode (per shape) records how shape_material_ke / shape_material_kd and mujoco.solref combine, with the same three states as joint limits. The list describes existing model and implementation behavior; the constants are not a public selection API:

• SOLREF_MODE_FORCE_SPACE — Newton force-space gains; the per-contact factor above applies.

• SOLREF_MODE_RAW — forward the authored mujoco.solref (e.g. from an MJCF/USD import) unchanged.

• SOLREF_MODE_MJCF_DEFAULT — registered default; preserves MuJoCo’s compile-time contact dynamics and the legacy unit-mass numerical convert_solref(ke, kd, 1, 1) round-trip in geom_solref.

Contact solref conversion

For positive numeric ke and kd, the legacy convert_solref(ke, kd, 1, 1) mapping writes:

\[\mathrm{timeconst} = 2 / kd, \qquad \mathrm{dampratio} = kd / (2 \sqrt{ke})\]

Under this unit-mass numerical mapping, sqrt(ke) behaves like a frequency and holding the numerical damping ratio fixed requires kd to scale with sqrt(ke). This is not a dimensionally physical critical-damping rule for an arbitrary contact mass. The force-space path applies the implemented body_invweight0 factor above before the same conversion; the formula then describes the scaled numerical solref, not an exact Jacobian-derived contact response. See the implementation in newton/_src/solvers/mujoco/kernels.py and its force-space contact tests in newton/tests/test_mujoco_solver.py.

With MuJoCo’s default refsafe guard enabled, MuJoCo-Warp evaluates positive solref using max(timeconst, 2 * dt) for the active constraint without rewriting the stored value. Direct-format negative solref bypasses this clamp. Once a requested positive timeconst falls below that floor, raising the gains at a fixed damping ratio no longer hardens the effective response; reduce the step passed to step() instead. See MuJoCo’s refsafe option.

These SOLREF_MODE_* names describe internal mode values; they are not public Newton symbols. MJCF/USD import selects the appropriate authored/default mode automatically. Do not import the constants from newton._src to change the mode from user code.

Note

use_mujoco_contacts=True and the MuJoCo CPU backend do not apply the per-contact two-body factor — MuJoCo’s internal contact_params averages per-geom solref, which cannot reproduce the inverse-mass sum. SOLREF_MODE_FORCE_SPACE shapes fall back to the legacy convert_solref(ke, kd, 1, 1) approximation on those paths.

For parameter interpretation, stability tradeoffs, and task-oriented guidance, see MuJoCo-Warp Contact Tuning.

Contact friction solreffriction mapping

For SolverMuJoCo, kf maps to MuJoCo’s per-contact solreffriction when the MuJoCo Warp backend uses elliptic friction cones (use_mujoco_cpu=False, cone="elliptic") with Newton contacts (use_mujoco_contacts=False). It targets the force-space friction slope f = -kf * v below the Coulomb limit. The mapping is exact when the sum of MuJoCo’s translational body_invweight0 values matches the contact’s inverse effective mass (the relevant diagonal of \(J M^{-1} J^T\)) and the contact operates at its maximum impedance dmax. Very large kf saturates at MuJoCo’s refsafe stability bound, where the reference time constant is clamped to twice the timestep.

The two shapes’ kf values combine with the usual priority/solmix weighting. A resolved kf = 0 makes the contact frictionless (condim = 1), removing its sliding, torsional, and rolling friction rows. If a positive kf cannot produce a positive, finite inverse-weight denominator, solreffriction remains unset and MuJoCo inherits the normal solref. The mapping is independent of the shape’s solref_mode above, which only governs the normal-direction solref.

The slope is calibrated for the sliding friction rows. With condim > 3, the torsional and rolling rows share the same per-contact solreffriction and MuJoCo scales their regularization by the corresponding friction-coefficient ratios, so their effective damping deviates from kf accordingly.

Actuators

Newton’s per-DOF joint_target_mode creates MuJoCo general actuators:

Mode	MuJoCo actuator(s)
POSITION	One actuator: gainprm = [kp], biasprm = [0, -kp, -kd].
VELOCITY	One actuator: gainprm = [kd], biasprm = [0, 0, -kd].
POSITION_VELOCITY	Two actuators — a position actuator (gainprm = [kp], biasprm = [0, -kp, 0]) and a velocity actuator (gainprm = [kd], biasprm = [0, 0, -kd]).
NONE, EFFORT	No MuJoCo actuator created.

joint_effort_limit is forwarded as actfrcrange on the joint (prismatic, revolute, and D6) or as forcerange on the actuator (ball).

The full MuJoCo general-actuator model (arbitrary gain/bias/dynamics types and parameters, explicit transmission targets, ctrl/force/act ranges) is only reachable through the mujoco custom-attribute namespace. The newton.solvers.mujoco helpers add_actuator_general, add_actuator_motor, add_actuator_position, and add_actuator_velocity author complete actuator rows from a typed ActuatorTarget. Scalar and D6 joints support local or absolute DOF selection. Ball/free joints instead require an explicit native MuJoCo gear vector: ball-joint torque is in the child body frame; free-joint force is in the world frame at the body origin, and its torque is in the child body frame. These are different from Newton’s parent-frame, COM-based DOF convention. Use joint_f for forces in Newton’s DOF convention. Additional actuators declared this way are appended after the joint-target actuators — see SolverMuJoCo._init_actuators.

Equality constraints

Use EqType for MuJoCo equality constraint types.

Each row’s data[...] reference below points into MuJoCo’s equality.data array; slot layout depends on the constraint type.

Newton type	MuJoCo equivalent	Notes
CONNECT	mjEQ_CONNECT	Anchor forwarded in data[0:3].
WELD	mjEQ_WELD	Anchor forwarded in data[0:3], relative pose in data[3:10], torque scale in data[10].
JOINT	mjEQ_JOINT	Polynomial coefficients forwarded in data[0:5].
Mimic	mjEQ_JOINT	Added via set_joint_mimic(). Maps the offset / multiplier in joint_mimic_coeffs to polynomial coefficients. Revolute, prismatic, and D6 joints are supported. Multi-axis D6 relationships produce one equality per matching pair of scalar axes.

Newton’s core API does not expose equality constraints as a dedicated builder call. Construct them with the newton.solvers.mujoco helpers add_equality_connect, add_equality_weld, and add_equality_joint, then read or update finalized fields via model.mujoco.equality_constraint_*:

from newton.solvers import mujoco

mujoco.add_equality_connect(builder, body1, body2, anchor=(0.0, 0.0, 0.0))

The helpers write rows in the MuJoCo custom-attribute namespace. The equivalent lower-level form uses add_custom_values() with the mujoco:equality_constraint_* keys; fields that do not apply to connect constraints retain their registered defaults.

import newton
import warp as wp

builder.add_custom_values(
    **{
        "mujoco:equality_constraint_type": int(
            newton.solvers.SolverMuJoCo.EqType.CONNECT
        ),
        "mujoco:equality_constraint_body1": body1,
        "mujoco:equality_constraint_body2": body2,
        "mujoco:equality_constraint_anchor": wp.vec3(0.0, 0.0, 0.0),
        "mujoco:equality_constraint_enabled": True,
    }
)

mujoco:equality_constraint_world has references="world", so omitting it assigns the row to builder.current_world. Pass an explicit world index, including -1 for the global world, when that is the intended owner instead.

Loop closures

Loop-closing joints (see Loop closure for the general authoring pattern) are not emitted as MuJoCo joints; instead the solver constrains the relative motion of the two bodies according to the joint type:

• FIXED — all 6 relative DOFs constrained (relative position and orientation locked).

• REVOLUTE — 5 DOFs constrained; one rotational DOF about the hinge axis remains free.

• BALL — the 3 translational DOFs constrained; all 3 rotational DOFs remain free.

Other joint types used as loop closures (PRISMATIC, FREE, DISTANCE, ROD) emit a warning and are silently skipped — the loop is not closed. A D6 is dispatched by its degrees of freedom: one angular axis behaves as a revolute closure and three as a ball closure; any other configuration is skipped.

Only the kinematic coupling implied by the joint type is enforced. Any drive (joint_target_q / joint_target_qd, PD gains, control.joint_f), joint limits, armature, friction, and effort/velocity limits authored on the loop-closing joint are ignored by SolverMuJoCo. Loop-joint DOFs and coordinates are excluded from MuJoCo’s nq / nv.

Tendons

Newton’s core API does not currently expose tendons (fixed or spatial) as first-class concepts. They are implemented through the MuJoCo custom-attribute namespace: populated on import from MJCF/USD and parsed into MuJoCo’s tendon structures by SolverMuJoCo._init_tendons. To author tendons programmatically, use add_tendon_fixed and add_tendon_spatial from newton.solvers.mujoco. Spatial tendons support site, geom, and pulley wrap elements; any other wrap type and any degenerate tendon definition produces a warning and is skipped rather than raising.

For force-based limit gains, set model.mujoco.tendon_limit_ke (stiffness [N/m]) and tendon_limit_kd (damping [N s/m]), select force-space authoring with tendon_solref_limit_mode = 0, then notify TENDON_PROPERTIES. For angular tendon coordinates, the corresponding units are [N m/rad] and [N m s/rad]. The solver converts these gains to solreflimit using tendon inverse inertia and impedance, and refreshes the conversion after inertia changes, as it does for joint limits. MuJoCo impedance and timestep clamping still affect transient response.

tendon_solref_limit_mode follows the joint-limit authoring convention: 0 selects Newton force gains, 1 preserves authored MuJoCo parameters, and 2 uses MuJoCo’s implicit default. Tendons default to mode 1 and report their equivalent force gains after solver initialization. In force-space mode, zero stiffness disables the limit without changing the authored tendon_range. Limit damping is independent of passive tendon_damping. Tendon limits must already be enabled in the imported model.

model.mujoco.tendon_limit_ke.fill_(100.0)
model.mujoco.tendon_limit_kd.fill_(20.0)
model.mujoco.tendon_solref_limit_mode.zero_()  # Newton force-space mode
solver.notify_model_changed(newton.ModelFlags.TENDON_PROPERTIES)

Collision pipeline

SolverMuJoCo uses MuJoCo’s built-in collision detection by default. Construct it with use_mujoco_contacts=False to feed contacts computed by Newton’s own collision pipeline into step() instead. Newton’s pipeline supports non-convex meshes, SDF-based contacts, and hydroelastic contacts, which are not available through MuJoCo’s collision detection.

Collision filtering

MuJoCo gives every geom two 32-bit masks, contype and conaffinity. Together, these masks decide whether two geoms are allowed to collide. For a candidate pair a, b, the mask test passes when (contype_a & conaffinity_b) != 0 or (contype_b & conaffinity_a) != 0. MuJoCo then applies other selection rules, including same-body suppression and body-wide <exclude> elements; explicit <pair> elements bypass the automatic mask test. See MuJoCo’s collision selection documentation and the geom mask attributes.

Importing MJCF masks.

parse_mjcf() resolves inherited contype and conaffinity values and determines which shape pairs may collide. It stores the same result in Newton collision groups and explicit excluded pairs. The original 32-bit values are also retained as model.mujoco.contype and model.mujoco.conaffinity custom attributes for a lossless round trip back to MuJoCo.

A mask domain is the set of shapes whose mask bits were authored together. Each parse_mjcf() call creates a new domain and records it in the internal model.mujoco.collision_mask_domain attribute. The domain is only a source label. It is not another collision mask and does not enable or disable contacts. When add_builder() combines separately built models, it gives the copied domains new IDs so they remain distinct from domains already in the destination builder.

Choosing masks for a MuJoCo solver.

With use_mujoco_contacts=True, preserved source masks are forwarded verbatim only when every selected collision shape has masks from the same domain and those masks already enforce all active Newton pair filters. Same-body filtering and imported body-wide <exclude> elements also count as enforced. This path preserves the source MJCF exactly. For a single import, the original masks therefore remain the source of truth even if its Newton collision groups are later edited.

A native shape, shapes from more than one domain, or a new Newton pair filter can make the original masks unsafe to reuse. The solver then lists the shape pairs that Newton allows and creates new MuJoCo masks that reproduce that list.

Example: combining two MJCF files.

Suppose file A and file B both use bit 0. In file A, bit 0 may control contacts between its floor and spheres. File B may reuse bit 0 for its own shapes. The files were authored independently, so that shared number says nothing about how a shape from A should interact with a shape from B.

After both files are added to one builder, Newton’s collision groups and excluded pairs define those new cross-file interactions. Copying the original masks would make MuJoCo treat bit 0 as one global rule and could allow or block the wrong cross-file pairs. Because the shapes have different domains, the solver instead creates new masks from Newton’s final list of allowed pairs.

Compiling Newton filtering to MuJoCo masks.

MuJoCo provides only 32 mask bits. One bit can encode all collisions between one set of shapes and another set. In graph terminology, that rule is a complete bipartite graph, or biclique. The solver tries to reproduce Newton’s full list of allowed pairs using at most 32 such rules. It is guaranteed to find an exact result for up to 33 selected shapes and often handles much larger models whose collision groups have a regular structure.

If the rules do not fit in 32 bits, the solver uses the established legacy graph-color approximation, which may allow extra contacts. Finding an exact result requires checking every shape pair, so models above 256 selected shapes or 1,024 explicit excluded pairs skip directly to that fallback.

Margin and gap mapping

shape_margin maps to MuJoCo geom_margin and shape_gap maps to geom_gap; authored contact-pair values similarly map to pair_margin and pair_gap. The margin mapping is subject to Margin zeroing below. The solver forwards gap values at construction and runtime property updates. MuJoCo reports surface distances in (margin, margin + gap] as inactive contacts without contact force. See margin and gap semantics for Newton’s contact geometry and MuJoCo’s margin and gap model for the three contact regimes.

MJCF and USD margin/gap values use direct MuJoCo 3.9+ semantics. Pass legacy_margin_gap=True to add_mjcf() or add_usd() only when reproducing Newton’s pre-3.9 import translation.

Multi-contact CCD. Constructing SolverMuJoCo with enable_multiccd=True allows up to four contact points per geom pair instead of one. Pairs where either geom has non-zero MuJoCo geom_margin still fall back to a single contact regardless of the flag (see Margin zeroing below for how Newton’s shape_margin is forwarded to it). MuJoCo Warp currently remains single-contact for cylinder–box; see Geometry-Pair Contact Behavior.

Margin zeroing. mujoco_warp rejects non-zero geom margins on box-box pairs (its default NATIVECCD path) and on any box/mesh pair when enable_multiccd=True. To stay compatible SolverMuJoCo zeroes geom_margin model-wide at compile time whenever a box geom exists, or whenever enable_multiccd=True is combined with mesh geoms; geoms with non-zero authored margins emit a warning when use_mujoco_contacts=True. The Newton model’s shape_margin array is left untouched, and when use_mujoco_contacts=False the authored margins are restored at runtime through update_geom_properties_kernel.

Contact pairs

Newton’s core API does not expose explicit MuJoCo-style <pair> contact overrides. They are implemented through the MuJoCo custom-attribute namespace and parsed into MuJoCo’s geom-pair contact structures by SolverMuJoCo._init_pairs. To author a pair programmatically, use add_contact_pair from newton.solvers.mujoco.

Multi-world support

Constructing SolverMuJoCo with separate_worlds=True (the default for GPU mode with multiple worlds) builds a MuJoCo model from the first world only and replicates it across all worlds via mujoco_warp. This requires all Newton worlds to be structurally identical (same bodies, joints, and shapes); SolverMuJoCo validates this at construction and raises ValueError on a mismatch.

Bodies, joints, equality constraints, and mimic relationships cannot have a negative world index — assigning any of them to the global world raises ValueError. Only shapes may live in the global world (-1); they are shared across all worlds without replication.

Runtime state synchronization

Each call to step() goes through the same three-phase cycle:

1. Push Newton → MuJoCo. SolverMuJoCo._apply_mjc_control and SolverMuJoCo._update_mjc_data transfer the Newton State and Control inputs to MuJoCo’s working data. When use_mujoco_contacts=False, Newton-side contacts are also converted before the integrator runs. The joint-state re-sync frequency can be controlled via the update_data_interval kwarg for substepping schemes.

2. Integrate. mujoco_warp steps the MuJoCo model forward by dt.

3. Pull MuJoCo → Newton. SolverMuJoCo._update_newton_state populates the output State from the integrated MuJoCo data. Kinematic roots pass through unchanged from state_in (see Kinematic links and fixed roots).

Contacts are not pulled back into a Newton Contacts object automatically. Call update_contacts() when you need contact points, forces, or material indices in Newton form.

Separated speculative contacts

With use_mujoco_contacts=False, Newton’s collision pipeline can generate separated candidates using velocity expansion. By default, MuJoCo activates constraints only inside the authored collision margin. Generating a candidate alone therefore does not prevent an object from crossing a thin collider in one dynamics step.

Set use_speculative_contacts=True to add frictionless normal constraints for separated candidates. Their target bounds closing velocity by the current clearance divided by the physics timestep. Collision margins and the material response of penetrating contacts retain their authored values. Friction begins when the surfaces enter the authored margin.

Experimental

The SolverMuJoCo(use_speculative_contacts=True) mode may change without prior notice. It requires Newton contacts on the MuJoCo Warp backend and Euler or implicitfast integration. It does not provide continuous collision detection or guarantee zero penetration: candidate coverage, rotation, contact compliance, forces, and timestep still matter.

This is a runtime solver option, like the choice of contact backend. It does not add an asset-authoring attribute or change the USD collision schema.

Pass a velocity-expansion horizon to the collision pipeline before each step:

pipeline = newton.CollisionPipeline(model, speculative_contact_gap_max=0.05)
contacts = pipeline.contacts()
solver = newton.solvers.SolverMuJoCo(
    model, use_mujoco_contacts=False, use_speculative_contacts=True
)
pipeline.collide(state_in, contacts, dt=dt)
solver.step(state_in, state_out, control, contacts, dt)

For scheduled collision refreshes, the expansion horizon must cover the interval until the next refresh. The solver’s velocity bound uses each individual dynamics timestep. Speculative constraints can consume additional constraint rows, so check contact and constraint capacities for the scene.

Push, pull, and contact-conversion are implemented by SolverMuJoCo._apply_mjc_control, SolverMuJoCo._update_newton_state, and update_contacts(), using kernels from newton/_src/solvers/mujoco/kernels.py — see Code pointers for the full anchor list.

Solver options

MuJoCo solver parameters follow a three-level resolution priority:

1. Constructor argument passed to SolverMuJoCo — one value, applied to all worlds. The full list of kwargs, their types, and their defaults is documented on the class itself.

2. Custom attribute (model.mujoco.<option>) — supports per-world values. Typically populated automatically by USD or MJCF import.

3. Default — if neither of the above is set, the MuJoCo default is used, with one Newton-opinionated exception: integrator defaults to implicitfast (MuJoCo’s default is euler) for better stability on stiff systems.

These values are read once during SolverMuJoCo construction. Editing model.mujoco.<option> afterwards has no effect — the resolved value is already baked into the underlying MuJoCo model.

See MuJoCo’s solver documentation and <option> XML reference for what each parameter does and when to tune it.

Sleeping

MuJoCo Warp can exclude stationary constraint islands from collision detection and the compact Newton solver. Newton keeps this optimization disabled by default. Enable it when simulating many passive objects that spend substantial time at rest. Sleeping adds island bookkeeping and uses the compact-solver path even while everything remains awake, so scenes in which most degrees of freedom remain awake can be slower than with sleeping disabled. Benchmark representative workloads before enabling it:

solver = SolverMuJoCo(
    model,
    enable_sleeping=True,
    sleep_tolerance=0.01,
)

Sleeping is only supported by Newton’s MuJoCo Warp GPU path. It requires solver="newton" and use_mujoco_contacts=True so MuJoCo Warp’s collision pipeline can wake sleeping bodies, and it does not support the RK4 integrator. Unsupported combinations raise ValueError during solver construction. When an imported MJCF contains <option><flag sleep="enable"/></option>, leaving enable_sleeping as None honors that setting. An explicit constructor value takes precedence.

sleep_tolerance is the scaled generalized-velocity threshold [m/s] below which an island becomes eligible to sleep. It follows the normal Solver options resolution order, including per-world model.mujoco.sleep_tolerance values. The default is 0.001.

MuJoCo’s per-tree body/sleep policy is available as the body-frequency model.mujoco.sleep_policy custom attribute and is imported from MJCF. The supported values are AUTO, NEVER, ALLOWED, and INIT. The policy must be assigned to the moving root body of a MuJoCo kinematic tree. For a programmatically built model, register the MuJoCo custom attributes before adding the body:

builder = newton.ModelBuilder()
SolverMuJoCo.register_custom_attributes(builder)
root = builder.add_link(
    custom_attributes={
        "mujoco:sleep_policy": SolverMuJoCo.SleepPolicy.INIT,
    },
)

INIT makes the tree start asleep and is the intended way to construct a solver with compact nvmax storage. The setting applies to the shared model, so replicated worlds receive the same initial tree policies. Their default joint velocities must also match because MuJoCo Warp uses one shared initial sleep state; solver construction rejects differing per-world defaults.

nvmax sizes the compact solver’s active-DOF workspace per world. If it is None, MuJoCo Warp uses the model’s full nv. This is the safe starting point but does not reduce compact-workspace memory. Tune a smaller value to the maximum number of DOFs expected to be awake simultaneously. The capacity must include every DOF that is awake in the initial MuJoCo state; Newton rejects smaller values before allocating solver data. nvmax is rejected when sleeping is disabled because MuJoCo Warp would otherwise allocate unused compact-solver workspace. If more than nvmax DOFs become active later, MuJoCo Warp sets the NVMAX bit in solver.mjw_data.overflow; increase nvmax and recreate the solver.

MuJoCo Warp automatically wakes islands for applied forces and contacts. Actuated trees are not allowed to sleep by default. If their sleep policy is explicitly changed to allow sleeping, changing actuator controls alone does not wake them; apply a force or set a nonzero velocity first. Newton-side joint-position edits wake only the affected sleeping trees. reset() restores the initial sleep state in selected worlds, while notify_model_changed() wakes all worlds after model-property updates. The sleeping path supports whole-step CUDA graph capture.

See MuJoCo’s sleeping-islands documentation and MuJoCo Warp compact-solver guide for the underlying sleep policy, wake triggers, and nvmax tuning guidance.

MuJoCo-specific parameters in USD and MJCF

MuJoCo has parameters with no counterpart in Newton’s core API. ModelBuilder handles them during MJCF / USD import via two mechanisms.

Custom-attribute namespace. A dedicated mujoco custom-attribute namespace (model.mujoco.<name>) is populated from MJCF elements and from attributes in the OpenUSD MuJoCo schema (mjc:*). To enable the namespace, call register_custom_attributes() on the ModelBuilder before adding anything to it:

import newton
from newton.solvers import SolverMuJoCo

builder = newton.ModelBuilder()
SolverMuJoCo.register_custom_attributes(builder)
# ...then add anything (e.g. import MJCF / USD, add joints, ...)
model = builder.finalize()

The authoritative list of registered attributes — names, defaults, dtypes, MJCF / USD source names, and the category each belongs to — is the body of register_custom_attributes() itself. See Custom Attributes for how Newton’s custom-attribute system works in general.

Direct mapping to Newton built-ins. Some MuJoCo-specific attributes are mapped onto Newton’s built-in properties during import (rather than the mujoco namespace). The MJCF parser handles these inline (newton/_src/utils/import_mjcf.py); USD goes through SchemaResolverMjc (newton/_src/usd/schemas.py). Native MuJoCo solver parameters such as MJCF solreflimit or USD mjc:solreflimit remain in the mujoco namespace and do not overwrite Newton’s generic force-space joint-limit gains.

MuJoCo joint damping maps to joint_damping. When importing MuJoCo-authored USD, opt into that mapping explicitly:

from newton.usd import SchemaResolverMjc, SchemaResolverNewton

builder.add_usd(
    stage,
    schema_resolvers=[SchemaResolverMjc(), SchemaResolverNewton()],
)

Registering MuJoCo custom attributes alone enables the model.mujoco namespace but does not map mjc:damping to the built-in property.

Unsupported MuJoCo features

The sections above describe what Newton forwards into MuJoCo. In the other direction, MuJoCo has several modeling concepts that are not imported when loading an MJCF or USD asset into Newton, and that SolverMuJoCo does not reconstruct during conversion:

• Sensors (<sensor> — force/torque, IMU, gyro, accelerometer, rangefinder, touch, camera-based, …). Newton has its own sensor pipeline (Sensors) that is independent of the MuJoCo solver.

• Cameras and lights declared in MJCF/USD. Newton uses its own viewer and lighting pipeline; camera/light primitives in the source asset are ignored.

• Keyframes (<keyframe>) — MuJoCo’s saved-state / reset mechanism is not imported.

• Composite and flex (<composite>, <flex>) — MuJoCo’s built-in deformables and soft bodies. Newton has dedicated solvers for cloth, MPM, and FEM; they are not part of the MuJoCo integration.

• Skinned meshes (<skin>) — visualization-only, not imported.

• User plugins (<plugin>) — MuJoCo’s plugin mechanism for custom passive forces or dynamics is not supported.

• User data and arbitrary custom elements (<custom>, <numeric>, <text>) — not imported. Newton-specific user data should use the Newton custom-attribute system instead.

• Actuator transmissions — joint, jointinparent, tendon, site, body, and slidercrank transmissions are supported (see TrnType for the enum).

Smaller limitations are documented inline where they are most relevant — see Caveats below for collision-radius, convex-hull fallback, and velocity limits; and the unsupported rows in Joint types and Geometry types.

Caveats

shape_collision_radius is ignored.

MuJoCo computes bounding-sphere radii (geom_rbound) internally from the geometry definition. Newton’s shape_collision_radius is not forwarded.

Non-convex meshes are convex-hulled.

MuJoCo only supports convex collision geometry. Non-convex MESH shapes are automatically convex-hulled at conversion time, changing the effective collision boundary.

Velocity limits are not forwarded.

Newton’s joint_velocity_limit has no MuJoCo equivalent and is ignored.

Kinematic-root armature override.

DOFs of kinematic articulation roots have their joint_armature replaced with a very large internal value (1e10) so MuJoCo treats them as effectively prescribed. The user-supplied armature on those DOFs is silently discarded. See Kinematic links and fixed roots.

Collision filtering has a 32-bit capacity.

The solver creates MuJoCo masks that reproduce Newton’s allowed collision pairs when they fit in 32 bits. See Collision filtering for the behavior of imported masks and the warned fallback used when the rules do not fit.

Kinematic links and fixed roots

Newton only allows is_kinematic=True on articulation roots, so a “kinematic link” in this section always means a kinematic root body. Any descendants of that root can still be dynamic and are converted normally.

At runtime, SolverMuJoCo keeps kinematic roots user-prescribed rather than dynamically integrated:

• When converting MuJoCo state back to Newton, the previous Newton joint_q and joint_qd values are passed through for kinematic roots instead of being overwritten from MuJoCo’s integrated qpos and qvel.

• Applied body wrenches and joint forces targeting kinematic bodies are ignored on the MuJoCo side.

• Kinematic bodies still participate in contacts, so they can act as moving or fixed obstacles for dynamic bodies.

During Newton-to-MuJoCo conversion (at SolverMuJoCo construction), roots are mapped by joint type:

• Kinematic roots with non-fixed joints become ordinary MuJoCo joints with the same Newton joint type and DOFs. A very large internal armature is assigned to those DOFs so MuJoCo treats them as prescribed, effectively infinite-mass coordinates.

• Roots attached to world with a fixed joint become MuJoCo mocap bodies (whether kinematic or not). MuJoCo has no joint coordinates for a fixed root, so Newton drives the pose through mjData.mocap_pos and mjData.mocap_quat instead. A D6 root with all axes locked (e.g. imported from a generic USD PhysicsJoint) is treated the same way.

• World-attached shapes that are not part of an articulation remain ordinary static MuJoCo geometry rather than mocap bodies.

If you edit joint_X_p or joint_X_c for a fixed-root articulation after constructing the solver, call notify_model_changed() with the JOINT_PROPERTIES flag to synchronize the updated fixed-root poses into MuJoCo.

Updating joint force properties

Use JOINT_DOF_FORCE_PROPERTIES with notify_model_changed() to publish joint friction, damping, target gains/modes, effort limits, passive stiffness, and limit coefficients/bounds. This includes the MuJoCo solreffriction, solimpfriction, dof_passive_stiffness, limit_margin, solimplimit, and solreflimit custom attributes. Optional attributes that are absent retain their solver values. General MuJoCo actuator properties still use ACTUATOR_PROPERTIES.

The force flag skips mass-constant recomputation, reference-pose updates, tendon-limit refreshes, and contact-cache invalidation. Joint-limit coefficients use the cached inverse weights. Compiled actuator length ranges are preserved, and pending tendon-limit edits are left unpublished. When sleeping is enabled, updated parameters wake all worlds. The MuJoCo Warp path supports CUDA graph capture; the MuJoCo CPU backend copies values to its host model and cannot be captured.

Use JOINT_DOF_INERTIAL_PROPERTIES for joint_armature changes. Reference-pose changes, including MuJoCo dof_ref and dof_springref, use JOINT_REFERENCE_POSE_PROPERTIES. These paths recompute constants; reference updates also shift limit ranges to the new reference. Both flags are intended for reset-time or domain-randomization changes. Constant recomputation is substantially more expensive than force updates, so avoid using either flag every simulation step. JOINT_PROPERTIES only publishes joint transforms and axes, without recomputing constants or applying pending reference edits. Combine flags with | when several categories change. The existing JOINT_DOF_PROPERTIES flag retains its integer value and full-update behavior, including force, armature, and reference properties.

Tendon-limit dependency: Notifications that recompute constants also refresh tendon limits using the current model.mujoco limit modes, gains, raw solref values, and ranges. Those pending edits are therefore published even without TENDON_PROPERTIES. This includes joint inertial/reference updates and the broad joint-DOF, body, body-inertial, and actuator notifications. Publish tendon edits explicitly with TENDON_PROPERTIES before these updates rather than relying on them to preserve pending tendon-limit changes. Force-only joint notifications do not recompute constants and leave tendon limits unchanged.

For example, actuator models with load-dependent friction can compute effective budgets and publish them in the same graph as the simulation step. Given device arrays friction_budget and damping_budget with one entry per Newton DOF:

with wp.ScopedCapture(device=model.device) as capture:
    wp.copy(model.joint_friction, friction_budget)
    wp.copy(model.joint_damping, damping_budget)
    solver.notify_model_changed(newton.ModelFlags.JOINT_DOF_FORCE_PROPERTIES)
    solver.step(state_in, state_out, control, contacts, dt)

The budget computation can precede these copies in the same graph. For an actuator controlling only some DOFs, scatter into those Newton model entries before notifying the solver; other entries retain their authored values. No MuJoCo DOF mapping or backend array access is needed.

The model arrays hold the effective total friction and damping. Publication replaces solver values rather than adding an actuator contribution to authored passive damping. Retain any authored baseline separately when combining contributions. Apply reset-time inertia and configuration changes first, then compute and publish the next step’s budgets. Full notifications also copy the current budgets. This API synchronizes existing runtime model arrays; it does not add actuator external-load feedback or authored USD properties.

Code pointers

For readers navigating the source, the following symbols are the most useful entry points. Symbols with a leading underscore are internal entry points — stable enough to navigate to, but not part of the public API and subject to change.

• register_custom_attributes() — authoritative registry of every MuJoCo-specific custom attribute and frequency.

• step() — per-step integration entry point.

• SolverMuJoCo._convert_to_mjc — Newton Model (and optional State) → MuJoCo mjModel / mjData (orchestrator).

• SolverMuJoCo._init_pairs / _init_actuators / _init_tendons — category-specific parsers that consume the MuJoCo custom attributes.

• SolverMuJoCo._apply_mjc_control, SolverMuJoCo._update_mjc_data, and SolverMuJoCo._update_newton_state — per-step control, data, and state sync between Newton and MuJoCo.

• update_contacts() — explicit pull of MuJoCo’s resolved contacts into a Newton Contacts object (default per-step path does not pull contacts back).

• notify_model_changed() — re-synchronize MuJoCo state after editing the Newton Model (e.g. fixed-root pose changes via joint_X_p / joint_X_c).

• newton/_src/solvers/mujoco/kernels.py — Warp kernels for coordinate, contact, and state conversion (quat_wxyz_to_xyzw, convert_mj_coords_to_warp_kernel, convert_newton_contacts_to_mjwarp_kernel, convert_solref, …).

• SchemaResolverMjc (newton/_src/usd/schemas.py) — USD mjc:* attribute → Newton built-in property mapping.