Mujoco

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

.. 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
: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 modifyable 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 superceded 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.

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

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

1. The ``simulate`` GUI is now available through the ``mujoco`` Python package as ``mujoco.viewer``.
See :ref:`documentation<PyViewer>` for details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`__.)
. The ``Renderer`` class from the MuJoCo tutorial Colab is now available directly in the native Python bindings.

General
^^^^^^^

3. The tendon :at:`springlength` attribute can now take two values. Given two non-decreasing values, `springlength`
specifies a `deadband <https://en.wikipedia.org/wiki/Deadband>`__ range for spring stiffness. If the tendon length is
between the two values, the force is 0. If length is outside this range, the force behaves like a regular spring, with
the spring resting length corresponding to the nearest :at:`springlength` value. This can be used to create tendons
whose limits are enforced by springs rather than constraints, which are cheaper and easier to analyse. See
`tendon_springlength.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/tendon_springlength.xml>`__
example model.

.. attention::
This is a minor breaking API change. ``mjModel.tendon_lengthspring`` now has size ``ntendon x 2`` rather than
``ntendon x 1``.

.. youtube:: -PJ6afdETUg
:align: right
:height: 150px

. Removed the requirement that stateless actuators come before stateful actuators.
. Added :ref:`mju_fill`, :ref:`mju_symmetrize` and :ref:`mju_eye` utility functions.
. Added :at:`gravcomp` attribute to :ref:`body<body>`, implementing gravity compensation and buoyancy.
See `balloons.xml <https://github.com/google-deepmind/mujoco/blob/main/model/balloons/balloons.xml>`__ example model.
. Renamed the ``cable`` plugin library to ``elasticity``.
. Added :at:`actdim` attribute to :ref:`general actuators<actuator-general>`. Values greater than 1 are only allowed
for dyntype :at-val:`user`, as native activation dynamics are all scalar. Added example test implementing 2nd-order
activation dynamics to
`engine_forward_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/engine/engine_forward_test.cc>`__.
. Improved particle :ref:`composite<body-composite>` type, which now permits a user-specified geometry and multiple
joints. See the two new examples:
`particle_free.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free.xml>`__ and
`particle_free2d.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free2d.xml>`__.
. Performance improvements for non-AVX configurations:

- 14% faster ``mj_solveLD`` using `restrict <https://en.wikipedia.org/wiki/Restrict>`__. See `engine_core_smooth_benchmark_test
<https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_core_smooth_benchmark_test.cc>`__.
- 50% faster ``mju_dotSparse`` using manual loop unroll. See `engine_util_sparse_benchmark_test
<https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_util_sparse_benchmark_test.cc>`__.
. Added new :at:`solid` passive force plugin:

.. youtube:: AGcTGHbbze4
:align: right
:height: 150px

- This is new force field compatible with the :ref:`composite<body-composite>` particles.
- Generates a tetrahedral mesh having particles with mass concentrated at vertices.
- Uses a piecewise-constant strain model equivalent to finite elements but expressed in a coordinate-free
formulation. This implies that all quantities can be precomputed except edge elongation, as in a mass-spring model.
- Only suitable for small strains (large displacements but small deformations). Tetrahedra may invert if subject to
large loads.

. Added API functions ``mj_loadPluginLibrary`` and ``mj_loadAllPluginLibraries``. The first function is identical to
``dlopen`` on a POSIX system, and to ``LoadLibraryA`` on Windows. The second function scans a specified directory for
all dynamic libraries file and loads each library found. Dynamic libraries opened by these functions are assumed to
register one or more MuJoCo plugins on load.
. Added an optional ``visualize`` callback to plugins, which is called during ``mjv_updateScene``. This callback allows
custom plugin visualizations. Enable stress visualization for the Cable plugin as an example.
. Sensors of type :ref:`user<sensor-user>` no longer require :at:`objtype`, :at:`objname` and :at:`needstage`. If
unspecified, the objtype is now :ref:`mjOBJ_UNKNOWN<mjtObj>`. ``user`` sensors :at:`datatype` default is now
:at-val:`"real"`, :at:`needstage` default is now :at-val:`"acc"`.
. Added support for capsules in URDF import.
. On macOS, issue an informative error message when run under `Rosetta 2 <https://support.apple.com/en-gb/HT211861>`__
translation on an Apple Silicon machine. Pre-built MuJoCo binaries make use of
`AVX <https://en.wikipedia.org/wiki/Advanced_Vector_Extensions>`__ instructions on x86-64 machines, which is not
supported by Rosetta 2. (Before this version, users only get a cryptic "Illegal instruction" message.)

Bug fixes
^^^^^^^^^

17. Fixed bug in ``mj_addFileVFS`` that was causing the file path to be ignored (introduced in 2.1.4).

Simulate
^^^^^^^^

18. Renamed the directory in which the ``simulate`` application searches for plugins from ``plugin`` to ``mujoco_plugin``.
. Mouse force perturbations are now applied at the selection point rather than the body center of mass.