Skip to content

Commit 237c17e

Browse files
mmossgcopybara-github
mmossg
authored and
copybara-github
committed
Update changelog for the 3.9.0 release.
PiperOrigin-RevId: 922002472 Change-Id: I92489261c59cff10b29def784698868e67aa43da
1 parent f6cd023 commit 237c17e

1 file changed

Lines changed: 64 additions & 63 deletions

File tree

‎doc/changelog.rst‎

Lines changed: 64 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -2,93 +2,94 @@
22
Changelog
33
=========
44

5-
Upcoming version (not yet released)
6-
-----------------------------------
5+
Version 3.9.0 (May 27, 2026)
6+
----------------------------
77

88
General
99
^^^^^^^
10-
- Added ``mjData.efc_Y``, the whitened constraint Jacobian :math:`Y = J M^{-1/2}`, allocated in the arena when
11-
dual solvers (PGS or NoSlip) are used or when :ref:`diagexact<option-flag-diagexact>` is enabled.
12-
- Added the :ref:`diagexact<option-flag-diagexact>` enable flag, which computes the exact diagonal of the
13-
constraint-space inertia matrix at the current configuration, replacing the default compile-time approximation.
14-
This improves solver quality for models with anisotropic inertias or complex kinematic coupling. See
15-
:ref:`Exact diagonal <soExactDiag>` for details.
16-
- The pseudo-random constraint visitation order in the :ref:`PGS solver<soAlgorithms>`, introduced in the previous
17-
release, now uses a fixed seed. The previous implementation seeded with ``mjData.time``, which introduced subtle yet
18-
undesirable time dependence.
19-
- Flexes are now allowed to sleep, with the exception of completely passive (constraint-free) flexes.
20-
- Added compiler timing diagnostics via the new :ref:`mjtCTimer` enum and the :ref:`mjs_getTimer` C API. After
21-
:ref:`mj_compile`, per-category timings (total, assets, mesh loading, convex hull, normals, inertia, BVH, octree,
22-
textures) are available via ``mjs_getTimer(spec)``. The :ref:`compile<saCompile>` sample prints a detailed timing
23-
breakdown when run without an output file.
24-
- Added :ref:`mjtBool` to represent boolean variables, replacing :ref:`mjtByte` across all boolean fields in
25-
:ref:`mjModel`, :ref:`mjData`, and public C API function signatures.
10+
1. Added ``mjData.efc_Y``, the whitened constraint Jacobian :math:`Y = J M^{-1/2}`, allocated in the arena when
11+
dual solvers (PGS or NoSlip) are used or when :ref:`diagexact<option-flag-diagexact>` is enabled.
12+
2. Added the :ref:`diagexact<option-flag-diagexact>` enable flag, which computes the exact diagonal of the
13+
constraint-space inertia matrix at the current configuration, replacing the default compile-time approximation.
14+
This improves solver quality for models with anisotropic inertias or complex kinematic coupling. See
15+
:ref:`Exact diagonal <soExactDiag>` for details.
16+
3. The pseudo-random constraint visitation order in the :ref:`PGS solver<soAlgorithms>`, introduced in the previous
17+
release, now uses a fixed seed. The previous implementation seeded with ``mjData.time``, which introduced subtle yet
18+
undesirable time dependence.
19+
4. Flexes are now allowed to sleep, with the exception of completely passive (constraint-free) flexes.
20+
5. Added compiler timing diagnostics via the new :ref:`mjtCTimer` enum and the :ref:`mjs_getTimer` C API. After
21+
:ref:`mj_compile`, per-category timings (total, assets, mesh loading, convex hull, normals, inertia, BVH, octree,
22+
textures) are available via ``mjs_getTimer(spec)``. The :ref:`compile<saCompile>` sample prints a detailed timing
23+
breakdown when run without an output file.
24+
6. Added :ref:`mjtBool` to represent boolean variables, replacing :ref:`mjtByte` across all boolean fields in
25+
:ref:`mjModel`, :ref:`mjData`, and public C API function signatures.
2626

2727
.. admonition:: Breaking API changes
2828
:class: attention
2929

30-
- The semantics of the contact ``margin`` and ``gap`` parameters have been redesigned for conceptual clarity and
31-
consistency with `Newton <https://github.com/newton-physics/newton>`__. See the new
32-
:ref:`margin and gap<coMarginGap>` documentation section for details.
30+
7. The semantics of the contact ``margin`` and ``gap`` parameters have been redesigned for conceptual clarity and
31+
consistency with `Newton <https://github.com/newton-physics/newton>`__. See the new
32+
:ref:`margin and gap<coMarginGap>` documentation section for details.
33+
34+
Previously, ``margin`` controlled the *detection threshold* (contacts exist when ``dist < margin``) and ``gap``
35+
was subtracted from it to produce the *force threshold* (forces generated when ``dist < margin - gap``). This was
36+
unintuitive: users expected ``margin`` to mean geometric inflation and ``gap`` to mean a spatial gap.
3337

34-
Previously, ``margin`` controlled the *detection threshold* (contacts exist when ``dist < margin``) and ``gap``
35-
was subtracted from it to produce the *force threshold* (forces generated when ``dist < margin - gap``). This was
36-
unintuitive: users expected ``margin`` to mean geometric inflation and ``gap`` to mean a spatial gap.
38+
Under the new semantics, ``margin`` is the geometric inflation of the geom surface and ``gap`` is an additional
39+
detection buffer beyond the inflated surface:
3740

