Mujoco

-----------------------------

General
^^^^^^^

1. Added primitive collider for sphere-cylinder contacts, previously this pair used the generic convex-convex collider.
. Added :ref:`joint-actuatorforcerange<body-joint-actuatorfrcrange>` for clamping total actuator force at joints and
:ref:`sensor-jointactuatorfrc<sensor-jointactuatorfrc>` for measuring total actuation force applied at a joint. The
most important use case for joint-level actuator force clamping is to ensure that
:ref:`Cartesian actuator<actuator-general-refsite>` forces are realizable by individual motors at the joints.
See :ref:`CForceRange` for details.
. Added an optional ``content_type`` attribute to hfield, texture, and mesh assets. This attribute supports a formatted
`Media Type <https://www.iana.org/assignments/media-types/media-types.xhtml>`_ (previously known as MIME type) string
used to determine the type of the asset file without resorting to pulling the type from the file extension.
. Added analytic derivatives for quaternion :ref:`subtraction<mjd_subQuat>` and :ref:`integration<mjd_quatIntegrate>`
(rotation with an angular velocity). Derivatives are in the 3D tangent space.
. Added :ref:`mjv_connector` which has identical functionality to ``mjv_makeConnector``, but with more convenient
"from-to" argument parametrization. ``mjv_makeConnector`` is now deprecated.
. Bumped oldest supported MacOS from version 10.12 to 11. MacOS 11 is the oldest version still maintained by Apple.

Python bindings
^^^^^^^^^^^^^^^

7. The :ref:`passive viewer<PyViewerPassive>` handle now exposes ``update_hfield``, ``update_mesh``, and
``update_texture`` methods to allow users to update renderable assets.
(Issues :github:issue:`812`, :github:issue:`958`, :github:issue:`965`).
. Allow a custom keyboard event callback to be specified in the :ref:`passive viewer<PyViewerPassive>`
(:github:issue:`766`).
. Fix GLFW crash when Python exits while the passive viewer is running (:github:issue:`790`).

Models
^^^^^^

10. Added simple `car <https://github.com/google-deepmind/mujoco/blob/main/model/car/car.xml>`__ example model.

-----------------------------

.. note::
MuJoCo 2.3.6 is the last version to officially support Python 3.7.

.. youtube:: ZppeDArq6AU
:align: right
:width: 240px

Models
^^^^^^

1. Added `3x3x3 cube <https://github.com/google-deepmind/mujoco/blob/main/model/cube/cube_3x3x3.xml>`__ example model.
See `README <https://github.com/google-deepmind/mujoco/blob/main/model/cube/README.md>`__ for details.

Bug fixes
^^^^^^^^^

2. Fixed a bug that was causing an incorrect computation of the mesh bounding box and coordinate frame if the volume was
invalid. In such case, now MuJoCo only accepts a non-watertight geometry if
:ref:`shellinertia<body-geom-shellinertia>` is equal to ``true``.
. Fixed the sparse Jacobian multiplication logic that is used to compute derivatives for tendon damping and fluid
force, which affects the behaviour of the :ref:`implicit and implicitfast integrators<geIntegration>`.
. Fixes to :ref:`mj_ray`, in line with geom visualisation conventions:

- Planes and height-fields respect the ``geom_group`` and ``flg_static`` arguments. Before this change, rays would
intersect planes and height-fields unconditionally.
- ``flg_static`` now applies to all static geoms, not just those which are direct children of the world body.

.. youtube:: hqIMTNGaLF4
:align: right
:width: 240px

Plugins
^^^^^^^

5. Added touch-grid sensor plugin. See `documentation <https://github.com/google-deepmind/mujoco/blob/main/plugin/sensor/README.md>`__
for details, and associated `touch_grid.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/sensor/touch_grid.xml>`__
example model. The plugin includes `in-scene visualisation <https://youtu.be/0LOJ3WMnqeA>`__.

Simulate
^^^^^^^^

.. youtube:: mXVPbppGk5I
:aspect: 16:7
:align: right
:width: 240px

6. Added Visualization tab to simulate UI, corresponding to elements of the :ref:`visual<visual>` MJCF element. After
modifying values in the GUI, a saved XML will contain the new values. The modifiable members of
:ref:`mjStatistic` (:ref:`extent<statistic-extent>`, :ref:`meansize<statistic-meansize>` and
:ref:`center<statistic-center>`) are computed by the compiler and therefore do not have defaults. In order for these
attributes to appear in the saved XML, a value must be specified in the loaded XML.

