newton.solvers.mujoco#

Programmatic model-authoring helpers for SolverMuJoCo.

The module-level helpers create MuJoCo-specific actuators, tendons, contact pairs, and equality constraints on a ModelBuilder without exposing custom-frequency storage details. Use SolverMuJoCo as the canonical public solver class.

Example:

from newton.solvers import mujoco

actuator = mujoco.add_actuator_position(
    builder,
    target=mujoco.ActuatorTarget.joint(joint),
    kp=10.0,
    kv=2.0,
)

Note

This page documents helper functions exposed through the newton.solvers.mujoco attribute. Because newton.solvers is a module rather than a package, use from newton.solvers import mujoco instead of import newton.solvers.mujoco.

Classes

class newton.solvers.mujoco.ActuatorTarget(kind, index, secondary_index=-1, dof=None)[source]#

A typed MuJoCo actuator transmission target.

Construct targets with joint(), joint_dof(), tendon(), site(), body(), or slider_crank(). The authoring helper resolves the target to MuJoCo’s heterogeneous trnid representation.

Targets must belong to the builder’s current world or the global world (-1). For ball and free joints, the native MuJoCo transmission requires an explicit three- or six-component gear, respectively, and does not select a Newton DOF. Ball gears express torque in the child body frame; free gears combine world-frame force at the body origin with child-frame torque. Use joint_f to apply forces in Newton’s DOF convention.

class Kind(*values)#

Transmission target kinds supported by ActuatorTarget.

BODY = 'body'#

A Newton body.

JOINT = 'joint'#

A Newton joint, optionally restricted to one local DOF.

JOINT_DOF = 'joint_dof'#

An absolute Newton joint-DOF index.

SITE = 'site'#

A Newton site shape, optionally relative to a reference site.

SLIDER_CRANK = 'slider_crank'#

The crank and slider sites of a slider-crank transmission.

TENDON = 'tendon'#

A mujoco:tendon row.

classmethod body(body)#

Target a Newton body.

Parameters:

body (int) – Newton body index.

Returns:

A typed body target.

Return type:

ActuatorTarget

classmethod joint(joint, *, dof=None)#

Target a Newton joint, selecting a scalar axis for D6 joints.

Parameters:

  • joint (int) – Newton joint index.

  • dof (int | None) – Local DOF within a scalar or D6 joint. Required for multi-axis D6 joints. Omit for ball/free joints and supply an explicit native MuJoCo gear to the actuator helper.

Returns:

A typed joint target.

Return type:

ActuatorTarget

classmethod joint_dof(dof)#

Target an absolute Newton joint-DOF index.

Parameters:

dof (int) – Absolute Newton joint-DOF index for a scalar or D6 joint. Ball/free joints require joint() with native gear instead.

Returns:

A typed joint-DOF target.

Return type:

ActuatorTarget

classmethod site(site, *, refsite=None)#

Target a Newton site shape, optionally relative to another site.

Parameters:

  • site (int) – Newton site-shape index.

  • refsite (int | None) – Optional reference site-shape index.

Returns:

A typed site target.

Return type:

ActuatorTarget

classmethod slider_crank(cranksite, slidersite)#

Target the crank and slider sites of a slider-crank transmission.

Parameters:

  • cranksite (int) – Newton crank site-shape index.

  • slidersite (int) – Newton slider site-shape index.

Returns:

A typed slider-crank target.

Return type:

ActuatorTarget

classmethod tendon(tendon)#

Target a mujoco:tendon row.

Parameters:

tendon (int) – Row index returned by add_tendon_fixed() or add_tendon_spatial().

Returns:

A typed tendon target.

Return type:

ActuatorTarget

__init__(kind, index, secondary_index=-1, dof=None)#
dof: int | None = None#

Local joint DOF, when kind is Kind.JOINT.

index: int#

Primary Newton entity index.

kind: Kind#

Transmission target kind.

secondary_index: int = -1#

Secondary Newton entity index, or -1 if unused.

