Add mj_setKeyframe function to save current state in k-th model keyframe.

Fixes #1719.

Also improve documentation of `mju_sigmoid`, was previously only documented in changelog.

PiperOrigin-RevId: 642637458
Change-Id: I811a0bf8f881c8b76c9a62d2faec8fdec4e7585b

doc/APIreference/functions.rst

@@ -235,6 +235,15 @@ mj_setState
 Copy concatenated state components specified by ``spec`` from  ``state`` into ``d``. The bits of the integer
 ``spec`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``spec`` is invalid.
 
+.. _mj_setKeyframe:
+
+mj_setKeyframe
+~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_setKeyframe
+
+Copy current state to the k-th model keyframe.
+
 .. _mj_addContact:
 
 mj_addContact
@@ -1866,7 +1875,15 @@ mju_sigmoid
 
 .. mujoco-include:: mju_sigmoid
 
-Sigmoid function over 0<=x<=1 using quintic polynomial.
+Twice continuously differentiable sigmoid function using a quintic polynomial:
+
+.. math::
+   s(x) =
+   \begin{cases}
+      0,                    &       & x \le 0  \\
+      6x^5 - 15x^4 + 10x^3, & 0 \lt & x \lt 1  \\
+      1,                    & 1 \le & x \qquad
+   \end{cases}
 
 .. _Interaction:
 

doc/APIreference/functions_override.rst

@@ -533,6 +533,18 @@ Symmetrize square matrix :math:`R = \frac{1}{2}(M + M^T)`.
 
 .. _Miscellaneous:
 
+.. _mju_sigmoid:
+
+Twice continuously differentiable sigmoid function using a quintic polynomial:
+
+.. math::
+   s(x) =
+   \begin{cases}
+      0,                    &       & x \le 0  \\
+      6x^5 - 15x^4 + 10x^3, & 0 \lt & x \lt 1  \\
+      1,                    & 1 \le & x \qquad
+   \end{cases}
+
 .. _Derivatives-api:
 
 The functions below provide useful derivatives of various functions, both analytic and

doc/changelog.rst

@@ -21,13 +21,14 @@ General
    :ref:`camera/orthographic<body-camera-orthographic>` and :ref:`global/orthographic<visual-global-orthographic>`
    attributes, respectively.
 3. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
-4. Add support for ``ball`` joints in the URDF parser.
+4. Added :ref:`mj_setKeyframe` for saving the current state into a model keyframe.
+5. Added support for ``ball`` joints in the URDF parser ("spherical" in URDF).
 
 MJX
 ~~~
-5. Added support for :ref:`elliptic friction cones<option-cone>`.
-6. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
-7. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.
+6. Added support for :ref:`elliptic friction cones<option-cone>`.
+7. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
+8. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.
 
 Version 3.1.6 (Jun 3, 2024)
 ---------------------------

doc/includes/references.h

@@ -3171,6 +3171,7 @@ void mj_constraintUpdate(const mjModel* m, mjData* d, const mjtNum* jar,
 int mj_stateSize(const mjModel* m, unsigned int spec);
 void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int spec);
 void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int spec);
+void mj_setKeyframe(mjModel* m, const mjData* d, int k);
 int mj_addContact(const mjModel* m, mjData* d, const mjContact* con);
 int mj_isPyramidal(const mjModel* m);
 int mj_isSparse(const mjModel* m);