Update mjd_transitionFD documentation.

Fixes #713

PiperOrigin-RevId: 506248062
Change-Id: I1fbf8b378f500a6463a07eb5da5349c4f01ccb88

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<geIntegration>`.
 
-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<geState>` 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<gePhysicsState>` 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.

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<gePhysicsState>` 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.
 

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<gePhysicsState>` 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.
+