Improve documentation related to engine-internal threading.

PiperOrigin-RevId: 573346658
Change-Id: I112eba10b8f71b3a0aa27fa162a4a589be7ec3a7

doc/APIreference/APItypes.rst

@@ -502,6 +502,8 @@ These are the possible framebuffers. They are used as an argument to the functio
 .. mujoco-include:: mjtFramebuffer
 
 
+.. _mjtDepthMap:
+
 mjtDepthMap
 ~~~~~~~~~~~
 

doc/changelog.rst

@@ -29,13 +29,16 @@ New features
      gradient at query points. See the :ref:`documentation<exWriting>` for more details.
 
 3. Added :ref:`mjThreadPool` and :ref:`mjTask` which allow for multi-threaded operations within the MuJoCo engine
-   pipeline.
+   pipeline. If engine-internal threading is enabled, the following operations will be multi-threaded:
 
-   If engine-level threading is enabled, the following operations will be multi-threaded:
+   - Island constraint resolution, if island discovery is :ref:`enabled<option-flag-island>` and the
-
+     :ref:`CG solver<option-solver>` is selected. The
-   - Island constraint resolution, if island discovery is :ref:`enable flag<option-flag-island>` and the :ref:`CG<option-solver>` is selected.
+     `22 humanoids <https://github.com/deepmind/mujoco/blob/main/model/humanoid/22_humanoids.xml>`__ model shows a 3x
+     speedup compared to the single threaded simulation.
    - Inertia-related computations and collision detection will happen in parallel.
 
+   Engine-internal threading is a work in progress and currently only available in first-party code via the
+   :ref:`testspeed<saTestspeed>` utility, exposed with the ``npoolthread`` flag.
 
 .. youtube:: ra2bTiZHGlw
    :align: right
@@ -108,7 +111,7 @@ General
 14. Added a new :ref:`dyntype<actuator-general-dyntype>`, ``filterexact``, which updates first-order filter states with
     the exact formula rather than with Euler integration.
 15. Added an actuator attribute, :ref:`actearly<actuator-general-actearly>`, which uses semi-implicit integration for
-    actuator forces: using the next step's actuator state to compute the current actuator forces at the current timestep.
+    actuator forces: using the next step's actuator state to compute the current actuator forces.
 16. Renamed ``actuatorforcerange`` and ``actuatorforcelimited``, introduced in the previous version to
     :ref:`actuatorfrcrange<body-joint-actuatorfrcrange>` and
     :ref:`actuatorfrclimited<body-joint-actuatorfrclimited>`, respectively.
@@ -132,24 +135,22 @@ General
       attributes are specified. See the following
       `example model <https://github.com/deepmind/mujoco/blob/main/test/engine/testdata/vis_visualize/frustum.xml>`__.
     - Note that these attributes only take effect for offline rendering and do not affect interactive visualisation.