class newton.solvers.mujoco.TendonWrapGeom(geom, sidesite=None)[source]#

A geometry wrapping entry in a spatial tendon path.

__init__(geom, sidesite=None)#
geom: int#

Newton non-site shape index.

sidesite: int | None = None#

Optional Newton site-shape index selecting the wrapping side.

class newton.solvers.mujoco.TendonWrapPulley(divisor)[source]#

A pulley entry in a spatial tendon path.

__init__(divisor)#
divisor: float#

Positive pulley divisor.

class newton.solvers.mujoco.TendonWrapSite(site)[source]#

A site entry in a spatial tendon path.

__init__(site)#
site: int#

Newton site-shape index.

Functions

newton.solvers.mujoco.add_actuator_dcmotor(builder, target, *, motorconst=(0.0,), resistance=0.0, nominal=(0.0,), saturation=(0.0,), inductance=(0.0,), cogging=(0.0,), controller=(0.0,), thermal=(0.0,), lugre=(0.0,), input='voltage', gear=(1.0,), damping=(0.0,), armature=0.0, ctrlrange=None, ctrllimited='auto', cranklength=None, ctrl=0.0, custom_attributes=None)[source]#

Add a native DC motor controlled through control.mujoco.ctrl.

Requires the optional mujoco package (included in newton[sim]), but not MuJoCo-Warp. Native MuJoCo resolves the electrical and controller parameters; these are construction-time properties, not runtime-editable general-actuator gains. No model is compiled by this helper. Parameter vectors are zero-padded before native default inference, as in MJCF. Force limits are derived from saturation, not separate forcerange/forcelimited options, matching the native shortcut.

Parameter ordering and inference follow the MuJoCo DC-motor reference.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the actuator.

  • target (ActuatorTarget) – Typed actuator transmission target.

  • motorconst (Sequence[float]) – Torque constant [N·m/A] and back-EMF constant [V·s/rad].

  • resistance (float) – Winding resistance [ohm]. Supply sufficient nonzero motorconst, resistance, or nominal values for native inference.

  • nominal (Sequence[float]) – Voltage [V], stall torque [N·m], and no-load speed [rad/s].

  • saturation (Sequence[float]) – Torque [N·m], current [A], and current-rate [A/s] limits.

  • inductance (Sequence[float]) – Winding inductance [H] and electrical time constant [s].

  • cogging (Sequence[float]) – Torque amplitude [N·m], pole count, and phase [rad].

  • controller (Sequence[float]) – kp, ki, kd, slew limit, integral limit, and voltage limit; see the linked native reference for input-dependent units.

  • thermal (Sequence[float]) – Thermal resistance [K/W], capacitance [J/K], time constant [s], resistance temperature coefficient [1/K], reference and ambient temperatures [degrees Celsius].

  • lugre (Sequence[float]) – Bristle stiffness [N·m/rad], damping [N·m·s/rad], Coulomb and static friction torques [N·m], and Stribeck speed [rad/s].

  • input (str | int) – Single control input: voltage (8), pos (1), or vel (2). Accepts a native keyword or its integer control signature. Other signatures raise NotImplementedError.

  • gear (Sequence[float]) – Native transmission gear, padded to six values. Ball/free joints require explicit native gear as described in ActuatorTarget. With nonzero damping on the Warp backend, gear must match across replicated worlds and cannot change after solver construction.

  • damping (Sequence[float]) – Coefficients of -d0*v - d1*abs(v)*v - d2*v**3 in actuator velocity v. Coefficient dn has units [N·m·(s/rad)^(n+1)] for angular transmissions or [N·(s/m)^(n+1)] for linear ones.

  • armature (float) – Passive rotor inertia [kg·m² or kg for linear transmissions]. Currently supported only by native MuJoCo.

  • ctrlrange (Sequence[float] | None) – Optional two-value control range: voltage [V], position [m or rad], or velocity [m/s or rad/s], in actuator coordinates.

  • ctrllimited (bool | int | str) – Control-limit tri-state (false, true, or auto).

  • cranklength (float | None) – Slider-crank length [m]. Required for slider-crank targets.

  • ctrl (float) – Initial control value, with the same units as ctrlrange.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:actuator attributes.

