Mujoco

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

Feature promotion
^^^^^^^^^^^^^^^^^
1. The :doc:`Model Editing<programming/modeledit>` framework afforded by :ref:`mjSpec`, introduced in 3.2.0 as an
in-development feature, is now stable and recommended for general use.
2. The native convex collision detection pipeline introduced in 3.2.3 and enabled by the
:ref:`nativeccd<option-flag-nativeccd>` flag, is not yet the default but is already recommended for general use.
Please try it when encountering collision-related problems and report any issues you encounter.

General
^^^^^^^

3. The global compiler flag ``exactmeshinertia`` has been removed and replaced with the mesh-specific
:ref:`inertia<asset-mesh-inertia>` attribute.
4. The not-useful ``convexhull`` compiler option (to disable computation of mesh convex hulls) has been removed.
5. Removed the deprecated ``mju_rotVecMat``, ``mju_rotVecMatT`` and ``mjv_makeConnector`` functions.
6. Sorting now uses a faster, native sort function (fixes :github:issue:`1638`).
7. The PBR texture layers introduced in 3.2.1 were refactored from seperate sub-elements to a single
:ref:`layer<material-layer>` sub-element.
8. The composite types box, cylinder, and sphere have been removed. Users should instead use the equivalent types
available in :ref:`flexcomp<body-flexcomp>`.

MJX
^^^
9. Added ``apply_ft``, ``jac``, and ``xfrc_accumulate`` as public functions.
10. Added ``TOUCH`` sensor.
11. Added support for ``eq_active``. Fixes :github:issue:`2173`.
12. Added ray intersection with ellipsoid.

Bug fixes
^^^^^^^^^
13. Fixed several bugs related to connect and weld constraints with site semantics (fixes :github:issue:`2179`, reported
by :github:user:`yinfanyi`). The introduction of site specification to connects and welds in 3.2.3 conditionally
changed the semantics of `mjData.eq_obj1id` and `mjData.eq_obj2id`, but these changes were not properly propagated in
several places leading to incorrect computations of constraint inertia, readings of affected force/torque sensors and
runtime enabling/disabling of such constraints.
14. Fixed a bug in slider-crank :ref:`transmission<geTransmission>`. The bug was introduced in 3.0.0.
15. Fixed a bug in flex texture coordinates that prevented the correct allocation of textures in mjModel.


Documentation
^^^^^^^^^^^^^
16. Function headers in the :doc:`API reference <../APIreference/APIfunctions>` now link to their source definitions
in GitHub.

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

General
^^^^^^^

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

1. The Newton solver no longer requires ``nv*nv`` memory allocation, allowing for much larger models. See e.g.,
`100_humanoids.xml <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/100_humanoids.xml>`__.
Two quadratic-memory allocations still remain to be fully sparsified: ``mjData.actuator_moment`` and the matrices used
by the PGS solver.
2. Removed the :at:`solid` and :at:`membrane` plugins and moved the associated computations into the engine. See `3D
example model <https://github.com/google-deepmind/mujoco/blob/main/model/flex/floppy.xml>`__ and `2D example model
<https://github.com/google-deepmind/mujoco/blob/main/model/flex/trampoline.xml>`__ for examples of flex objects
that previously required these plugins.
3. Replaced the function ``mjs_setActivePlugins`` with :ref:`mjs_activatePlugin`.

MJX
^^^
4. Added ``mocap_pos`` and ``mocap_quat`` in kinematics.
5. Added support for :ref:`spatial tendons <tendon-spatial>` with pulleys and external sphere and cylinder wrapping.
6. Added sphere-cylinder and sphere-ellipsoid collision functions (:github:issue:`2126`).
7. Fixed a bug with frictionloss constraints.
8. Added ``TENDONPOS`` and ``TENDONVEL`` sensors.
9. Fixed a bug with the computation of tangential contact forces in ``_decode_pyramid``.
10. Added ``JOINTINPARENT`` actuator transmission type.

Python bindings
^^^^^^^^^^^^^^^
11. Removed support for Python 3.8, now that it's `deprecated upstream <https://devguide.python.org/versions>`__.

