Restructure numeric constants table in API docs

Break the monolithic numeric constants table into 6 sub-grouped tables:
Version, Engine constants, Array sizes, Visualization, Rendering, UI constants.

Fix stale values: mjMAXUITEXT (500->300), mjMAXUIMULTI (20->35),
mjMAXUIEDIT (5->7), mjMAXUIRECT (15->25).

Add missing constants: mjMAXLIGHT, mjMAXMATERIAL.

Fix placeholder description for mjMAXFLEXNODES.

PiperOrigin-RevId: 875010581
Change-Id: Id47846de4d98b62cb96087b72ecd28358d5db9c7

doc/APIreference/APIglobals.rst

@@ -368,10 +368,41 @@ Numeric constants
 ^^^^^^^^^^^^^^^^^
 
 Many integer constants were already documented in the primitive types above. In addition, the header files define
-several other constants documented here. Unless indicated otherwise, each entry in the table below is defined in
+several other constants documented here. Note that some extended key codes are defined in
-`mjmodel.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_. Note that some extended key
+`mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_ which are not shown below. Their
-codes are defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_ which are not
+names are in the format ``mjKEY_XXX``. They correspond to GLFW key codes.
-shown in the table below. Their names are in the format ``mjKEY_XXX``. They correspond to GLFW key codes.
+
+
+.. _glNumericVersion:
+
+Version
+~~~~~~~
+
+Defined in `mujoco.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_.
+
+.. list-table::
+   :widths: 2 1 8
+   :header-rows: 1
+
+   * - symbol
+     - value
+     - description
+   * - ``mjVERSION_HEADER``
+     - 3005001
+     - The version of the MuJoCo headers. This is an integer calculated from the version string "S.M.P"
+       using the formula ``(S * 1e6) + (M * 1e3) + P``. For example, version 4.2.1 is represented as 4002001.
+       The API function :ref:`mj_version` returns a number with the same meaning
+       but for the compiled library. See
+       `VERSIONING.md <https://github.com/google-deepmind/mujoco/blob/main/VERSIONING.md>`__ for details.
+
+
+.. _glNumericEngine:
+
+Engine constants
+~~~~~~~~~~~~~~~~
+
+Defined in `mjmodel.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_ unless
+indicated otherwise.
 
 .. list-table::
    :widths: 2 1 8
@@ -384,6 +415,7 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr
      - 1E-15
      - The minimal value allowed in any denominator, and in general any mathematical operation where 0 is not allowed.
        In almost all cases, MuJoCo silently clamps smaller values to mjMINVAL.
+       Defined in `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`_.
    * - ``mjPI``
      - :math:`\pi`
      - The value of :math:`\pi`. This is used in various trigonometric functions, and also for conversion from degrees
@@ -416,17 +448,38 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr
        is raised and ray casting may not be possible. For a balanced hierarchy, this implies 1E15 bounding volumes.
    * - ``mjMAXFLEXNODES``
      - 27
-     - Some number by Alessio that needs documentation. I guess it's related to trilinear flexes?
+     - The maximum number of nodes in a trilinear flex element.
    * - ``mjMINAWAKE``
      - 10
      - The minimum number of timesteps that must pass after a tree is awoken, before it is allowed to go back to sleep.
+   * - ``mjMAXTHREAD``
+     - 128
+     - Maximum number of OS threads that can be used in a thread pool.
+       Defined in `mjthread.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjthread.h>`_.
+
+
+.. _glNumericSizes:
+
+Array sizes
+~~~~~~~~~~~
+
+Defined in `mjmodel.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_. These constants
+correspond to array sizes which we have not fully settled. There may be reasons to increase them in the future, so as to
+accommodate extra parameters needed for more elaborate computations. This is why we maintain them as symbolic constants
+that can be easily changed, as opposed to the array size for representing quaternions for example -- which has no reason
+to change.
+
+.. list-table::
+   :widths: 2 1 8
+   :header-rows: 1
+
+   * - symbol
+     - value
+     - description
    * - ``mjNEQDATA``
      - 11
      - The maximal number of real-valued parameters used to define each equality constraint. Determines the size of
-       ``mjModel.eq_data``. This and the next five constants correspond to array sizes which we have not fully settled.
+       ``mjModel.eq_data``.
-       There may be reasons to increase them in the future, so as to accommodate extra parameters needed for more
-       elaborate computations. This is why we maintain them as symbolic constants that can be easily changed, as opposed
-       to the array size for representing quaternions for example -- which has no reason to change.
    * - ``mjNDYN``
      - 10
      - The maximal number of real-valued parameters used to define the activation dynamics of each actuator.