Returns:

The mujoco:actuator row index.

Return type:

int

newton.solvers.mujoco.add_actuator_general(builder, target, *, dyntype='none', gaintype='fixed', biastype='none', dynprm=(1.0,), gainprm=(1.0,), biasprm=(0.0,), gear=(1.0,), ctrlrange=None, ctrllimited='auto', forcerange=None, forcelimited='auto', actrange=None, actlimited='auto', actdim=None, actearly=False, cranklength=None, ctrl=0.0, custom_attributes=None)[source]#

Add a MuJoCo-native general actuator controlled through control.mujoco.ctrl.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the actuator.

  • target (ActuatorTarget) – Typed actuator transmission target.

  • dyntype (int | str) – MuJoCo activation dynamics type.

  • gaintype (int | str) – MuJoCo gain type.

  • biastype (int | str) – MuJoCo bias type.

  • dynprm (Sequence[float]) – Activation dynamics parameters, padded to ten values.

  • gainprm (Sequence[float]) – Gain parameters, padded to ten values.

  • biasprm (Sequence[float]) – Bias parameters, padded to ten values.

  • gear (Sequence[float]) – Native MuJoCo transmission gear, padded to six values. Ball/free joints require at least three/six components; these use MuJoCo’s frames and force reference point, as described in ActuatorTarget.

  • ctrlrange (Sequence[float] | None) – Optional control range.

  • ctrllimited (bool | int | str) – Control-limit tri-state (false, true, or auto).

  • forcerange (Sequence[float] | None) – Optional actuator force range [N or N·m].

  • forcelimited (bool | int | str) – Force-limit tri-state (false, true, or auto).

  • actrange (Sequence[float] | None) – Optional activation-state range.

  • actlimited (bool | int | str) – Activation-limit tri-state (false, true, or auto).

  • actdim (int | None) – Activation-state dimension, or None for automatic selection.

  • actearly (bool) – Whether force uses the next activation state.

  • cranklength (float | None) – Slider-crank length [m]. Required for slider-crank targets.

  • ctrl (float) – Initial MuJoCo control value.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:actuator attributes.

Returns:

The mujoco:actuator row index.

Return type:

int

newton.solvers.mujoco.add_actuator_motor(builder, target, *, gear=(1.0,), ctrlrange=None, ctrllimited='auto', forcerange=None, forcelimited='auto', cranklength=None, ctrl=0.0, custom_attributes=None)[source]#

Add a MuJoCo motor shortcut controlled through control.mujoco.ctrl.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the actuator.

  • target (ActuatorTarget) – Typed actuator transmission target.

  • gear (Sequence[float]) – Native MuJoCo transmission gear, padded to six values. Ball/free joints require at least three/six components; these use MuJoCo’s frames and force reference point, as described in ActuatorTarget.

  • ctrlrange (Sequence[float] | None) – Optional control range.

  • ctrllimited (bool | int | str) – Control-limit tri-state (false, true, or auto).

  • forcerange (Sequence[float] | None) – Optional actuator force range [N or N·m].

  • forcelimited (bool | int | str) – Force-limit tri-state (false, true, or auto).

  • cranklength (float | None) – Slider-crank length [m]. Required for slider-crank targets.

  • ctrl (float) – Initial MuJoCo control value.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:actuator attributes.

Returns:

The mujoco:actuator row index.

Return type:

int

newton.solvers.mujoco.add_actuator_position(builder, target, *, kp=1.0, kv=0.0, dampratio=0.0, gear=(1.0,), ctrlrange=None, ctrllimited='auto', forcerange=None, forcelimited='auto', cranklength=None, ctrl=0.0, custom_attributes=None)[source]#

