From 40e000784940f550d5a53c932837a952dceb29ad Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Wed, 25 Feb 2026 00:53:38 -0800 Subject: [PATCH] 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 | 158 ++++++++++++++++++------ doc/APIreference/functions.rst | 4 +- doc/APIreference/functions_override.rst | 4 +- doc/XMLreference.rst | 4 +- doc/changelog.rst | 4 +- doc/computation/index.rst | 14 +-- doc/mjwarp/index.rst | 2 +- doc/modeling.rst | 2 +- doc/programming/index.rst | 2 +- doc/programming/simulation.rst | 4 +- 10 files changed, 140 insertions(+), 58 deletions(-) diff --git a/doc/APIreference/APIglobals.rst b/doc/APIreference/APIglobals.rst index 2292549e..656c6a07 100644 --- a/doc/APIreference/APIglobals.rst +++ b/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 -`mjmodel.h `_. Note that some extended key -codes are defined in `mjui.h `_ which are not -shown in the table below. Their names are in the format ``mjKEY_XXX``. They correspond to GLFW key codes. +several other constants documented here. Note that some extended key codes are defined in +`mjui.h `_ which are not shown below. Their +names are in the format ``mjKEY_XXX``. They correspond to GLFW key codes. + + +.. _glNumericVersion: + +Version +~~~~~~~ + +Defined in `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 `__ for details. + + +.. _glNumericEngine: + +Engine constants +~~~~~~~~~~~~~~~~ + +Defined in `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 `_. * - ``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 `_. + + +.. _glNumericSizes: + +Array sizes +~~~~~~~~~~~ + +Defined in `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. - 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. + ``mjModel.eq_data``. * - ``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 `_. + +.. 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 `_. + * - ``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 `_. * - ``mjMAXLINE`` - 100 - The maximal number of lines per 2D figure (:ref:`mjvFigure`). - Defined in `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 `_. * - ``mjMAXPLANEGRID`` - 200 - The maximal number of grid lines in each dimension for rendering planes. - Defined in `mjvisualize.h `_. + + +.. _glNumericRendering: + +Rendering +~~~~~~~~~ + +Defined in `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 `_. * - ``mjMAXTEXTURE`` - 1000 - Maximum number of textures allowed. - Defined in `mjrender.h `_. - * - ``mjMAXTHREAD`` - - 128 - - Maximum number OS threads that can be used in a thread pool. - Defined in `mjthread.h `_. + * - ``mjMAXMATERIAL`` + - 1000 + - Maximum number of materials with textures. + + +.. _glNumericUI: + +UI constants +~~~~~~~~~~~~ + +Defined in `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 `_. * - ``mjMAXUIITEM`` - 200 - Maximum number of items per UI section. - Defined in `mjui.h `_. * - ``mjMAXUITEXT`` - - 500 + - 300 - Maximum number of characters in UI fields 'edittext' and 'other'. - Defined in `mjui.h `_. * - ``mjMAXUINAME`` - 40 - Maximum number of characters in any UI name. - Defined in `mjui.h `_. * - ``mjMAXUIMULTI`` - - 20 + - 35 - Maximum number of radio and select items in UI group. - Defined in `mjui.h `_. * - ``mjMAXUIEDIT`` - - 5 + - 7 - Maximum number of elements in UI edit list. - Defined in `mjui.h `_. * - ``mjMAXUIRECT`` - - 15 + - 25 - Maximum number of UI rectangles. - Defined in `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 `__ for details. .. _Macros: diff --git a/doc/APIreference/functions.rst b/doc/APIreference/functions.rst index 5cbb95c5..bec885ae 100644 --- a/doc/APIreference/functions.rst +++ b/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`, where 1 means the group should be included. Pass +- ``geomgroup`` is an array of length :ref:`mjNGROUP`, 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`) 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` and :ref:`mjMAXUIITEM`. Exceeding these maxima results in low-level errors. +:ref:`mjMAXUISECT` and :ref:`mjMAXUIITEM`. Exceeding these maxima results in low-level errors. .. _mjui_addToSection: diff --git a/doc/APIreference/functions_override.rst b/doc/APIreference/functions_override.rst index 1e0d5bbf..88e90085 100644 --- a/doc/APIreference/functions_override.rst +++ b/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`, where 1 means the group should be included. Pass +- ``geomgroup`` is an array of length :ref:`mjNGROUP`, 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`) 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` and :ref:`mjMAXUIITEM`. Exceeding these maxima results in low-level errors. +:ref:`mjMAXUISECT` and :ref:`mjMAXUIITEM`. Exceeding these maxima results in low-level errors. .. _mjui_update: diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 2e12173c..5b5392a9 100644 --- a/doc/XMLreference.rst +++ b/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 ` value of 1E-14) result in compile error; + too small (below the :ref:`mjMINVAL ` 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 `); any contacts beyond that are discarded. To avoid penetration due to discarded + (:ref:`mjMAXCONPAIR `); 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: diff --git a/doc/changelog.rst b/doc/changelog.rst index 21552163..74178e54 100644 --- a/doc/changelog.rst +++ b/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` was set to 20. - - :ref:`mjNSOLVER` was reduced from 1000 to 200. + - The new constant :ref:`mjNISLAND` was set to 20. + - :ref:`mjNSOLVER` was reduced from 1000 to 200. - Added :ref:`mjData.solver_nisland`: 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``. diff --git a/doc/computation/index.rst b/doc/computation/index.rst index 422e4860..537d9884 100644 --- a/doc/computation/index.rst +++ b/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 ` + | :ref:`mjMAXCONPAIR ` - | HFieldCCD - | :ref:`mjMAXCONPAIR ` + | :ref:`mjMAXCONPAIR ` - | HFieldCCD - | :ref:`mjMAXCONPAIR ` + | :ref:`mjMAXCONPAIR ` - | HFieldCCD - | :ref:`mjMAXCONPAIR ` + | :ref:`mjMAXCONPAIR ` - | HFieldCCD - | :ref:`mjMAXCONPAIR ` + | :ref:`mjMAXCONPAIR ` - | HFieldCCD - | :ref:`mjMAXCONPAIR ` + | :ref:`mjMAXCONPAIR ` - | HFieldSDF | :ref:`sdf_initpoints ` * - Sphere @@ -1762,7 +1762,7 @@ sleeping mechanism is provided in the :ref:`Simulation chapter` 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 ` for :ref:`mjMINAWAKE ` time steps is marked as "ready to sleep". + :ref:`tolerance ` for :ref:`mjMINAWAKE ` 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` attribute of a tree root to "init", it is marked as "initialized-asleep" and put to sleep during :ref:`mjData` initialization. diff --git a/doc/mjwarp/index.rst b/doc/mjwarp/index.rst index ed5af221..591061cc 100644 --- a/doc/mjwarp/index.rst +++ b/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 ` and some contacts are ignored. To resolve this warning, reduce the height field + :ref:`mjMAXCONPAIR ` 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 diff --git a/doc/modeling.rst b/doc/modeling.rst index fc5979fd..127bc1a0 100644 --- a/doc/modeling.rst +++ b/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 -`] which is currently set to [0.0001 0.9999]. It causes the solver to interpolate between the unforced +`] 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 diff --git a/doc/programming/index.rst b/doc/programming/index.rst index 7d91d013..5d246f78 100644 --- a/doc/programming/index.rst +++ b/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 ` and the library provides the function +the symbol :ref:`mjVERSION_HEADER ` and the library provides the function :ref:`mj_version`. Thus the header and library versions can be compared with: .. code-block:: C diff --git a/doc/programming/simulation.rst b/doc/programming/simulation.rst index da6c2b16..c172b785 100644 --- a/doc/programming/simulation.rst +++ b/doc/programming/simulation.rst @@ -1098,7 +1098,7 @@ implementation details. The high level sleep state of :ref:`trees` 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`), and for every timestep where their velocity falls below the sleep :ref:`tolerance ++ |-| :ref:`mjMINAWAKE`), and for every timestep where their velocity falls below the sleep :ref:`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` instead of exposing it to + A concrete example is the decision to hard-code the value of :ref:`mjMINAWAKE` 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`, 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