3.0.0

New features

1. Added simulation on GPU and TPU via the new MuJoCo XLA (MJX) Python module. Python users can now natively run MuJoCo simulations at millions of steps per second on Google TPU or their own accelerator hardware.

   • MJX is designed to work with on-device reinforcement learning algorithms. This Colab notebook demonstrates using MJX along with reinforcement learning to train humanoid and quadruped robots to locomote:
   • The MJX API is compatible with MuJoCo but is missing some features in this release. See the outline of MJX feature parity for more details.

2. Added new signed distance field (SDF) collision primitive. SDFs can take any shape and are not constrained to be convex. Collision points are found by minimizing the maximum of the two colliding SDFs via gradient descent.

   • Added new SDF plugin for defining implicit geometries. The plugin must define methods computing an SDF and its gradient at query points. See the documentation for more details.

3. Added new low-level model element called flex, used to define deformable objects. These simplicial complexes can be of dimension 1, 2 or 3, corresponding to stretchable lines, triangles or tetrahedra. Two new MJCF elements are used to define flexes. The top-level deformable section contains the low-level flex definition. The flexcomp element, similar to composite is a convenience macro for creating deformables, and supports the GMSH tetrahedral file format.

   • Added shell passive force plugin, computing bending forces using a constant precomputed Hessian (cotangent operator).

     Note: This feature is still under development and subject to change. In particular, deformable object functionality is currently available both via deformable and composite, and both are modifiable by the first-party elasticity plugins. We expect some of this functionality to be unified in the future.

4. Added constraint island discovery with mj_island. Constraint islands are disjoint sets of constraints and degrees-of-freedom that do not interact. The only solver which currently supports islands is CG. Island discovery can be activated using a new enable flag. If island discovery is enabled, geoms, contacts and tendons will be colored according to the corresponding island, see video. Island discovery is currently disabled for models that have deformable objects (see previous item).

5. Added mjThreadPool and mjTask which allow for multi-threaded operations within the MuJoCo engine pipeline. If engine-internal threading is enabled, the following operations will be multi-threaded:

   • Island constraint resolution, if island discovery is enabled and the CG solver is selected. The 22 humanoids 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 testspeed utility, exposed with the npoolthread flag.

6. Added capability to initialize composite particles from OBJ files. Fixes #642 and #674.

General

Important

Breaking API changes

7. Removed the macros mjMARKSTACK and mjFREESTACK.

   Migration: These macros have been replaced by new functions mj_markStack and mj_freeStack. These functions manage the mjData stack in a fully encapsulated way (i.e., without introducing a local variable at the call site).

8. Renamed mj_stackAlloc to mj_stackAllocNum. The new function mj_stackAllocByte allocates an arbitrary number of bytes and has an additional argument for specifying the alignment of the returned pointer.

   Migration: The functionality for allocating mjtNum arrays is now available via mj_stackAllocNum.

9. Renamed the nstack field in mjModel and mjData to narena. Changed narena, pstack, and maxuse_stack to count number of bytes rather than number of mjtNums.

10. Changed mjData.solver, the array used to collect solver diagnostic information. This array of mjSolverStat structs is now of length mjNISLAND * mjNSOLVER, interpreted as as a matrix. Each row of length mjNSOLVER contains separate solver statistics for each constraint island. If the solver does not use islands, only row 0 is filled.

    • The new constant mjNISLAND was set to 20.
    • mjNSOLVER was reduced from 1000 to 200.
    • Added mjData.solver_nisland: the number of islands for which the solver ran.
    • Renamed mjData.solver_iter to solver_niter. Both this member and mjData.solver_nnz are now integer vectors of length mjNISLAND.

11. Removed mjOption.collision and the associated option/collision attribute.

    Migration:

    • For models which have <option collision="all"/>, delete the attribute.
    • For models which have <option collision="dynamic"/>, delete all pair elements.
    • For models which have <option collision="pair"/>, disable all dynamic collisions (determined via contype/conaffinity) by first deleting all contype and conaffinity attributes in the model and then setting them globally to 0 using
      <default> <geom contype="0" conaffinity="0"/> </default>.

12. Removed the rope and cloth composite objects.

    Migration: Users should use the cable and shell elasticity plugins.

13. Added mjData.eq_active user input variable, for enabling/disabling the state of equality constraints. Renamed mjModel.eq_active to mjModel.eq_active0, which now has the semantic of "initial value of mjData.eq_active". Fixes #876.

    Migration: Replace uses of mjModel.eq_active with mjData.eq_active.

14. Changed the default of autolimits from "false" to "true". This is a minor breaking change. The potential breakage applies to models which have elements with "range" defined and "limited" not set. Such models cannot be loaded since version 2.2.2 (July 2022).

15. Added a new dyntype, filterexact, which updates first-order filter states with the exact formula rather than with Euler integration.

16. Added an actuator attribute, actearly, which uses semi-implicit integration for actuator forces: using the next step's actuator state to compute the current actuator forces.

17. Renamed actuatorforcerange and actuatorforcelimited, introduced in the previous version to actuatorfrcrange and actuatorfrclimited, respectively.

18. Added the flag eulerdamp, which disables implicit integration of joint damping in the Euler integrator. See the Numerical Integration section for more details.

19. Added the flag invdiscrete, which enables discrete-time inverse dynamics for all integrators other than RK4. See the flag documentation for more details.

20. Added ls_iterations and ls_tolerance options for adjusting linesearch stopping criteria in CG and Newton solvers. These can be useful for performance tuning.

21. Added mesh_pos and mesh_quat fields to mjModel to store the normalizing transformation applied to mesh assets. Fixes #409.

22. Added camera resolution attribute and camprojection sensor. If camera resolution is set to positive values, the camera projection sensor will report the location of a target site, projected onto the camera image, in pixel coordinates.

23. Added camera calibration attributes:

    • The new attributes are resolution, focal, focalpixel, principal, principalpixel and sensorsize.
    • Visualize the calibrated frustum using the mjVIS_CAMERA visualization flag when these attributes are specified. See the following example model.
    • Note that these attributes only take effect for offline rendering and do not affect interactive visualisation.

24. Implemented reversed Z rendering for better depth precision. An enum mjtDepthMap was added with values mjDEPTH_ZERONEAR and mjDEPTH_ZEROFAR, which can be used to set the new readDepthMap attribute in mjrContext to control how the depth returned by mjr_readPixels is mapped from znear to zfar. Contribution #978 by @aftersomemath.

25. Deleted the code sample testxml. The functionality provided by this utility is implemented in the WriteReadCompare test.

26. Deleted the code sample derivative. Functionality provided by mjd_transitionFD.

Python bindings

27. Fixed #870 where calling update_scene with an invalid camera name used the default camera.
28. Added user_scn to the passive viewer handle, which allows users to add custom visualization geoms (#1023).
29. 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

30. Added state history mechanism to simulate and the managed Python viewer. State history can be viewed by scrubbing the History slider and (more precisely) with the left and right arrow keys.

31. The LOADING... label is now shown correctly. Contribution #1070 by @aftersomemath.

Documentation

32. Added detailed documentation of fluid force modeling, and an illustrative example model showing tumbling cards using the ellipsoid-based fluid model.

Bug fixes

33. Fixed a bug that was causing geom margin to be ignored during the construction of midphase collision trees.

34. Fixed a bug that was generating incorrect values in efc_diagApprox for weld equality constraints.