Add a MuJoCo position shortcut controlled through control.mujoco.ctrl.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the actuator.

  • target (ActuatorTarget) – Typed actuator transmission target.

  • kp (float) – Position feedback gain.

  • kv (float) – Velocity feedback gain.

  • dampratio (float) – Damping ratio used when kv is zero.

  • gear (Sequence[float]) – Native MuJoCo transmission gear, padded to six values. Ball/free joints require at least three/six components; these use MuJoCo’s frames and force reference point, as described in ActuatorTarget.

  • ctrlrange (Sequence[float] | None) – Optional control range.

  • ctrllimited (bool | int | str) – Control-limit tri-state (false, true, or auto).

  • forcerange (Sequence[float] | None) – Optional actuator force range [N or N·m].

  • forcelimited (bool | int | str) – Force-limit tri-state (false, true, or auto).

  • cranklength (float | None) – Slider-crank length [m]. Required for slider-crank targets.

  • ctrl (float) – Initial MuJoCo control value.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:actuator attributes.

Returns:

The mujoco:actuator row index.

Return type:

int

newton.solvers.mujoco.add_actuator_velocity(builder, target, *, kv=1.0, gear=(1.0,), ctrlrange=None, ctrllimited='auto', forcerange=None, forcelimited='auto', cranklength=None, ctrl=0.0, custom_attributes=None)[source]#

Add a MuJoCo velocity shortcut controlled through control.mujoco.ctrl.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the actuator.

  • target (ActuatorTarget) – Typed actuator transmission target.

  • kv (float) – Velocity feedback gain.

  • gear (Sequence[float]) – Native MuJoCo transmission gear, padded to six values. Ball/free joints require at least three/six components; these use MuJoCo’s frames and force reference point, as described in ActuatorTarget.

  • ctrlrange (Sequence[float] | None) – Optional control range.

  • ctrllimited (bool | int | str) – Control-limit tri-state (false, true, or auto).

  • forcerange (Sequence[float] | None) – Optional actuator force range [N or N·m].

  • forcelimited (bool | int | str) – Force-limit tri-state (false, true, or auto).

  • cranklength (float | None) – Slider-crank length [m]. Required for slider-crank targets.

  • ctrl (float) – Initial MuJoCo control value.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:actuator attributes.

Returns:

The mujoco:actuator row index.

Return type:

int

newton.solvers.mujoco.add_contact_pair(builder, geom1, geom2, *, condim=3, solref=(0.02, 1.0), solreffriction=(0.02, 1.0), solimp=(0.9, 0.95, 0.001, 0.5, 2.0), margin=0.0, gap=0.0, friction=(1.0, 1.0, 0.005, 0.0001, 0.0001), custom_attributes=None)[source]#

Add an explicit MuJoCo contact pair.

The pair belongs to current_world. Both shapes must belong to that world or to the global world (-1).

Parameters:

  • builder (ModelBuilder) – Model builder receiving the pair.

  • geom1 (int) – First Newton shape index.

  • geom2 (int) – Second Newton shape index.

  • condim (int) – MuJoCo contact dimensionality.

  • solref (Sequence[float]) – Normal constraint reference parameters.

  • solreffriction (Sequence[float]) – Friction constraint reference parameters.

  • solimp (Sequence[float]) – Constraint impedance parameters.

  • margin (float) – Contact inclusion margin [m].

  • gap (float) – Inactive contact gap [m].

  • friction (Sequence[float]) – Sliding, torsional, and rolling friction coefficients.

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:pair attributes.

Returns:

The mujoco:pair row index.

Return type:

int

newton.solvers.mujoco.add_equality_connect(builder, body1, body2=-1, *, anchor=None, label=None, enabled=True, solref=None, solimp=None, custom_attributes=None)[source]#

Add a MuJoCo connect equality between two bodies.

Both operands must belong to the current world or the global world (-1).

