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_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, shape0, shape1, *, 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.
shape0 (int) – First Newton shape index.
shape1 (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.
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) – Relative pose of the second body 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