From 51126caf3ff51696e43cc7f29fb27977290e3b3f Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Mon, 24 Apr 2023 09:02:44 -0700 Subject: [PATCH] Cosmetic improvements to Actuation Model documentation. PiperOrigin-RevId: 526659426 Change-Id: If0ca9a505bb77e496739938a946ead5780b93d0f --- doc/computation.rst | 86 ++++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 37 deletions(-) diff --git a/doc/computation.rst b/doc/computation.rst index 646adc47..bd47c07a 100644 --- a/doc/computation.rst +++ b/doc/computation.rst @@ -258,7 +258,7 @@ actuator works. The user can set them independently for maximum flexibility, or .. _geTransmission: 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 vector of moment arms. It determines the mapping from scalar @@ -266,19 +266,23 @@ actuator force to joint force. The transmission properties are determined by the is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, :at:`jointinparent`, :at:`slider-crank`, :at:`site`, and :at:`body`. +:at:`joint` and :at:`tendon` The :at:`joint` and :at:`tendon` transmission types act as expected and correspond to the actuator applying forces or - torques to the target object. Ball joints are special, see the :at:`joint` documentation in - :ref:`actuator` reference for more details. + torques to the target object. Ball joints are special, see the :ref:`actuator/general/joint` + documentation for more details. +:at:`jointinparent` 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` :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` :at:`site` transmission (without a :at:`refsite`, see below) and :at:`body` transmission targets have a fixed zero length :math:`l_i(q) = 0`. They can therefore not be used to maintain a desired length, but can be used to apply forces. Site transmissions correspond to applying a Cartsian force/torque at the site, and are useful for modeling @@ -292,51 +296,59 @@ is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, be controlled with a :el:`position` actuator, enabling Cartesian end-effector control. See the :at:`refsite` documentation in :ref:`actuator` reference for more details. +.. _geActivation: + Activation dynamics - Some actuators such as pneumatic and hydraulic cylinders as well as biological muscles have an internal state called - "activation". This is a true dynamic state, beyond the joint positions :math:`q` and velocities :math:`v`. Including - such actuators in the model results in 3rd-order dynamics. We denote the vector of actuator activations :math:`w`. - They have some first-order dynamics +^^^^^^^^^^^^^^^^^^^ - .. math:: - \dot{w}_i \left( u_i, w_i, l_i, \dot{l}_i \right) +Some actuators such as pneumatic and hydraulic cylinders as well as biological muscles have an internal state called +"activation". This is a true dynamic state, beyond the joint positions :math:`q` and velocities :math:`v`. Including +such actuators in the model results in 3rd-order dynamics. We denote the vector of actuator activations :math:`w`. +They have some first-order dynamics - determined by the activation type and corresponding model parameters. Note that each actuator has scalar dynamics - independent of the other actuators. The activation types currently implemented are +.. math:: + \dot{w}_i \left( u_i, w_i, l_i, \dot{l}_i \right) - .. math:: - \begin{aligned} - \text{integrator}: & & \dot{w}_i &= u_i \\ - \text{filter}: & & \dot{w}_i &= (u_i - w_i) / t \\ - \end{aligned} +determined by the activation type and corresponding model parameters. Note that each actuator has scalar dynamics +independent of the other actuators. The activation types currently implemented are - where :math:`t` is an actuator-specific time constant stored in ``mjModel.actuator_dynprm``. In addition the type can - be "user", in which case :math:`w_i` is computed by the user-defined callback :ref:`mjcb_act_dyn`. The type can also - be "none" which corresponds to a regular actuator with no activation state. The dimensionality of :math:`w` equals - the number of actuators whose activation type is different from "none". +.. math:: + \begin{aligned} + \text{integrator}: & & \dot{w}_i &= u_i \\ + \text{filter}: & & \dot{w}_i &= (u_i - w_i) / t \\ + \end{aligned} + +where :math:`t` is an actuator-specific time constant stored in ``mjModel.actuator_dynprm``. In addition the type can +be "user", in which case :math:`w_i` is computed by the user-defined callback :ref:`mjcb_act_dyn`. The type can also +be "none" which corresponds to a regular actuator with no activation state. The dimensionality of :math:`w` equals +the number of actuators whose activation type is different from "none". + +.. _geActuatorForce: Force generation - Each actuator generates a scalar force :math:`p_i` which is some function +^^^^^^^^^^^^^^^^ - .. math:: - p_i \left( u_i, w_i, l_i, \dot{l}_i \right) +Each actuator generates a scalar force :math:`p_i` which is some function - Similarly to activation dynamics, the force generation mechanism is actuator-specific and cannot interact with the - other actuators in the model. Currently the force is affine in the activation state when present, and in the control - otherwise: +.. math:: + p_i \left( u_i, w_i, l_i, \dot{l}_i \right) - .. math:: - p_i = (a w_i \; \text{or} \; a u_i) + b_0 + b_1 l_i + b_2 \dot{l}_i +Similarly to activation dynamics, the force generation mechanism is actuator-specific and cannot interact with the +other actuators in the model. Currently the force is affine in the activation state when present, and in the control +otherwise: - Here :math:`a` is an actuator-specific gain parameter and :math:`b_0, b_1, b_2` are actuator-specific bias - parameters, stored in ``mjModel.actuator_gainprm`` and ``mjModel.actuator_biasprm`` respectively. Different settings - of the gain and bias parameters can be used to model direct force control as well as position and velocity servos -in - which case the control/activation has the meaning of reference position or velocity. One can also compute custom gain - and bias terms by installing the callbacks :ref:`mjcb_act_gain` and :ref:`mjcb_act_bias` and setting the gain and - bias type to "user". Note that affine force generation makes it possible to infer the controls/activations from the - applied force computed in inverse dynamics, using the pseudo-inverse of the matrix of moment arms. However some of - the actuators used in the real world are not affine (especially those that have embedded low-level controllers), so - we are considering extensions to the above model. +.. math:: + p_i = (a w_i \; \text{or} \; a u_i) + b_0 + b_1 l_i + b_2 \dot{l}_i + +Here :math:`a` is an actuator-specific gain parameter and :math:`b_0, b_1, b_2` are actuator-specific bias +parameters, stored in ``mjModel.actuator_gainprm`` and ``mjModel.actuator_biasprm`` respectively. Different settings +of the gain and bias parameters can be used to model direct force control as well as position and velocity servos -in +which case the control/activation has the meaning of reference position or velocity. One can also compute custom gain +and bias terms by installing the callbacks :ref:`mjcb_act_gain` and :ref:`mjcb_act_bias` and setting the gain and +bias type to "user". Note that affine force generation makes it possible to infer the controls/activations from the +applied force computed in inverse dynamics, using the pseudo-inverse of the matrix of moment arms. However some of +the actuators used in the real world are not affine (especially those that have embedded low-level controllers), so +we are considering extensions to the above model. Putting all this together, the net force in generalized coordinates contributed by all actuators is