Improvements related to models where joint-actuator relationship is not one-to-one:
- Add `joint-actuatorforcerange` for clamping total actuator force at joints. Add `sensor-jointactuatorfrc` for sensing total actuator forces on a single joint. See [documentation](https://mujoco.readthedocs.io/en/latest//modeling.html#actuator-force-clamping) for justification and use cases. - Add simple car model to `model/`. - Move actuation-related test models into `engine/testdata/actuation/`. PiperOrigin-RevId: 549355941 Change-Id: I27f6c1f80426d73a2811ef5ae74684a228b2fbd1
This commit is contained in:
Yuval Tassa
committed by
Copybara-Service
Copybara-Service
parent
7603b07a20
commit
51aa375af0
+52
-1
@@ -1421,6 +1421,8 @@ if omitted.
|
||||
|
||||
.. _default-joint-limited:
|
||||
|
||||
.. _default-joint-actuatorforcelimited:
|
||||
|
||||
.. _default-joint-solreflimit:
|
||||
|
||||
.. _default-joint-solimplimit:
|
||||
@@ -1433,6 +1435,8 @@ if omitted.
|
||||
|
||||
.. _default-joint-range:
|
||||
|
||||
.. _default-joint-actuatorforcerange:
|
||||
|
||||
.. _default-joint-margin:
|
||||
|
||||
.. _default-joint-ref:
|
||||
@@ -3053,6 +3057,16 @@ unit quaternions.
|
||||
attribute is "auto", and :at:`autolimits` is set in :ref:`compiler <compiler>`, joint limits will be enabled
|
||||
if range is defined.
|
||||
|
||||
.. _body-joint-actuatorforcelimited:
|
||||
|
||||
:at:`actuatorforcelimited`: :at-val:`[false, true, auto], "auto"`
|
||||
This attribute specifies whether actuator forces acting on the joint should be clamped. See :ref:`CForceRange` for
|
||||
details. It is available only for scalar joints (hinge and slider) and ignored for ball and free joints. |br| This
|
||||
attribute interacts with the actuatorforcerange attribute below. If this attribute is "false", actuator force
|
||||
clamping is disabled. If it is "true", actuator force clamping is enabled. If this attribute is "auto", and
|
||||
:at:`autolimits` is set in :ref:`compiler <compiler>`, actuator force clamping will be enabled if actuatorforcerange
|
||||
is defined.
|
||||
|
||||
.. _body-joint-solreflimit:
|
||||
|
||||
.. _body-joint-solimplimit:
|
||||
@@ -3084,6 +3098,14 @@ unit quaternions.
|
||||
|br| Setting this attribute without specifying :at:`limited` is an error, unless :at:`autolimits` is set in
|
||||
:ref:`compiler <compiler>`.
|
||||
|
||||
.. _body-joint-actuatorforcerange:
|
||||
|
||||
:at:`actuatorforcerange`: :at-val:`real(2), "0 0"`
|
||||
Range for clamping total actuator forces acting on this joint. See :ref:`CForceRange` for details. It is available
|
||||
only for scalar joints (hinge and slider) and ignored for ball and free joints. |br| The compiler expects the first
|
||||
value to be smaller than the second value. |br| Setting this attribute without specifying :at:`actuatorforcelimited`
|
||||
is an error, unless :at:`compiler-autolimits` is set.
|
||||
|
||||
.. _body-joint-margin:
|
||||
|
||||
:at:`margin`: :at-val:`real, "0"`
|
||||
@@ -5009,7 +5031,8 @@ specify them independently.
|
||||
:at:`refsite`: :at-val:`string, optional`
|
||||
When using a :at:`site` transmission, measure the translation and rotation w.r.t the frame of the :at:`refsite`. In
|
||||
this case the actuator *does* have length and :el:`position` actuators can be used to directly control an end
|
||||
effector, see `refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example
|
||||
effector, see `refsite.xml
|
||||
<https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/actuation/refsite.xml>`__ example
|
||||
model. As above, the length is the dot product of the :at:`gear` vector and the frame difference. So ``gear="0 1 0 0
|
||||
0 0"`` means "Y-offset of :at:`site` in the :at:`refsite` frame", while ``gear="0 0 0 0 0 1"`` means rotation "Z-
|
||||
rotation of :at:`site` in the :at:`refsite` frame". It is recommended to use a normalized :at:`gear` vector with
|
||||
@@ -6217,6 +6240,34 @@ arms determined by the transmission). This sensor can be attached to any actuato
|
||||
The actuator whose scalar force output will be sensed. The sensor output is copied from mjData.actuator_force.
|
||||
|
||||
|
||||
.. _sensor-jointactuatorfrc:
|
||||
|
||||
:el-prefix:`sensor/` |-| **jointactuatorfrc** (*)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This element creates an actuator force sensor, measured at a joint. The quantity being sensed is the
|
||||
generalized force contributed by all actuators to a single scalar joint (hinge or slider). This type of sensor is
|
||||
important when multiple actuators act on a single joint or when a single actuator act on multiple joints. See
|
||||
:ref:`CForceRange` for details.
|
||||
|
||||
|
||||
.. _sensor-jointactuatorfrc-name:
|
||||
|
||||
.. _sensor-jointactuatorfrc-noise:
|
||||
|
||||
.. _sensor-jointactuatorfrc-cutoff:
|
||||
|
||||
.. _sensor-jointactuatorfrc-user:
|
||||
|
||||
:at:`name`, :at:`noise`, :at:`cutoff`, :at:`user`
|
||||
See :ref:`CSensor`.
|
||||
|
||||
.. _sensor-jointactuatorfrc-joint:
|
||||
|
||||
:at:`joint`: :at-val:`string, required`
|
||||
The joint where actuator forces will be sensed. The sensor output is copied from ``mjData.qfrc_actuator``.
|
||||
|
||||
|
||||
.. _sensor-ballquat:
|
||||
|
||||
:el-prefix:`sensor/` |-| **ballquat** (*)
|
||||
|
||||
+21
-10
@@ -220,15 +220,15 @@
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`axis<default-joint-axis>` | :ref:`springdamper<default-joint-springdamper>` | :ref:`limited<default-joint-limited>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`solreflimit<default-joint-solreflimit>` | :ref:`solimplimit<default-joint-solimplimit>` | :ref:`solreffriction<default-joint-solreffriction>` | |
|
||||
| | | | :ref:`actuatorforcelimited<default-joint-actuatorforcelimited>` | :ref:`solreflimit<default-joint-solreflimit>` | :ref:`solimplimit<default-joint-solimplimit>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`solimpfriction<default-joint-solimpfriction>` | :ref:`stiffness<default-joint-stiffness>` | :ref:`range<default-joint-range>` | |
|
||||
| | | | :ref:`solreffriction<default-joint-solreffriction>` | :ref:`solimpfriction<default-joint-solimpfriction>` | :ref:`stiffness<default-joint-stiffness>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`margin<default-joint-margin>` | :ref:`ref<default-joint-ref>` | :ref:`springref<default-joint-springref>` | |
|
||||
| | | | :ref:`range<default-joint-range>` | :ref:`actuatorforcerange<default-joint-actuatorforcerange>` | :ref:`margin<default-joint-margin>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`armature<default-joint-armature>` | :ref:`damping<default-joint-damping>` | :ref:`frictionloss<default-joint-frictionloss>` | |
|
||||
| | | | :ref:`ref<default-joint-ref>` | :ref:`springref<default-joint-springref>` | :ref:`armature<default-joint-armature>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`user<default-joint-user>` | | | |
|
||||
| | | | :ref:`damping<default-joint-damping>` | :ref:`frictionloss<default-joint-frictionloss>` | :ref:`user<default-joint-user>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| |_| default |br| |_| |L| | | .. table:: |
|
||||
@@ -627,15 +627,17 @@
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`group<body-joint-group>` | :ref:`pos<body-joint-pos>` | :ref:`axis<body-joint-axis>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`springdamper<body-joint-springdamper>` | :ref:`limited<body-joint-limited>` | :ref:`solreflimit<body-joint-solreflimit>` | |
|
||||
| | | | :ref:`springdamper<body-joint-springdamper>` | :ref:`limited<body-joint-limited>` | :ref:`actuatorforcelimited<body-joint-actuatorforcelimited>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`solimplimit<body-joint-solimplimit>` | :ref:`solreffriction<body-joint-solreffriction>` | :ref:`solimpfriction<body-joint-solimpfriction>` | |
|
||||
| | | | :ref:`solreflimit<body-joint-solreflimit>` | :ref:`solimplimit<body-joint-solimplimit>` | :ref:`solreffriction<body-joint-solreffriction>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`stiffness<body-joint-stiffness>` | :ref:`range<body-joint-range>` | :ref:`margin<body-joint-margin>` | |
|
||||
| | | | :ref:`solimpfriction<body-joint-solimpfriction>` | :ref:`stiffness<body-joint-stiffness>` | :ref:`range<body-joint-range>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`ref<body-joint-ref>` | :ref:`springref<body-joint-springref>` | :ref:`armature<body-joint-armature>` | |
|
||||
| | | | :ref:`actuatorforcerange<body-joint-actuatorforcerange>` | :ref:`margin<body-joint-margin>` | :ref:`ref<body-joint-ref>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`damping<body-joint-damping>` | :ref:`frictionloss<body-joint-frictionloss>` | :ref:`user<body-joint-user>` | |
|
||||
| | | | :ref:`springref<body-joint-springref>` | :ref:`armature<body-joint-armature>` | :ref:`damping<body-joint-damping>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`frictionloss<body-joint-frictionloss>` | :ref:`user<body-joint-user>` | | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| |_| body |br| |_| |L| | | .. table:: |
|
||||
@@ -1294,6 +1296,15 @@
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| |_| sensor |br| |_| |L| | | .. table:: |
|
||||
| :ref:`jointactuatorfrc | \* | :class: mjcf-attributes |
|
||||
| <sensor-jointactuatorfrc>` | | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`name<sensor-jointactuatorfrc-name>` | :ref:`joint<sensor-jointactuatorfrc-joint>` | :ref:`cutoff<sensor-jointactuatorfrc-cutoff>` | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
| | | | :ref:`noise<sensor-jointactuatorfrc-noise>` | :ref:`user<sensor-jointactuatorfrc-user>` | | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| |_| sensor |br| |_| |L| | | .. table:: |
|
||||
| :ref:`ballquat | \* | :class: mjcf-attributes |
|
||||
| <sensor-ballquat>` | | |
|
||||
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
|
||||
|
||||
+11
-1
@@ -9,6 +9,11 @@ General
|
||||
^^^^^^^
|
||||
|
||||
- Added primitive collider for sphere-cylinder contacts, previously this pair used the generic convex-convex collider.
|
||||
- Added :ref:`joint-actuatorforcerange<body-joint-actuatorforcerange>` for clamping total actuator force at joints and
|
||||
:ref:`sensor-jointactuatorfrc<sensor-jointactuatorfrc>` for measuring total actuation force applied at a joint. The
|
||||
most important use case for joint-level actuator force clamping is to ensure that
|
||||
:ref:`Cartesian actuator<actuator-general-refsite>` forces are realizable by individual motors at the joints.
|
||||
See :ref:`CForceRange` for details.
|
||||
- Added an optional ``content_type`` attribute to hfield, texture, and mesh assets. This attribute supports a formatted
|
||||
`MIME <https://en.wikipedia.org/wiki/MIME>`_ string used to determine the type of the asset file without resorting to
|
||||
pulling the type from the file extension.
|
||||
@@ -26,6 +31,10 @@ Python bindings
|
||||
(`#812 <https://github.com/deepmind/mujoco/issues/812>`_, `#958 <https://github.com/deepmind/mujoco/issues/958>`_,
|
||||
`#965 <https://github.com/deepmind/mujoco/issues/965>`_)
|
||||
|
||||
Models
|
||||
^^^^^^
|
||||
|
||||
- Added simple `car <https://github.com/deepmind/mujoco/blob/main/model/car/car.xml>`__ example model.
|
||||
|
||||
Version 2.3.6 (June 20, 2023)
|
||||
-----------------------------
|
||||
@@ -551,7 +560,8 @@ General
|
||||
|
||||
#. Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site`
|
||||
transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<actuator-general>` documentation
|
||||
and `refsite.xml <https://github.com/deepmind/mujoco/blob/main/test/engine/testdata/refsite.xml>`_ example model.
|
||||
and `refsite.xml <https://github.com/deepmind/mujoco/blob/main/test/engine/testdata/actuation/refsite.xml>`_ example
|
||||
model.
|
||||
|
||||
#. Added :at:`autolimits` compiler option. If ``true``, joint and tendon :at:`limited` attributes and actuator
|
||||
:at:`ctrllimited`, :at:`forcelimited` and :at:`actlimited` attributes will automatically be set to ``true`` if the
|
||||
|
||||
+2
-2
@@ -293,8 +293,8 @@ is attached; the possible attachment object types are :at:`joint`, :at:`tendon`,
|
||||
If a :at:`site` transmission target is defined with the optional :at:`refsite` attribute, forces and torques are
|
||||
applied in the frame of the reference site rather than the site's own frame. If a reference site is defined then
|
||||
the length of the actuator is nonzero and corresponds to the pose difference of the two sites. This length can then
|
||||
be controlled with a :el:`position` actuator, enabling Cartesian end-effector control. See the :at:`refsite`
|
||||
documentation in :ref:`actuator<actuator-general>` reference for more details.
|
||||
be controlled with a :el:`position` actuator, enabling Cartesian end-effector control. See the
|
||||
:ref:`refsite<actuator-general-refsite>` documentation for more details.
|
||||
|
||||
.. _geActivation:
|
||||
|
||||
|
||||
@@ -559,6 +559,7 @@ typedef enum mjtSensor_ { // type of sensor
|
||||
mjSENS_ACTUATORPOS, // scalar actuator position
|
||||
mjSENS_ACTUATORVEL, // scalar actuator velocity
|
||||
mjSENS_ACTUATORFRC, // scalar actuator force
|
||||
mjSENS_JOINTACTFRC, // scalar actuator force, measured at the joint
|
||||
|
||||
// sensors related to ball joints
|
||||
mjSENS_BALLQUAT, // 4D ball joint quaternion
|
||||
@@ -915,12 +916,14 @@ struct mjModel_ {
|
||||
int* jnt_bodyid; // id of joint's body (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)
|
||||
mjtNum* jnt_solref; // constraint solver reference: limit (njnt x mjNREF)
|
||||
mjtNum* jnt_solimp; // constraint solver impedance: limit (njnt x mjNIMP)
|
||||
mjtNum* jnt_pos; // local anchor position (njnt x 3)
|
||||
mjtNum* jnt_axis; // local joint axis (njnt x 3)
|
||||
mjtNum* jnt_stiffness; // stiffness coefficient (njnt x 1)
|
||||
mjtNum* jnt_range; // joint limits (njnt x 2)
|
||||
mjtNum* jnt_actfrcrange; // range of total actuator force (njnt x 2)
|
||||
mjtNum* jnt_margin; // min distance for limit detection (njnt x 1)
|
||||
mjtNum* jnt_user; // user data (njnt x nuser_jnt)
|
||||
|
||||
|
||||
+45
-3
@@ -591,6 +591,48 @@ defaults class and in the creation of actual model elements. If a given model re
|
||||
create multiple defaults classes, or avoid using defaults for actuators and instead specify all their attributes
|
||||
explicitly.
|
||||
|
||||
.. _CForceRange:
|
||||
|
||||
Actuator force clamping
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Actuator forces are usually limited between lower and upper bounds. These limits can be enforced in three ways:
|
||||
|
||||
Control clamping with :ref:`ctrlrange<actuator-general-ctrlrange>`:
|
||||
If this actuator attribute is set, the input control value will be clamped. For simple :ref:`motors<actuator-motor>`,
|
||||
clamping the control input is equivalent to clamping the force output.
|
||||
|
||||
Force clamping at actuator output with :ref:`forcerange<actuator-general-forcerange>`:
|
||||
If this actuator attribute is set, the actuator's output force will be clamped. This attribute is useful for e.g.
|
||||
:ref:`position actuators<actuator-position>`, to keep the forces within bounds. Note that position actuators
|
||||
usually also require control range clamping to avoid hitting joint limits.
|
||||
|
||||
Force clamping at joint input with :ref:`joint/actuatorforcerange<body-joint-actuatorforcerange>`:
|
||||
This joint attribute clamps input forces from all actuators acting on the joint, after passing through the
|
||||
:ref:`transmission<geTransmission>`. Clamping actuator forces at the joint is equivalent to clamping them at the
|
||||
actuator if the transmission is trivial (there is a one-to-one relationship between the actuator and the joint).
|
||||
However, in situations where multiple actuators act on one joint or one actuator acts on multiple joints---yet the
|
||||
actual torque is applied by a single physical actuator at the joint---it is desirable to clamp the forces at the joint
|
||||
itself. Below are three examples where it is desirable to clamp actuator forces at the joint, rather than the
|
||||
actuator:
|
||||
|
||||
- In `this example model
|
||||
<https://github.com/deepmind/mujoco/blob/main/test/engine/testdata/actuation/joint_force_clamp.xml>`__ ,
|
||||
two actuators, a :ref:`motor<actuator-motor>` and a :ref:`damper<actuator-damper>`, act on a single joint.
|
||||
- In `this example model <https://github.com/deepmind/mujoco/blob/main/model/car/car.xml>`__ (similar to a "Dubin's
|
||||
Car"), two actuators act on two wheels via a ref:`fixed tendon<tendon-fixed>` transmission in order to apply
|
||||
symmetric (roll forward/back) and antisymmetric (turn right/left) torques.
|
||||
- In `this example model <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/actuation/refsite.xml>`__,
|
||||
a :ref:`site transmission<actuator-general-refsite>` implements a Cartesian controller of an arm end-effector.
|
||||
In order for the computed torques to be realisable by individual, torque-limited joint motors, they need to be
|
||||
clamped at the joints.
|
||||
|
||||
Note that in this case, where forces/torques are combined by the transmission, one should use the
|
||||
:ref:`jointactuatorfrc<sensor-jointactuatorfrc>` sensor to report the total actuator force acting on a joint.
|
||||
The standard :ref:`actuatorfrc<sensor-actuatorfrc>` sensor will continue to report the pre-clamped actuator force.
|
||||
|
||||
The three clamping options above are non-exclusive and can be combined as required.
|
||||
|
||||
.. _CActRange:
|
||||
|
||||
Activation clamping
|
||||
@@ -601,9 +643,9 @@ with internal dynamics whose states are called "activations". One useful applica
|
||||
"integrated-velocity" actuator, implemented by the :ref:`intvelocity<actuator-intvelocity>` shortcut. Different from the
|
||||
:ref:`pure velocity<actuator-velocity>` actuators, which implement direct feedback on transmission target's velocity,
|
||||
*integrated-velocity* actuators couple an *integrator* with a *position-feedback* actuator. In this case the semantics
|
||||
of the activation state are "the target of the position actuator", and the semantics of the control signal are "the
|
||||
velocity of the target of the position actuator". Note that in real robotic systems this integrated-velocity actuator is
|
||||
the most common implementation of actuators with velocity semantics, rather than pure feedback on velocity which is
|
||||
of the activation state are "the setpoint of the position actuator", and the semantics of the control signal are "the
|
||||
velocity of the setpoint of the position actuator". Note that in real robotic systems this integrated-velocity actuator
|
||||
is the most common implementation of actuators with velocity semantics, rather than pure feedback on velocity which is
|
||||
often quite unstable (both in real life and in simulation).
|
||||
|
||||
In the case of integrated-velocity actuators, it is often desirable to *clamp* the activation state, since otherwise the
|
||||
|
||||
Reference in New Issue
Block a user