Bug fixes
^^^^^^^^^
12. Fixed a bug where ``actuator_force`` was not set in MJX (:github:issue:`2068`).
13. Fixed bug where MJX data tendon fields were incorrect after calling ``mjx.put_data``.
14. The compiler now returns an error if height fields are used with :ref:`collision sensors<collision-sensors>` as they
are not yet supported.

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

General
^^^^^^^

.. admonition:: Breaking API changes
:class: attention

1. The runtime options ``mpr_tolerance`` and ``mpr_iterations`` were renamed to
:ref:`ccd_tolerance<option-ccd_tolerance>` and :ref:`ccd_iterations<option-ccd_iterations>`, both in XML and in
the :ref:`mjOption` struct. This is because the new convex collision detection pipeline (see below) does not use
the MPR algorithm. The semantics of these options remain identical.
2. The functions ``mjs_findMesh`` and ``mjs_findKeyframe`` were replaced by ``mjs_findElement``, which allows to look
for any object type.
3. The experimental use of 2D/3D elasticity plugins with :ref:`composite<body-composite>` has been removed. Users
should instead use :ref:`flexcomp<body-flexcomp>`, which provides the correct collision behavior.

4. Added the :ref:`nativeccd<option-flag-nativeccd>` flag. When this flag is enabled, general convex collision
detection is handled with a new native code path, rather than `libccd <https://github.com/danfis/libccd>`__.
This feature is in early stages of testing, but users who've experienced issues related to collsion detection are
welcome to experiment with it and report any issues.

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

5. Added a new way of defining :ref:`connect<equality-connect>` and :ref:`weld<equality-weld>` equality constraints,
using two sites. The new semantic is useful when the assumption that the constraint is satisfied
in the base configuration does not hold. In this case the sites will "snap together" at the beginning of the
simulation. Additionally, changing the site positions (``mjModel.site_pos``) and orientations
( ``mjModel.site_quat``) at runtime will correctly modify the constraint definition. This
`example model <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/equality_site.xml>`__ using
the new semantic is shown in the video on the right.
6. Introduced **free joint alignment**, an optimization that applies to bodies with a free joint and no child bodies
(simple free-floating bodies): automatically aligning the body frame with the inertial frame. This feature can be
toggled individually using the :ref:`freejoint/align<body-freejoint-align>` attribute or globally using the compiler
:ref:`alignfree<compiler-alignfree>` attribute. The alignment diagonalizes the related 6x6 inertia sub-matrix,
leading to both faster and more stable simulation of free bodies.

While this optimization is a strict improvement, it changes the semantics of the joint's degrees-of-freedom.
Therefore, ``qpos`` and ``qvel`` values saved in older versions (for example, in :ref:`keyframes<keyframe>`) will
become invalid. The global compiler attribute currently defaults to "false" due to this potential breakage, but could
be changed to "true" in a future release. Aligned free joints are recommended for all new models.

7. Added an :ref:`mjSpec` option for creating a texture directly from a buffer.
8. :ref:`shell (surface) inertia <body-geom-shellinertia>` is now supported by all geom types.
9. When :ref:`attaching<meAttachment>` sub-models, :ref:`keyframes<keyframe>` will now be correctly merged into the
parent model, but only on the first attachment.
10. Added the :ref:`mjtSameFrame` enum which contains the possible frame alignments of bodies and their children. These
alignments are used for computation shortcuts in :ref:`mj_kinematics`.
11. Added :ref:`mj_jacDot` for computing time-derivatives of kinematic Jacobians. Fixes :github:issue:`411`.

