newton.solvers.SolverMuJoCo#

class newton.solvers.SolverMuJoCo(model, *, separate_worlds=None, njmax=None, nconmax=None, iterations=None, ls_iterations=None, ccd_iterations=None, sdf_iterations=None, sdf_initpoints=None, solver=None, integrator=None, cone=None, jacobian=None, impratio=None, tolerance=None, ls_tolerance=None, ccd_tolerance=None, density=None, viscosity=None, wind=None, magnetic=None, use_mujoco_cpu=False, disable_contacts=False, update_data_interval=1, save_to_mjcf=None, ls_parallel=False, use_mujoco_contacts=True, include_sites=True, skip_visual_only_geoms=True)[source]#

Bases: SolverBase

This solver provides an interface to simulate physics using the MuJoCo physics engine, optimized with GPU acceleration through mujoco_warp. It supports both MuJoCo and mujoco_warp backends, enabling efficient simulation of articulated systems with contacts and constraints.

Note

This solver requires mujoco_warp and its dependencies to be installed.
For installation instructions, see the mujoco_warp repository.
shape_collision_radius from Newton models is not used by MuJoCo. Instead, MuJoCo computes bounding sphere radii (geom_rbound) internally based on the geometry definition.

Joint support:

Supported joint types: PRISMATIC, REVOLUTE, BALL, FIXED, FREE, D6. DISTANCE and CABLE joints are not supported.
joint_armature, joint_friction, joint_effort_limit, joint_limit_ke/joint_limit_kd, joint_target_ke/joint_target_kd, joint_target_mode, and joint_f are supported.
Equality constraints (CONNECT, WELD, JOINT) and mimic constraints (REVOLUTE and PRISMATIC only) are supported.
joint_velocity_limit and joint_enabled are not supported.

See Joint Feature Support for the full comparison across solvers.

Example

solver = newton.solvers.SolverMuJoCo(model)

# simulation loop
for i in range(100):
    solver.step(state_in, state_out, control, contacts, dt)
    state_in, state_out = state_out, state_in

Debugging#

To debug the SolverMuJoCo, you can save the MuJoCo model that is created from the newton.Model in the constructor of the SolverMuJoCo:

solver = newton.solvers.SolverMuJoCo(model, save_to_mjcf="model.xml")

This will save the MuJoCo model as an MJCF file, which can be opened in the MuJoCo simulator.

It is also possible to visualize the simulation running in the SolverMuJoCo through MuJoCo’s own viewer. This may help to debug the simulation and see how the MuJoCo model looks like when it is created from the Newton model.

import newton

solver = newton.solvers.SolverMuJoCo(model)

for _ in range(num_frames):
    # step the solver
    solver.step(state_in, state_out, control, contacts, dt)
    state_in, state_out = state_out, state_in

    solver.render_mujoco_viewer()

class CtrlSource(*values)#

Bases: IntEnum

Control source for MuJoCo actuators.

Determines where an actuator gets its control input from:

JOINT_TARGET: Maps from Newton’s joint_target_pos/joint_target_vel arrays
CTRL_DIRECT: Uses control.mujoco.ctrl directly (for MuJoCo-native control)

CTRL_DIRECT = 1#

JOINT_TARGET = 0#

class CtrlType(*values)#

Bases: IntEnum

Control type for MuJoCo actuators.

For JOINT_TARGET mode, determines which target array to read from:

POSITION: Maps from joint_target_pos, syncs gains from joint_target_ke. For POSITION-only actuators, also syncs damping from joint_target_kd. For POSITION_VELOCITY mode, kd is handled by the separate velocity actuator.
VELOCITY: Maps from joint_target_vel, syncs gains from joint_target_kd
GENERAL: Used with CTRL_DIRECT mode for motor/general actuators

GENERAL = 2#

POSITION = 0#

VELOCITY = 1#

class TrnType(*values)#

Bases: IntEnum

Transmission type values for MuJoCo actuators.

BODY = 4#

JOINT = 0#

JOINT_IN_PARENT = 1#

SITE = 3#

SLIDERCRANK = 5#

TENDON = 2#

UNDEFINED = -1#

classmethod import_mujoco()#: Import the MuJoCo Warp dependencies and cache them as class variables.

classmethod register_custom_attributes(builder)#

Declare custom attributes to be allocated on the Model object within the mujoco namespace. Note that we declare all custom attributes with the newton.ModelBuilder.CustomAttribute.usd_attribute_name set to "mjc" here to leverage the MuJoCo USD schema where attributes are named "mjc:attr" rather than "newton:mujoco:attr".