38-
Under the new semantics, ``margin`` is the geometric inflation of the geom surface and ``gap`` is an additional
39-
detection buffer beyond the inflated surface:
41+
- **Detection**: contacts are created when ``dist < margin + gap``.
42+
- **Force generation**: constraint forces are applied when ``dist < margin``.
43+
- **Inactive contacts**: contacts with ``margin < dist ≤ margin + gap`` are included in ``mjData.contact`` but
44+
generate no force (``efc_address = -1``). This is useful for :ref:`adhesion<actuator-adhesion>` actuators and
45+
custom callbacks.
4046

41-
- **Detection**: contacts are created when ``dist < margin + gap``.
42-
- **Force generation**: constraint forces are applied when ``dist < margin``.
43-
- **Inactive contacts**: contacts with ``margin < dist ≤ margin + gap`` are included in ``mjData.contact`` but
44-
generate no force (``efc_address = -1``). This is useful for :ref:`adhesion<actuator-adhesion>` actuators and
45-
custom callbacks.
47+
With the default values ``margin = 0``, ``gap = 0``, the behavior is unchanged.
4648

47-
With the default values ``margin = 0``, ``gap = 0``, the behavior is unchanged.
49+
.. image:: images/modeling/margin_gap_light.svg
50+
:width: 80%
51+
:align: center
52+
:class: only-light
4853

49-
.. image:: images/modeling/margin_gap_light.svg
50-
:width: 80%
51-
:align: center
52-
:class: only-light
54+
.. image:: images/modeling/margin_gap_dark.svg
55+
:width: 80%
56+
:align: center
57+
:class: only-dark
5358

54-
.. image:: images/modeling/margin_gap_dark.svg
55-
:width: 80%
56-
:align: center
57-
:class: only-dark
59+
|
5860
59-
|
61+
**Migration:** Models that use the default ``gap="0"`` (the vast majority) require no changes. For models with
62+
``gap > 0``, apply the following transformation to preserve identical behavior:
6063

61-
**Migration:** Models that use the default ``gap="0"`` (the vast majority) require no changes. For models with
62-
``gap > 0``, apply the following transformation to preserve identical behavior:
64+
.. code-block::
6365
64-
.. code-block::
66+
margin_new = margin_old - gap_old
67+
gap_new = gap_old
6568
66-
margin_new = margin_old - gap_old
67-
gap_new = gap_old
69+
For example, a geom with the old attributes ``margin="0.1" gap="0.1"`` should be changed to
70+
``margin="0" gap="0.1"``.
6871

69-
For example, a geom with the old attributes ``margin="0.1" gap="0.1"`` should be changed to
70-
``margin="0" gap="0.1"``.
72+
Negative ``margin`` values are now permitted (corresponding to ``gap > margin`` under the old semantics). The
73+
constraint ``margin + gap >= 0`` should be maintained to ensure valid collision detection.
7174

72-
Negative ``margin`` values are now permitted (corresponding to ``gap > margin`` under the old semantics). The
73-
constraint ``margin + gap >= 0`` should be maintained to ensure valid collision detection.
75+
8. The :ref:`mjfCollision` functions now populate the :ref:`mjPreContact` struct instead of the :ref:`mjContact`
76+
struct. The :ref:`mjPreContact` only contains the necessary fields needed for the narrowphase collision detection.
7477

75-
- The :ref:`mjfCollision` functions now populate the :ref:`mjPreContact` struct instead of the :ref:`mjContact`
76-
struct. The :ref:`mjPreContact` only contains the necessary fields needed for the narrowphase collision detection.
78+
9. The header file ``mjtnum.h`` was renamed to
79+
`mjtype.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtype.h>` and now includes all
80+
enum type definitions.
7781

78-
- The header file ``mjtnum.h`` was renamed to
79-
`mjtype.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtype.h>` and now includes all
80-
enum type definitions.
82+
10. The :ref:`tactile<sensor-tactile>` sensor now reports raw depth instead of an estimated pressure.
8183

82-
- The :ref:`tactile<sensor-tactile>` sensor now reports raw depth instead of an estimated pressure.
84+
11. MJX: Removed the deprecated ``nconmax`` argument from ``mjx.make_data`` and ``mjx.put_data`` in favor of
85+
``naconmax``.
8386

84-
- MJX: Removed the deprecated ``nconmax`` argument from ``mjx.make_data`` and ``mjx.put_data`` in favor of
85-
``naconmax``.
87+
12. Maybe-breaking: Added `mjassert.h
88+
<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjassert.h>`__, a new header containing
89+
compile-time assertions that verify the sizes of MuJoCo's public types for ABI stability. This is a first step
90+
towards replacing ``int`` with strongly-typed enums in the public API. If these assertions fail on your compiler or
91+
platform, please report the issue on GitHub.
8692

87-
- Maybe-breaking: Added `mjassert.h
88-
<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjassert.h>`__, a new header containing
89-
compile-time assertions that verify the sizes of MuJoCo's public types for ABI stability. This is a first step
90-
towards replacing ``int`` with strongly-typed enums in the public API. If these assertions fail on your compiler or
91-
platform, please report the issue on GitHub.
9293

9394
Version 3.8.1 (May 11, 2026)
9495
----------------------------

0 commit comments

Comments
 (0)