Multi-Joint dynamics with Contact. A general purpose physics simulator.
mjVFS
is used. Users are advised to skip to version 2.3.5 instead.visual-global
flag ellipsoidinertia
to visualize equivalent body inertias with ellipsoids instead of the default boxes.mjData
.introspect
module.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 or segmentation fault.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 documentation for details.viewer.launch_repl
function has been removed since its functionality is superceded by launch_passive
.introspect
metadata.mj_copyData
, which can considerably slow down the copying operation (#568).shellinertia
ignore exactmeshinertia
, which is only used for legacy volume computations (#759).Improvements to implicit integration:
implicitfast
was added. It is similar to the existing implicit integrator, but skips the derivatives of Coriolis and centripetal forces. See the numerical integration 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 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.
timing | Euler | implicitfast | implicit (new) | implicit (old) |
---|---|---|---|---|
one step (ms) | 0.5 | 0.53 | 0.77 | 5.0 |
steps/second | 2000 | 1900 | 1300 | 200 |
mjd_transitionFD
function no longer triggers sensor calculation unless explicitly requested.inteval
attribute to interval
in the mjLROpt struct.mjtNum
s, now only requires ~6000. Very large models can now load and run with the CG solver.mju_error
and mju_warning
to be variadic functions (support for printf-like arguments). The functions mju_error_i
, mju_error_s
, mju_warning_i
, and mju_warning_s
are now deprecated.mju_sqrMatTDSparse
function that doesn't require dense memory allocation.mj_stackAllocInt
to get correct size for allocating ints on mjData stack. Reducing stack memory usage by 10% - 15%.viewer.launch_repl
. The launch_repl
function now provides seamless continuation of an IPython interactive shell session, and is no longer considered experimental feature.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 viewer documentation.)mjpython
launcher for macOS, which is required for viewer.launch_passive
to function there.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.mjVisual
and mjvPerturb
structs.Implemented a workaround for broken VSync on macOS so that the frame rate is correctly capped when the Vertical Sync toggle is enabled.
Added optional labels to contact visualization, indicating which two geoms are contacting (names if defined, ids otherwise). This can be useful in cluttered scenes.
mj_name2id
is now implemented using a hash function instead of a linear search for better performance.mj_printData
output now contains contacting geom names.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.fitaabb
.launch_repl
functionality in the Python viewer has been fixed.time
correctly in mjd_transitionFD
, to support time-dependent user code.user
type sensors are present.nsensordata
callback is encountered during model compilation.TM_END
) mj_fwdConstraint
returns early.mj_deleteFileVFS
.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.capabilities
field in mjpPlugin
is renamed capabilityflags
to more clearly indicate that this is a bit field.simulate
GUI is now available through the mujoco
Python package as mujoco.viewer
. See documentation for details. (Contribution by Levi Burner.)Renderer
class from the MuJoCo tutorial Colab is now available directly in the native Python bindings.The tendon springlength
attribute can now take two values. Given two non-decreasing values, springlength
specifies a 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 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 example model. This is a minor breaking API change. mjModel.tendon_lengthspring
now has size ntendon x 2
rather than ntendon x 1
.
Removed the requirement that stateless actuators come before stateful actuators.
Added mju_fill, mju_symmetrize and mju_eye utility functions.
Added gravcomp
attribute to body implementing gravity compensation and buoyancy. See balloons.xml example model.
Renamed the cable
plugin library to elasticity
.
Added actdim
attribute to general actuators. Values greater than 1 are only allowed for user
, as native activation dynamics are all scalar. Added example test implementing 2nd-order activation dynamics to engine_forward_test.cc.
Improved particle composite type, which now permits a user-specified geometry and multiple joints. See the two new examples: particle_free.xml and particle_free2d.xml.
Performance improvements for non-AVX configurations:
mj_solveLD
using restrict. See engine_core_smooth_benchmark_test.mju_dotSparse
using manual loop unroll. See engine_util_sparse_benchmark_test.Added new solid
passive force plugin.
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 user no longer require objtype
, objname
and needstage
. If unspecified, the objtype is now mjOBJ_UNKNOWN. user
sensors datatype
default is now real
, needstage
default is now acc
.
Added support for capsules in URDF import.
On macOS, issue an informative error message when run under Rosetta 2 translation on an Apple Silicon machine. Pre-built MuJoCo binaries make use of AVX instructions on x86-64 machines, which is not supported by Rosetta 2. (Before this version, users only get a cryptic "Illegal instruction" message.)
mj_addFileVFS
that was causing the file path to be ignored (introduced in 2.1.4).simulate
application searches for plugins from plugin
to mujoco_plugin
.2.3.1.post1
(6 December 2022)mujoco.viewer
that were causing errors in Python 3.7 and 3.8.The contact
array and arrays prefixed with efc_
in mjData
were moved out of the buffer
into a new arena
memory space. These arrays are no longer allocated with fixed sizes when mjData
is created. Instead, the exact memory requirement is determined during each call to mj_forward
(specifically, in mj_collision
and mj_makeConstraint
) and the arrays are allocated from the arena
space. The stack
now also shares its available memory with arena
. This change reduces the memory footprint of mjData
in models that do not use the PGS solver, and will allow for significant memory reductions in the future. See the Memory allocation section for details.
Added colab notebook tutorial showing how to balance the humanoid on one leg with a Linear Quadratic Regulator. The
notebook uses MuJoCo's native Python bindings, and includes a draft Renderer
class, for easy rendering in Python. Try it yourself:
Updates to humanoid model:
Added mju_boxQP
and allocation function mju_boxQPmalloc
for solving the box-constrained Quadratic Program: $x^* = \text{argmin} ; \tfrac{1}{2} x^T H x + x^T g \quad \text{s.t.} \quad l \le x \le u$ The algorithm, introduced in Tassa et al. 2014, converges after 2-5 Cholesky factorisations, independent of problem size.
Added mju_mulVecMatVec
to multiply a square matrix $M$ with vectors $x$ and $y$ on both sides. The function returns $x^TMy$.
Added new plugin API. Plugins allow developers to extend MuJoCo's capability without modifying core engine code. The plugin mechanism is intended to replace the existing callbacks, though these will remain for the time being as an option for simple use cases and backward compatibility. The new mechanism manages stateful plugins and supports multiple plugins from different sources, allowing MuJoCo extensions to be introduced in a modular fashion, rather than as global overrides. Note the new mechanism is currently undocumented except in code, as we test it internally. If you are interested in using the plugin mechanism, please get in touch first.
Added assetdir
compiler option, which sets the values of both meshdir
and texturedir
. Values in the latter attributes take precedence over assetdir
.
Added realtime
option to visual
for starting a simulation at a slower speed.
Added new cable
composite type:
initial
parameter specifies the joint at the starting boundary: free
, ball
, or none
.B_left
and B_right
.vertex
.Added new cable
passive force plugin:
twist
and bend
.flat
.Added id
and name
properties to named accessor objects. These provide more Pythonic API access to mj_name2id
and mj_id2name
respectively.
The length of MjData.contact
is now ncon
rather than nconmax
, allowing it to be straightforwardly used as
an iterator without needing to check ncon
.
Fix a memory leak when a Python callable is installed as callback (#527).
Added adhesion actuators mimicking vacuum grippers and adhesive biomechanical appendages.
Added related example model and video.
Added mj_jacSubtreeCom
for computing the translational Jacobian of the center-of-mass of a subtree.
Added torquescale
and anchor
attributes to weld
constraints. torquescale
sets the torque-to-force ratio exerted by the constraint, anchor
sets the point at which the weld wrench is applied. See weld for more details.
Increased mjNEQDATA
, the row length of equality constraint parameters in mjModel.eq_data
, from 7 to 11.
Added visualisation of anchor points for both connect
and weld
constraints (activated by the 'N' key in simulate
).
Added weld.xml showing different uses of new weld attributes.
Cartesian 6D end-effector control is now possible by adding a reference site to actuators with site
transmission. See description of new refsite
attribute in the actuator documentation and refsite.xml example model. Video
Added autolimits
compiler option. If true
, joint and tendon limited
attributes and actuator ctrllimited
, forcelimited
and actlimited
attributes will automatically be set to true
if the corresponding range is defined and false
otherwise.
If autolimits="false"
(the default) models where a range
attribute is specified without the limited
attribute will fail to compile. A future release will change the default of autolimits
to true
, and this compilation error allows users to catch this future change of behavior.
This is a breaking change. In models where a range was defined but limited
was unspecified, explicitly set limited to false
or remove the range to maintain the current behavior of your model.
Added moment of inertia computation for all well-formed meshes. This option is activated by setting the compiler flag exactmeshinertia
to true
(defaults to false
). This default may change in the future.
Added parameter shellinertia
to geom
, for locating the inferred inertia on the boundary (shell). Currently only meshes are supported.
For meshes from which volumetric inertia is inferred, raise error if the orientation of mesh faces is not consistent. If this occurs, fix the mesh in e.g., MeshLab or Blender.
Added catenary visualisation for hanging tendons. The model seen in the video can be found here.
Added azimuth
and elevation
attributes to visual/global, defining the initial orientation of the free camera at model load time.
Added mjv_defaultFreeCamera
which sets the default free camera, respecting the above attributes.
simulate
now supports taking a screenshot via a button in the File section or via Ctrl-P
.
Improvements to time synchronisation in simulate
, in particular report actual real-time factor if different from requested factor (if e.g., the timestep is so small that simulation cannot keep up with real-time).
Added a disable flag for sensors.
mju_mulQuat
and mju_mulQuatAxis
support in place computation. For example mju_mulQuat(a, a, b);
sets the quaternion a
equal to the product of a
and b
.
Added sensor matrices to mjd_transitionFD
(note this is an API change).
distance
constraints.intvelocity
defaults parsing.mjd_transitionFD
to compute efficient finite difference approximations of the state-transition and control-transition matrices, see here for more details.ctrl
attribute to keyframes.clock
sensor which measures time.free
and ball
joints and for actuators with site
transmission.<intvelocity>
actuator shortcut for "integrated velocity" actuators, documented here.<damper>
actuator shortcut for active-damping actuators, documented here.mju_rotVecMat
and mju_rotVecMatT
now support in-place multiplication.mjData.ctrl
values are no longer clamped in-place, remain untouched by the engine.mjModel.buffer
and mjData.buffer
that do not lie within an array, and for MSAN to detect reads from uninitialised fields in mjData
following mj_resetData
.model/
.quat
and an alternative specifier e.g., <geom ... quat=".1 .2 .3 .4" euler="10 20 30">
, would lead to the quat
being ignored and only euler
being used. After this change a parse error will be thrown.<geom size="1/2 3 4">
would have been parsed as size="1 0 0"
and no error would have been thrown. Now throws an error.NaN
via XML like <geom size="1 NaN 4">
, while allowed for debugging purposes, will now print a warning.mj_loadModel
.mjModel
buffer sizes.mjWARN_BADCTRL
.mujoco.framework
embedded in MuJoCo.app
can be used to build applications externally.MuJoCo is now fully open-source software. Newly available top level directories are:
src/
: All source files. Subdirectories correspond to the modules described in the Programming chapter introduction:
src/engine/
: Core engine.src/xml/
: XML parser.src/user/
: Model compiler.src/visualize/
: Abstract visualizer.src/ui/
: UI framework.test/
: Tests and corresponding asset files.dist/
: Files related to packaging and binary distribution.Added contributor's guide and style guide.
Added analytic derivatives of smooth (unconstrained) dynamics forces, with respect to velocities:
Added implicit
integrator. Using the analytic derivatives above, a new implicit-in-velocity integrator was added. This integrator lies between the Euler and Runge Kutta integrators in terms of both stability and computational cost. It is most useful for models which use fluid drag (e.g. for flying or swimming) and for models which use velocity actuators. For more details, see the Numerical Integration section.
Added actlimited
and actrange
attributes to general actuators, for clamping actuator internal states (activations). This clamping is useful for integrated-velocity actuators, see the Activation clamping section for details.
mjData
fields qfrc_unc
(unconstrained forces) and qacc_unc
(unconstrained accelerations) were renamed qfrc_smooth
and qacc_smooth
, respectively. While "unconstrained" is precise, "smooth" is more intelligible than "unc".
Public headers have been moved from /include
to /include/mujoco/
, in line with the directory layout common in other open source projects. Developers are encouraged to include MuJoCo public headers in their own codebase via #include <mujoco/filename.h>
.
The default shadow resolution specified by the shadowsize attribute was increased from 1024 to 4096.
Saved XMLs now use 2-space indents.
Antialiasing was disabled for segmentation rendering. Before this change, if the offsamples attribute was greater than 0 (the default value is 4), pixels that overlapped with multiple geoms would receive averaged segmentation IDs, leading to incorrect or non-existent IDs. After this change offsamples
is ignored during segmentation rendering.
The value of the enable flag for the experimental multiCCD feature was made sequential with other enable flags. Sequentiality is assumed in the simulate
UI and elsewhere.
Fix issue of duplicated meshes when saving models with OBJ meshes using mj_saveLastXML
.
Update 1 (27 May 2022): Replaced Linux tarball to fix RPATH on the sample binaries. No change in functionality.
GLAD initialization logic on Linux now calls dlopen
to load a GL platform dynamic library if a *GetProcAddress
function is not already present in the process' global symbol table. In particular, processes that use GLFW to set up a rendering context that are not explicitly linked against libGLX.so
(this applies to the Python interpreter, for example) will now work correctly rather than fail with a gladLoadGL
error when mjr_makeContext
is called. Fixes https://github.com/deepmind/dm_control/issues/283.
In the Python bindings, named indexers for scalar fields (e.g. the ctrl
field for actuators) now return a NumPy array of shape (1,)
rather than ()
. This allows values to be assigned to these fields more straightforwardly. Fixes https://github.com/deepmind/mujoco/issues/238.
MuJoCo now uses GLAD to manage OpenGL API access instead of GLEW. On Linux, there is no longer a need to link against different GL wrangling libraries depending on whether GLX, EGL, or OSMesa is being used. Instead, users can simply use GLX, EGL, or OSMesa to create a GL context and mjr_makeContext
will detect which one is being used.
Add visualisation for contact frames. This is useful when writing or modifying collision functions, when the actual direction of the x and y axes of a contact can be important.
_nogl
dynamic library is no longer provided on Linux and Windows. The switch to GLAD allows us to resolve OpenGL symbols when mjr_makeContext
is called rather than when the library is loaded. As a result, the MuJoCo library no longer has an explicit dynamic dependency on OpenGL, and can be used on system where OpenGL is not present.Fix a bug in simulate where pressing '[' or ']' when a model is not loaded causes a crash.
Contact frame visualisation is added to the Simulate GUI.
Rename "set key", "reset to key" to "save key" and "load key", respectively.
Change bindings of F6 and F7 from the not very useful "vertical sync" and "busy wait" to the more useful cycling of frames and labels.
mj_resetData
now zeroes out the solver_nnz
field.
Remove a special branch in mju_quat2mat
for unit quaternions. Previously, mju_quat2mat
skipped all computation if the real part of the quaternion equals 1.0. For very small angles (e.g. when finite differencing), the cosine can evaluate to exactly 1.0 at double precision while the sine is still nonzero.