Cosmetic documentation improvements

PiperOrigin-RevId: 530074671
Change-Id: I07e000c9c506ae8532ade10fb731b4e1fc0970ea

doc/APIreference/functions.rst

@@ -986,14 +986,14 @@ Print sparse matrix to screen.
 Virtual file system
 ^^^^^^^^^^^^^^^^^^^
 
-Virtual file system (VFS) functionality was introduced in MuJoCo 1.50. It enables the user to load all necessary files
+Virtual file system (VFS) enables the user to load all necessary files in memory, including MJB binary model files, XML
-in memory, including MJB binary model files, XML files (MJCF, URDF and included files), STL meshes, PNGs for textures
+files (MJCF, URDF and included files), STL meshes, PNGs for textures and height fields, and HF files in our custom
-and height fields, and HF files in our custom height field format. Model and resource files in the VFS can also be
+height field format. Model and resource files in the VFS can also be constructed programmatically (say using a Python
-constructed programmatically (say using a Python library that writes to memory). Once all desired files are in the VFS,
+library that writes to memory). Once all desired files are in the VFS, the user can call :ref:`mj_loadModel` or
-the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the
+:ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the loaders will first check the VFS for any
-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
+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
-in the VFS. The file names stored in the VFS have their name and extension but the path information is stripped; this
+VFS have their name and extension but the path information is stripped; this can be bypassed however by using a custom
-can be bypassed however by using a custom path symbol in the file names, say "mydir_myfile.xml".
+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
@@ -1423,11 +1423,11 @@ mjv_select
 
 .. mujoco-include:: mjv_select
 
-This function is used for mouse selection. Previously selection was done via OpenGL, but as of MuJoCo 1.50 it relies on
+This function is used for mouse selection, relying on ray intersections. aspectratio is the viewport width/height. relx
-ray intersections which are much more efficient. aspectratio is the viewport width/height. relx and rely are the
+and rely are the relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function
-relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function returns the id of
+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
-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).
+not a model geom). The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate<saSimulate>` for
-The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate<saSimulate>` for an illustration.
+an illustration.
 
 .. _Visualization-api:
 

doc/APIreference/functions_override.rst

@@ -8,14 +8,14 @@ The functions in this section are maintained for backward compatibility with the
 
 .. _Virtualfilesystem:
 
-Virtual file system (VFS) functionality was introduced in MuJoCo 1.50. It enables the user to load all necessary files
+Virtual file system (VFS) enables the user to load all necessary files in memory, including MJB binary model files, XML
-in memory, including MJB binary model files, XML files (MJCF, URDF and included files), STL meshes, PNGs for textures
+files (MJCF, URDF and included files), STL meshes, PNGs for textures and height fields, and HF files in our custom
-and height fields, and HF files in our custom height field format. Model and resource files in the VFS can also be
+height field format. Model and resource files in the VFS can also be constructed programmatically (say using a Python
-constructed programmatically (say using a Python library that writes to memory). Once all desired files are in the VFS,
+library that writes to memory). Once all desired files are in the VFS, the user can call :ref:`mj_loadModel` or
-the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the
+:ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the loaders will first check the VFS for any
-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
+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
-in the VFS. The file names stored in the VFS have their name and extension but the path information is stripped; this
+VFS have their name and extension but the path information is stripped; this can be bypassed however by using a custom
-can be bypassed however by using a custom path symbol in the file names, say "mydir_myfile.xml".
+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
@@ -178,11 +178,11 @@ illustrated in :ref:`simulate<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
+This function is used for mouse selection, relying on ray intersections. aspectratio is the viewport width/height. relx
-ray intersections which are much more efficient. aspectratio is the viewport width/height. relx and rely are the
+and rely are the relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function
-relative coordinates of the 2D point of interest in the viewport (usually mouse cursor). The function returns the id of
+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
-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).
+not a model geom). The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate<saSimulate>` for
-The 3D coordinates of the clicked point are returned in selpnt. See :ref:`simulate<saSimulate>` for an illustration.
+an illustration.
 
 .. _Visualization-api:
 

doc/computation.rst

@@ -1290,8 +1290,7 @@ representations of the constraint Jacobian and related matrices.
 
 **Newton** : Newton's method
    This algorithm implements the exact Newton method, with analytical second-order derivatives and Cholesky
-   factorization of the Hessian. The line-search is the same as in the CG method. This is the default solver as of
+   factorization of the Hessian. The line-search is the same as in the CG method. It is the default solver.
-   MuJoCo 1.50.
 
 **PGS** : Projected Gauss-Seidel method
    This is the most common algorithm used in physics simulators, and used to be the default in MuJoCo, until we

doc/modeling.rst

@@ -448,8 +448,8 @@ the array mjData.userdata whose size is determined by the :at:`nuserdata` attrib
 
 .. _CAlgorithms:
 
-Algorithms and related settings
+Solver settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
 
 The computation of constraint forces and constrained accelerations involves solving an optimization problem
 numerically. MuJoCo has three algorithms for solving this optimization problem: CG, Newton, PGS. Each of them can be