@@ -464,75 +517,104 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr
      - The number of islands for which solver statistics can be stored in ``mjData.solver``. This array is
        used to store diagnostic information about each iteration of the constraint solver.
        The actual number of islands for which the solver was run is given by ``mjData.nsolver_island``.
+
+
+.. _glNumericVisualization:
+
+Visualization
+~~~~~~~~~~~~~
+
+Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
+
+.. list-table::
+   :widths: 2 1 8
+   :header-rows: 1
+
+   * - symbol
+     - value
+     - description
    * - ``mjNGROUP``
      - 6
      - The number of geom, site, joint, tendon and actuator groups whose rendering can be enabled and disabled via
        :ref:`mjvOption`.
-       Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
+   * - ``mjMAXLIGHT``
+     - 100
+     - The maximum number of lights in a scene.
    * - ``mjMAXOVERLAY``
      - 500
      - The maximal number of characters in overlay text for rendering.
-       Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
    * - ``mjMAXLINE``
      - 100
      - The maximal number of lines per 2D figure (:ref:`mjvFigure`).
-       Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
    * - ``mjMAXLINEPNT``
      - 1001
      - The maximal number of points in each line in a 2D figure. Note that the buffer ``mjvFigure.linepnt`` has length
        ``2*mjMAXLINEPNT`` because each point has X and Y coordinates.
-       Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
    * - ``mjMAXPLANEGRID``
      - 200
      - The maximal number of grid lines in each dimension for rendering planes.
-       Defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
+
+
+.. _glNumericRendering:
+
+Rendering
+~~~~~~~~~
+
+Defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_.
+
+.. list-table::
+   :widths: 2 1 8
+   :header-rows: 1
+
+   * - symbol
+     - value
+     - description
    * - ``mjNAUX``
      - 10
      - Number of auxiliary buffers that can be allocated in mjrContext.
-       Defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_.
    * - ``mjMAXTEXTURE``
      - 1000
      - Maximum number of textures allowed.
-       Defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_.
+   * - ``mjMAXMATERIAL``
-   * - ``mjMAXTHREAD``
+     - 1000
-     - 128
+     - Maximum number of materials with textures.
-     - Maximum number OS threads that can be used in a thread pool.
+
-       Defined in `mjthread.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjthread.h>`_.
+
+.. _glNumericUI:
+
+UI constants
+~~~~~~~~~~~~
+
+Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
+
+.. list-table::
+   :widths: 2 1 8
+   :header-rows: 1
+
+   * - symbol
+     - value
+     - description
    * - ``mjMAXUISECT``
      - 10
      - Maximum number of UI sections.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUIITEM``
      - 200
      - Maximum number of items per UI section.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUITEXT``
-     - 500
+     - 300
      - Maximum number of characters in UI fields 'edittext' and 'other'.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUINAME``
      - 40
      - Maximum number of characters in any UI name.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUIMULTI``
-     - 20
+     - 35
      - Maximum number of radio and select items in UI group.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUIEDIT``
-     - 5
+     - 7
      - Maximum number of elements in UI edit list.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
    * - ``mjMAXUIRECT``
-     - 15
+     - 25
      - Maximum number of UI rectangles.
-       Defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
-   * - ``mjVERSION_HEADER``
-     - 3005001
-     - The version of the MuJoCo headers. This is an integer calculated from the version string "S.M.P"
-       using the formula ``(S * 1e6) + (M * 1e3) + P``. For example, version 4.2.1 is represented as 4002001.
-       Defined in mujoco.h. The API function :ref:`mj_version` returns a number with the same meaning
-       but for the compiled library. See
-       `VERSIONING.md <https://github.com/google-deepmind/mujoco/blob/main/VERSIONING.md>`__ for details.
 
 .. _Macros:
 

doc/APIreference/functions.rst

@@ -1252,7 +1252,7 @@ Intersect ray ``pnt+x*vec, x >= 0`` with geoms.
 - If ``normal`` is not NULL, write the surface normal at the intersection point. The normal always points **out of the
   geometry**, regardless of the ray's direction (i.e., including rays hitting the surface from the inside).
 - Exclude geoms in body with id ``bodyexclude``, use -1 to include all bodies.
-- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumeric>`, where 1 means the group should be included. Pass
+- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumericVisualization>`, where 1 means the group should be included. Pass
   NULL to skip geom group exclusion.
 - If ``flg_static`` is 0, static geoms will be excluded.
 
@@ -2911,7 +2911,7 @@ each corresponding to one item. The last (unused) item has its type set to -1, t
 after the end of the last used section. There is also another version of this function
 (:ref:`mjui_addToSection<mjui_addToSection>`) which adds items to a specified section instead of adding them at the end
 of the UI. Keep in mind that there is a maximum preallocated number of sections and items per section, given by
