From e2691f58a5cde9ba81005596794ea96bed27a7bd Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Wed, 1 Feb 2023 01:52:20 -0800 Subject: [PATCH] Update `mjd_transitionFD` documentation. Fixes #713 PiperOrigin-RevId: 506248062 Change-Id: I1fbf8b378f500a6463a07eb5da5349c4f01ccb88 --- doc/computation.rst | 18 ++++++++++-------- doc/functions.rst | 20 ++++++++++++++++++-- doc/functions_override.rst | 21 +++++++++++++++++++-- 3 files changed, 47 insertions(+), 12 deletions(-) diff --git a/doc/computation.rst b/doc/computation.rst index 5eac95e8..dd313634 100644 --- a/doc/computation.rst +++ b/doc/computation.rst @@ -1556,20 +1556,22 @@ MuJoCo's entire computational pipline and uniquely -- its constraint solver -- a efficient implementations of these derivatives is a long term goal of the development team. Analytic derivatives of the smooth dynamics with respect to velocity are already in place and power the :ref:`implicit integrator`. -The function ``mjd_transitionFD`` computes state-transition and control-transition Jacobians. Given any valid MuJoCo +The function :ref:`mjd_transitionFD` computes state-transition and control-transition Jacobians. Given any valid MuJoCo model ``mjModel* m`` with an initial :ref:`simulation state` in ``mjData* d``, -- Let :math:`x` denote the *physics state* of the simulation at time :math:`t` -- the concatenation of positions, - velocities and actuator states ``[d->qpos; d->qvel; d->act]``. +- Let :math:`x` denote the :ref:`physics state` of the simulation at time :math:`t` -- the concatenation + of positions, velocities and actuator states ``[d->qpos; d->qvel; d->act]``. - Let :math:`u` denote the vector of controls at time :math:`t`, corresponding to ``d->ctrl``. - Let :math:`y` denote the physical state of the simulation at time :math:`t+h`, where :math:`h` corresponds to ``m->opt.timstep``. -- The high level function ``mj_step(m, d)`` computes :math:`y(x, u)` -- the next state as a function of - the current state and control. -- ``mjd_transitionFD`` computes the Jacobians :math:`A = \frac{\partial y}{\partial x}` and - :math:`B = \frac{\partial y}{\partial u}` using efficient finite-differencing of ``mj_step``. +- Let :math:`s` denote the values of the sensors defined in the model. +- The high level function :ref:`mj_step` computes :math:`(x,u) \rightarrow (y,s)`: the next state and + sensor values as a function of the current state and control. +- ``mjd_transitionFD`` computes the Jacobians :math:`A = \frac{\partial y}{\partial x}`, + :math:`B = \frac{\partial y}{\partial u}`, :math:`C = \frac{\partial s}{\partial x}` and + :math:`D = \frac{\partial s}{\partial u}` using efficient finite-differencing of :ref:`mj_step`. -These derivatives are efficient by exploiting MuJoCo's configurable computation pipeline so that quantities are not +These derivatives are made efficient by exploiting MuJoCo's configurable computation pipeline so that quantities are not recomputed when not required. For example when differencing with respect to controls, quantities which depend only on position and velocity are not recomputed. Additionally, solver warmstarts, quaternions and control clamping are handled correctly. Both forward and centered differences are supported. diff --git a/doc/functions.rst b/doc/functions.rst index 161a676a..c14b5513 100644 --- a/doc/functions.rst +++ b/doc/functions.rst @@ -2983,6 +2983,22 @@ mjd_transitionFD .. mujoco-include:: mjd_transitionFD -Finite differenced state-transition and control-transition matrices dx(t+h) = A*dx(t) + B*du(t). Required output matrix -dimensions: A: (2*nv+na x 2*nv+na), B: (2*nv+na x nu). +Finite differenced transition matrices. Letting :math:`x, u` denote the current :ref:`state` and control +vectors and letting :math:`y, s` denote the next state and sensor values, the top-level :ref:`mj_step` function computes +:math:`(x,u) \rightarrow (y,s)`. :ref:`mjd_transitionFD` computes the four associated Jacobians using +finite-differencing. These matrices and their dimensions are: + +.. csv-table:: + :header: "matrix", "Jacobian", "dimension" + :widths: auto + :align: left + + ``A``, :math:`\partial y / \partial x`, ``2*nv+na x 2*nv+na`` + ``B``, :math:`\partial y / \partial u`, ``2*nv+na x nu`` + ``C``, :math:`\partial s / \partial x`, ``nsensordata x 2*nv+na`` + ``D``, :math:`\partial s / \partial u`, ``nsensordata x nu`` + +- All four matrix outputs are optional (can be ``NULL``). +- ``eps`` is the finite-differencing epsilon. +- ``centered`` is a flag denoting whether to use forward (0) or centered (1) differences. diff --git a/doc/functions_override.rst b/doc/functions_override.rst index 6880aee3..844c3634 100644 --- a/doc/functions_override.rst +++ b/doc/functions_override.rst @@ -368,5 +368,22 @@ Symmetrize square matrix :math:`R = \frac{1}{2}(M + M^T)`. .. _mjd_transitionFD: -Finite differenced state-transition and control-transition matrices dx(t+h) = A*dx(t) + B*du(t). Required output matrix -dimensions: A: (2*nv+na x 2*nv+na), B: (2*nv+na x nu). +Finite differenced transition matrices. Letting :math:`x, u` denote the current :ref:`state` and control +vectors and letting :math:`y, s` denote the next state and sensor values, the top-level :ref:`mj_step` function computes +:math:`(x,u) \rightarrow (y,s)`. :ref:`mjd_transitionFD` computes the four associated Jacobians using +finite-differencing. These matrices and their dimensions are: + +.. csv-table:: + :header: "matrix", "Jacobian", "dimension" + :widths: auto + :align: left + + ``A``, :math:`\partial y / \partial x`, ``2*nv+na x 2*nv+na`` + ``B``, :math:`\partial y / \partial u`, ``2*nv+na x nu`` + ``C``, :math:`\partial s / \partial x`, ``nsensordata x 2*nv+na`` + ``D``, :math:`\partial s / \partial u`, ``nsensordata x nu`` + +- All four matrix outputs are optional (can be NULL). +- ``eps`` is the finite-differencing epsilon. +- ``centered`` is a flag denoting whether to use forward (0) or centered (1) differences. +