@@ -484,14 +484,12 @@ general guidelines and observations:
    convergence with a good rate, but it cannot compete with Newton in terms of number of iterations, especially when
    high accuracy is desired. However its iterations are much faster, and are not affected by fill-in or increased
    complexity due to elliptic cones. If Newton proves to be too slow, try CG next.
--  The PGS solver used to be the default solver until recently, and was substantially improved in MuJoCo 1.50 by making
+-  The PGS solver is best when the number of degrees of freedom is larger than the number of constraints. PGS solves a
-   it work with sparse models. However we have not yet found a situation where it is the best algorithm, which is not to
+   constrained optimization problem and has sub-linear convergence in our experience, however it usually makes rapid
-   say that such situations do not exist. PGS solves a constrained optimization problem and has sub-linear convergence
+   progress on the first few iterations. So it is a good choice when inaccurate solutions can be tolerated. For systems
-   in our experience, however it usually makes rapid progress on the first few iterations. So it is a good choice when
+   with large mass ratios or other model properties causing poor conditioning, PGS convergence tends to be rather slow.
-   inaccurate solutions can be tolerated. For systems with large mass ratios or other model properties causing poor
+   Keep in mind that PGS performs sequential updates, and therefore breaks symmetry in systems where the physics should
-   conditioning, PGS convergence tends to be rather slow. Keep in mind that PGS performs sequential updates, and
+   be symmetric. In contrast, CG and Newton perform parallel updates and preserve symmetry.
-   therefore breaks symmetry in systems where the physics should be symmetric. In contrast, CG and Newton perform
-   parallel updates and preserve symmetry.
 -  The Noslip solver is a modified PGS solver. It is executed as a post-processing step after the main solver (which can
    be Newton, CG or PGS). The main solver updates all unknowns. In contrast, the Noslip solver updates only the
    constraint forces in friction dimensions, and ignores constraint regularization. This has the effect of suppressing
@@ -1251,26 +1249,26 @@ Memory allocation
 MuJoCo preallocates all the memory needed at runtime in :ref:`mjData`, and does not access the heap allocator after
 model creation. Memory in :ref:`mjData` is allocated by :ref:`mj_makeData` in two contiguous blocks:
 
-  - ``mjData.buffer`` contains fixed-size arrays.
+- ``mjData.buffer`` contains fixed-size arrays.
-  - ``mjData.arena`` contains dynamically-sized arrays.
+- ``mjData.arena`` contains dynamically-sized arrays.
 
 There are two types of dynamic arrays allocated in the ``arena`` memory space.
 
-  - contacts and constraint-related arrays are laid out from the beginning of the ``arena``.
+- contacts and constraint-related arrays are laid out from the beginning of the ``arena``.
-  - :ref:`stack <siStack>` arrays are laid out from the end of the ``arena``.
+- :ref:`stack <siStack>` arrays are laid out from the end of the ``arena``.
 
 By allocating dynamic quantities from both sides of the ``arena`` space, variable-sized memory allocation is controlled
 by a single number: the :at:`memory` attribute of the :ref:`size <size>` MJCF element. Unlike the fixed-size arrays in
 the ``buffer``, variable-sized arrays in the arena can be ``NULL``, for example after a call to :ref:`mj_resetData`.
 When ``arena`` memory runs out, one of three things will happen, depending on the type of memory requested:
 
-  - If memory runs out during contact allocation, a warning will be raised and subsequent contacts will not be added in
+- If memory runs out during contact allocation, a warning will be raised and subsequent contacts will not be added in
-    this step, but simulation continues as usual.
+  this step, but simulation continues as usual.
-  - If memory runs out during constraint-related allocation, a warning will be raised and the constraint solver will be
+- If memory runs out during constraint-related allocation, a warning will be raised and the constraint solver will be
-    disabled in this step, but simulation continues as usual. Note that physics without the constraint solver will
+  disabled in this step, but simulation continues as usual. Note that physics without the constraint solver will
-    generally be very different, but allowing the simulation to continue can still be useful, e.g. during
+  generally be very different, but allowing the simulation to continue can still be useful, e.g. during
-    scene initialization when many bodies are temporarily overlapping.
+  scene initialization when many bodies are temporarily overlapping.
-  - If memory runs out during stack array allocation, a hard error will occur.
+- If memory runs out during stack array allocation, a hard error will occur.
 
 Unlike the size of the ``buffer``, the size of the ``arena`` cannot be pre-computed, since the number of contacts and
 stack usage is not known in advance. So how should one choose it? The following simple heuristic is currently used,

doc/programming/index.rst

@@ -104,10 +104,10 @@ Building from source
 
 To build MuJoCo from source, you will need CMake and a working C++17 compiler installed. The steps are:
 