-:ref:`mjMAXUISECT<glNumeric>` and :ref:`mjMAXUIITEM<glNumeric>`. Exceeding these maxima results in low-level errors.
+:ref:`mjMAXUISECT<glNumericUI>` and :ref:`mjMAXUIITEM<glNumericUI>`. Exceeding these maxima results in low-level errors.
 
 .. _mjui_addToSection:
 

doc/APIreference/functions_override.rst

@@ -403,7 +403,7 @@ Intersect ray ``pnt+x*vec, x >= 0`` with geoms.
 - If ``normal`` is not NULL, write the surface normal at the intersection point. The normal always points **out of the
   geometry**, regardless of the ray's direction (i.e., including rays hitting the surface from the inside).
 - Exclude geoms in body with id ``bodyexclude``, use -1 to include all bodies.
-- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumeric>`, where 1 means the group should be included. Pass
+- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumericVisualization>`, where 1 means the group should be included. Pass
   NULL to skip geom group exclusion.
 - If ``flg_static`` is 0, static geoms will be excluded.
 
@@ -444,7 +444,7 @@ each corresponding to one item. The last (unused) item has its type set to -1, t
 after the end of the last used section. There is also another version of this function
 (:ref:`mjui_addToSection<mjui_addToSection>`) which adds items to a specified section instead of adding them at the end
 of the UI. Keep in mind that there is a maximum preallocated number of sections and items per section, given by
-:ref:`mjMAXUISECT<glNumeric>` and :ref:`mjMAXUIITEM<glNumeric>`. Exceeding these maxima results in low-level errors.
+:ref:`mjMAXUISECT<glNumericUI>` and :ref:`mjMAXUIITEM<glNumericUI>`. Exceeding these maxima results in low-level errors.
 
 .. _mjui_update:
 

doc/XMLreference.rst

@@ -1249,7 +1249,7 @@ The full list of processing steps applied by the compiler to each mesh is as fol
    transformations in ``mjModel.mesh_{pos, quat, scale}``.
 #. Construct the convex hull if specified;
 #. Find the centroid of all triangle faces, and construct the union-of-pyramids representation. Triangles whose area is
-   too small (below the :ref:`mjMINVAL <glNumeric>` value of 1E-14) result in compile error;
+   too small (below the :ref:`mjMINVAL <glNumericEngine>` value of 1E-14) result in compile error;
 #. Compute the center of mass and inertia matrix of the union-of-pyramids. Use eigenvalue decomposition to find the
    principal axes of inertia. Center and align the mesh, saving the translational and rotational offsets for subsequent
    geom-related computations.
@@ -1518,7 +1518,7 @@ also known as terrain map, is a 2D matrix of elevation data. The data can be spe
   and other geoms (except for planes and other height fields which are not supported) are computed by first selecting
   the sub-grid of prisms that could collide with the geom based on its bounding box, and then using the general convex
   collider. The number of possible contacts between a height field and a geom is limited to 50
-  (:ref:`mjMAXCONPAIR <glNumeric>`); any contacts beyond that are discarded. To avoid penetration due to discarded
+  (:ref:`mjMAXCONPAIR <glNumericEngine>`); any contacts beyond that are discarded. To avoid penetration due to discarded
   contacts, the spatial features of the height field should be large compared to the geoms it collides with.
 
 .. _asset-hfield-name:

doc/changelog.rst

@@ -1463,8 +1463,8 @@ General
        Each row of length ``mjNSOLVER`` contains separate solver statistics for each constraint island.
        If the solver does not use islands, only row 0 is filled.
 
-       - The new constant :ref:`mjNISLAND<glNumeric>` was set to 20.
+       - The new constant :ref:`mjNISLAND<glNumericSizes>` was set to 20.
-       - :ref:`mjNSOLVER<glNumeric>` was reduced from 1000 to 200.
+       - :ref:`mjNSOLVER<glNumericSizes>` was reduced from 1000 to 200.
        - Added :ref:`mjData.solver_nisland<mjData>`: the number of islands for which the solver ran.
        - Renamed ``mjData.solver_iter`` to ``solver_niter``. Both this member and ``mjData.solver_nnz`` are now integer
          vectors of length ``mjNISLAND``.

doc/computation/index.rst

@@ -1621,17 +1621,17 @@ will generate up to 1 contact or with ``multiccd`` up to 4 contacts.
        | **1**
    * - HField
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldCCD
-       | :ref:`mjMAXCONPAIR <glNumeric>`
+       | :ref:`mjMAXCONPAIR <glNumericEngine>`
      - | HFieldSDF
        | :ref:`sdf_initpoints <option-sdf_initpoints>`
    * - Sphere