__init__(model, *, separate_worlds=None, njmax=None, nconmax=None, iterations=None, ls_iterations=None, ccd_iterations=None, sdf_iterations=None, sdf_initpoints=None, solver=None, integrator=None, cone=None, jacobian=None, impratio=None, tolerance=None, ls_tolerance=None, ccd_tolerance=None, density=None, viscosity=None, wind=None, magnetic=None, use_mujoco_cpu=False, disable_contacts=False, update_data_interval=1, save_to_mjcf=None, ls_parallel=False, use_mujoco_contacts=True, include_sites=True, skip_visual_only_geoms=True)#

Solver options (e.g., impratio) follow this resolution priority:

Constructor argument - If provided, same value is used for all worlds.
Newton model custom attribute (model.mujoco.<option>) - Supports per-world values.
MuJoCo default - Used if neither of the above is set.

Parameters:

model (Model) – The model to be simulated.
separate_worlds (bool | None) – If True, each Newton world is mapped to a separate MuJoCo world. Defaults to not use_mujoco_cpu.
njmax (int | None) – Maximum number of constraints per world. If None, a default value is estimated from the initial state. Note that the larger of the user-provided value or the default value is used.
nconmax (int | None) – Number of contact points per world. If None, a default value is estimated from the initial state. Note that the larger of the user-provided value or the default value is used.
iterations (int | None) – Number of solver iterations. If None, uses model custom attribute or MuJoCo’s default (100).
ls_iterations (int | None) – Number of line search iterations for the solver. If None, uses model custom attribute or MuJoCo’s default (50).
ccd_iterations (int | None) – Maximum CCD iterations. If None, uses model custom attribute or MuJoCo’s default (35).
sdf_iterations (int | None) – Maximum SDF iterations. If None, uses model custom attribute or MuJoCo’s default (10).
sdf_initpoints (int | None) – Number of SDF initialization points. If None, uses model custom attribute or MuJoCo’s default (40).
solver (int | str | None) – Solver type. Can be “cg” or “newton”, or their corresponding MuJoCo integer constants. If None, uses model custom attribute or Newton’s default (“newton”).
integrator (int | str | None) – Integrator type. Can be “euler”, “rk4”, or “implicitfast”, or their corresponding MuJoCo integer constants. If None, uses model custom attribute or Newton’s default (“implicitfast”).
cone (int | str | None) – The type of contact friction cone. Can be “pyramidal”, “elliptic”, or their corresponding MuJoCo integer constants. If None, uses model custom attribute or Newton’s default (“pyramidal”).
jacobian (int | str | None) – Jacobian computation method. Can be “dense”, “sparse”, or “auto”, or their corresponding MuJoCo integer constants. If None, uses model custom attribute or MuJoCo’s default (“auto”).
impratio (float | None) – Frictional-to-normal constraint impedance ratio. If None, uses model custom attribute or MuJoCo’s default (1.0).
tolerance (float | None) – Solver tolerance for early termination. If None, uses model custom attribute or MuJoCo’s default (1e-8).
ls_tolerance (float | None) – Line search tolerance for early termination. If None, uses model custom attribute or MuJoCo’s default (0.01).
ccd_tolerance (float | None) – Continuous collision detection tolerance. If None, uses model custom attribute or MuJoCo’s default (1e-6).
density (float | None) – Medium density for lift and drag forces. If None, uses model custom attribute or MuJoCo’s default (0.0).
viscosity (float | None) – Medium viscosity for lift and drag forces. If None, uses model custom attribute or MuJoCo’s default (0.0).
wind (tuple | None) – Wind velocity vector (x, y, z) for lift and drag forces. If None, uses model custom attribute or MuJoCo’s default (0, 0, 0).
magnetic (tuple | None) – Global magnetic flux vector (x, y, z). If None, uses model custom attribute or MuJoCo’s default (0, -0.5, 0).
use_mujoco_cpu (bool) – If True, use the MuJoCo-C CPU backend instead of mujoco_warp.
disable_contacts (bool) – If True, disable contact computation in MuJoCo.
update_data_interval (int) – Frequency (in simulation steps) at which to update the MuJoCo Data object from the Newton state. If 0, Data is never updated after initialization.
save_to_mjcf (str | None) – Optional path to save the generated MJCF model file.
ls_parallel (bool) – If True, enable parallel line search in MuJoCo. Defaults to False.
use_mujoco_contacts (bool) – If True, use the MuJoCo contact solver. If False, use the Newton contact solver (newton contacts must be passed in through the step function in that case).
include_sites (bool) – If True (default), Newton shapes marked with ShapeFlags.SITE are exported as MuJoCo sites. Sites are non-colliding reference points used for sensor attachment, debugging, or as frames of reference. If False, sites are skipped during export. Defaults to True.
skip_visual_only_geoms (bool) – If True (default), geometries used only for visualization (i.e. not involved in collision) are excluded from the exported MuJoCo spec. This avoids mismatches with models that use explicit <contact> definitions for collision geometry.

close_mujoco_viewer()#: Close the MuJoCo viewer if it exists.