.. image:: images/changelog/simulate_text_width.png
:align: right
:width: 380px
:alt: Before / After

7. Increased text width for UI elements in the default spacing. [before / after]:

General
^^^^^^^

8. Added :ref:`mj_getState` and :ref:`mj_setState` for getting and setting the simulation state as a concatenated vector
of floating point numbers. See the :ref:`State<geState>` section for details.
. Added :ref:`mjContact.solreffriction<mjContact>`, allowing different :ref:`solref<CSolver>` parameters for the normal
and frictional axes of contacts when using :ref:`elliptic friction cones<option-cone>`. This attribute is required
for elastic frictional collisions, see associated
`example model <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/spin_recoil.xml>`__
mimicking the spin-bounce recoil behaviour of `elastic rubber balls <https://www.youtube.com/watch?v=uFLJcRegIVQ&t=3s>`__.
This is an advanced option currently only supported by explicit :ref:`contact pairs<contact-pair>`, using the
:ref:`solreffriction<contact-pair-solreffriction>` attribute.
. Added :ref:`mjd_inverseFD` for finite-differenced inverse-dynamics derivatives.
. Added functions for operations on banded-then-dense "arrowhead" matrices. Such matrices are common when doing direct
trajectory optimization. See :ref:`mju_cholFactorBand` documentation for details.
. Added :ref:`mj_multiRay` function for intersecting multiple rays emanating from a single point.
This is significantly faster than calling :ref:`mj_ray` multiple times.
. Ray-mesh collisions are now up to 10x faster, using a bounding volume hierarchy of mesh faces.
. Increased ``mjMAXUIITEM`` (maximum number of UI elements per section in Simulate) to 100.
. Added :ref:`documentation<exProvider>` for resource providers.
. Changed the formula for :ref:`mju_sigmoid`, a finite-support sigmoid :math:`s \colon \mathbf R \rightarrow [0, 1]`.
Previously, the smooth part consisted of two stitched quadratics, once continuously differentiable.
It is now a single quintic, twice continuously differentiable:

.. math::
s(x) =
\begin{cases}
0, & & x \le 0 \\
6x^5 - 15x^4 + 10x^3, & 0 \lt & x \lt 1 \\
1, & 1 \le & x \qquad
\end{cases}

17. Added optional :ref:`tausmooth<actuator-muscle-tausmooth>` attribute to muscle actuators. When positive, the
time-constant :math:`\tau` of muscle activation/deactivation uses :ref:`mju_sigmoid` to transition smoothly
between the two extremal values given by the `Millard et al. (2013) <https://doi.org/10.1115/1.4023390>`__ muscle
model, within a range of width tausmooth. See :ref:`Muscle actuators<CMuscle>` for more details.
Relatedly, :ref:`mju_muscleDynamics` now takes 3 parameters instead of 2, adding the new smoothing-width parameter.
. Moved public C macro definitions out of mujoco.h into a new public header file called
`mjmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmacro.h>`__. The new file
is included by mujoco.h so this change does not break existing user code.
. Added instrumentation for the `Address Sanitizer (ASAN) <https://clang.llvm.org/docs/AddressSanitizer.html>`__ and
`Memory Sanitizer (MSAN) <https://clang.llvm.org/docs/MemorySanitizer.html>`__ to detect memory bugs when allocating
from the ``mjData`` stack and arena.
. Removed ``pstack`` and ``parena`` from the output of ``mj_printData``, since these are implementation details of the
``mjData`` allocators that are affected by diagnostic paddings in instrumented builds.
. Removed the ``mj_activate`` and ``mj_deactivate`` functions. These had been kept around for compatibility with old
user code from when MuJoCo was closed source, but have been no-op functions since open sourcing.

------------------------------

Bug fixes
^^^^^^^^^

1. Fix asset loading bug that prevented OBJ and PNG files from being read from disk when :ref:`mjVFS` is used.
. Fix occasional segmentation faults on macOS when mouse perturbations are applied in the Python passive viewer.

Plugins
^^^^^^^

3. The ``visualize`` callback in :ref:`mjpPlugin` now receives an :ref:`mjvOption` as an input argument.

------------------------------

.. note::

This version is affected by an asset loading bug that prevents OBJ and PNG files from being read from disk when
``mjVFS`` is used. Users are advised to skip to version 2.3.5 instead.

General
^^^^^^^

1. Removed the "global" setting of the :ref:`compiler/coordinate<compiler-coordinate>` attribute. This rarely-used
setting complicates the compiler logic and is blocking future improvements. In order to convert older models which
used this option, load and save them in MuJoCo 2.3.3 or older.