@@ -1762,7 +1762,7 @@ sleeping mechanism is provided in the :ref:`Simulation chapter<siSleep>` but her
 Sleeping can occur in one of two ways:
 
 - **Automatic:** A tree whose maximum velocity in absolute value is less than the
-  :ref:`tolerance <option-sleep_tolerance>` for :ref:`mjMINAWAKE <glNumeric>` time steps is marked as "ready to sleep".
+  :ref:`tolerance <option-sleep_tolerance>` for :ref:`mjMINAWAKE <glNumericEngine>` time steps is marked as "ready to sleep".
   If all trees in an island are ready to sleep, they are put to sleep during state advancement.
 - **Initialized asleep:** By setting the :ref:`body/sleep<body-sleep>` attribute of a tree root to "init", it is
   marked as "initialized-asleep" and put to sleep during :ref:`mjData` initialization.

doc/mjwarp/index.rst

@@ -724,7 +724,7 @@ Warnings are provided when memory requirements exceed existing allocations durin
   setting `m.opt.contact_sensor_maxmatch`. Alternatively, refactor the contact sensor matching criteria, for example if
   the 2 geoms of interest are known, specify ``geom1`` and ``geom2``.
 - ``height field collision overflow``: The number of potential contacts generated by a height field exceeds
-  :ref:`mjMAXCONPAIR <glNumeric>` and some contacts are ignored. To resolve this warning, reduce the height field
+  :ref:`mjMAXCONPAIR <glNumericEngine>` and some contacts are ignored. To resolve this warning, reduce the height field
   resolution or reduce the size of the geom interacting with the height field.
 
 Compilation

doc/modeling.rst

@@ -301,7 +301,7 @@ We begin by explaining the constraint impedance :math:`d`.
    at rest. Impedance is set using the :at:`solimp` attribute.
 
 Recall that :math:`d` must lie between 0 and 1; internally MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP
-<glNumeric>`] which is currently set to [0.0001 0.9999]. It causes the solver to interpolate between the unforced
+<glNumericEngine>`] which is currently set to [0.0001 0.9999]. It causes the solver to interpolate between the unforced
 acceleration :math:`\au` and reference acceleration :math:`\ar`. The user can set :math:`d` to a constant, or
 take advantage of its interpolating property and make it position-dependent, i.e., a function of the constraint
 violation :math:`r`. Position-dependent impedance can be used to model soft contact layers around objects, or define

doc/programming/index.rst

@@ -200,7 +200,7 @@ The situation is more subtle if existing code was developed with a certain versi
 compiled and linked with a different version. If the definitions of the API functions used in that code have changed,
 either the compiler or the linker will generate errors. But even if the function definitions have not changed, it may
 still be a good idea to assert that the software version is the same. To this end, the main header (mujoco.h) defines
-the symbol :ref:`mjVERSION_HEADER <glNumeric>` and the library provides the function
+the symbol :ref:`mjVERSION_HEADER <glNumericVersion>` and the library provides the function
 :ref:`mj_version`. Thus the header and library versions can be compared with:
 
 .. code-block:: C

doc/programming/simulation.rst

@@ -1098,7 +1098,7 @@ implementation details.
 
 The high level sleep state of :ref:`trees<ElemTree>` is described by ``mjData.tree_asleep`` (though see caveat below). A
 negative value means a tree is awake, non-negative means asleep. Maximally awake trees are given the value - |-| (1 |-|
-+ |-| :ref:`mjMINAWAKE<glNumeric>`), and for every timestep where their velocity falls below the sleep :ref:`tolerance
++ |-| :ref:`mjMINAWAKE<glNumericEngine>`), and for every timestep where their velocity falls below the sleep :ref:`tolerance
 <option-sleep_tolerance>`, this integer is incremented, up to -1, which means "ready to sleep". If all trees in an
 island are ready to sleep, they are put to sleep during state advancement and their associated values in ``tree_asleep``
 are set to a (non-negative) index cycle: the "sleeping island". If any tree in the island is woken, all are woken.
@@ -1213,7 +1213,7 @@ Notes
 **Provisional choices**
   Some implementation choices are provisional and subject to change.
 
-  A concrete example is the decision to hard-code the value of :ref:`mjMINAWAKE<glNumeric>` instead of exposing it to
+  A concrete example is the decision to hard-code the value of :ref:`mjMINAWAKE<glNumericEngine>` instead of exposing it to
   the user as a runtime option. This was done for two reasons. First, in our experiments, we've found that changing this
   value is equivalent to changing the :ref:`sleep_tolerance<option-sleep_tolerance>`, which is the more useful knob.
   Second, one could argue for a time-to-sleep semantic that is in units of time rather than an integer number of