chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity

Improve documentation related to engine-internal threading.

Browse Source 
PiperOrigin-RevId: 573346658
Change-Id: I112eba10b8f71b3a0aa27fa162a4a589be7ec3a7
This commit is contained in:
Yuval Tassa
2023-10-13 16:31:41 -07:00
committed by Copybara-Service
parent e90b347cbf
commit c0357ef3d0
4 changed files with 84 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/APIreference/APItypes.rst
+2
View File
@@ -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
+22 -21
View File
@@ -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:`enable flag<option-flag-island>` and the :ref:`CG<option-solver>` is selected.
- Island constraint resolution, if island discovery is :ref:`enabled<option-flag-island>` and the
:ref:`CG solver<option-solver>` is selected. The
`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>`
exposed via npoolthread flag. The `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.
24. Implemented reversed Z rendering for better depth precision. An enum :ref:`mjtDepthMap` was added with values
:ref:`mjDEPTH_ZERONEAR` and :ref:`mjDEPTH_ZEROFAR`, which can be used to set the new ``readDepthMap`` attribute in
:ref:`mjrContext`` to control how the depth returned by :ref:`mjr_readPixels` is mapped from ``znear`` to ``zfar``.
`Contribution <https://github.com/google-deepmind/mujoco/pull/978>`__ by `Levi Burner <https://github.com/aftersomemath>`__.
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.
23. Implemented reversed Z rendering for better depth precision. An enum :ref:`mjtDepthMap` was added with values
``mjDEPTH_ZERONEAR`` and ``mjDEPTH_ZEROFAR``, which can be used to set the new ``readDepthMap`` attribute in
:ref:`mjrContext` to control how the depth returned by :ref:`mjr_readPixels` is mapped from ``znear`` to ``zfar``.
`Contribution <https://github.com/google-deepmind/mujoco/pull/978>`__ by
`Levi Burner <https://github.com/aftersomemath>`__.
24. 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
+59 -12
View File
@@ -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
number of time steps to simulate, the number of parallel threads to use, and a flag to enable internal profiling (the
last two are optional). When N threads are specified with N>1, the code allocates a single mjModel and per-thread
mjData, and runs N identical simulations in parallel. The idea is to test performance with all cores active, similar
to Reinforcement Learning scenarios where samples are collected in parallel. The optimal N usually equals the number
of logical cores. By default the simulation starts from the model reference configuration qpos0 and qvel=0. However if
a keyframe named "test" is present in the model, it is used as the initial state state.
This code sample times the simulation of a given model. The timing is straightforward: the simulation of the passive
dynamics (with optional control noise) is rolled-out for the specified number of steps, while collecting statistics
about the number of contacts, scalar constraints, and CPU times from internal profiling. The results are then printed to
the console. To simulate controlled dynamics instead of passive dynamics one can either install a control callback
:ref:`mjcb_control`, or modify the code to set control signals explicitly, as explained in the :ref:`simulation loop
<siSimulation>` section below. This command-line utility is run with
The timing code is straightforward: the simulation of the passive dynamics is advanced for the specified number of
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
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.
.. code-block:: Shell
testspeed modelfile [nstep nthread ctrlnoise npoolthread]
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
+1 -1
View File
@@ -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"