.. image:: images/changelog/ellipsoidinertia.gif
:align: right
:width: 240px

2. Added :ref:`visual-global<visual-global>` flag :ref:`ellipsoidinertia<visual-global-ellipsoidinertia>` to visualize
equivalent body inertias with ellipsoids instead of the default boxes.
. Added midphase and broadphase collision statistics to :ref:`mjData`.
. Added documentation for :ref:`engine plugins<exPlugin>`.
. Added struct information to the ``introspect`` module.
. Added a new extension mechanism called :ref:`resource providers<exProvider>`. This extensible mechanism allows MuJoCo
to read assets from data sources other than the local OS filesystem or
the :ref:`Virtual file system<Virtualfilesystem>`.

Python bindings
^^^^^^^^^^^^^^^

7. Offscreen rendering on macOS is no longer restricted to the main thread. This is achieved by using the low-level
Core OpenGL (CGL) API to create the OpenGL context, rather than going via GLFW which relies on Cocoa's NSOpenGL.
The resulting context is not tied to a Cocoa window, and is therefore not tied to the main thread.
. Fixed a race condition in ``viewer.launch_passive`` and ``viewer.launch_repl``. These functions could previously
return before an internal call to ``mj_forward``. This allows user code to continue and potentially modify physics
state concurrently with the internal ``mj_forward``, resulting in e.g.
`MuJoCo stack overflow error <https://github.com/google-deepmind/mujoco/issues/783>`__
or `segmentation fault <https://github.com/google-deepmind/mujoco/issues/790>`__.
. The ``viewer.launch_passive`` function now returns a handle which can be used to interact with the viewer. The
passive viewer now also requires an explicit call to ``sync`` on its handle to pick up any update to the physics
state. This is to avoid race conditions that can result in visual artifacts. See
:ref:`documentation<PyViewerPassive>` for details.
. The ``viewer.launch_repl`` function has been removed since its functionality is superseded by ``launch_passive``.
. Added a small number of missing struct fields discovered through the new ``introspect`` metadata.

Bug fixes
^^^^^^^^^

12. Fixed bug in the handling of ellipsoid-based fluid model forces in the new implicitfast integrator.
. Removed spurious whole-arena copying in `mj_copyData`, which can considerably
`slow down <https://github.com/google-deepmind/mujoco/issues/568>`__ the copying operation.
. Make :ref:`shellinertia<body-geom-shellinertia>` ignore ``exactmeshinertia``, which is
only used for legacy volume computations (`759 <https://github.com/google-deepmind/mujoco/issues/759>`__).

------------------------------

General
^^^^^^^

1. Improvements to implicit integration:

- The derivatives of the RNE algorithm are now computed using sparse math, leading to significant speed
improvements for large models when using the :ref:`implicit integrator<geIntegration>`.
- A new integrator called ``implicitfast`` was added. It is similar to the existing implicit integrator, but skips the
derivatives of Coriolis and centripetal forces. See the :ref:`numerical integration<geIntegration>` section for a
detailed motivation and discussion. The implicitfast integrator is recommended for all new models and will
become the default integrator in a future version.

The table below shows the compute cost of the 627-DoF `humanoid100
<https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/humanoid100.xml>`__ model using different
integrators. "implicit (old)" uses dense RNE derivatives, "implicit (new)" is after the sparsification mentioned
above. Timings were measured on a single core of an AMD 3995WX CPU.

.. csv-table::
:header: "timing", "Euler", "implicitfast", "implicit (new)", "implicit (old)"
:widths: auto
:align: left

one step (ms), 0.5, 0.53, 0.77, 5.0
steps/second, 2000, 1900, 1300, 200

.. image:: images/computation/midphase.gif
:align: right
:width: 350px

.. _midphase:

2. Added a collision mid-phase for pruning geoms in body pairs, see :ref:`documentation<coSelection>` for more details.
This is based on static AABB bounding volume hierarchy (a BVH binary tree) in the body inertial frame. The GIF on
the right is cut from `this longer video <https://youtu.be/e0babIM8hBo>`__.
. The ``mjd_transitionFD`` function no longer triggers sensor calculation unless explicitly requested.
. Corrected the spelling of the ``inteval`` attribute to ``interval`` in the :ref:`mjLROpt` struct.
. Mesh texture and normal mappings are now 3-per-triangle rather than 1-per-vertex. Mesh vertices are no longer
duplicated in order to circumvent this limitation as they previously were.
. The non-zeros for the sparse constraint Jacobian matrix are now precounted and used for matrix memory allocation.
For instance, the constraint Jacobian matrix from the `humanoid100
<https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/humanoid100.xml>`__ model, which previously
required ~500,000 ``mjtNum``'s, now only requires ~6000. Very large models can now load and run with the CG solver.
. Modified :ref:`mju_error` and :ref:`mju_warning` to be variadic functions (support for printf-like arguments). The
functions :ref:`mju_error_i`, :ref:`mju_error_s`, :ref:`mju_warning_i`, and :ref:`mju_warning_s` are now deprecated.
. Implemented a performant ``mju_sqrMatTDSparse`` function that doesn't require dense memory allocation.
. Added ``mj_stackAllocInt`` to get correct size for allocating ints on mjData stack. Reducing stack memory usage
by 10% - 15%.


Python bindings
^^^^^^^^^^^^^^^

10. Fixed IPython history corruption when using ``viewer.launch_repl``. The ``launch_repl`` function now provides
seamless continuation of an IPython interactive shell session, and is no longer considered experimental feature.
. Added ``viewer.launch_passive`` which launches the interactive viewer in a passive, non-blocking mode. Calls to
``launch_passive`` return immediately, allowing user code to continue execution, with the viewer automatically
reflecting any changes to the physics state. (Note that this functionality is currently in experimental/beta stage,
and is not yet described in our :ref:`viewer documentation<PyViewer>`.)
. Added the ``mjpython`` launcher for macOS, which is required for ``viewer.launch_passive`` to function there.
. Removed ``efc_`` fields from joint indexers. Since the introduction of arena memory, these fields now have dynamic
sizes that change between time steps depending on the number of active constraints, breaking strict correspondence
between joints and ``efc_`` rows.
. Added a number of missing fields to the bindings of ``mjVisual`` and ``mjvPerturb`` structs.

Simulate
^^^^^^^^

15. Implemented a workaround for `broken VSync <https://github.com/glfw/glfw/issues/2249>`__ on macOS so that the frame
rate is correctly capped when the Vertical Sync toggle is enabled.

.. image:: images/changelog/contactlabel.png
:align: right
:width: 400px

16. Added optional labels to contact visualization, indicating which two geoms are contacting (names if defined, ids
otherwise). This can be useful in cluttered scenes.

|br|

--------------------------------

General
^^^^^^^

1. A more performant mju_transposeSparse has been implemented that doesn't require dense memory allocation.
For a constraint Jacobian matrix from the
`humanoid100.xml <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/humanoid100.xml>`__ model,
this function is 35% faster.
. The function :ref:`mj_name2id` is now implemented using a hash function instead of a linear search for better
performance.
. Geom names are now parsed from URDF. Any duplicate names are ignored.
``mj_printData`` output now contains contacting geom names.

Bug fixes
^^^^^^^^^

4. Fixed a bug that for :at:`shellinertia` equal to ``true`` caused the mesh orientation to be overwritten by the
principal components of the shell inertia, while the vertex coordinates are rotated using the volumetric inertia.
Now the volumetric inertia orientation is used also in the shell case.
. Fixed misalignment bug in mesh-to-primitive fitting when using the bounding box fitting option :at:`fitaabb`.

.. image:: images/changelog/meshfit.png
:align: right
:width: 300px

6. The ``launch_repl`` functionality in the Python viewer has been fixed.
. Set ``time`` correctly in ``mjd_transitionFD``, to support time-dependent user code.
. Fixed sensor data dimension validation when ``user`` type sensors are present.
. Fixed incorrect plugin error message when a null ``nsensordata`` callback is encountered during model compilation.
. Correctly end the timer (``TM_END``) ``mj_fwdConstraint`` returns early.
. Fixed an infinite loop in ``mj_deleteFileVFS``.

Simulate
^^^^^^^^

12. Increased precision of simulate sensor plot y-axis by 1 digit
(`719 <https://github.com/google-deepmind/mujoco/issues/719>`_).
. Body labels are now drawn at the body frame rather than inertial frame, unless inertia is being visualised.

Plugins
^^^^^^^

14. The ``reset`` callback now receives instance-specific ``plugin_state`` and ``plugin_data`` as arguments, rather than
the entire ``mjData``. Since ``reset`` is called inside ``mj_resetData`` before any physics forwarding call has been
made, it is an error to read anything from ``mjData`` at this stage.
. The ``capabilities`` field in ``mjpPlugin`` is renamed ``capabilityflags`` to more clearly indicate that this is a
bit field.