get_max_contact_count()#

Return the maximum number of rigid contacts that can be generated by MuJoCo.

notify_model_changed(flags)#

render_mujoco_viewer(show_left_ui=True, show_right_ui=True, show_contact_points=True, show_contact_forces=False, show_transparent_geoms=True)#

Create and synchronize the MuJoCo viewer. The viewer will be created if it is not already open.

Note

The MuJoCo viewer only supports rendering Newton models with a single world, unless use_mujoco_cpu is True or the solver was initialized with separate_worlds set to False.

The MuJoCo viewer is only meant as a debugging tool.

Parameters:

show_left_ui (bool) – Whether to show the left UI.
show_right_ui (bool) – Whether to show the right UI.
show_contact_points (bool) – Whether to show contact points.
show_contact_forces (bool) – Whether to show contact forces.
show_transparent_geoms (bool) – Whether to show transparent geoms.

step(state_in, state_out, control, contacts, dt)#

update_contacts(contacts, state=None)#

Update contacts from MuJoCo contacts when running with use_mujoco_contacts.

body_free_qd_start: wp.array(dtype=wp.int32) | None#: Per-body mapping to the free-joint qd_start index (or -1 if not free).

mjc_actuator_ctrl_source: wp.array(dtype=wp.int32) | None#

Control source for each MuJoCo actuator.

Values: 0=JOINT_TARGET (uses joint_target_pos/vel), 1=CTRL_DIRECT (uses mujoco.ctrl) Shape [nu], dtype int32.

mjc_actuator_to_newton_idx: wp.array(dtype=wp.int32) | None#

Mapping from MuJoCo actuator to Newton index.

For JOINT_TARGET: sign-encoded DOF index (>=0: position, -1: unmapped, <=-2: velocity with -(idx+2)) For CTRL_DIRECT: MJCF-order index into control.mujoco.ctrl array

Shape [nu], dtype int32.

mjc_body_to_newton: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, body] to Newton body index. Shape [nworld, nbody], dtype int32.

mjc_dof_to_newton_dof: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, dof] to Newton DOF index. Shape [nworld, nv], dtype int32.

mjc_eq_to_newton_eq: wp.array(dtype=wp.int32, ndim=2) | None#

Mapping from MuJoCo [world, eq] to Newton equality constraint index.

Corresponds to the equality constraints that are created in MuJoCo from Newton’s equality constraints. A value of -1 indicates that the MuJoCo equality constraint has been created from a Newton joint, see mjc_eq_to_newton_jnt for the corresponding joint index.

Shape [nworld, neq], dtype int32.

mjc_eq_to_newton_jnt: wp.array(dtype=wp.int32, ndim=2) | None#

Mapping from MuJoCo [world, eq] to Newton joint index.

Corresponds to the equality constraints that are created in MuJoCo from Newton joints that have no associated articulation, i.e. where newton.Model.joint_articulation is -1 for the joint which results in 2 equality constraints being created in MuJoCo. A value of -1 indicates that the MuJoCo equality constraint is not associated with a Newton joint but an explicitly created Newton equality constraint, see mjc_eq_to_newton_eq for the corresponding equality constraint index.

Shape [nworld, neq], dtype int32.

mjc_eq_to_newton_mimic: wp.array(dtype=wp.int32, ndim=2) | None#

Mapping from MuJoCo [world, eq] to Newton mimic constraint index.

Corresponds to the equality constraints that are created in MuJoCo from Newton’s mimic constraints. A value of -1 indicates that the MuJoCo equality constraint is not associated with a Newton mimic constraint.

Shape [nworld, neq], dtype int32.

mjc_geom_to_newton_shape: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, geom] to Newton shape index. Shape [nworld, ngeom], dtype int32.

mjc_jnt_to_newton_dof: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, joint] to Newton DOF index. Shape [nworld, njnt], dtype int32.

mjc_jnt_to_newton_jnt: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, joint] to Newton joint index. Shape [nworld, njnt], dtype int32.

mjc_mocap_to_newton_jnt: wp.array(dtype=wp.int32, ndim=2) | None#: Mapping from MuJoCo [world, mocap] to Newton joint index. Shape [nworld, nmocap], dtype int32.

mjc_tendon_to_newton_tendon: wp.array(dtype=wp.int32, ndim=2) | None#

Mapping from MuJoCo [world, tendon] to Newton tendon index.

Shape [nworld, ntendon], dtype int32.

newton_dof_to_body: wp.array(dtype=wp.int32) | None#: Mapping from Newton DOF index to child body index. Shape [joint_dof_count], dtype int32.

newton_shape_to_mjc_geom: wp.array(dtype=wp.int32) | None#: Inverse mapping from Newton shape index to MuJoCo geom index. Only created when use_mujoco_contacts=False. Shape [nshape], dtype int32.