Autogenerate functions.rst for API reference docs.

PiperOrigin-RevId: 501496950
Change-Id: I92ab013e6acb4d6772eb5dcf56740105908afc97

doc/conf.py

@@ -58,7 +58,7 @@ templates_path = ['templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'functions.rst',
-    'XMLschema.rst'
+    'functions_override.rst', 'XMLschema.rst'
 ]
 
 redirects = {

doc/ext/header_reader.py

@@ -38,7 +38,7 @@ _STRUCT_END_REGEX_2 = re.compile(r'^}\s+(?P<token>mj\w+);')
 _ENUM_END_REGEX = re.compile(r'^}\s+(?P<token>mj\w+);')
 
 
-@dataclasses.dataclass(frozen=True)
+@dataclasses.dataclass
 class ApiDefinition:
   """Defines a C reference parsed from a C header file."""
   token: str

doc/functions.rst

@@ -1,3 +1,7 @@
+..
+  AUTOGENERATE: DO NOT EDIT
+
+
 .. _Activation:
 
 Activation
@@ -12,7 +16,7 @@ mj_activate
 
 .. mujoco-include:: mj_activate
 
-Does nothing, returns 1.
+Return 1 (for backward compatibility).
 
 .. _mj_deactivate:
 
@@ -21,7 +25,7 @@ mj_deactivate
 
 .. mujoco-include:: mj_deactivate
 
-Does nothing.
+Do nothing (for backward compatibility).
 
 .. _Virtualfilesystem:
 
@@ -58,7 +62,7 @@ mj_addFileVFS
 
 .. mujoco-include:: mj_addFileVFS
 
-Add file to VFS, return 0: success, 1: full, 2: repeated name, -1: not found on disk.
+Add file to VFS, return 0: success, 1: full, 2: repeated name, -1: failed to load.
 
 .. _mj_makeEmptyFileVFS:
 
@@ -112,8 +116,9 @@ mj_loadXML
 
 .. mujoco-include:: mj_loadXML
 
-Parse XML file in MJCF or URDF format, compile it, return low-level model. If vfs is not NULL, look up files in vfs
+Parse XML file in MJCF or URDF format, compile it, return low-level model.
-before reading from disk. If error is not NULL, it must have size error_sz.
+If vfs is not ``NULL``, look up files in vfs before reading from disk.
+If error is not ``NULL``, it must have size error_sz.
 
 .. _mj_saveLastXML:
 
@@ -122,8 +127,8 @@ mj_saveLastXML
 
 .. mujoco-include:: mj_saveLastXML
 
-Update XML data structures with info from low-level model, save as MJCF. If error is not NULL, it must have size
+Update XML data structures with info from low-level model, save as MJCF.
-error_sz.
+If error is not ``NULL``, it must have size error_sz.
 
 .. _mj_freeLastXML:
 
@@ -286,7 +291,7 @@ mj_copyModel
 
 .. mujoco-include:: mj_copyModel
 
-Copy mjModel, allocate new if dest is NULL.
+Copy ``mjModel``, allocate new if dest is ``NULL``.
 
 .. _mj_saveModel:
 
@@ -304,7 +309,8 @@ mj_loadModel
 
 .. mujoco-include:: mj_loadModel
 
-Load model from binary MJB file. If vfs is not NULL, look up file in vfs before reading from disk.
+Load model from binary MJB file.
+If vfs is not ``NULL``, look up file in vfs before reading from disk.
 
 .. _mj_deleteModel:
 
@@ -331,7 +337,8 @@ mj_makeData
 
 .. mujoco-include:: mj_makeData
 
-Allocate mjData corresponding to given model.
+Allocate ``mjData`` corresponding to given model.
+If the model buffer is unallocated the initial configuration will not be set.
 
 .. _mj_copyData:
 
@@ -340,7 +347,8 @@ mj_copyData
 
 .. mujoco-include:: mj_copyData
 
-Copy mjData.
+Copy ``mjData``.
+m is only required to contain the size fields from MJMODEL_INTS.
 
 .. _mj_resetData:
 
@@ -376,7 +384,7 @@ mj_stackAlloc
 
 .. mujoco-include:: mj_stackAlloc
 
-Allocate array of specified size on mjData stack. Call mju_error on stack overflow.
+Allocate array of specified size on ``mjData`` stack. Call mju_error on stack overflow.
 
 .. _mj_deleteData:
 
@@ -385,7 +393,7 @@ mj_deleteData
 
 .. mujoco-include:: mj_deleteData
 
-Free memory allocation in mjData.
+Free memory allocation in ``mjData``.
 
 .. _mj_resetCallbacks:
 
@@ -394,7 +402,7 @@ mj_resetCallbacks
 
 .. mujoco-include:: mj_resetCallbacks
 
-Reset all callbacks to NULL pointers (NULL is the default).
+Reset all callbacks to ``NULL`` pointers (``NULL`` is the default).
 
 .. _mj_setConst:
 
@@ -403,7 +411,7 @@ mj_setConst
 
 .. mujoco-include:: mj_setConst
 
-Set constant fields of mjModel, corresponding to qpos0 configuration.
+Set constant fields of ``mjModel``, corresponding to qpos0 configuration.
 
 .. _mj_setLengthRange:
 
@@ -421,7 +429,6 @@ Printing
 
 These functions can be used to print various quantities to the screen for debugging purposes.
 
-
 .. _mj_printFormattedModel:
 
 mj_printFormattedModel
@@ -429,8 +436,8 @@ mj_printFormattedModel
 
 .. mujoco-include:: mj_printFormattedModel
 
-Print ``mjModel`` to text file, specifying format. ``float_format`` must be a valid printf-style format string for a
+Print ``mjModel`` to text file, specifying format.
-single float value.
+float_format must be a valid printf-style format string for a single float value.
 
 .. _mj_printModel:
 
@@ -444,12 +451,12 @@ Print model to text file.
 .. _mj_printFormattedData:
 
 mj_printFormattedData
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
 
 .. mujoco-include:: mj_printFormattedData
 
-Print ``mjData`` to text file, specifying format. ``float_format`` must be a valid printf-style format string for a
+Print ``mjData`` to text file, specifying format.
-single float value.
+float_format must be a valid printf-style format string for a single float value
 
 .. _mj_printData:
 
@@ -683,6 +690,8 @@ mj_comPos
 
 Map inertias and motion dofs to global frame centered at CoM.
 
+.. _mj_camlight:
+
 mj_camlight
 ~~~~~~~~~~~
 
@@ -690,6 +699,8 @@ mj_camlight
 
 Compute camera and light positions and orientations.
 
+.. _mj_tendon:
+
 mj_tendon
 ~~~~~~~~~
 
@@ -697,6 +708,8 @@ mj_tendon
 
 Compute tendon lengths, velocities and moment arms.
 
+.. _mj_transmission:
+
 mj_transmission
 ~~~~~~~~~~~~~~~
 
@@ -704,6 +717,8 @@ mj_transmission
 
 Compute actuator transmission lengths and moments.
 
+.. _mj_crb:
+
 mj_crb
 ~~~~~~
 
@@ -747,6 +762,8 @@ mj_comVel
 
 Compute cvel, cdof_dot.
 
+.. _mj_passive:
+
 mj_passive
 ~~~~~~~~~~
 
@@ -763,6 +780,8 @@ mj_subtreeVel
 
 subtree linear velocity and angular momentum
 
+.. _mj_rne:
+
 mj_rne
 ~~~~~~
 
@@ -815,14 +834,14 @@ mj_referenceConstraint
 
 Compute efc_vel, efc_aref.
 
-. _mj_constraintUpdate:
+.. _mj_constraintUpdate:
 
 mj_constraintUpdate
 ~~~~~~~~~~~~~~~~~~~
 
 .. mujoco-include:: mj_constraintUpdate
 
-Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not NULL, set \*cost = s(jar)
+Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not ``NULL``, set \*cost = s(jar)
 where jar = Jac*qacc-aref.
 
 .. _Support:
@@ -877,7 +896,7 @@ mj_mulJacVec
 
 .. mujoco-include:: mj_mulJacVec
 
-This function multiplies the constraint Jacobian mjData.efc_J by a vector. Note that the Jacobian can be either dense or
+This function multiplies the constraint Jacobian ``mjData.efc_J`` by a vector. Note that the Jacobian can be either dense or
 sparse; the function is aware of this setting. Multiplication by J maps velocities from joint space to constraint space.
 
 .. _mj_mulJacTVec:
@@ -899,7 +918,7 @@ mj_jac
 
 This function computes an "end-effector" Jacobian, which is unrelated to the constraint Jacobian above. Any MuJoCo body
 can be treated as end-effector, and the point for which the Jacobian is computed can be anywhere in space (it is treated
-as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing NULL for
+as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing ``NULL`` for
 either pointer will skip part of the computation. Each component is a 3-by-nv matrix. Each row of this matrix is the
 gradient of the corresponding 3D coordinate of the specified point with respect to the degrees of freedom. The ability
 to compute end-effector Jacobians analytically is one of the advantages of working in minimal coordinates - so use it!
@@ -930,7 +949,7 @@ mj_jacSubtreeCom
 
 .. mujoco-include:: mj_jacSubtreeCom
 
-Compute subtree center-of-mass end-effector Jacobian. ``jacp`` is 3 x nv.
+Compute subtree center-of-mass end-effector Jacobian.
 
 .. _mj_jacGeom:
 
@@ -993,7 +1012,7 @@ mj_mulM
 
 .. mujoco-include:: mj_mulM
 
-This function multiplies the joint-space inertia matrix stored in mjData.qM by a vector. qM has a custom sparse format
+This function multiplies the joint-space inertia matrix stored in ``mjData.qM`` by a vector. qM has a custom sparse format
 that the user should not attempt to manipulate directly. Alternatively one can convert qM to a dense matrix with
 mj_fullM and then user regular matrix-vector multiplication, but this is slower because it no longer benefits from
 sparsity.
@@ -1014,7 +1033,8 @@ mj_addM
 
 .. mujoco-include:: mj_addM
 
-Add inertia matrix to destination matrix. Destination can be sparse uncompressed, or dense when all int\* are NULL
+Add inertia matrix to destination matrix.
+Destination can be sparse uncompressed, or dense when all int* are ``NULL``
 
 .. _mj_applyFT:
 
@@ -1024,7 +1044,7 @@ mj_applyFT
 .. mujoco-include:: mj_applyFT
 
 This function can be used to apply a Cartesian force and torque to a point on a body, and add the result to the vector
-mjData.qfrc_applied of all applied forces. Note that the function requires a pointer to this vector, because sometimes
+``mjData.qfrc_applied`` of all applied forces. Note that the function requires a pointer to this vector, because sometimes
 we want to add the result to a different vector.
 
 .. _mj_objectVelocity:
@@ -1113,6 +1133,36 @@ mj_setTotalmass
 
 Scale body masses and inertias to achieve specified total mass.
 
+.. _mj_getPluginConfig:
+
+mj_getPluginConfig
+~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_getPluginConfig
+
+Return a config attribute value of a plugin instance;
+``NULL``: invalid plugin instance ID or attribute name
+
+.. _mj_loadPluginLibrary:
+
+mj_loadPluginLibrary
+~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_loadPluginLibrary
+
+Load a dynamic library. The dynamic library is assumed to register one or more plugins.
+
+.. _mj_loadAllPluginLibraries:
+
+mj_loadAllPluginLibraries
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_loadAllPluginLibraries
+
+Scan a directory and load all dynamic libraries. Dynamic libraries in the specified directory
+are assumed to register one or more plugins. Optionally, if a callback is specified, it is called
+for each dynamic library encountered that registers plugins.
+
 .. _mj_version:
 
 mj_version
@@ -1122,7 +1172,7 @@ mj_version
 
 Return version number: 1.0.2 is encoded as 102.
 
-.. mj_versionString:
+.. _mj_versionString:
 
 mj_versionString
 ~~~~~~~~~~~~~~~~
@@ -1155,7 +1205,7 @@ mj_ray
 Intersect ray (pnt+x*vec, x>=0) with visible geoms, except geoms in bodyexclude. Return geomid and distance (x) to
 nearest surface, or -1 if no intersection.
 
-geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=NULL to skip
+geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=``NULL`` to skip
 group exclusion.
 If flg_static is 0, static geoms will be excluded.
 bodyexclude=-1 can be used to indicate that all bodies are included.
@@ -1167,7 +1217,7 @@ mj_rayHfield
 
 .. mujoco-include:: mj_rayHfield
 
-Interect ray with hfield, return nearest distance or -1 if no intersection.
+Intersect ray with hfield, return nearest distance or -1 if no intersection.
 
 .. _mj_rayMesh:
 
@@ -1176,7 +1226,7 @@ mj_rayMesh
 
 .. mujoco-include:: mj_rayMesh
 
-Interect ray with mesh, return nearest distance or -1 if no intersection.
+Intersect ray with mesh, return nearest distance or -1 if no intersection.
 
 .. _mju_rayGeom:
 
@@ -1185,7 +1235,7 @@ mju_rayGeom
 
 .. mujoco-include:: mju_rayGeom
 
-Interect ray with pure geom, return nearest distance or -1 if no intersection.
+Intersect ray with pure geom, return nearest distance or -1 if no intersection.
 
 .. _mju_raySkin:
 
@@ -1194,7 +1244,8 @@ mju_raySkin
 
 .. mujoco-include:: mju_raySkin
 
-Interect ray with skin, return nearest vertex id.
+Intersect ray with skin, return nearest distance or -1 if no intersection,
+and also output nearest vertex id.
 
 .. _Interaction:
 
@@ -1328,8 +1379,8 @@ mjv_applyPerturbPose
 
 .. mujoco-include:: mjv_applyPerturbPose
 
-Set perturb pos,quat in d->mocap when selected body is mocap, and in d->qpos otherwise. Write d->qpos only if flg_paused
+Set perturb pos,quat in d->mocap when selected body is mocap, and in d->qpos otherwise.
-and subtree root for selected body has free joint.
+Write d->qpos only if flg_paused and subtree root for selected body has free joint.
 
 .. _mjv_applyPerturbForce:
 
@@ -1396,7 +1447,7 @@ mjv_initGeom
 
 .. mujoco-include:: mjv_initGeom
 
-Initialize given geom fields when not NULL, set the rest to their default values.
+Initialize given geom fields when not ``NULL``, set the rest to their default values.
 
 .. _mjv_makeConnector:
 
@@ -1405,8 +1456,8 @@ mjv_makeConnector
 
 .. mujoco-include:: mjv_makeConnector
 
-Set (type, size, pos, mat) for connector-type geom between given points. Assume that mjv_initGeom was already called to
+Set (type, size, pos, mat) for connector-type geom between given points.
-set all other properties.
+Assume that mjv_initGeom was already called to set all other properties.
 
 .. _mjv_defaultScene:
 
@@ -1576,8 +1627,8 @@ mjr_setBuffer
 
 .. mujoco-include:: mjr_setBuffer
 
-Set OpenGL framebuffer for rendering: mjFB_WINDOW or mjFB_OFFSCREEN. If only one buffer is available, set that buffer
+Set OpenGL framebuffer for rendering: mjFB_WINDOW or mjFB_OFFSCREEN.
-and ignore framebuffer argument.
+If only one buffer is available, set that buffer and ignore framebuffer argument.
 
 .. _mjr_readPixels:
 
@@ -1586,8 +1637,8 @@ mjr_readPixels
 
 .. mujoco-include:: mjr_readPixels
 
-Read pixels from current OpenGL framebuffer to client buffer. Viewport is in OpenGL framebuffer; client buffer starts at
+Read pixels from current OpenGL framebuffer to client buffer.
-(0,0).
+Viewport is in OpenGL framebuffer; client buffer starts at (0,0).
 
 .. _mjr_drawPixels:
 
@@ -1596,8 +1647,8 @@ mjr_drawPixels
 
 .. mujoco-include:: mjr_drawPixels
 
-Draw pixels from client buffer to current OpenGL framebuffer. Viewport is in OpenGL framebuffer; client buffer starts at
+Draw pixels from client buffer to current OpenGL framebuffer.
-(0,0).
+Viewport is in OpenGL framebuffer; client buffer starts at (0,0).
 
 .. _mjr_blitBuffer:
 
@@ -1606,8 +1657,8 @@ mjr_blitBuffer
 
 .. mujoco-include:: mjr_blitBuffer
 
-Blit from src viewpoint in current framebuffer to dst viewport in other framebuffer. If src, dst have different size and
+Blit from src viewpoint in current framebuffer to dst viewport in other framebuffer.
-flg_depth==0, color is interpolated with GL_LINEAR.
+If src, dst have different size and flg_depth==0, color is interpolated with GL_LINEAR.
 
 .. _mjr_setAux:
 
@@ -1666,7 +1717,7 @@ Draw rectangle.
 .. _mjr_label:
 
 mjr_label
-~~~~~~~~~~~~~
+~~~~~~~~~
 
 .. mujoco-include:: mjr_label
 
@@ -1740,6 +1791,8 @@ mjui_themeColor
 
 Get builtin UI theme color (ind: 0-3).
 
+.. _mjui_add:
+
 mjui_add
 ~~~~~~~~
 
@@ -1747,6 +1800,8 @@ mjui_add
 
 Add definitions to UI.
 
+.. _mjui_addToSection:
+
 mjui_addToSection
 ~~~~~~~~~~~~~~~~~
 
@@ -1754,6 +1809,8 @@ mjui_addToSection
 
 Add definitions to UI section.
 
+.. _mjui_resize:
+
 mjui_resize
 ~~~~~~~~~~~
 
@@ -1770,12 +1827,16 @@ mjui_update
 
 Update specific section/item; -1: update all.
 
+.. _mjui_event:
+
 mjui_event
 ~~~~~~~~~~
 
 .. mujoco-include:: mjui_event
 
-Handle UI event, return pointer to changed item, NULL if no change.
+Handle UI event, return pointer to changed item, ``NULL`` if no change.
+
+.. _mjui_render:
 
 mjui_render
 ~~~~~~~~~~~
@@ -1825,6 +1886,8 @@ mju_warning
 
 Main warning function; returns to caller.
 
+.. _mju_warning_i:
+
 mju_warning_i
 ~~~~~~~~~~~~~
 
@@ -1832,6 +1895,8 @@ mju_warning_i
 
 Warning function with int argument.
 
+.. _mju_warning_s:
+
 mju_warning_s
 ~~~~~~~~~~~~~
 
@@ -1873,7 +1938,7 @@ mj_warning
 
 .. mujoco-include:: mj_warning
 
-High-level warning function: count warnings in mjData, print only the first.
+High-level warning function: count warnings in ``mjData``, print only the first.
 
 .. _mju_writeLog:
 
@@ -2006,6 +2071,8 @@ mju_ceil
 Vector math
 ^^^^^^^^^^^
 
+.. _mju_zero3:
+
 mju_zero3
 ~~~~~~~~~
 
@@ -2013,6 +2080,8 @@ mju_zero3
 
 Set res = 0.
 
+.. _mju_copy3:
+
 mju_copy3
 ~~~~~~~~~
 
@@ -2020,6 +2089,8 @@ mju_copy3
 
 Set res = vec.
 
+.. _mju_scl3:
+
 mju_scl3
 ~~~~~~~~
 
@@ -2027,6 +2098,8 @@ mju_scl3
 
 Set res = vec*scl.
 
+.. _mju_add3:
+
 mju_add3
 ~~~~~~~~
 
@@ -2034,6 +2107,8 @@ mju_add3
 
 Set res = vec1 + vec2.
 
+.. _mju_sub3:
+
 mju_sub3
 ~~~~~~~~
 
@@ -2077,6 +2152,8 @@ mju_addScl3
 
 Set res = vec1 + vec2*scl.
 
+.. _mju_normalize3:
+
 mju_normalize3
 ~~~~~~~~~~~~~~
 
@@ -2084,6 +2161,8 @@ mju_normalize3
 
 Normalize vector, return length before normalization.
 
+.. _mju_norm3:
+
 mju_norm3
 ~~~~~~~~~
 
@@ -2091,6 +2170,8 @@ mju_norm3
 
 Return vector length (without normalizing the vector).
 
+.. _mju_dot3:
+
 mju_dot3
 ~~~~~~~~
 
@@ -2098,6 +2179,8 @@ mju_dot3
 
 Return dot-product of vec1 and vec2.
 
+.. _mju_dist3:
+
 mju_dist3
 ~~~~~~~~~
 
@@ -2112,7 +2195,7 @@ mju_rotVecMat
 
 .. mujoco-include:: mju_rotVecMat
 
-Multiply vector by 3D rotation matrix: res = mat \* vec.
+Multiply vector by 3D rotation matrix: res = mat * vec.
 
 .. _mju_rotVecMatT:
 
@@ -2121,7 +2204,9 @@ mju_rotVecMatT
 
 .. mujoco-include:: mju_rotVecMatT
 
-Multiply vector by transposed 3D rotation matrix: res = mat' \* vec.
+Multiply vector by transposed 3D rotation matrix: res = mat' * vec.
+
+.. _mju_cross:
 
 mju_cross
 ~~~~~~~~~
@@ -2130,6 +2215,8 @@ mju_cross
 
 Compute cross-product: res = cross(a, b).
 
+.. _mju_zero4:
+
 mju_zero4
 ~~~~~~~~~
 
@@ -2137,6 +2224,8 @@ mju_zero4
 
 Set res = 0.
 
+.. _mju_unit4:
+
 mju_unit4
 ~~~~~~~~~
 
@@ -2144,6 +2233,8 @@ mju_unit4
 
 Set res = (1,0,0,0).
 
+.. _mju_copy4:
+
 mju_copy4
 ~~~~~~~~~
 
@@ -2151,6 +2242,8 @@ mju_copy4
 
 Set res = vec.
 
+.. _mju_normalize4:
+
 mju_normalize4
 ~~~~~~~~~~~~~~
 
@@ -2158,6 +2251,8 @@ mju_normalize4
 
 Normalize vector, return length before normalization.
 
+.. _mju_zero:
+
 mju_zero
 ~~~~~~~~
 
@@ -2174,6 +2269,8 @@ mju_fill
 
 Set res = val.
 
+.. _mju_copy:
+
 mju_copy
 ~~~~~~~~
 
@@ -2181,6 +2278,8 @@ mju_copy
 
 Set res = vec.
 
+.. _mju_sum:
+
 mju_sum
 ~~~~~~~
 
@@ -2206,6 +2305,8 @@ mju_scl
 
 Set res = vec*scl.
 
+.. _mju_add:
+
 mju_add
 ~~~~~~~
 
@@ -2213,6 +2314,8 @@ mju_add
 
 Set res = vec1 + vec2.
 
+.. _mju_sub:
+
 mju_sub
 ~~~~~~~
 
@@ -2256,6 +2359,8 @@ mju_addScl
 
 Set res = vec1 + vec2*scl.
 
+.. _mju_normalize:
+
 mju_normalize
 ~~~~~~~~~~~~~
 
@@ -2263,6 +2368,8 @@ mju_normalize
 
 Normalize vector, return length before normalization.
 
+.. _mju_norm:
+
 mju_norm
 ~~~~~~~~
 
@@ -2270,6 +2377,8 @@ mju_norm
 
 Return vector length (without normalizing vector).
 
+.. _mju_dot:
+
 mju_dot
 ~~~~~~~
 
@@ -2284,7 +2393,7 @@ mju_mulMatVec
 
 .. mujoco-include:: mju_mulMatVec
 
-Multiply matrix and vector: res = mat \* vec.
+Multiply matrix and vector: res = mat * vec.
 
 .. _mju_mulMatTVec:
 
@@ -2293,7 +2402,7 @@ mju_mulMatTVec
 
 .. mujoco-include:: mju_mulMatTVec
 
-Multiply transposed matrix and vector: res = mat' \* vec.
+Multiply transposed matrix and vector: res = mat' * vec.
 
 .. _mju_mulVecMatVec:
 
@@ -2302,7 +2411,9 @@ mju_mulVecMatVec
 
 .. mujoco-include:: mju_mulVecMatVec
 
-Multiply square matrix with vectors on both sides: return vec1' \* mat \* vec2.
+Multiply square matrix with vectors on both sides: returns vec1' * mat * vec2.
+
+.. _mju_transpose:
 
 mju_transpose
 ~~~~~~~~~~~~~
@@ -2336,7 +2447,7 @@ mju_mulMatMat
 
 .. mujoco-include:: mju_mulMatMat
 
-Multiply matrices: res = mat1 \* mat2.
+Multiply matrices: res = mat1 * mat2.
 
 .. _mju_mulMatMatT:
 
@@ -2345,7 +2456,7 @@ mju_mulMatMatT
 
 .. mujoco-include:: mju_mulMatMatT
 
-Multiply matrices, second argument transposed: res = mat1 \* mat2'.
+Multiply matrices, second argument transposed: res = mat1 * mat2'.
 
 .. _mju_mulMatTMat:
 
@@ -2354,7 +2465,7 @@ mju_mulMatTMat
 
 .. mujoco-include:: mju_mulMatTMat
 
-Multiply matrices, first argument transposed: res = mat1' \* mat2.
+Multiply matrices, first argument transposed: res = mat1' * mat2.
 
 .. _mju_sqrMatTD:
 
@@ -2363,7 +2474,7 @@ mju_sqrMatTD
 
 .. mujoco-include:: mju_sqrMatTD
 
-Set res = mat' \* diag \* mat if diag is not NULL, and res = mat' \* mat otherwise.
+Set res = mat' * diag * mat if diag is not ``NULL``, and res = mat' * mat otherwise.
 
 .. _mju_transformSpatial:
 
@@ -2372,8 +2483,8 @@ mju_transformSpatial
 
 .. mujoco-include:: mju_transformSpatial
 
-Coordinate transform of 6D motion or force vector in rotation:translation format. rotnew2old is 3-by-3, NULL means no
+Coordinate transform of 6D motion or force vector in rotation:translation format.
-rotation; flg_force specifies force or motion type.
+rotnew2old is 3-by-3, ``NULL`` means no rotation; flg_force specifies force or motion type.
 
 .. _Quaternions:
 
@@ -2396,7 +2507,7 @@ mju_negQuat
 
 .. mujoco-include:: mju_negQuat
 
-Negate quaternion.
+Conjugate quaternion, corresponding to opposite rotation.
 
 .. _mju_mulQuat:
 
@@ -2509,7 +2620,7 @@ mju_negPose
 
 .. mujoco-include:: mju_negPose
 
-Negate pose.
+Conjugate pose, corresponding to the opposite spatial transformation.
 
 .. _mju_trnVecPose:
 
@@ -2522,8 +2633,8 @@ Transform vector by pose.
 
 .. _Decompositions:
 
-Decompositions
+Decompositions / Solvers
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. _mju_cholFactor:
 
@@ -2541,7 +2652,7 @@ mju_cholSolve
 
 .. mujoco-include:: mju_cholSolve
 
-Solve mat \* res = vec, where mat is Cholesky-factorized
+Solve mat * res = vec, where mat is Cholesky-factorized
 
 .. _mju_cholUpdate:
 
@@ -2552,6 +2663,8 @@ mju_cholUpdate
 
 Cholesky rank-one update: L*L' +/- x*x'; return rank.
 
+.. _mju_eig3:
+
 mju_eig3
 ~~~~~~~~
 
@@ -2687,6 +2800,17 @@ mju_max
 
 Return max(a,b) with single evaluation of a and b.
 
+.. _mju_clip:
+
+mju_clip
+~~~~~~~~
+
+.. mujoco-include:: mju_clip
+
+Clip x to the range [min, max].
+
+.. _mju_sign:
+
 mju_sign
 ~~~~~~~~
 
@@ -2694,6 +2818,8 @@ mju_sign
 
 Return sign of x: +1, -1 or 0.
 
+.. _mju_round:
+
 mju_round
 ~~~~~~~~~
 
@@ -2726,7 +2852,7 @@ mju_writeNumBytes
 
 .. mujoco-include:: mju_writeNumBytes
 
-Construct a human readable number of bytes using standard letter suffix.
+Return human readable number of bytes using standard letter suffix.
 
 .. _mju_warningText:
 
@@ -2764,6 +2890,8 @@ mju_standardNormal
 
 Standard normal random number generator (optional second number).
 
+.. _mju_f2n:
+
 mju_f2n
 ~~~~~~~
 
@@ -2771,6 +2899,8 @@ mju_f2n
 
 Convert from float to mjtNum.
 
+.. _mju_n2f:
+
 mju_n2f
 ~~~~~~~
 
@@ -2778,6 +2908,8 @@ mju_n2f
 
 Convert from mjtNum to float.
 
+.. _mju_d2n:
+
 mju_d2n
 ~~~~~~~
 
@@ -2785,6 +2917,8 @@ mju_d2n
 
 Convert from double to mjtNum.
 
+.. _mju_n2d:
+
 mju_n2d
 ~~~~~~~
 
@@ -2819,6 +2953,8 @@ mju_Halton
 
 Generate Halton sequence.
 
+.. _mju_strncpy:
+
 mju_strncpy
 ~~~~~~~~~~~
 
@@ -2826,6 +2962,8 @@ mju_strncpy
 
 Call strncpy, then set dst[n-1] = 0.
 
+.. _mju_sigmoid:
+
 mju_sigmoid
 ~~~~~~~~~~~
 
@@ -2833,6 +2971,11 @@ mju_sigmoid
 
 Sigmoid function over 0<=x<=1 constructed from half-quadratics.
 
+.. _Derivatives-api:
+
+Derivatives
+^^^^^^^^^^^
+
 .. _mjd_transitionFD:
 
 mjd_transitionFD
@@ -2842,3 +2985,4 @@ 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).
+

doc/functions_override.rst

@@ -0,0 +1,372 @@
+..
+  This file contains each section text along with function doc overrides.  By default the docs use the function doc
+  pulled from the header files.
+
+.. _Activation:
+
+The functions in this section are maintained for backward compatibility with the now-removed activation mechanism.
+
+.. _Virtualfilesystem:
+
+Virtual file system (VFS) functionality was introduced in MuJoCo 1.50. It enables the user to load all necessary files
+in memory, including MJB binary model files, XML files (MJCF, URDF and included files), STL meshes, PNGs for textures
+and height fields, and HF files in our custom height field format. Model and resource files in the VFS can also be
+constructed programmatically (say using a Python library that writes to memory). Once all desired files are in the VFS,
+the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the
+loaders will first check the VFS for any file they are about to load, and only access the disk if the file is not found
+in the VFS. The file names stored in the VFS have their name and extension but the path information is stripped; this
+can be bypassed however by using a custom path symbol in the file names, say "mydir_myfile.xml".
+
+The entire VFS is contained in the data structure :ref:`mjVFS`. All utility functions for maintaining the VFS operate on
+this data structure. The common usage pattern is to first clear it with mj_defaultVFS, then add disk files to it with
+mj_addFileVFS (which allocates memory buffers and loads the file content in memory), then call mj_loadXML or
+mj_loadModel, and then clear everything with mj_deleteVFS.
+
+.. _Parseandcompile:
+
+The key function here is mj_loadXML. It invokes the built-in parser and compiler, and either returns a pointer to a
+valid mjModel, or NULL - in which case the user should check the error information in the user-provided string. The
+model and all files referenced in it can be loaded from disk or from a VFS when provided.
+
+.. _Mainsimulation:
+
+These are the main entry points to the simulator. Most users will only need to call ``mj_step``, which computes
+everything and advanced the simulation state by one time step. Controls and applied forces must either be set in advance
+(in mjData.ctrl, qfrc_applied and xfrc_applied), or a control callback mjcb_control must be installed which will be
+called just before the controls and applied forces are needed. Alternatively, one can use ``mj_step1`` and ``mj_step2``
+which break down the simulation pipeline into computations that are executed before and after the controls are needed;
+in this way one can set controls that depend on the results from ``mj_step1``. Keep in mind though that the RK4 solver
+does not work with mj_step1/2.
+
+mj_forward performs the same computations as ``mj_step`` but without the integration. It is useful after loading or
+resetting a model (to put the entire mjData in a valid state), and also for out-of-order computations that involve
+sampling or finite-difference approximations.
+
+mj_inverse runs the inverse dynamics, and writes its output in mjData.qfrc_inverse. Note that mjData.qacc must be set
+before calling this function. Given the state (qpos, qvel, act), mj_forward maps from force to acceleration, while
+mj_inverse maps from acceleration to force. Mathematically these functions are inverse of each other, but numerically
+this may not always be the case because the forward dynamics rely on a constraint optimization algorithm which is
+usually terminated early. The difference between the results of forward and inverse dynamics can be computed with the
+function :ref:`mj_compareFwdInv`, which can be though of as another solver accuracy check (as well as a general sanity
+check).
+
+The skip version of mj_forward and mj_inverse are useful for example when qpos was unchanged but qvel was changed
+(usually in the context of finite differencing). Then there is no point repeating the computations that only depend on
+qpos. Calling the dynamics with skipstage = mjSTAGE_POS will achieve these savings.
+
+.. _Initialization:
+
+This section contains functions that load/initialize the model or other data structures. Their use is well illustrated
+in the code samples.
+
+.. _Printing:
+
+These functions can be used to print various quantities to the screen for debugging purposes.
+
+.. _Components:
+
+These are components of the simulation pipeline, called internally from mj_step, mj_forward and mj_inverse. It is
+unlikely that the user will need to call them.
+
+.. _Subcomponents:
+
+These are sub-components of the simulation pipeline, called internally from the components above. It is very unlikely
+that the user will need to call them.
+
+.. _mj_factorM:
+
+Compute sparse :math:`L^T D L` factorizaton of inertia matrix.
+
+.. _mj_solveM:
+
+Solve linear system :math:`M x = y` using factorization: :math:`x = (L^T D L)^{-1} y`
+
+.. _mj_solveM2:
+
+Half of linear solve: :math:`x = \sqrt{D^{-1}} (L^T)^{-1} y`
+
+.. _mj_constraintUpdate:
+
+Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians. If cost is not NULL, set \*cost = s(jar)
+where jar = Jac*qacc-aref.
+
+.. _Support:
+
+These are support functions that need access to mjModel and mjData, unlike the utility functions which do not need such
+access. Support functions are called within the simulator but some of them can also be useful for custom computations,
+and are documented in more detail below.
+
+.. _mj_mulJacVec:
+
+This function multiplies the constraint Jacobian mjData.efc_J by a vector. Note that the Jacobian can be either dense or
+sparse; the function is aware of this setting. Multiplication by J maps velocities from joint space to constraint space.
+
+.. _mj_mulJacTVec:
+
+Same as mj_mulJacVec but multiplies by the transpose of the Jacobian. This maps forces from constraint space to joint
+space.
+
+.. _mj_jac:
+
+This function computes an "end-effector" Jacobian, which is unrelated to the constraint Jacobian above. Any MuJoCo body
+can be treated as end-effector, and the point for which the Jacobian is computed can be anywhere in space (it is treated
+as attached to the body). The Jacobian has translational (jacp) and rotational (jacr) components. Passing NULL for
+either pointer will skip part of the computation. Each component is a 3-by-nv matrix. Each row of this matrix is the
+gradient of the corresponding 3D coordinate of the specified point with respect to the degrees of freedom. The ability
+to compute end-effector Jacobians analytically is one of the advantages of working in minimal coordinates - so use it!
+
+.. _mj_jacBody:
+
+This and the remaining variants of the Jacobian function call mj_jac internally, with the center of the body, geom or
+site. They are just shortcuts; the same can be achieved by calling mj_jac directly.
+
+.. _mj_mulM:
+
+This function multiplies the joint-space inertia matrix stored in mjData.qM by a vector. qM has a custom sparse format
+that the user should not attempt to manipulate directly. Alternatively one can convert qM to a dense matrix with
+mj_fullM and then user regular matrix-vector multiplication, but this is slower because it no longer benefits from
+sparsity.
+
+.. _mj_applyFT:
+
+This function can be used to apply a Cartesian force and torque to a point on a body, and add the result to the vector
+mjData.qfrc_applied of all applied forces. Note that the function requires a pointer to this vector, because sometimes
+we want to add the result to a different vector.
+
+.. _mj_differentiatePos:
+
+This function subtracts two vectors in the format of qpos (and divides the result by dt), while respecting the
+properties of quaternions. Recall that unit quaternions represent spatial orientations. They are points on the unit
+sphere in 4D. The tangent to that sphere is a 3D plane of rotational velocities. Thus when we subtract two quaternions
+in the right way, the result is a 3D vector and not a 4D vector. This the output qvel has dimensionality nv while the
+inputs have dimensionality nq.
+
+.. _mj_integratePos:
+
+This is the opposite of mj_differentiatePos. It adds a vector in the format of qvel (scaled by dt) to a vector in the
+format of qpos.
+
+.. _Raycollisions:
+
+Ray collision functionality was added in MuJoCo 1.50. This is a new collision detection module that uses analytical
+formulas to intersect a ray (p + x*v, x>=0) with a geom, where p is the origin of the ray and v is the vector specifying
+the direction. All functions in this family return the distance to the nearest geom surface, or -1 if there is no
+intersection. Note that if p is inside a geom, the ray will intersect the surface from the inside which still counts as
+an intersection.
+
+All ray collision functions rely on quantities computed by :ref:`mj_kinematics` (see :ref:`mjData`), so must be called
+after  :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`).
+
+.. _mj_ray:
+
+Intersect ray (pnt+x*vec, x>=0) with visible geoms, except geoms in bodyexclude. Return geomid and distance (x) to
+nearest surface, or -1 if no intersection.
+
+geomgroup is an array of length mjNGROUP, where 1 means the group should be included. Pass geomgroup=NULL to skip
+group exclusion.
+If flg_static is 0, static geoms will be excluded.
+bodyexclude=-1 can be used to indicate that all bodies are included.
+
+.. _Interaction:
+
+These function implement abstract mouse interactions, allowing control over cameras and perturbations. Their use is well
+illustrated in :ref:`simulate.cc <saSimulate>`.
+
+.. _mjv_select:
+
+This function is used for mouse selection. Previously selection was done via OpenGL, but as of MuJoCo 1.50 it relies on
+ray intersections which are much more efficient. aspectratio is the viewport width/height. relx and rely are the
+relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function returns the id of
+the geom under the specified 2D point, or -1 if there is no geom (note that they skybox if present is not a model geom).
+The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate.cc <saSimulate>` for an illustration.
+
+.. _Visualization-api:
+
+The functions in this section implement abstract visualization. The results are used by the OpenGL rendered, and can
+also be used by users wishing to implement their own rendered, or hook up MuJoCo to advanced rendering tools such as
+Unity or Unreal Engine. See :ref:`simulate.cc <saSimulate>` for illustration of how to use these functions.
+
+.. _OpenGLrendering:
+
+These functions expose the OpenGL renderer. See :ref:`simulate.cc <saSimulate>` for an illustration
+of how to use these functions.
+
+.. _UIframework:
+
+.. _Errorandmemory:
+
+.. _Standardmath:
+
+The "functions" in this section are preprocessor macros replaced with the corresponding C standard library math
+functions. When MuJoCo is compiled with single precision (which is not currently available to the public, but we
+sometimes use it internally) these macros are replaced with the corresponding single-precision functions (not shown
+here). So one can think of them as having inputs and outputs of type mjtNum, where mjtNum is defined as double or float
+depending on how MuJoCo is compiled. We will not document these functions here; see the C standard library
+specification.
+
+mju_sqrt
+~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_sqrt    sqrt
+
+mju_exp
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_exp     exp
+
+mju_sin
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_sin     sin
+
+mju_cos
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_cos     cos
+
+mju_tan
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_tan     tan
+
+mju_asin
+~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_asin    asin
+
+mju_acos
+~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_acos    acos
+
+mju_atan2
+~~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_atan2   atan2
+
+mju_tanh
+~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_tanh    tanh
+
+mju_pow
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_pow     pow
+
+mju_abs
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_abs     fabs
+
+mju_log
+~~~~~~~
+
+.. code-block:: C
+
+   #define mju_log     log
+
+mju_log10
+~~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_log10   log10
+
+mju_floor
+~~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_floor   floor
+
+mju_ceil
+~~~~~~~~
+
+.. code-block:: C
+
+   #define mju_ceil    ceil
+
+.. _Vectormath:
+
+.. _Quaternions:
+
+.. _Poses:
+
+.. _Decompositions:
+
+.. _mju_boxQP:
+
+Minimize :math:`\tfrac{1}{2} x^T H x + x^T g \quad \text{s.t.} \quad l \le x \le u`, return rank or -1 if failed.
+
+inputs:
+  ``n``           - problem dimension
+
+  ``H``           - SPD matrix                ``n*n``
+
+  ``g``           - bias vector               ``n``
+
+  ``lower``       - lower bounds              ``n``
+
+  ``upper``       - upper bounds              ``n``
+
+  ``res``         - solution warmstart        ``n``
+
+return value:
+  ``nfree <= n``  - rank of unconstrained subspace, -1 if failure
+
+outputs (required):
+  ``res``         - solution                  ``n``
+
+  ``R``           - subspace Cholesky factor  ``nfree*nfree``,    allocated: ``n*(n+7)``
+
+outputs (optional):
+  ``index``       - set of free dimensions    ``nfree``,          allocated: ``n``
+
+notes:
+  The initial value of ``res`` is used to warmstart the solver.
+  ``R`` must have allocatd size ``n*(n+7)``, but only ``nfree*nfree`` values are used in output.
+  ``index`` (if given) must have allocated size ``n``, but only ``nfree`` values are used in output.
+  The convenience function :ref:`mju_boxQPmalloc` allocates the required data structures.
+  Only the lower triangles of H and R and are read from and written to, respectively.
+
+.. _mju_boxQPmalloc:
+
+Allocate heap memory for box-constrained Quadratic Program.
+As in :ref:`mju_boxQP`, ``index``, ``lower``, and ``upper`` are optional.
+Free all pointers with ``mju_free()``.
+
+.. _mju_symmetrize:
+
+Symmetrize square matrix :math:`R = \frac{1}{2}(M + M^T)`.
+
+.. _Miscellaneous:
+
+.. _Derivatives-api:
+
+.. _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).