-  #. Clone the ``mujoco`` repository from GitHub.
+ #. Clone the ``mujoco`` repository from GitHub.
-  #. Create a new build directory somewhere, and ``cd`` into it.
+ #. Create a new build directory somewhere, and ``cd`` into it.
-  #. Run ``cmake $PATH_TO_CLONED_REPO`` to configure the build.
+ #. Run ``cmake $PATH_TO_CLONED_REPO`` to configure the build.
-  #. Run ``cmake --build .`` to build.
+ #. Run ``cmake --build .`` to build.
 
 MuJoCo's build system automatically fetches dependencies from upstream repositories over the Internet using CMake's
 `FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ module.
@@ -117,8 +117,10 @@ bindings are not built. Those come with their own build instructions, which can
 section of the documentation.
 
 Additionally, the CMake setup also implements an installation phase which will copy and organize the output files to a
-target directory. Specify the directory using ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``.
+target directory.
-After successfully building MuJoCo following the instructions above, you can install it using ``cmake --install .``.
+
+ 5. Select the directory: ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``
+ #. After building, install with ``cmake --install .``
 
 .. tip::
    As a reference, a working build configuration can be found in MuJoCo's
@@ -198,40 +200,40 @@ Naming convention
 All symbols defined in the API start with the prefix "mj". The character after "mj" in the prefix determines the family
 to which the symbol belongs. First we list the prefixes corresponding to type definitions.
 
-mj
+``mj``
    Core simulation data structure (C struct), for example :ref:`mjModel`. If all characters
    after the prefix are capital, for example :ref:`mjMIN`, this is a macro or a symbol (#define).
-mjt
+``mjt``
    Primitive type, for example :ref:`mjtGeom`. Except for mjtByte and mjtNum, all other
    definitions in this family are enums.
-mjf
+``mjf``
    Callback function type, for example :ref:`mjfGeneric`.
-mjv
+``mjv``
    Data structure related to abstract visualization, for example :ref:`mjvCamera`.
-mjr
+``mjr``
    Data structure related to OpenGL rendering, for example :ref:`mjrContext`.
-mjui
+``mjui``
    Data structure related to UI framework, for example :ref:`mjuiSection`.
 
 Next we list the prefixes corresponding to function definitions. Note that function prefixes always end with underscore.
 
-mj\_
+``mj_``
    Core simulation function, for example :ref:`mj_step`. Almost all such functions have
    pointers to mjModel and mjData as their first two arguments, possibly followed by other arguments. They usually write
    their outputs to mjData.
-mju\_
+``mju_``
    Utility function, for example :ref:`mju_mulMatVec`. These functions are self-contained
    in the sense that they do not have mjModel and mjData pointers as their arguments.
-mjv\_
+``mjv_``
    Function related to abstract visualization, for example :ref:`mjv_updateScene`.
-mjr\_
+``mjr_``
    Function related to OpenGL rendering, for example :ref:`mjr_render`.
-mjui\_
+``mjui_``
    Function related to UI framework, for example :ref:`mjui_update`.
-mjcb\_
+``mjcb_``
    Global callback function pointer, for example :ref:`mjcb_control`. The user can install
    custom callbacks by setting these global pointers to user-defined functions.
-mjd\_
+``mjd_``
    Functions for computing derivatives, for example :ref:`mjd_transitionFD`.
 
 .. _inOpenGL:

doc/programming/simulation.rst

@@ -50,9 +50,9 @@ low-level :ref:`mju_error` or :ref:`mju_warning` is called with the error/warnin
 argument to all API functions that need model access. Note that most functions treat this pointer as ``const``; more on
 this in :ref:`model changes <siChange>` below.
 
-The virtual file system (VFS) was introduced in MuJoCo 1.50. It allows disk resources to be loaded in memory or
+The virtual file system (VFS) allows disk resources to be loaded in memory or created programmatically by the user, and
-created programmatically by the user, and then MuJoCo's load functions search for files in the VFS before accessing
+then MuJoCo's load functions search for files in the VFS before accessing the disk. See :ref:`Virtualfilesystem` in the
-the disk. See :ref:`Virtualfilesystem` in the API Reference chapter.
+API Reference chapter.
 
 In addition to mjModel which holds the model description, we also need mjData which is the workspace where all
 computations are performed. Note that mjData is specific to a given mjModel. The API functions generally assume that

doc/programming/visualization.rst

@@ -163,12 +163,10 @@ Selection
 '''''''''
 
 In many applications we need to click on a point and determine the 3D object to which this point/pixel belongs. This is
-done with the function :ref:`mjv_select`. Prior to MuJoCo 1.50 this function (called mjr_select) used OpenGL rendering
+done with the function :ref:`mjv_select`, which uses :ref:`ray collisions <Raycollisions>`. Ray collisions functionality
-in a special mode to recover the object identity and 3D position of the clicked point. Now it uses a new collision
+is engine-level and does not depend on the visualizer (indeed it is also used to simulate :ref:`rangefinder
-detection module that intersects a ray with all geoms in the model. This is actually engine-level functionality and does
+<sensor-rangefinder>` sensors independent of visualization), but the select function is implemented in the visualizer
-not depend on the visualizer (indeed it is also used to simulate :ref:`rangefinder <sensor-rangefinder>` sensors
+because it needs information about the camera and viewport.
-independent of visualization), but the select function is implemented in the visualizer because it needs information
-about the camera and viewport.
 
 The function mjv_select returns the index of the geom at the specified window coordinates, or -1 if there is no geom
 at those coordinates. The 3D position is also returned. See the code sample :ref:`simulate.cc <saSimulate>` for an