chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Allow actuators to add damping and armature to joint and tendon transmissions.

Browse Source 
PiperOrigin-RevId: 886899849
Change-Id: I02200ee0d4f7c96096d8188b95f823b566562a30
This commit is contained in:
Yuval Tassa
2026-03-20 11:40:35 -07:00
committed by Copybara-Service
parent f7bd6d15f7
commit 510d75f4cf
25 changed files with 1164 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/XMLreference.rst
+111 -8
View File
@@ -5353,6 +5353,45 @@ specify them independently.
the first element of this vector is used. The remaining elements are needed for joint, jointinparent and site
transmissions where this attribute is used to specify 3D force and torque axes.
.. _actuator-general-damping:
:at:`damping`: :at-val:`real(3), "0 0 0"`
Viscous damping coefficients, contributed by the actuator to its transmission target (joint or tendon only).
The damping value is scaled by :ref:`gear<actuator-general-gear>` squared, because the gear ratio scales both forces
and velocities, leading to reflected damping (analogous to :ref:`reflected inertia<actuator-general-armature>`).
Like :ref:`joint damping<body-joint-damping>`, coefficients correspond to linear, quadratic and cubic velocity.
See :ref:`Polynomial forces<gePolynomial>` for details.
Several actuator shortcuts have a :at:`kv` attribute which maps to :ref:`-biasprm[2]<actuator-general-biasprm>` and
has similar semantics to :at:`damping`: (e.g.,
:ref:`position/kv<actuator-position-kv>`). The differences between these attributes are:
- :at:`damping` is applied at the transmission target, and therefore includes the gear\ :sup:`2` factor. This factor
is not required for :at:`kv` as it is already applied in actuator space (so the units are identical).
- Implicit integration works for :at:`damping` when using the Euler integrator but not for :at:`kv`.
To get implicit integration for :at:`kv`, implicit or implicitfast is required, see
:ref:`Integration<CIntegrator>`.
- :at:`damping` allows for polynomial damping, while :at:`kv` is only linear.
- Damping forces generated by :at:`kv` are subject to :ref:`forcerange<actuator-general-forcerange>` clamping, but
forces generated by :at:`damping` are not.
Finally, note that while it is permitted for nonzero damping and :ref:`armature<actuator-general-armature>` to be
specified for multiple actuators acting on the same transmission target, it is more performant to specify
them for only one actuator. Since these values are summed anyway, it is recommended to place all damping and
armature for one transmission target in a single actuator definition.
.. _actuator-general-armature:
:at:`armature`: :at-val:`real, "0"`
Armature inertia (or mass for slider joints) contributed by the actuator to its transmission target (joint or tendon
only). This is the actual inertia of the spinning element inside the actuator (e.g., a rotor). The contributed value
is scaled by :ref:`gear<actuator-general-gear>` squared, because the gear ratio scales both forces and velocities,
leading to `reflected inertia <https://en.wikipedia.org/wiki/Reflective_inertia>`__. See
:ref:`joint<body-joint-armature>` and :ref:`tendon<tendon-fixed-armature>` armature for more details.
See also the note in :ref:`damping<actuator-general-damping>` regarding multiple actuators acting on the same
transmission target.
.. _actuator-general-cranklength:
:at:`cranklength`: :at-val:`real, "0"`
@@ -5596,11 +5635,15 @@ This element does not have custom attributes. It only has common attributes, whi
.. _actuator-motor-user:
.. _actuator-motor-damping:
.. _actuator-motor-armature:
.. |actuator/motor attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/motor attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -5667,10 +5710,14 @@ This element has one custom attribute in addition to the common attributes:
.. _actuator-position-user:
.. _actuator-position-damping:
.. _actuator-position-armature:
.. |actuator/position attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/position attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -5786,10 +5833,14 @@ This element has one custom attribute in addition to the common attributes:
.. _actuator-velocity-user:
.. _actuator-velocity-damping:
.. _actuator-velocity-armature:
.. |actuator/velocity attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/velocity attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -5864,10 +5915,14 @@ This element has one custom attribute in addition to the common attributes:
.. _actuator-intvelocity-user:
.. _actuator-intvelocity-damping:
.. _actuator-intvelocity-armature:
.. |actuator/intvelocity attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`actrange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`,
:at:`tendon`, :at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`tendon`, :at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/intvelocity attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -5958,10 +6013,14 @@ This element has one custom attribute in addition to the common attributes:
.. _actuator-damper-user:
.. _actuator-damper-damping:
.. _actuator-damper-armature:
.. |actuator/damper attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/damper attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -6033,10 +6092,14 @@ This element has four custom attributes in addition to the common attributes:
.. _actuator-cylinder-user:
.. _actuator-cylinder-damping:
.. _actuator-cylinder-armature:
.. |actuator/cylinder attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`site`, :at:`refsite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/cylinder attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -6119,11 +6182,15 @@ This element has nine custom attributes in addition to the common attributes:
.. _actuator-muscle-user:
.. _actuator-muscle-damping:
.. _actuator-muscle-armature:
.. |actuator/muscle attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`ctrllimited`, :at:`forcelimited`, :at:`ctrlrange`,
:at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`, :at:`jointinparent`, :at:`tendon`,
:at:`cranksite`, :at:`slidersite`, :at:`user`
:at:`cranksite`, :at:`slidersite`, :at:`user`, :at:`damping`, :at:`armature`
|actuator/muscle attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -6336,11 +6403,15 @@ Associate this actuator with an :ref:`engine plugin<exPlugin>`. Either :at:`plug
.. _actuator-plugin-actearly:
.. _actuator-plugin-damping:
.. _actuator-plugin-armature:
.. |actuator/plugin attrib list| replace::
:at:`name`, :at:`class`, :at:`group`, :at:`delay`, :at:`actlimited`, :at:`ctrllimited`, :at:`forcelimited`,
:at:`ctrlrange`, :at:`forcerange`, :at:`lengthrange`, :at:`gear`, :at:`cranklength`, :at:`joint`,
:at:`jointinparent`, :at:`site`, :at:`tendon`, :at:`cranksite`, :at:`slidersite`, :at:`user`, :at:`actdim`,
:at:`dynprm`, :at:`actearly`
:at:`dynprm`, :at:`actearly`, :at:`damping`, :at:`armature`
|actuator/plugin attrib list|
Same as in actuator/ :ref:`general <actuator-general>`.
@@ -9454,6 +9525,10 @@ if omitted.
.. _default-general-gear:
.. _default-general-damping:
.. _default-general-armature:
.. _default-general-cranklength:
.. _default-general-user:
@@ -9502,6 +9577,10 @@ if omitted.
.. _default-motor-gear:
.. _default-motor-damping:
.. _default-motor-armature:
.. _default-motor-cranklength:
.. _default-motor-user:
@@ -9538,6 +9617,10 @@ tendon, slidersite, cranksite.
.. _default-position-gear:
.. _default-position-damping:
.. _default-position-armature:
.. _default-position-cranklength:
.. _default-position-user:
@@ -9577,6 +9660,10 @@ refsite, tendon, slidersite, cranksite.
.. _default-velocity-gear:
.. _default-velocity-damping:
.. _default-velocity-armature:
.. _default-velocity-cranklength:
.. _default-velocity-user:
@@ -9614,6 +9701,10 @@ refsite, tendon, slidersite, cranksite.
.. _default-intvelocity-gear:
.. _default-intvelocity-damping:
.. _default-intvelocity-armature:
.. _default-intvelocity-cranklength:
.. _default-intvelocity-user:
@@ -9649,6 +9740,10 @@ site, refsite, tendon, slidersite, cranksite.
.. _default-damper-gear:
.. _default-damper-damping:
.. _default-damper-armature:
.. _default-damper-cranklength:
.. _default-damper-user:
@@ -9682,6 +9777,10 @@ refsite, tendon, slidersite, cranksite.
.. _default-cylinder-gear:
.. _default-cylinder-damping:
.. _default-cylinder-armature:
.. _default-cylinder-cranklength:
.. _default-cylinder-user:
@@ -9721,6 +9820,10 @@ refsite, tendon, slidersite, cranksite.
.. _default-muscle-gear:
.. _default-muscle-damping:
.. _default-muscle-armature:
.. _default-muscle-cranklength:
.. _default-muscle-user:
doc/XMLschema.rst
+102
View File
@@ -2287,6 +2287,12 @@
.. grid-item::
:ref:`gear<actuator-general-gear>`
.. grid-item::
:ref:`damping<actuator-general-damping>`
.. grid-item::
:ref:`armature<actuator-general-armature>`
.. grid-item::
:ref:`cranklength<actuator-general-cranklength>`
@@ -2383,6 +2389,12 @@
.. grid-item::
:ref:`gear<actuator-motor-gear>`
.. grid-item::
:ref:`damping<actuator-motor-damping>`
.. grid-item::
:ref:`armature<actuator-motor-armature>`
.. grid-item::
:ref:`cranklength<actuator-motor-cranklength>`
@@ -2455,6 +2467,12 @@
.. grid-item::
:ref:`gear<actuator-position-gear>`
.. grid-item::
:ref:`damping<actuator-position-damping>`
.. grid-item::
:ref:`armature<actuator-position-armature>`
.. grid-item::
:ref:`cranklength<actuator-position-cranklength>`
@@ -2536,6 +2554,12 @@
.. grid-item::
:ref:`gear<actuator-velocity-gear>`
.. grid-item::
:ref:`damping<actuator-velocity-damping>`
.. grid-item::
:ref:`armature<actuator-velocity-armature>`
.. grid-item::
:ref:`cranklength<actuator-velocity-cranklength>`
@@ -2614,6 +2638,12 @@
.. grid-item::
:ref:`gear<actuator-intvelocity-gear>`
.. grid-item::
:ref:`damping<actuator-intvelocity-damping>`
.. grid-item::
:ref:`armature<actuator-intvelocity-armature>`
.. grid-item::
:ref:`cranklength<actuator-intvelocity-cranklength>`
@@ -2689,6 +2719,12 @@
.. grid-item::
:ref:`gear<actuator-damper-gear>`
.. grid-item::
:ref:`damping<actuator-damper-damping>`
.. grid-item::
:ref:`armature<actuator-damper-armature>`
.. grid-item::
:ref:`cranklength<actuator-damper-cranklength>`
@@ -2761,6 +2797,12 @@
.. grid-item::
:ref:`gear<actuator-cylinder-gear>`
.. grid-item::
:ref:`damping<actuator-cylinder-damping>`
.. grid-item::
:ref:`armature<actuator-cylinder-armature>`
.. grid-item::
:ref:`cranklength<actuator-cylinder-cranklength>`
@@ -2842,6 +2884,12 @@
.. grid-item::
:ref:`gear<actuator-muscle-gear>`
.. grid-item::
:ref:`damping<actuator-muscle-damping>`
.. grid-item::
:ref:`armature<actuator-muscle-armature>`
.. grid-item::
:ref:`cranklength<actuator-muscle-cranklength>`
@@ -2989,6 +3037,12 @@
.. grid-item::
:ref:`gear<actuator-plugin-gear>`
.. grid-item::
:ref:`damping<actuator-plugin-damping>`
.. grid-item::
:ref:`armature<actuator-plugin-armature>`
.. grid-item::
:ref:`cranklength<actuator-plugin-cranklength>`
@@ -5623,6 +5677,12 @@
.. grid-item::
:ref:`gear<default-general-gear>`
.. grid-item::
:ref:`damping<default-general-damping>`
.. grid-item::
:ref:`armature<default-general-armature>`
.. grid-item::
:ref:`cranklength<default-general-cranklength>`
@@ -5686,6 +5746,12 @@
.. grid-item::
:ref:`gear<default-motor-gear>`
.. grid-item::
:ref:`damping<default-motor-damping>`
.. grid-item::
:ref:`armature<default-motor-armature>`
.. grid-item::
:ref:`cranklength<default-motor-cranklength>`
@@ -5728,6 +5794,12 @@
.. grid-item::
:ref:`gear<default-position-gear>`
.. grid-item::
:ref:`damping<default-position-damping>`
.. grid-item::
:ref:`armature<default-position-armature>`
.. grid-item::
:ref:`cranklength<default-position-cranklength>`
@@ -5779,6 +5851,12 @@
.. grid-item::
:ref:`gear<default-velocity-gear>`
.. grid-item::
:ref:`damping<default-velocity-damping>`
.. grid-item::
:ref:`armature<default-velocity-armature>`
.. grid-item::
:ref:`cranklength<default-velocity-cranklength>`
@@ -5827,6 +5905,12 @@
.. grid-item::
:ref:`gear<default-intvelocity-gear>`
.. grid-item::
:ref:`damping<default-intvelocity-damping>`
.. grid-item::
:ref:`armature<default-intvelocity-armature>`
.. grid-item::
:ref:`cranklength<default-intvelocity-cranklength>`
@@ -5872,6 +5956,12 @@
.. grid-item::
:ref:`gear<default-damper-gear>`
.. grid-item::
:ref:`damping<default-damper-damping>`
.. grid-item::
:ref:`armature<default-damper-armature>`
.. grid-item::
:ref:`cranklength<default-damper-cranklength>`
@@ -5914,6 +6004,12 @@
.. grid-item::
:ref:`gear<default-cylinder-gear>`
.. grid-item::
:ref:`damping<default-cylinder-damping>`
.. grid-item::
:ref:`armature<default-cylinder-armature>`
.. grid-item::
:ref:`cranklength<default-cylinder-cranklength>`
@@ -5965,6 +6061,12 @@
.. grid-item::
:ref:`gear<default-muscle-gear>`
.. grid-item::
:ref:`damping<default-muscle-damping>`
.. grid-item::
:ref:`armature<default-muscle-armature>`
.. grid-item::
:ref:`cranklength<default-muscle-cranklength>`
doc/changelog.rst
+5
View File
@@ -8,6 +8,11 @@ Upcoming version (not yet released)
General
^^^^^^^
- Actuators with joint or tendon transmissions can now contribute
:ref:`damping<actuator-general-damping>` and :ref:`armature<actuator-general-armature>` to their transmission target.
These are applied during the passive force and inertia computations, respectively, and are scaled by gear\ :sup:`2`
("reflected" damping/inertia).
.. youtube:: aKa3ZlEF9_Y
:align: right
:width: 35%
doc/includes/references.h
+7
View File
@@ -1171,6 +1171,7 @@ struct mjModel_ {
int* jnt_qposadr; // start addr in 'qpos' for joint's data (njnt x 1)
int* jnt_dofadr; // start addr in 'qvel' for joint's data (njnt x 1)
int* jnt_bodyid; // id of joint's body (njnt x 1)
int* jnt_actuatorid; // actuator contributing damping / armature (njnt x 1)
int* jnt_group; // group for visibility (njnt x 1)
mjtByte* jnt_limited; // does joint have limits (njnt x 1)
mjtByte* jnt_actfrclimited; // does joint have actuator force limits (njnt x 1)
@@ -1487,6 +1488,7 @@ struct mjModel_ {
int* tendon_adr; // address of first object in tendon's path (ntendon x 1)
int* tendon_num; // number of objects in tendon's path (ntendon x 1)
int* tendon_matid; // material id for rendering (ntendon x 1)
int* tendon_actuatorid; // actuator contributing damping / armature (ntendon x 1)
int* tendon_group; // group for visibility (ntendon x 1)
int* tendon_treenum; // number of trees along tendon's path (ntendon x 1)
int* tendon_treeid; // first two trees along tendon's path (ntendon x 2)
@@ -1526,6 +1528,9 @@ struct mjModel_ {
int* actuator_gaintype; // gain type (mjtGain) (nu x 1)
int* actuator_biastype; // bias type (mjtBias) (nu x 1)
int* actuator_trnid; // transmission id: joint, tendon, site (nu x 2)
mjtNum* actuator_damping; // linear damping coefficient (nu x 1)
mjtNum* actuator_dampingpoly; // high-order damping coefficients (nu x mjNPOLY)
mjtNum* actuator_armature; // armature added to target (joint, tendon) (nu x 1)
int* actuator_actadr; // first activation address; -1: stateless (nu x 1)
int* actuator_actnum; // number of activation variables (nu x 1)
int* actuator_group; // group for visibility (nu x 1)
@@ -2449,6 +2454,8 @@ typedef struct mjsActuator_ { // actuator specification
double cranklength; // crank length, for slider-crank
double lengthrange[2]; // transmission length range
double inheritrange; // automatic range setting for position and intvelocity
double damping[mjNPOLY+1]; // damping coefficients
double armature; // armature inertia
// input/output clamping
int ctrllimited; // are control limits defined (mjtLimited)