diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index ff7f3890..512da299 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -2386,6 +2386,11 @@ slidersite, cranksite. All :ref:`muscle ` attributes are available here except: name, class, joint, jointinparent, site, tendon, slidersite, cranksite. +:el-prefix:`default/` **adhesion** (?) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All :ref:`adhesion ` attributes are available here except: name, class, body. + .. _custom: **custom** (*) @@ -4287,7 +4292,7 @@ specify them independently. Identical to joint, except that for ball and free joints, the 3d rotation axis given by gear is defined in the parent frame (which is the world frame for free joints) rather than the child frame. :at:`site`: :at-val:`string, optional` - This actuator can applies force and torque at a site. The gear vector defines a 3d translation axis followed by a 3d + This transmission can apply force and torque at a site. The gear vector defines a 3d translation axis followed by a 3d rotation axis. Both are defined in the site's frame. This can be used to model jets and propellers. The effect is similar to actuating a free joint, and the actuator length is again defined as zero. One difference from the joint and jointinparent transmissions above is that here the actuator operates on a site rather than a joint, but this @@ -4295,6 +4300,11 @@ specify them independently. that for site transmissions both the translation and rotation axes are defined in local coordinates. In contrast, translation is global and rotation is local for joint, and both translation and rotation are global for jointinparent. +:at:`body`: :at-val:`string, optional` + This transmission can apply linear forces at contact points in the direction of the contact normal. The set of + contacts is all those belonging to the specified :at:`body`. This can be used to model natural active adhesion + mechanisms like the feet of geckos and insects. The actuator length is again defined as zero. For more information, + see the :ref:`adhesion` shortcut below. :at:`tendon`: :at-val:`string, optional` If specified, the actuator acts on the given tendon. The actuator length equals the tendon length times the gear ratio. Both spatial and fixed tendons can be used. @@ -4487,7 +4497,9 @@ This element has one custom attribute in addition to the common attributes: :el-prefix:`actuator/` **damper** (*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This element is an active damper which produces a force proportional to both velocity and control: ``F = - kv * velocity * control``, where ``kv`` must be nonnegative. :at:`ctrlrange` is required and must also be nonnegative. The underlying :el:`general` attributes are set as follows: +This element is an active damper which produces a force proportional to both velocity and control: ``F = - kv * velocity +* control``, where ``kv`` must be nonnegative. :at:`ctrlrange` is required and must also be nonnegative. The underlying +:el:`general` attributes are set as follows: =========== ======= ========= ======= Attribute Setting Attribute Setting @@ -4501,8 +4513,9 @@ ctrllimited true This element has one custom attribute in addition to the common attributes: -.. |actuator/damper attrib list| replace:: - :at:`name`, :at:`class`, :at:`group`, :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:`user` +.. |actuator/damper attrib list| replace:: :at:`name`, :at:`class`, :at:`group`, :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:`user` |actuator/damper attrib list| Same as in actuator/ :ref:`general `. @@ -4593,10 +4606,52 @@ This element has nine custom attributes in addition to the common attributes: :at:`fvmax`: :at-val:`real, "1.2"` Active force generated at saturating lengthening velocity, relative to the peak rest force. +.. _adhesion: + +:el-prefix:`actuator/` **adhesion** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. youtube:: HdBue4MUZys + :align: right + :height: 200px + +This element defines an active adhesion actuator which injects force at contacts in the normal direction. On the right +is a video demonstrating the this actuator type. The model shown in the video can be found `here +`_. The transmission target is a :el:`body`, and adhesive +forces are injected into all contacts invloving geoms which belong to this body. The force is devided equally between +multiple active contacts. Because it requires contact, it cannot apply force at a distance, and is more like the active +adhesion on the feet of geckos and insects rather than an industrial vaccum gripper. Adhesion actuators' length is +always 0. :at:`ctrlrange` is required and must also be nonnegative (no repulsive forces are allowed). The underlying +:el:`general` attributes are set as follows: + +=========== ======= =========== ======== +Attribute Setting Attribute Setting +=========== ======= =========== ======== +dyntype none dynprm 1 0 0 +gaintype fixed gainprm gain 0 0 +biastype none biasprm 0 0 0 +trntype body ctrllimited true +=========== ======= =========== ======== + + +This element has a subset of the common attributes and two custom attributes. + +.. |actuator/adhesion attrib list| replace:: :at:`name`, :at:`class`, :at:`group`, + :at:`forcelimited`, :at:`ctrlrange`, :at:`forcerange`, :at:`user` + +|actuator/adhesion attrib list| + Same as in actuator/ :ref:`general `. +:at:`body`: :at-val:`string, required` + The actuator acts on all contacts involving this body's geoms. +:at:`gain`: :at-val:`real, "1"` + Gain of the adhesion actuator, units of force. The total adhesion force applied by the actuator is the control value + multiplied by the gain. This force is distributed equally between all the contacts involving geoms belonging to the + target body. + .. _sensor: **sensor** (*) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~ This is a grouping element for sensor definitions. It does not have attributes. The outputs of all sensors are concatenated in the field mjData.sensordata which has size mjModel.nsensordata. This data is not used in any internal diff --git a/doc/changelog.rst b/doc/changelog.rst index 7bca7bb7..fbf27ad9 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -7,9 +7,11 @@ Upcoming version (not yet released) General ^^^^^^^ +- Added :ref:`adhesion actuators`. +- Added an `active adhesion example model `_. - Added :ref:`mj_jacSubtreeCom` for computing the translational Jacobian of the center-of-mass of a subtree. -- Added moment of inertia computation for concave meshes. This is a breaking change, to get back to the previous - behavior set the compiler flag :at:`exactmeshinertia` to false. +- Added moment of inertia computation for concave meshes. This is currently activated by setting the compiler flag + :at:`exactmeshinertia` to ``true`` (defaults to ``false``). This default may change in the future. - Added parameter :at:`shellinertia` in :at:`geom` for treating a mesh as a boundary mesh (shell) for inertia computations. This is currently supported only for meshes. - Raise error if the orientation of mesh faces is not consistent, which causes the inertia computations to be @@ -17,6 +19,7 @@ General Bug fixes ^^^^^^^^^ +- Fixed rendering of some transparent geoms in relflection. Version 2.2.1 (July 18, 2022) ----------------------------- @@ -24,45 +27,45 @@ Version 2.2.1 (July 18, 2022) General ^^^^^^^ -- Added ``mjd_transitionFD`` to compute efficient finite difference approximations of the state-transition and - control-transition matrices, :ref:`see here` for more details. -- Added derivatives for the ellipsoid fluid model. -- Added ``ctrl`` attribute to :ref:`keyframes`. -- Added ``clock`` sensor which :ref:`measures time`. -- Added visualisation groups to skins. -- Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission. -- Added visualisation for actuator activations. -- Added ```` actuator shortcut for "integrated velocity" actuators, documented :ref:`here `. -- Added ```` actuator shortcut for active-damping actuators, documented :ref:`here `. -- ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication. -- ``mjData.ctrl`` values are no longer clamped in-place, remain untouched by the engine. -- Arrays in mjData's buffer now align to 64-byte boundaries rather than 8-byte. -- Add memory poisoning when building with Address Sanitizer (ASAN) and Memory Sanitizer (MSAN). This allows ASAN to - detect reads and writes to regions in ``mjModel.buffer`` and ``mjData.buffer`` that do not lie within an array, and - for MSAN to detect reads from uninitialised fields in ``mjData`` following ``mj_resetData``. -- Add a `slider-crank example `_ to ``model/``. +1. Added ``mjd_transitionFD`` to compute efficient finite difference approximations of the state-transition and + control-transition matrices, :ref:`see here` for more details. +#. Added derivatives for the ellipsoid fluid model. +#. Added ``ctrl`` attribute to :ref:`keyframes`. +#. Added ``clock`` sensor which :ref:`measures time`. +#. Added visualisation groups to skins. +#. Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission. +#. Added visualisation for actuator activations. +#. Added ```` actuator shortcut for "integrated velocity" actuators, documented :ref:`here `. +#. Added ```` actuator shortcut for active-damping actuators, documented :ref:`here `. +#. ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication. +#. ``mjData.ctrl`` values are no longer clamped in-place, remain untouched by the engine. +#. Arrays in mjData's buffer now align to 64-byte boundaries rather than 8-byte. +#. Added memory poisoning when building with Address Sanitizer (ASAN) and Memory Sanitizer (MSAN). This allows ASAN to + detect reads and writes to regions in ``mjModel.buffer`` and ``mjData.buffer`` that do not lie within an array, and + for MSAN to detect reads from uninitialised fields in ``mjData`` following ``mj_resetData``. +#. Added a `slider-crank example model `_. Bug fixes ^^^^^^^^^ -- :ref:`Activation clamping ` was not being applied in the :ref:`implicit integrator`. -- Stricter parsing of orientation specifiers. Before this change, a specification that included both ``quat`` and an - :ref:`alternative specifier` e.g., ````, would lead to the - ``quat`` being ignored and only ``euler`` being used. After this change a parse error will be thrown. -- Stricter parsing of XML attributes. Before this change an erroneous XML snippet like ```` would - have been parsed as ``size="1 0 0"`` and no error would have been thrown. Now throws an error. -- Trying to load a ``NaN`` via XML like ````, while allowed for debugging purposes, will now print - a warning. -- Fixed null pointer dereference in ``mj_loadModel``. -- Fixed memory leaks when loading an invalid model from MJB. -- Integer overflows are now avoided when computing ``mjModel`` buffer sizes. -- Added missing warning string for ``mjWARN_BADCTRL``. +15. :ref:`Activation clamping ` was not being applied in the :ref:`implicit integrator`. +#. Stricter parsing of orientation specifiers. Before this change, a specification that included both ``quat`` and an + :ref:`alternative specifier` e.g., ````, would lead to + the ``quat`` being ignored and only ``euler`` being used. After this change a parse error will be thrown. +#. Stricter parsing of XML attributes. Before this change an erroneous XML snippet like ```` would + have been parsed as ``size="1 0 0"`` and no error would have been thrown. Now throws an error. +#. Trying to load a ``NaN`` via XML like ````, while allowed for debugging purposes, will now print + a warning. +#. Fixed null pointer dereference in ``mj_loadModel``. +#. Fixed memory leaks when loading an invalid model from MJB. +#. Integer overflows are now avoided when computing ``mjModel`` buffer sizes. +#. Added missing warning string for ``mjWARN_BADCTRL``. Packaging ^^^^^^^^^ -- Changed MacOS packaging so that the copy of ``mujoco.framework`` embedded in ``MuJoCo.app`` can be used to build - applications externally. +23. Changed MacOS packaging so that the copy of ``mujoco.framework`` embedded in ``MuJoCo.app`` can be used to build + applications externally. Version 2.2.0 (May 23, 2022) diff --git a/doc/computation.rst b/doc/computation.rst index 5ceabc1c..82421373 100644 --- a/doc/computation.rst +++ b/doc/computation.rst @@ -256,12 +256,28 @@ actuator works. The user can set them independently for maximum flexibility, or ` which instantiate common actuator types. Transmission + Each actuator has a scalar length :math:`l_i(q)` defined by the type of transmission and its parameters. The gradient - :math:`\nabla l_i` is an :math:`n_V`-dimensional column vector of moment arms. It determines the mapping from scalar + :math:`\nabla l_i` is an :math:`n_V`-dimensional vector of moment arms. It determines the mapping from scalar actuator force to joint force. The transmission properties are determined by the MuJoCo object to which the actuator - is attached; the possible attachment object types are joint, tendon, site and slider-crank. The latter can also be - modeled explicitly by creating MuJoCo bodies and coupling them with equality constraints to the rest of the system, - but that would be less efficient. + is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, :at:`jointinparent`, + :at:`slider-crank`, :at:`site`, and :at:`body`. The :at:`joint` and :at:`tendon` transmission types act as expected + mechanically and correspond to the actuator applying forces or torques to the target object. + + The :at:`jointinparent` transmission is unique to ball and free joint and asserts that rotation should be measured + in the parent rather than child frame. + + :at:`slider-crank` `transmissions `_ transform a linear force to + a torque, as in a piston-driven combustion engine. `This model + `_ contains pedagogical examples. Slider-cranks can + also be modeled explicitly by creating MuJoCo bodies and coupling them with equality constraints to the rest of the + system, but that would be less efficient. + + :at:`site` and :at:`body` are degenerate transmission targets, as their length :math:`l_i(q)` is always 0. + They can therefore not be used to maintain a desired length value, as with a position actuator. Site + transmissions correspond to applying a Cartsian force/torque at the site, while :el:`body` transmissions correspond + to applying forces at contact points belonging to a body. For more information about adhesion, see the + :ref:`adhesion` shorcut documentation. Activation dynamics Some actuators such as pneumatic and hydraulic cylinders as well as biological muscles have an internal state called @@ -1458,14 +1474,14 @@ The top-level function :ref:`mj_step` invokes the sequence of computations below cameras and lights. It also normalizes all quaternions, just in case. #. Compute the body inertias and joint axes, in global frames centered at the centers of mass of the corresponding kinematic subtrees (to improve floating-point accuracy). -#. Compute the tendon lengths and moment arms. This includes the computation of minimal-length paths for spatial - tendons. #. Compute the actuator lengths and moment arms. #. Compute the composite rigid body inertias and construct the joint-space inertia matrix. #. Compute the sparse factorization of the joint-space inertia matrix. #. Construct the list of active contacts. This includes both broad-phase and near-phase collision detection. #. Construct the constraint Jacobian and compute the constraint residuals. #. Compute the matrices and vectors needed by the constraint solvers. +#. Compute the tendon lengths and moment arms. This includes the computation of minimal-length paths for spatial + tendons. #. Compute sensor data that only depends on position, and the potential energy if enabled. #. Compute the tendon and actuator velocities. #. Compute the body velocities and rates of change of the joint axes, again in the global coordinate frames centered at diff --git a/doc/modeling.rst b/doc/modeling.rst index 5c11b2a3..0582bc9c 100644 --- a/doc/modeling.rst +++ b/doc/modeling.rst @@ -492,9 +492,10 @@ addition, the user can specify the maximum number of iterations, and tolerance l There is also a second Noslip solver, which is a post-processing step enabled by specifying a positive number of noslip iterations. All these algorithm settings can be specified in the :ref:`option