MJX
^^^
12. Added ``efc_pos`` to ``mjx.Data`` (:github:issue:`1388`).
13. Added position-dependent sensors: ``MAGNETOMETER``, ``CAMPROJECTION``, ``RANGEFINDER``, ``JOINTPOS``,
``ACTUATORPOS``, ``BALLQUAT``, ``FRAMEPOS``, ``FRAMEXAXIS``, ``FRAMEYAXIS``, ``FRAMEZAXIS``, ``FRAMEQUAT``,
``SUBTREECOM``, ``CLOCK``.
14. Added velocity-dependent sensors: ``VELOCIMETER``, ``GYRO``, ``JOINTVEL``, ``ACTUATORVEL``, ``BALLANGVEL``,
``FRAMELINVEL``, ``FRAMEANGVEL``, ``SUBTREELINVEL``, ``SUBTREEANGMOM``.
15. Added acceleration/force-dependent sensors: ``ACCELEROMETER``, ``FORCE``, ``TORQUE``, ``ACTUATORFRC``,
``JOINTACTFRC``, ``FRAMELINACC``, ``FRAMEANGACC``.
16. Changed default policy to avoid placing unused (MuJoCo-only) arrays on device.
17. Added ``device`` parameter to ``mjx.make_data`` to bring it to parity with ``mjx.put_model`` and ``mjx.put_data``.
18. Added support for :ref:`implicitfast integration<geIntegration>` for all cases except
:doc:`fluid drag <computation/fluid>`.
19. Fixed a bug where ``qLDiagInv`` had the wrong size for sparse mass matrices.
20. Added support for joint and tendon :ref:`frictionloss <coFriction>`.
21. Added support for :ref:`connect<equality-connect>` equality constraints using two sites.
22. Added support for :ref:`spatial tendons <tendon-spatial>` with site wrapping.

Bug fixes
^^^^^^^^^
23. Fixed a performance regression introduced in 3.1.7 in mesh Bounding Volume Hierarchies (:github:issue:`1875`,
contribution by :github:user:`michael-ahn`).
24. Fixed a bug wherein, for models that have both muscles and stateless actuators and used one of the implicit
integrators, wrong derivatives would be computed.
25. Fixed a bug in tendon wrapping around spheres. Before this fix, tendons that wrapped around spheres with an
externally-placed :ref:`sidesite<spatial-geom-sidesite>` could jump inside the sphere instead of wrapping around it.
26. Fixed a bug that caused :at:`meshdir` and :at:`texturedir` to be overwritten during model
:ref:`attachment<meAttachment>`, preventing model attachment for models with assets in different directories.

Python bindings
^^^^^^^^^^^^^^^
27. Added support for engine plugins in :ref:`mjSpec` (:github:issue:`1903`).
28. Better error reporting for issues with the assets dictionary, when loading models.

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

General
^^^^^^^
1. Increase texture and material limit back to 1000. 3.2.0 inadvertently reduced this limit to 100, breaking some
existing models (:github:issue:`1877`).

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

General
^^^^^^^
1. Renamed ``mjModel.tex_rgb`` to ``mjModel.tex_data``.
2. Added a new :ref:`autoreset<option-flag-autoreset>` flag to disable automatic reset when NaNs or infinities are
detected.
3. Added sub-elements to the MJCF :ref:`material<asset-material>` element, to allow specification of multiple textures
for rendering (e.g., ``occlusion, roughness, metallic``). Note that the MuJoCo renderer doesn't
support these new features, and they are made available for use with external renderers.
4. Sorting (``mjQUICKSORT``) now calls ``std::sort`` when building with C++ (:github:issue:`1638`).

MJX
^^^
5. Added more fields to ``mjx.Model`` and ``mjx.Data`` for further compatibility with the corresponding MuJoCo structs.
6. Added support for :ref:`fixed tendons <tendon-fixed>`.
7. Added support for tendon length limits (``mjCNSTR_LIMIT_TENDON`` in :ref:`mjtConstraint`).
8. Added support for tendon equality constraints (``mjEQ_TENDON`` in :ref:`mjtEq`).
9. Added support for tendon actuator transmission (``mjTRN_TENDON`` in :ref:`mjtTrn`).

Python bindings
^^^^^^^^^^^^^^^
10. Added support for asset dictionary argument in ``mujoco.spec.from_file``, ``mujoco.spec.from_string`` and
``mujoco.spec.compile``.