Parameters:

  • builder (ModelBuilder) – Model builder receiving the constraint.

  • body1 (int) – First body index, or -1 for the world.

  • body2 (int) – Second body index, or -1 for the world.

  • anchor (Vec3 | None) – Anchor point in the first body’s frame [m].

  • label (str | None) – Optional constraint label.

  • enabled (bool) – Whether the constraint is active.

  • solref (Sequence[float] | None) – Optional MuJoCo constraint reference parameters.

  • solimp (Sequence[float] | None) – Optional MuJoCo constraint impedance parameters.

  • custom_attributes (dict[str, Any] | None) – Additional registered equality-frequency attributes.

Returns:

The mujoco:equality_constraint row index.

Return type:

int

newton.solvers.mujoco.add_equality_joint(builder, joint1, joint2, *, polycoef=(0.0, 1.0), label=None, enabled=True, solref=None, solimp=None, custom_attributes=None)[source]#

Add a MuJoCo polynomial equality between two scalar joints.

Both joints must belong to the current world or the global world (-1).

Parameters:

  • builder (ModelBuilder) – Model builder receiving the constraint.

  • joint1 (int) – Dependent Newton joint index.

  • joint2 (int) – Reference Newton joint index.

  • polycoef (Sequence[float]) – Up to five polynomial coefficients. Omitted higher-order terms are zero, whereas MJCF polycoef fills omitted terms from MuJoCo’s 0 1 0 0 0 default.

  • label (str | None) – Optional constraint label.

  • enabled (bool) – Whether the constraint is active.

  • solref (Sequence[float] | None) – Optional MuJoCo constraint reference parameters.

  • solimp (Sequence[float] | None) – Optional MuJoCo constraint impedance parameters.

  • custom_attributes (dict[str, Any] | None) – Additional registered equality-frequency attributes.

Returns:

The mujoco:equality_constraint row index.

Return type:

int

newton.solvers.mujoco.add_equality_tendon(builder, tendon1, tendon2=-1, *, polycoef=(0.0, 1.0), label=None, enabled=True, solref=None, solimp=None, custom_attributes=None)[source]#

Add a MuJoCo polynomial equality between two tendon lengths.

Lengths are measured relative to their values at the reference configuration. Without tendon2, only polycoef[0] is used and the length of tendon1 is held at that offset. Both tendons must belong to the current world or the global world (-1).

Parameters:

  • builder (ModelBuilder) – Model builder receiving the constraint.

  • tendon1 (int) – Dependent mujoco:tendon index.

  • tendon2 (int) – Reference mujoco:tendon index, or -1 for none.

  • polycoef (Sequence[float]) – Up to five polynomial coefficients. Omitted higher-order terms are zero, whereas MJCF polycoef fills omitted terms from MuJoCo’s 0 1 0 0 0 default.

  • label (str | None) – Optional constraint label.

  • enabled (bool) – Whether the constraint is active.

  • solref (Sequence[float] | None) – Optional MuJoCo constraint reference parameters.

  • solimp (Sequence[float] | None) – Optional MuJoCo constraint impedance parameters.

  • custom_attributes (dict[str, Any] | None) – Additional registered equality-frequency attributes.

Returns:

The mujoco:equality_constraint row index.

Return type:

int

newton.solvers.mujoco.add_equality_weld(builder, body1, body2=-1, *, relpose=None, torquescale=1.0, label=None, enabled=True, solref=None, solimp=None, custom_attributes=None)[source]#

Add a MuJoCo weld equality between two bodies.

Both operands must belong to the current world or the global world (-1).

Parameters:

  • builder (ModelBuilder) – Model builder receiving the constraint.

  • body1 (int) – First body index, or -1 for the world.

  • body2 (int) – Second body index, or -1 for the world.

  • relpose (Transform | None) – The position in the first body’s frame where the second body’s origin is held, and the second body’s orientation in the first body’s frame. If omitted, preserve the bodies’ initial relative pose.

  • torquescale (float) – Angular residual length scale [m].

  • label (str | None) – Optional constraint label.

  • enabled (bool) – Whether the constraint is active.

  • solref (Sequence[float] | None) – Optional MuJoCo constraint reference parameters.

  • solimp (Sequence[float] | None) – Optional MuJoCo constraint impedance parameters.

  • custom_attributes (dict[str, Any] | None) – Additional registered equality-frequency attributes.