-23. Added multi-threaded constraint solving via :ref:`mj_island` and :ref:`mjThreadPool` to :ref:`testspeed<saTestspeed>`
+23. Implemented reversed Z rendering for better depth precision. An enum :ref:`mjtDepthMap` was added with values
-    exposed via npoolthread flag. The `22 humanoids <https://github.com/deepmind/mujoco/blob/main/model/humanoid/22_humanoids.xml>`__
+    ``mjDEPTH_ZERONEAR`` and ``mjDEPTH_ZEROFAR``, which can be used to set the new ``readDepthMap`` attribute in
-    model shows a 3x speedup compared to the single threaded simulation.
+    :ref:`mjrContext` to control how the depth returned by :ref:`mjr_readPixels` is mapped from ``znear`` to ``zfar``.
-24. Implemented reversed Z rendering for better depth precision. An enum :ref:`mjtDepthMap` was added with values
+    `Contribution <https://github.com/google-deepmind/mujoco/pull/978>`__ by
-    :ref:`mjDEPTH_ZERONEAR` and :ref:`mjDEPTH_ZEROFAR`, which can be used to set the new ``readDepthMap`` attribute in
+    `Levi Burner <https://github.com/aftersomemath>`__.
-    :ref:`mjrContext`` to control how the depth returned by :ref:`mjr_readPixels` is mapped from ``znear`` to ``zfar``.
+24. Deleted the code sample ``testxml``. The functionality provided by this utility is implemented in the
-    `Contribution <https://github.com/google-deepmind/mujoco/pull/978>`__ by `Levi Burner <https://github.com/aftersomemath>`__.
+    `WriteReadCompare <https://github.com/google-deepmind/mujoco/blob/main/test/xml/xml_native_writer_test.cc>`__ test.
-25. Deleted the code sample ``testxml``. The functionality provided by this utility is implemented in the
-    `WriteReadCompare <https://github.com/google-deepmind/mujoco/blob/main/test/xml/xml_native_writer_test.cc>__ test.
 
 Python bindings
 ^^^^^^^^^^^^^^^
 
-26. Fixed `#870 <https://github.com/google-deepmind/mujoco/issues/870>`__ where calling ``update_scene`` with an invalid
+25. Fixed `#870 <https://github.com/google-deepmind/mujoco/issues/870>`__ where calling ``update_scene`` with an invalid
     camera name used the default camera.
-27. Added ``user_scn`` to the :ref:`passive viewer<PyViewerPassive>` handle, which allows users to add custom
+26. Added ``user_scn`` to the :ref:`passive viewer<PyViewerPassive>` handle, which allows users to add custom
     visualization geoms (`#1023 <https://github.com/google-deepmind/mujoco/issues/870>`__).
-28. Added optional boolean keyword arguments ``show_left_ui`` and ``show_right_ui`` to the functions ``viewer.launch``
+27. Added optional boolean keyword arguments ``show_left_ui`` and ``show_right_ui`` to the functions ``viewer.launch``
     and ``viewer.launch_passive``, which allow users to launch a viewer with UI panels hidden.
 
 Simulate
@@ -159,21 +160,21 @@ Simulate
    :align: right
    :width: 240px
 
-29. Added **state history** mechanism to :ref:`simulate<saSimulate>` and the managed
+28. Added **state history** mechanism to :ref:`simulate<saSimulate>` and the managed
     :ref:`Python viewer<PyViewerManaged>`. State history can be viewed by scrubbing the History slider and (more
     precisely) with the left and right arrow keys. See screen capture:
 
-30. The ``LOADING...`` label is now shown correctly.
+29. The ``LOADING...`` label is now shown correctly.
     `Contribution <https://github.com/google-deepmind/mujoco/pull/1070>`__ by
     `Levi Burner <https://github.com/aftersomemath>`__.
 
 Bug fixes
 ^^^^^^^^^
 
-31. Fixed a bug that was causing :ref:`geom margin<body-geom-margin>` to be ignored during the construction of
+30. Fixed a bug that was causing :ref:`geom margin<body-geom-margin>` to be ignored during the construction of
     midphase collision trees.
 
-32. Fixed a bug that was generating incorrect values in ``efc_diagApprox`` for weld equality constraints.
+31. Fixed a bug that was generating incorrect values in ``efc_diagApprox`` for weld equality constraints.
 
 
 Version 2.3.7 (July 20, 2023)

doc/programming/samples.rst

