Add MuJoCo DC motor actuator import

changelog/3950.added.md

@@ -0,0 +1 @@
+Import MuJoCo DC-motor actuators from MJCF and compiled `MjcActuator` USD for `SolverMuJoCo`.

changelog/3950.fixed.1.md

@@ -0,0 +1 @@
+Avoid allocating high-level DC-motor parameter arrays for MuJoCo models without DC-motor actuators.

changelog/3950.fixed.md

@@ -0,0 +1 @@
+Recognize MuJoCo DC-motor and SO3 actuator dynamics, gain, and bias types when importing compiled actuator parameters.

docs/solvers/mujoco.rst

@@ -348,6 +348,26 @@ only reachable through the ``mujoco`` :ref:`custom-attribute namespace <mujoco-c
 Additional actuators declared this way are appended after the joint-target
 actuators — see ``SolverMuJoCo._init_actuators``.
 
+MJCF ``<dcmotor>`` actuators follow this MuJoCo-specific path. The importer
+preserves their high-level electrical, controller, thermal, cogging, and LuGre
+parameters, and :class:`~newton.solvers.SolverMuJoCo` reconstructs them through
+MuJoCo's native DC-motor compiler for both the CPU and MuJoCo-Warp backends.
+Commands use the MJCF actuator order in ``control.mujoco.ctrl``. The supported
+``input`` signatures each consume one control value: ``voltage``, ``pos``, or
+``vel``; ``position`` and ``velocity`` are accepted as compatibility aliases.
+MuJoCo's ``ff``, ``none``, and combined multi-input signatures are not yet
+supported because they require control handling that MuJoCo-Warp does not yet
+provide. Compiled USD ``MjcActuator`` rows can preserve the low-level parameter
+arrays and a supported ``mjc:ctrlSpec`` value instead.
+When using ``separate_worlds=True``, corresponding high-level ``<dcmotor>``
+actuators must have identical parameters because MuJoCo-Warp replicates one
+compiled template model across worlds.
+
+This native, stateful MuJoCo actuator is distinct from
+:class:`~newton.actuators.ClampingDCMotor`, which is a stateless Newton
+clamping stage and does not model winding current, thermal effects, cogging, or
+LuGre friction.
+
 
 .. _mujoco-equality-constraints:
 

newton/_src/solvers/mujoco/kernels.py

@@ -1540,6 +1540,8 @@ def convert_mjw_contacts_to_newton_kernel(
 
 CTRL_SOURCE_JOINT_TARGET = wp.constant(0)
 CTRL_SOURCE_CTRL_DIRECT = wp.constant(1)
+CTRL_TYPE_DCMOTOR = wp.constant(3)
+ACTUATOR_GAIN_TYPE_DCMOTOR = wp.constant(3)
 
 
 @wp.func
@@ -2114,6 +2116,9 @@ def update_axis_properties_kernel(
 def update_ctrl_direct_actuator_properties_kernel(
     mjc_actuator_ctrl_source: wp.array[wp.int32],
     mjc_actuator_to_newton_idx: wp.array[wp.int32],
+    newton_actuator_ctrl_type: wp.array[wp.int32],
+    newton_actuator_gain_type: wp.array[wp.int32],
+    newton_actuator_ctrlspec: wp.array[wp.int32],
     newton_actuator_gainprm: wp.array[vec10],
     newton_actuator_biasprm: wp.array[vec10],
     newton_actuator_dynprm: wp.array[vec10],
@@ -2142,6 +2147,9 @@ def update_ctrl_direct_actuator_properties_kernel(
     Args:
         mjc_actuator_ctrl_source: 0=JOINT_TARGET, 1=CTRL_DIRECT
         mjc_actuator_to_newton_idx: Index into Newton's mujoco:actuator arrays
+        newton_actuator_ctrl_type: Intrinsic actuator shortcut type
+        newton_actuator_gain_type: MuJoCo actuator gain type
+        newton_actuator_ctrlspec: MuJoCo 3.12 DC-motor control-input mask
         newton_actuator_gainprm: Newton's model.mujoco.actuator_gainprm
         newton_actuator_biasprm: Newton's model.mujoco.actuator_biasprm
         newton_actuator_dynprm: Newton's model.mujoco.actuator_dynprm
@@ -2163,11 +2171,34 @@ def update_ctrl_direct_actuator_properties_kernel(
         return
 
     world_newton_idx = world * actuators_per_world + newton_idx
-    actuator_gain[world, actuator] = newton_actuator_gainprm[world_newton_idx]
-    actuator_bias[world, actuator] = newton_actuator_biasprm[world_newton_idx]
-    actuator_dynprm[world, actuator] = newton_actuator_dynprm[world_newton_idx]
+    # High-level MJCF DC-motor rows keep placeholder general-actuator arrays;
+    # preserve the parameters and force range compiled by set_to_dcmotor().
+    if newton_actuator_ctrl_type[world_newton_idx] != CTRL_TYPE_DCMOTOR:
+        actuator_gain[world, actuator] = newton_actuator_gainprm[world_newton_idx]
+        actuator_bias[world, actuator] = newton_actuator_biasprm[world_newton_idx]
+        actuator_dynprm[world, actuator] = newton_actuator_dynprm[world_newton_idx]
+        actuator_forcerange[world, actuator] = newton_actuator_forcerange[world_newton_idx]
+
+    # MuJoCo 3.12 stores the DC-motor input signature in actuator_ctrlspec,
+    # while MuJoCo-Warp currently reads its legacy value from gainprm[8].
+    # Patch only that compatibility slot after preserving or copying the
+    # compiled parameters above. A zero ctrlspec denotes legacy compiled data.
+    ctrlspec = newton_actuator_ctrlspec[world_newton_idx]
+    is_dcmotor = (
+        newton_actuator_ctrl_type[world_newton_idx] == CTRL_TYPE_DCMOTOR
+        or newton_actuator_gain_type[world_newton_idx] == ACTUATOR_GAIN_TYPE_DCMOTOR
+    )
+    if is_dcmotor and ctrlspec > 0:
+        gain = actuator_gain[world, actuator]
+        if ctrlspec == 1:  # position
+            gain[8] = 1.0
+        elif ctrlspec == 2:  # velocity
+            gain[8] = 2.0
+        else:  # voltage
+            gain[8] = 0.0
+        actuator_gain[world, actuator] = gain
+
     actuator_ctrlrange[world, actuator] = newton_actuator_ctrlrange[world_newton_idx]
-    actuator_forcerange[world, actuator] = newton_actuator_forcerange[world_newton_idx]
     actuator_actrange[world, actuator] = newton_actuator_actrange[world_newton_idx]
     actuator_gear[world, actuator] = newton_actuator_gear[world_newton_idx]
     actuator_cranklength[world, actuator] = newton_actuator_cranklength[world_newton_idx]