Bug fixes
^^^^^^^^^
11. Fixed a bug where implicit integrators did not take into account disabled actuators (:github:issue:`1838`).

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

New features
^^^^^^^^^^^^

1. Introduced a major new feature: **procedural model creation and editing**, using a new top-level data-structure
:ref:`mjSpec`. See the :doc:`Model Editing<programming/modeledit>` chapter for details.
Note that as of this release this feature is still in testing and subject to future breaking changes.
Fixes :github:issue:`364`.

General
^^^^^^^

.. admonition:: Breaking API changes
:class: attention

2. Removed deprecated ``mj_makeEmptyFileVFS`` and ``mj_findFileVFS`` functions. The constants ``mjMAXVFS`` and
``mjMAXVFSNAME`` are also removed as they are no longer needed.

**Migration:** Use :ref:`mj_addBufferVFS` to copy a buffer into a VFS file directly.

3. Calls to :ref:`mj_defaultVFS` may allocate memory inside VFS, and the corresponding
:ref:`mj_deleteVFS` must be called to deallocate any internal allocated memory.

4. Deprecated ``mju_rotVecMat`` and ``mju_rotVecMatT`` in favor of :ref:`mju_mulMatVec3` and
:ref:`mju_mulMatTVec3`. These function names and argument order are more consistent with the rest of the API.
The older functions have been removed from the Python bindings and will be removed from the C API in the next
release.
5. Removed the ``actuator_actdim`` callback from actuator plugins. They now have the ``actdim`` attribute, which
must be used with actuators that write state to the ``act`` array. This fixed a crash which happend when
keyframes were used in a model with stateful actuator plugins. The PID plugin will give an error when the wrong
value of actdim is provided.

6. Added :ref:`attach<body-attach>` meta-element to MJCF, which allows :ref:`attaching<meAttachment>` a subtree from a
different model to a body in the current model.
7. The :ref:`VFS<Virtualfilesystem>` implementation has been rewritten in C++ and is now considerably more efficient in
speed and memory footprint.

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

8. Added support for orthographic cameras. This is available for both fixed cameras and the free camera, using the
:ref:`camera/orthographic<body-camera-orthographic>` and :ref:`global/orthographic<visual-global-orthographic>`
attributes, respectively.
9. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
10. Added :ref:`mj_setKeyframe` for saving the current state into a model keyframe.
11. Added support for ``ball`` joints in the URDF parser ("spherical" in URDF).
12. Replaced ``mjUSEDOUBLE`` which was previously hard-coded in
`mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__
with the build-time flag ``mjUSESINGLE``. If this symbol is not defined, MuJoCo will use double-precision floating
point, as usual. If ``mjUSESINGLE`` is defined, MuJoCo will use single-precision floating point. See :ref:`mjtNum`.

Relatedly, fixed various type errors that prevented building with single-precision.
13. Quaternions in ``mjData.qpos`` and ``mjData.mocap_quat`` are no longer normalized in-place by
:ref:`mj_kinematics`. Instead they are normalized when they are used. After the first step, quaternions in
``mjData.qpos`` will be normalized.
14. Mesh loading in the compiler, which is usually the slowest part of the loading process, is now multi-threaded.

MJX
~~~
15. Added support for :ref:`elliptic friction cones<option-cone>`.
16. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
17. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.


.. youtube:: P83tKA1iz2Y
:align: right
:width: 360px

Simulate
^^^^^^^^
18. Added improved tutorial video.
19. Improved the Brownian noise generator.
20. Now displaying model load times if they are longer than 0.25 seconds.

Python bindings
^^^^^^^^^^^^^^^
21. Fixed a memory leak when using ``copy.deepcopy()`` on a ``mujoco.MjData`` instance (:github:issue:`1572`).

Bug fixes
^^^^^^^^^
22. Fix an issue where ``mj_copyData`` (or ``copy.copy()`` in the Python bindings) was not copying contact information
correctly (:github:issue:`1710`).
23. Fix an issue with saving to XML that caused frames to be written multiple times (:github:issue:`1802`).