@@ -12,19 +12,66 @@ with the library.
 `testspeed <https://github.com/google-deepmind/mujoco/blob/main/sample/testspeed.cc>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This code sample tests the simulation speed for a given model. The command line arguments are the model file, the
+This code sample times the simulation of a given model. The timing is straightforward: the simulation of the passive
-number of time steps to simulate, the number of parallel threads to use, and a flag to enable internal profiling (the
+dynamics (with optional control noise) is rolled-out for the specified number of steps, while collecting statistics
-last two are optional). When N threads are specified with N>1, the code allocates a single mjModel and per-thread
+about the number of contacts, scalar constraints, and CPU times from internal profiling. The results are then printed to
-mjData, and runs N identical simulations in parallel. The idea is to test performance with all cores active, similar
+the console. To simulate controlled dynamics instead of passive dynamics one can either install a control callback
-to Reinforcement Learning scenarios where samples are collected in parallel. The optimal N usually equals the number
+:ref:`mjcb_control`, or modify the code to set control signals explicitly, as explained in the :ref:`simulation loop
-of logical cores. By default the simulation starts from the model reference configuration qpos0 and qvel=0. However if
+<siSimulation>` section below. This command-line utility is run with
-a keyframe named "test" is present in the model, it is used as the initial state state.
 
-The timing code is straightforward: the simulation of the passive dynamics is advanced for the specified number of
+.. code-block:: Shell
-steps, while collecting statistics about the number of contacts, scalar constraints, and CPU times from internal
+
-profiling. The results are then printed in the console. To simulate controlled dynamics instead of passive dynamics
+   testspeed modelfile [nstep nthread ctrlnoise npoolthread]
-one can either install the control callback :ref:`mjcb_control`, or set control signals
+
-explicitly as explained in the :ref:`simulation loop <siSimulation>` section below.
+Where the command line arguments are
+
+.. list-table::
+   :width: 95%
+   :align: left
+   :widths: 1 1 5
+   :header-rows: 1
+
+   * - Argument
+     - Default
+     - Meaning
+   * - ``modelfile``
+     - (required)
+     - path to model
+   * - ``nstep``
+     - 10000
+     - number of steps per rollout
+   * - ``nthread``
+     - 1
+     - number of threads running parallel rollouts
+   * - ``ctrlnoise``
+     - 0.01
+     - scale of pseudo-random noise injected into actuators
+   * - ``npoolthread``
+     - 1
+     - number of threads in engine-internal threadpool
+
+**Notes:**
+
+- When ``nthread > 1`` is specified, the code allocates a single mjModel and per-thread mjData, and runs ``nthread``
+  identical simulations in parallel. This tests performance with all cores active, as in Reinforcement
+  Learning scenarios where samples are collected in parallel. The optimal ``nthread`` usually equals the number of
+  logical cores.
+- By default, the simulation starts from the model reference configuration with zero velocities. However, if a
+  keyframe named "test" is present in the model, it is used as the initial state.
+- The ``ctrlnoise`` argument prevents models from settling into a static state where, due to warmstarts, one can
+  measure artificially faster simulation.
+- When ``npoolthread > 1`` is specified, an engine-internal :ref:`mjThreadPool` is created with the specified number of
+  threads, to speed up simulation of large scenes. Note that while it is possible to to use both ``nthread`` and
+  ``npoolthread``, the scenarios for which one would want these different type of multithreading are usually mutually
+  exclusive.
+- For more repeatable performance statistics, run the tool with the ``performance``
+  `governor <https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt>`__ on Linux, or the
+  ``High Performance`` power plan on Windows, to reduce noise from CPU scaling.
+- Many modern CPUs contain a mixture of "performance" and "efficiency" cores. Users should consider restricting the
+  process to only run on the same type of cores for more interpretable performance statistics. This can be done via the
+  `taskset <https://man7.org/linux/man-pages/man1/taskset.1.html>`__ command on Linux, or the
+  `start /affinity <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/start>`__
+  command on Windows (processor affinity cannot be specified through documented API means on macOS).
 
 .. _saCompile:
 

sample/testspeed.cc

@@ -116,7 +116,7 @@ int main(int argc, char** argv) {
       "  --------      -------     --------\n"
       "  modelfile                 path to model (required)\n"
       "  nstep         10000       number of steps per rollout\n"
-      "  nthread       1           number of threads for which to run parallel rollouts\n"
+      "  nthread       1           number of threads running parallel rollouts\n"
       "  ctrlnoise     0.01        scale of pseudo-random noise injected into actuators\n"
       "  npoolthread   0           number of threads in engine-internal threadpool\n"
       "\n"