Returns:

The mujoco:equality_constraint row index.

Return type:

int

newton.solvers.mujoco.add_tendon_fixed(builder, joints, *, label=None, stiffness=0.0, damping=0.0, frictionloss=0.0, limited='auto', limit_range=(0.0, 0.0), margin=0.0, solref_limit=(0.02, 1.0), solimp_limit=(0.9, 0.95, 0.001, 0.5, 2.0), solref_friction=(0.02, 1.0), solimp_friction=(0.9, 0.95, 0.001, 0.5, 2.0), armature=0.0, springlength=(-1.0, -1.0), custom_attributes=None)[source]#

Add a fixed tendon as a linear combination of Newton joints.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the tendon.

  • joints (Sequence[tuple[int, float]]) – Ordered (joint_index, coefficient) entries for revolute or prismatic joints in the current world or the global world (-1).

  • label (str | None) – Optional tendon label.

  • stiffness (float) – Tendon stiffness [N/m].

  • damping (float) – Tendon damping [N·s/m].

  • frictionloss (float) – Tendon friction loss [N].

  • limited (bool | int | str) – Tendon-limit tri-state (false, true, or auto).

  • limit_range (Sequence[float]) – Tendon length range [m].

  • margin (float) – Tendon limit margin [m].

  • solref_limit (Sequence[float]) – Limit constraint reference parameters.

  • solimp_limit (Sequence[float]) – Limit constraint impedance parameters.

  • solref_friction (Sequence[float]) – Friction constraint reference parameters.

  • solimp_friction (Sequence[float]) – Friction constraint impedance parameters.

  • armature (float) – Tendon armature [kg].

  • springlength (Sequence[float]) – Tendon spring length range [m].

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:tendon attributes.

Returns:

The mujoco:tendon row index.

Return type:

int

newton.solvers.mujoco.add_tendon_spatial(builder, path, *, label=None, stiffness=0.0, damping=0.0, frictionloss=0.0, limited='auto', limit_range=(0.0, 0.0), margin=0.0, solref_limit=(0.02, 1.0), solimp_limit=(0.9, 0.95, 0.001, 0.5, 2.0), solref_friction=(0.02, 1.0), solimp_friction=(0.9, 0.95, 0.001, 0.5, 2.0), armature=0.0, springlength=(-1.0, -1.0), custom_attributes=None)[source]#

Add a spatial tendon from typed site, geometry, and pulley entries.

Parameters:

  • builder (ModelBuilder) – Model builder receiving the tendon.

  • path (Sequence[TendonWrapSite | TendonWrapGeom | TendonWrapPulley]) – Ordered spatial tendon path entries. All sites, geoms, and sidesites must belong to the current world or the global world (-1).

  • label (str | None) – Optional tendon label.

  • stiffness (float) – Tendon stiffness [N/m].

  • damping (float) – Tendon damping [N·s/m].

  • frictionloss (float) – Tendon friction loss [N].

  • limited (bool | int | str) – Tendon-limit tri-state (false, true, or auto).

  • limit_range (Sequence[float]) – Tendon length range [m].

  • margin (float) – Tendon limit margin [m].

  • solref_limit (Sequence[float]) – Limit constraint reference parameters.

  • solimp_limit (Sequence[float]) – Limit constraint impedance parameters.

  • solref_friction (Sequence[float]) – Friction constraint reference parameters.

  • solimp_friction (Sequence[float]) – Friction constraint impedance parameters.

  • armature (float) – Tendon armature [kg].

  • springlength (Sequence[float]) – Tendon spring length range [m].

  • custom_attributes (dict[str, Any] | None) – Additional registered mujoco:tendon attributes.

Returns:

The mujoco:tendon row index.

Return type:

int