Improve armature documentation

PiperOrigin-RevId: 742583729
Change-Id: I18d1c95a91f4d70b842c680d4a0f4d0b04476894

doc/XMLreference.rst

@@ -2151,14 +2151,28 @@ rotations as unit quaternions.
    corresponding to mjModel.qpos_spring is also used to compute the spring reference lengths of all tendons, stored in
    mjModel.tendon_lengthspring. This is because :ref:`tendons <tendon>` can also have springs.
 
+.. image:: images/XMLreference/armature.gif
+   :width: 40%
+   :align: right
+   :class: only-light
+   :target: https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/armature_equivalence.xml
+.. image:: images/XMLreference/armature_dark.gif
+   :width: 40%
+   :align: right
+   :class: only-dark
+   :target: https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/armature_equivalence.xml
+
 .. _body-joint-armature:
 
 :at:`armature`: :at-val:`real, "0"`
    Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually
    due to a rotor (a.k.a `armature <https://en.wikipedia.org/wiki/Armature_(electrical)>`__) spinning faster than the
-   joint itself due to a geared transmission; in this case the added inertia is known as "reflected inertia" and its
+   joint itself due to a geared transmission. In the illustration, we compare (*left*) a 2-dof system with an armature
-   value is the rotational inertia of the spinning element multiplied by the square of the gear ratio. The value applies
+   body (purple box), coupled with a gear ratio of :math:`3` to the pendulum using a :ref:`joint
-   to all degrees of freedom created by this joint.
+   equality<equality-joint>` constraint, and (*right*) a simple 1-dof pendulum with an equivalent :at:`armature`.
+   Because the gear ratio appears twice, multiplying both forces and lengths, the effect is known as "reflected
+   inertia" and the equivalent value is the inertia of the spinning body multiplied by the *square of the gear ratio*,
+   in this case :math:`9=3^2`. The value applies to all degrees of freedom created by this joint.
 
    Besides increasing the realism of joints with geared transmission, positive :at:`armature` significantly improves
    simulation stability, even for small values, and is a recommended possible fix when encountering stability issues.

test/engine/testdata/armature_equivalence.xml

@@ -1,4 +1,13 @@
 <mujoco>
+  <visual>
+    <global elevation="-20"/>
+    <headlight ambient=".3 .3 .3" diffuse=".9 .9 .9"/>
+  </visual>
+
+  <default>
+    <geom rgba="0.8 0.6 .4 1"/>
+  </default>
+
   <worldbody>
     <body name="link1">
       <!-- inertia of link1 is 1.0 -->
@@ -10,7 +19,7 @@
       <!-- inertia of motor1 is 1/12 * m * (0.2^2 + 0.2^2) = 0.2
            see https://en.wikipedia.org/wiki/List_of_moments_of_inertia -->
       <joint name="motor1" axis="0 -1 0"/>
-      <geom type="box" size=".1 .1 .1" mass="30" contype="0" conaffinity="0"/>
+      <geom type="box" size=".1 .1 .1" mass="30" contype="0" conaffinity="0" rgba=".6 .4 .8 1"/>
     </body>
 
     <body name="link2" pos="1.5 0 0">
@@ -27,8 +36,8 @@
   </equality>
 
   <actuator>
-    <position name="link1" joint="motor1" kp="1" kv=".1" ctrlrange="-5 5"/>
+    <position name="link1" joint="motor1" kp=".3" ctrlrange="-5 5"/>
     <!-- actuators are made equivalent by setting link2 gear to link1 gear ratio -->
-    <position name="link2" joint="link2"  kp="1" kv=".1" ctrlrange="-5 5" gear="3"/>
+    <position name="link2" joint="link2"  kp=".3" ctrlrange="-5 5" gear="3"/>
   </actuator>
 </mujoco>