MuJoCo 2.0 was released on October 1, 2018. The list of changes is below.
- MuJoCo (formerly MuJoCo Pro)
MuJoCo is a dynamic library with C/C++ API. It is intended for researchers and developers with computational background. It includes an XML parser, model compiler, simulator, and interactive OpenGL visualizer.
Commercial license. Compatible with 64-bit Windows, Linux and macOS.
MuJoCo requires an activation key which is provided to licensed users. See License page.
Download mujoco200 win64
- MuJoCo HAPTIX
MuJoCo HAPTIX is an end-user product with full-featured GUI. It has a socket-based API exposing a subset of the functions and data structures available in the MuJoCo library. MuJoCo HAPTIX can be used as a generic simulator, or as a simulator customized for the needs of the DARPA Hand Proprioception & Touch Interfaces (HAPTIX) program. To achieve the latter goal, it integrates real-time motion capture which is used to move the base of a simulated prosthetic hand as well as track the user's head and implement a stereoscopic virtual environment.
Free license. Compatible with 64-bit Windows only.
- MuJoCo Plugin and Unity Integration
MuJoCo Plugin and Unity Integration is a new product, allowing MuJoCo physics to be combined with Unity rendering. Users can import MuJoCo models in the Unity Editor, adjust their visual properties, and render them under the control of a MuJoCo simulation providing model poses over a socket. The package includes developer tools as well as a Unity demo with multiple MuJoCo simulations.
Free license. Compatible with 64-bit Windows, Linux and MacOS. A separate MuJoCo license is needed to take full advantage of this product.
Download mjuni155 win64
- MuJoCo VR
MuJoCo VR is a standalone simulator allowing the user to interact with MuJoCo models in VR. Only the HTC Vive is currently supported. The code used to create this simulator is available as a code sample in the online MuJoCo documentation, and can be compiled for Windows, Linux and OSX. The precompiled executable available here is Windows only.
Free license. Compatible with 64-bit Windows only.
Download mjvr140 beta1
List of changes and additions in each software release
Clink on a link in the table below to scroll to the change list for the selected software version.
|Software version||Release date|
|MuJoCo Pro 1.5||4/23/2017|
|MuJoCo Pro 1.4||8/22/2016|
|MuJoCo Pro 1.31||4/23/2016|
|MuJoCo Pro 1.3||4/6/2016|
|MuJoCo Pro 1.22||11/26/2015|
|MuJoCo Pro 1.21||9/21/2015|
|MuJoCo Pro 1.2||9/8/2015|
|MuJoCo Pro 1.1||8/24/2015|
|MuJoCo Pro 1.0||7/20/2015|
MuJoCo 2.0, released on 10/1/2018
An earlier version of this release was available from 9/28 to 10/1. If you downloaded it in that period, please download again; there are some minor fixes in the final version.
Main additions. The focus of this release is increased usability: we have added several user-facing components that make it easier to utilize MuJoCo's core capabilities. The main additions are summarized here, followed by the detailed changelist.
- A native user interface (UI) was added. It is rendered in OpenGL. The code sample simulate.cpp is now a full-blown UI application.
- Systematic support for muscle modeling was added. This includes automatic computation of muscle length ranges (via multi-threaded simulation inside the compiler), models of muscle activation dynamics and force-length-velocity curves derived from biomechanics, and interactive rendering of control signals.
- Support for soft bodies was added - including rope, cloth and sponge-like 3D objects. Soft bodies are modeled as collections of standard MuJoCo bodies and soft constraints. These (large) collections are generated automatically by the model compiler. The generator is configured on a high level from the XML.
- Skinned meshes were added - used for soft body rendering as well as more realistic animated characters. Explicit texture coordinates can now be applied to both skinned meshes and static meshes. This opens up the possibility to import gaming assets automatically (although we do not currently provide such importers).
- Bodies without joints can now be optimized away by the compiler, by fusing them with their parent body. This produces models that are physically equivalent but faster to simulate. Such optimization is particularly useful when importing URDF models - which often contain many dummy bodies that are not needed in MuJoCo.
- A MATLAB wrapper for MuJoCo was added as a code sample. It has basic functionality but the code is quite readable and easy to extend. Given that MATLAB does not allow pointers, this is not intended to replace Python wrappers used for Reinforcement Learning. Rather, it is intended for data analysis and visualization as well as prototyping of manually-designed controllers.
- Physics simulation is now faster, up to 40% for large models. This is due to extensive code optimizations and exploitation of special cases where some computations can be skipped. The physics are also more stable and accurate thanks to improved computation of contact normals.
Modeling and XML. The new software components require new XML elements and attributes. Some existing elements are also extended.
- Soft bodies are generated using the new XML element composite. It has multiple attributes and sub-elements used to configure the automatic generator.
- A new actuator shortcut was added: muscle. It has attributes needed to adjust the properties of the new muscle model. As always, the same effect can be achieved using a general actuator and setting the attributes dynamics, gain and bias to the new type "muscle".
- A new tendon wrapping mode was added: tendons can be required to pass through a sphere or a cylinder instead of going around it. This is enabled by simply placing the sidesite within the sphere/cylinder wrapping object.
- Feasible actuator lengths (needed for muscle modeling) can now be computed automatically by the compiler. This is controlled by the new XML element lengthrange and its attributes. Alternatively, all actuators now have attribute lengthrange which can be used to set this parameter directly if known.
- Because lengthrange computations rely on simulation which can be slow, the compiler now has the option to run in multi-threaded mode. This is controlled by the new compiler attribute usethread.
- The compiler can now optimize models with static bodies (i.e. bodies without joints) by fusing these bodies with their parents. This is controlled with the new compiler attribute fusestatic, and is particularly useful when importing URDFs which contain many dummy bodies.
- Meshes can now be loaded from custom binary files (in addition to STL files), as well as entered directly in the XML without a file. The latter is done with the new mesh attributes vertex, normal, face, texcoord.
- Mesh data can now be translated and rotated using the new attributes refpos and refquat. Auto-generation of face normals can now be adjusted with the new attribute smoothnormal.
- Explicit texture coordinates can now be defined for meshes. These can be loaded from custom binary files, or entered directly in the XML with the new attribute texcoord.
- Textures can now be loaded from custom binary files (in addition to PNG files). The images can be flipped using the new attributes hflip, vflip.
- Skinned meshes can now be modeled. They are loaded from custom binary files or entered directly in the XML, similar to meshes. There are many new options here.
- The constraint impedance (solimp) now has 5 parameters instead of 3, yet it is backward compatible. The last 2 parameters adjust the skewness and offset of the function, providing better control over remote contact forces. The defaults correspond to the MuJoCo 1.50 impedance function.
- The constraint reference (solref) can now have negative values, in which case automatic scaling is bypassed and solref specifies constraint stiffness and damping directly. This can be used to model perfect restitution - which is not possible when using automatic scaling with positive values.
- Planes and height fields can now be attached to static children of the world body, and in particular to mocap bodies that can move around at runtime.
- Plane size can now be 0, corresponding to infinite planes; see visualization changes below. Infinite planes connect seamlessly with skyboxes using a new haze rendering feature.
- A number of elements and attributes have been added under visual: haze, contactgap, rangefinder, haze, actuatornegative, actuatorpositive, actuatortendon. Numarrows has been removed since it was not actually used.
- The from-to mechanism for specifying geom size and position has been extended to box and ellipsoid (previously it was only applicable to capsule and cylinder). Sites can now also be defined using from-to.
- Site size and tendon width now have positive defaults, no longer resulting in compiler errors when omitted.
- Tendons now have a springlength attribute specifying the reference length for spring forces (when tendon stiffness is set).
- Joints, tendons and actuators now have groups, similar to existing geom and site groups. These groups are used for visualization, and also for constructing UIs with sliders.
- Keyframes, contact pairs and contact exclude statements can now be named, like all other model elements.
- Unused assets are no longer removed by the compiler - in case the user needs them for custom computations.
- Massless dynamic bodies are now allowed if they have static children with mass. Note however that a singular inertia matrix triggers an engine warning which is now considered a compiler error - so the general rule regarding mass is, do whatever you want as long as the resulting inertia matrix is full-rank.
- Geoms have a new attribute: priority. It affects how the contact properties condim, friction, solref and solimp are computed from the corresponding properties of the two colliding geoms. It also interacts with the existing solmix attribute and contact overrides.
- Weld equality constraints have a new attribute: relpose. It allows the user to specify the relative pose (i.e. translation and rotation) in which the two bodies are welded. Previous this pose always corresponded to the model reference configuration qpos0.
- The XML parser now reads any comment immediately after the top-level <mujoco> element, and when the model is saved as XML this comment is also saved. In this way headers (with comments or license information) propagate to saved models.
Abstract visualization. The visualizer has been extended to accommodate the new model elements, and provide more user control over what is being visualized at runtime.
- Actuator rendering now includes tendon actuators in addition to joint actuators. The control signal is now used to interpolate the color of the actuator object; see new attributes actuatornegative, actuatorpositive. Actuated tendons are rendered as being thicker than the underlying tendons; the scaling is set by the new attribute actuatortendon.
- Tendon visualization, as well as the new haze and skin visualization can now be enabled and disabled with new visualization flags. Furthermore joints, tendons and actuators now have groups, allowing finer control over what is being visualized.
- Model cameras in targeting mode now remain horizontal.
- The default znear is now set to 0.01. This avoids clipping of nearby objects in some scenes.
- Contacts that are found by the collision detector but excluded from physics computations by the gap mechanism are now visualized, using a different color specified by contactgap.
- Rangefinder sensors are now visualized, using the new mjvGeom type mjGEOM_LINE. This is rendered as an OpenGL line and does not cast shadows (like a laser beam).
- Ray collisions no longer "see" planes from the back. This makes it possible to select objects enclosed in volumes made of inward-facing planes. Note that rays see the newly added skinned meshes during mouse selection, but not when simulating rangefinder sensors. This is because skinned mesh updates can be slow, and so we update them when a frame is rendered and not at every physics step.
- There is a new inertial box visualization option where the box is scaled so that its volume equals mass * 1000 (where 1000 is the density of water). To see the effect, enable this feature in addition to regular inertia visualization.
- Multiple improvements were introduced in 2D figure rendering. They are controlled via new fields in the data structures passed to mjvFigure.
OpenGL rendering. There are several extension to the renderer, most notably those related to the new UI and skinned meshes.
- A native UI can now be rendered using OpenGL. This is a new module and is not part of the renderer (and has a new include file mjui.h) Nevertheless the renderer had to be extended to accommodate the UI, in particular we added support for auxiliary buffers; see new functions mjr_addAux, mjr_setAux, mjr_blitAux. These buffers are generally available for user applications as well.
- Until this release, all meshes were static and could be uploaded to the GPU as pre-compiled display lists. Skinned meshes change at every frame, which is why we have added VBO support. The vertices and normals are computed every time the scene is updated (see API changes below) and streamed to the GPU.
- If explicit texture coordinates are provided for regular or skinned meshes, they replace the default auto-generation mechanism.
- There is now additive transparency mode in addition to regular transparency. This is useful for rendering movement trajectories (by combining the model poses over time in the same scene). The corresponding rendering flag is mjRND_ADDITIVE.
- There is a new rendering mode (mjRND_SEGMENT and mjRND_IDCOLOR) where lighting is disabled and each geom is rendered with a unique solid color. This can be used in computer vision applications for segmentation. The color could be either automatically generated and bright, or correspond to the bit-wise representation of the geom id (in which case it is dark and hard to see but is more useful for programmatic access).
- Additional font sizes were generated. We how have 50, 100, 150, ... 300. We switched to the Nokora font. The big font was reduced from 24 to 20 point.
- We now support rendering of planes that are infinite in one or both directions. To define a direction as infinite, set the corresponding geom size to 0. The renderer then generates a plane large enough to extend outside the zfar radius of the camera, and moves the plane automatically so that it always covers the visible range. There is also a new haze mechanism which connects an infinite plane with a skybox seamlessly.
- mjMAXPLANEGRID was increased to 200, to allow better illumination of large planes. mjMAXTEXTURE was added to mjrender.h and set to 1000. Previously this limit was baked into the code and set to 100.
Physics simulation. The core physics has improvements related to speed and stability.
- The convex collision detector (libccd) can sometimes return contact normals that are not actually normal to the surface. We now re-compute these normals analytically whenever a smooth geom primitive is involved in the collision. This resolves several problems with contact inaccuracies that have been reported with previous versions.
- We have introduced a number of optimizations making MuJoCo faster with large models. These include fully-sparse Jacobian construction, as well as recognizing special cases where some computations can be skipped. The latter relies on the new notion of "simple body" which is a body guaranteed to have diagonal inertia matrix. Such bodies are flagged by the compiler (in the new field mjModel.body_simple) and exploited by the simulator.
- The sparse algebra functions used internally were optimized, using AVX intrinsics and also recognizing and exploiting super-nodes. These functions are no longer exposed in mujoco.h because they rely on undocumented data formats.
- The function mj_rnePostConstraint is no longer called by default. Instead, it is called only when the model contains force-related sensors which need the results of this function. The user can still call it directly in order to compute the mjData fields cacc, cfrc_ext, cfrc_int if desired.
- Similarly, the function mj_subtreeVel which computes the mjData fields subtree_linvel and subtree_angmom is only called if a sensor defined in the model needs these fields. This function is now exposed in mujoco.h and the user can call it directly if desired.
- The flag "skipsensorenergy" in mj_forwardSkip and mj_inverseSkip waw renamed to "skipsensor". As the new name suggests, this flag no longer affects energy computations. Instead, energy is computed only when enabled with the mjENBL_ENERGY flag.
- Mesh-plane collisions can now generate up to 3 contact points (previously they generated at most one point). This makes meshes resting on planes more stable, and is particularly useful for meshes with large faces - for example prisms, which are easily created with the new mechanism for specifying mesh data directly in the XML.
- When solref is set to negative values, these values are interpreted as constraint stiffness and damping, and automatic scaling is bypassed. In this way one can specify perfect restitution with no damping for example.
- Solimp now has 5 parameters, allowing better control over the impedance function. The impedance function itself is used in the same way as before, but its shape is now more flexible.
- Sparse dot-products now use AVX intrinsics, speeding up simulation of larger models.
- mj_solveM is now faster with a batch of vectors.
The computation of diagApprox is modified so that the following identity holds in all contact dimensions:
R = (1-imp)/imp * diagApprox
API changes. The biggest API change is the new UI, although some other aspects of the API are also extended.
- The new UI offers a unique trade-off between ease of programming and feature completeness. See new UI section in the documentation, as well as simulate.cpp code sample which is now UI-based.
- A number of functions were added or exposed: mju_sum, mju_sumabs, mjv_makeLights, mjr_restoreBuffer, mjr_changeFont, mjr_findRect, mju_subQuat, mj_mulM2, mju_muscleGain, mju_muscleBias, mju_muscleDynamics, mjv_defaultScene, mju_strncpy, mj_loadXMLnotest.
- The callback mjcb_contactfilter was added; it allows user control over contact filtering.
- mjvScene now has buffers for skinned mesh data updated at each frame. This means that mjvScene is now model-dependent, and needs to be reconstructed at each model load, similar to mjrContext. The function mjv_makeScene is modified to do that, and it expects mjv_defaultScene to be called once at initialization.
- The object selection mechanism is extended to accommodate skinned meshes - which are not in one-to-one correspondence with bodies. The function mjv_select now returns the selected body, geom and skin if applicable. The structure mjvPert has a new skinselect field.
- The field efc_KBIP was added to mjData. It contains the output of the solref and solimp computations, and is used by the constraints solver.
- The field actuator_invweight0 was replaced with actuator_acc0 in mjData. The new field is more useful for muscle force scaling. The field actuator_lengthrange which was previously unused is now set (either by the user or compiler) and is needed for muscle modeling.
- The field qacc_warmstart was moved to the beginning of mjData. This field is strictly speaking another state variable, and should be considered as such when warmstart is enabled.
- The constants mjNDYN, mjNGAIN, mjNBIAS were increased to 10, to allow more elaborate actuator modeling. The muscle model uses 9 out of the 10 allowed parameters for gain and bias.
- mjNGROUP was increased to 6, to allow better control over visualization for large models. Note that tendons, actuators and joints now have groups, in addition to geoms and sites.
- The new solimp format can model a continuum of impedance functions. Previously we had discrete modes (constant, linear, sigmoid) corresponding to isolated points in that continuum. These discrete modes are no longer used, and so the corresponding types and callbacks are removed: mjIMP_XXX, mjREF_XXX, mjcb_sol_imp, mjcb_sol_ref, mjfSolImp, mjfSolRef. The fields impedance and reference of mjOption are also removed.
- If model compilation succeeds but generates a warning, the function mj_loadXML now returns the compiled model and also returns the warning in the error buffer. If there is no warning, it sets error = 0.
Bug fixes. A number of bugs have been fixed, including bugs that affected the physics.
- Weld constraints between dynamics bodies used to act in non-physical ways due to an error in our derivation. This is now fixed.
- Ball joint Jacobians were computed incorrectly, now fixed.
- Some equality constraints were ignored in situations where the number of constrained quantities exceeded the number of DOFs. Now fixed. As a result, the constraint Jacobian can now have zero rows - which makes little sense mathematically, but is harmless and removing it would require support for various partial constraints.
- The no-slip solver can occasionally generate singular A-matrices, which previously resulted in huge contact forces. The code now guards against this.
- The QCQP solver was written with the assumption of full-rank matrices but that assumption does not always hold. The code now uses mild regularization to guard against this.
- The singalurity check for the inertia matrix was ignoring a zero at coordinates (0,0). Now fixed.
- Tendon-cylinder wrapping had a bug causing geometric inaccuracies at large angles. Now fixed.
- Subtree mass used to have NaNs due to division by zero in some singular situations. Now fixed.
- body_subtreemass was computed internally in the compiler and not in the function mj_setConst. As a result, changing body masses at runtime and calling mj_setConst did not produce a consistent model as intended. This code is now moved to mj_setConst.
- There was a bug in the handling of the geomgroup parameter of mj_ray, now fixed.
- The function mjv_initGeom used to clear (objtype, objid, category, segid) which was a design bug. Now it no longer touches these fields.
- The pointer to VFS in mj_loadModel was made const in mujoco.h, now matching the headers used during build.
- solver_Nnnz in mjxmacro.h was renamed to solver_nnz, as it should be.
- Fog rendering was interacting with shadows in unexpected ways; now fixed.
- Errors generated by the qhull library are now intercepted, like other compiler errors. Previously such errors (although extremely rare) would cause the software to crash.
- Fixed rendering of convex hulls on macOS.
- Fixed OpenGL errors caused by small window sizes and minimized windows.
- Fixed OpenGL shadow issues caused by dense plane grids.
- Fixed indexing bug in derivative.cpp code sample, causing inaccuracies with quaterion joints.
- Fixed cfrc_int for the world body. Previously it was accumulating over time, which did not affect anything since cfrc_int for the world body is not used, but it was bad style.
- Explicit geom pairs with undefined contact parameters now inherit the properties of the two geoms, as they do at runtime. Previously they were set to the global defaults and the geom properties were ignored.
- Defining explicit geom pairs previously caused all other contacts between the same two bodies to be excluded (which was a design bug). This is now fixed.
- URDF element "dynamics" was not parsed previously, and therefore joint damping and friction in URDF models were ignored. This is now fixed.
Build changes. The build changed by platform are as follows.
- On macOS we now link against libc++ instead of libstdc++, because libc++ is standard and better maintained on that platform. We use clang/Apple LLVM 9.0.0 which is standard on macOS Sierra. The MuJoCo model compiler is now multi-threaded, so '-pthread' needs to be added when compiling and linking user code.
- On Linux we link against libstdc++ and compile with gcc 4.8.4 which is standard on Ubuntu 14.04.5. This is because we have customers whose IT departments have not yet upgraded to newer versions of libstdc++, and our attempts to use newer compilers with older libraries have been unsuccessful. The flag '-pthread' now needs to be added when compiling and linking user code.
- On Windows we compile with the latest Visual Studio 17 (version 15.8.1) and link the runtime library statically. Win32 support is dropped. Our tests show that Visual Studio produces around 10% faster code compared to the latest versions of gcc and clang (last time we did this comparison, Visual Studio, Intel and clang were comparable while gcc was behind).
- The code samples on Linux are now built with "-rpath $ORIGIN", so that LD_LIBRARY_PATH is no longer needed. See makefile in the sample directory.
Code samples. There are new code samples, and some existing code samples have changed substantially.
- simulate.cpp was upgraded to a full-blown UI application. It serves two purposes: a useful simulator with many new features, and a compact (for its scope) code sample which users can adapt to their needs. Reading the code is the best way to learn how to program the new UI. Accessing UI functionality from user code also requires uitools.c which is in the include directory.
- mjx.cpp was added. It is a MuJoCo wrapper for MATLAB. The corresponding build script is mjxmake.m in the sample directory (it should be called from MATLAB). On Windows this works well and we have provided the pre-compiled mex file in the bin directory. On Linux there are strange MATLAB crashes, possibly due to compiler/library version incompatibilities... we leave this as an exercise for the user. On macOS the code will not work because it handles mouse and keyboard inputs in a background rendering thread, and macOS only sends events to the main thread. It could be adapted to macOS by limiting the interactive rendering functionality.
- test.cpp was split into testxml.cpp and testspeed.cpp. The latter can now run the simulation in multiple threads, similar to how people in Reinforcement Learning use MuJoCo. It now prints detailed information from MuJoCo's built-in profiler, showing where the CPU time is spent. Instead of always starting from qpos0, it now starts from keyframe named "test" if such a keyframe is defined in the model.
- Linux users with NVidia drivers have experienced crashes in glfwTerminate(), which has been reproduced independent of MuJoCo. Apparently this is due to some incompatibility between GLFW and the NVidia drivers (or X implementation) which is beyond our control. Thus we now use conditional compilation to skip the call to glfwTerminate in simulate.cpp, basic.cpp, mjx.cpp and record.cpp on Linux.
Documentation. The main MuJoCo documentation has been updated to version 2.0. Note that the add-ons (HAPTIX, Unit Plugin, VR) are not yet updated to the 2.0 version of the main library, thus their documentation is unchanged for now. The main additions are:
- The Modeling chapter previously contained user guide and reference documentation. This is now split in two chapters: Modeling is the user modeling guide, while XML Reference is the reference documentation of the MJCF modeling language. Both contain new and revised material reflecting the XML changes (see below). This split is similar to the existing Programming and API Reference chapters.
- A new section on Length range computation was added. This explains the automated computation of actuator length ranges done by the compiler.
- A new section on Muscles was added. This is a long section explaining everything related to muscle modeling.
- A new section on Composite objects was added. This is another long section explaining the use of automatically-generated composite objects.
- Multiple new sections were added under the new high-level topic Tips and tricks. They explain how some common modeling tasks can be accomplished.
- The Solver parameters section was updated to describe the new formats of the solref and solimp constraint parameters.
- The Code samples section in the Programming chapter was updated to describe the new and changed code samples.
MuJoCo Pro 1.5, released on 4/23/2017
Constraint solver. The main improvement in this release is a comprehensive overhaul of the constraint solver mechanisms. As a result, MuJoCo can now simulate larger and more complex models faster and more accurately (see humanoid100.xml included with the distribution). The defaults are modified to take advantage of the new machinery, but users wishing to push the limits should familiarize themselves with the updated documentation. There is also a built-in visual profiler (see new simulate.cpp) to help fine-tune the solvers for more challenging models.
- A new Newton solver was added. It optimizes the primal cost in acceleration space, and has true quadratic convergence near the global minimum, usually reached in less than 10 iterations. It uses the exact Hessian, direct Cholesky factorization followed by rank-one updates and downdates, and works with both dense and sparse Jacobians. This is the new default solver.
- The PGS solver was extended to handle sparse systems; this is possible because the inverse inertia in constraint space (mjData.efc_AR) is usually quite sparse. The handling of elliptic cones is now more accurate. Equality constraints are no longer handled separately.
- The line-search used in the CG solver and the new Newton solver is now more accurate in the case of friction loss and elliptic cones. It uses a new one-dimensional Newton method which is essentially exact: the residual slope is shown in the new profiler.
- Instead of using the solver type to determine the cone shape (pyramidal or elliptic) and Jacobian type (dense or sparse), these options are now set independently. The possible solvers are Newton, CG, PGS. Each of them works with both pyramidal and elliptic friction cones, and both dense and sparse constraint Jacobians. The other solvers have been removed.
- The new default settings are: solver = Newton, cone = pyramidal, jacobian = auto (switches from dense to sparse when mjModel.nv>60), tolerance = 1e-8, iterations = 100.
- Solver convergence (i.e. early termination based on the tolerance setting) is now measured in terms of iteration-to-iteration cost improvement for PGS, and the smaller of the cost improvement and the gradient norm for Newton and CG. The cost and gradient are normalized by the trace of the inertia matrix in qpos0, in an attempt to make the tolerance model-independent (which is not exactly possible because the cost magnitude also depends on the constraint hardness). The solver convergence warning was removed.
- A new post-processing step (Noslip solver) is now available. Its goal is to reduce drift in friction dimensions. It is enabled by setting the new option noslip_iterations to a positive number; noslip_tolerance is also available. This is a modified PGS solver that only updates the constraint forces in the friction dimensions while ignoring constraint regularization (which is the root cause of the drift). Note that when the Noslip solver is enabled, MuJoCo no longer solves a well-defined optimization problem, but instead uses an adhoc cascade of solvers similar to gaming engines. We recommend using this as a last resort. A more principled way to reduce friction drift is to use the new Newton solver with elliptic cones, and set impratio to a large value.
- Because the new Noslip solver is actually solving a different problem, its solution is not appropriate for warm-starting the main solver. Thus the new field mjData.qacc_warmstart was introduced. It contains the output of the main solver, and is used for warm-start at the next simulation step. The warm-start mechanism uses the better of (qacc_warmstart, qacc_unc) for Newton and CG, and the better of (efc(qacc_warmstart), 0) for PGS.
Modeling and XML. Several new model elements and attributes and associated XML keywords have been introduced. There are also some minor changes that break backward compatibility, but MJCF models using the affected features are easily upgraded.
- The 'option' element has new attributes corresponding to the new solver mechanisms: 'cone', 'jacobian', 'noslip_iter', 'noslip_tol'. The 'solver' attribute has modified keywords: Newton, CG, PGS.
- Some attributes in the 'flags' element have been removed: 'boxconvex', 'sensor', 'mocap', 'broadphase'. These stages of the computation can no longer be enabled/disabled via the option flags.
- The XML attribute 'frictional' in elements 'joint' and 'tendon' was removed. The corresponding mjModel fields dof_frictional and tendon_frictional were also removed. Instead, friction loss is now enabled automatically whenever the setting of the 'frictionloss' attribute is positive.
- The attribuge 'meaninertia' was added to element 'statistic', and the corresponding field was added to mjStats. This stores the average diagonal value of the inertia matrix in qpos0, and is used for cost and gradient normalization by the new solvers. Recall that all model statistics are computed automatically by the model compiler, however the user can override them in the XML.
- The XML element 'freejoint' was added. It compiles into a free joint which could already be specified in the XML. However, this new element only allows a 'name' attribute and does not inherit any of the joint defaults. The reason to introduce it is because many users have had issues when free joints unintentionally inherited default settings (such as damping etc). The 'freejoint' element is now the preferred way of creating free joints in MJFS.
- When the model is defined in local coordinates, body pos can now be left undefined, in which case it defaults to (0,0,0). Previously this was a compiler error.
- Cameras now allow userdata, like many other elements. This can be used to store custom resolutions etc which are not used by MuJoCo.
- The sites used to specify the sensor zone for touch sensors can now have any geom type. Previously they were limited to ellipsoids and boxes (due to lack of ray collisions, which has now been resolved).
- A new 'rangefinder' sensor type was added. It is attached to a site, and measures the nearest distance to any geom along the ray defined by the positive Z-axis of the site frame.
- The attribute 'cutoff' was added to all sensors. For sensors with scalar data types, it imposes a cutoff in terms of absolute value. Positive settings enable this new feature, 0 disables it. The cutoff is also used to normalize the sensor data in the new sensor plots.
- The XML keyword 'quat' was renamed to 'quaternion' for user sensor data types. The new data type 'positive' was introduced, corresponding to sensors that return scalar positive values (such as the new rangefinder, and the existing touch sensor which was classified as 'real' before).
- Height field assets that are not referenced by any model geoms are now automatically removed by the model compiler, similar to unreferenced meshes.
Simulation. Minor changes were made in the available callbacks and in mjData, mostly to accommodate the new solvers.
- The callback mjcb_contactfilter was added. When installed, this overrides the default contact filtering (including contype and conaffinity, parent-child relations etc). Instead, the user function is responsible for telling MuJoCo if the two geoms should be checked for collision or not.
- The callback mjcb_timer now returns mjtNum instead of long long. We normally use a time unit of msec, but the user is free to use other units.
- A new warning mjWARN_BADCTRL was added. This is triggered when any element of mjData.ctrl is too big or not a number. When triggered, the entire mjData.ctrl is set to 0. This is the same mechanism as used to check qpos, qvel and qacc.
- The constant mjMINVAL was reduced to 1e-15. This automatically clamps from below all numbers used in any denominator in MuJoCo.
- The constant mjMAXCONPAIR was increased to 50. This allows for more contacts per geom pair, which can be useful with complex height fields.
- The mjData fields fc_XXX were removed. They were used for special handling of equality constraints in PGS which has been removed.
- The mjData fields efc_J_XXX, efc_JT_XXX and efc_AR_XXX were added to represent the sparse version of efc_J, efc_JT and efc_AR. The field qacc_warmstart was also added to avoid issues with the new Noslip solver.
- The mjData field efc_state was added. It stores the states of the (soft) constraints, and has integer type given by the new enum mjtConstraintState.
- The constant mjNTRACE was renamed to mjNSOLVER and increased to 1000. This allows keeping statistics about more iterations of the constraint solver (even though the new Newton method actually reduces the number of iterations needed).
- The solver statistics kept in mjData are now organized in the data structure mjSolverStat. Similarly, timing statistics are now in mjTimerStat and warning statistics are in mjWarningStat. The solver statistics are now significantly expanded - see documentation.
- The fields coef and zone of mjContact were removed as they are no longer used. The new field H was added; it represents the local contact Hessian for elliptic cones.
- There is a new define mjUSEAVX in mjModel.h. This enables AVX intrinsics at compile time. Like mjUSEDOUBLE, this is informational only and the user should not attempt to change it.
Ray intersection. There is a new collision detection module that can intersect rays with all other geom types, including meshes and height fields. This is used for selection, rangefinder sensors, and is also available to the user for custom computations. It is not used by the contact solver.
- The new function mj_ray intersects all visible geoms in the model with a given ray, and returns the distance to the nearest geom as well as the geom id. Note that this is an engine-level function and not a visualization-level function, thus it needs arguments specifying which geoms are visible. These arguments are designed in such a way that one can simply pass the corresponding fields of mjvScene.
- For custom computations, the low-level ray collision funtions mj_rayMesh, mj_rayHfield and mju_rayGeom are also exposed. Meshes and hfields are stored in the model, so the corresponding functions need access to mjModel and mjData. All other geoms types are handled by the utility function mju_rayGeom.
Visualization. The visualizer now plots elaborate 2D figures, used in the new profiler and sensor data plots and also available for custom figures. There are also minor improvements to 3D rendering.
- The data structure mjvFigure was introduced. It describes a 2D figure with many options. The new function mjv_figureDefault sets it to the default empty figure, which is then populated programmatically. See new simulate.cpp for an example how to use it.
- The new function mjr_figure renders the mjvFigure. This replaces the (more limited) mjr_lines.
- Selection is now done at the abstract visualization level with the new mjv_select function. This uses the new ray intersection mechanism and no longer depends on OpenGL rendering. The previous selection function mjr_select is removed.
- When contact forces are rendered in split mode ('p' in simulate.cpp) both the tangential and normal arrows are now one-directional. In this way the user can see the direction of contact force. For normal forces this is not essential because the normal force always pushes the geoms apart, but for friction forces the direction is not otherwise obvious.
- The constant mjMAXPLANEGRID = 100 was introduced. It limits the ratio of size[0,1]/size for plane geoms. This ratio sets the number of grid lines used to render planes. Previously, when users accidentally set size to a very small value, the renderer generated a vast number of grid lines, overwhelming the video driver and GPU.
Virtual file system. All files that MuJoCo reads from disk can now be read from a new virtual file system (VFS). This includes XML files (MJCF, URDF, included models), STL meshes, PNG textures and height fields, and height fields in our custom format. MJB models can also be loaded from the VFS. This can be useful when models are assembled programmatically before being compiled, or in distributed environments where storing models on the disk of each node is undesirable/impossible.
- The entire VFS is contained in the new data structure mjVFS. For each file it stores the file name (without path information - so the organization is flat), size, and pointer to memory buffer with the file contents.
- Disk files are loaded into the VFS with mj_addFileVFS. Empty files to be filled-in by the user programmaticaly are created with mj_makeEmptyFileVFS. There are several other functions for working with the VFS: mj_defaultVFS, mj_findFileVFS, mj_deleteFileVFS, mj_deleteVFS.
- To use the VFS, pass a pointer to it to mj_loadXML or mj_loadModel. When this pointer (a new function argument) is not NULL, all MuJoCo functions look for the specified file names in the VFS first before attempting to load from disk.
New functions. Several new functions have been added to the public API, and some existing functions have been exposed.
- Math utility functions for working with 4D vectors have been added: mju_zero4, mju_unit4, mju_normalize4, mju_copy4. These are mostly useful for working with quaternions.
- mju_insertionSort was added. Note that with small lists of numbers (up to 10) insertion sort is the most efficient way to sort.
- mju_Halton was added. This generates a Halton sequence of pseudo-random numbers that are more uniform than a regular random number generator (but also slower to generate). This is used in the new 2D plotting to generate visually-distinct random colors when the number of lines is large, and is also available for custom computations.
- The new function mju_cholUpdate performs rank-one updates and downdates to the (dense) Cholesky factorization of a square matrix.
- Sparse Cholesky factorization, solve and rank-one update functions were added: mju_cholFactorSparse, mju_cholSolveSparse, mju_cholUpdateSparse. These perform reverse-order Cholesky factorization, which has less fill-in in our case.
- A number of other utility functions for sparse algebra were added: all function names that end with the word 'Sparse'.
- Added the utility mju_subFrom, and the indicator functions mj_isXXX to check if the solver is primal or dual, dense or sparse, pyramidal or elliptic.
- The function mj_updateConstraint was exposed. This function computes the soft-constraint penalty s(.) described in the documentation, as well as the constraint forces (which are the negative gradient of s) and the elliptic contact Hessians.
- The function mju_writeLog was exposed. This allows appending messages to the file MUJOCO.LOG. The function mju_error used to write to the log automatically even when a user error handled was installed. Now it doesn't write to the log - so the user handler can write to the log if desired.
- The function mj_freeLastXML was added. It frees the XML model that is parsed in memory and remains hidden until the next mj_loadXML. This is not really necessary because the model is cleared when the program closes or when a new model is loaded, but we have added it for stylistic reasons.
- The abstract visualization functions mjv_initGem and mjv_makeConnector were exposed, to make it easier for users to add custom mjvGeoms to mjvScene. mjv_averageCamera was also exposed - it returns the average of the two OpenGL cameras in stereoscopic applications, and is useful for ray selection from a viewpoint between the eyes.
Changed and removed functions. Some existing functions were modified and others we removed. Note that we do not repeat here changes that we already listed above.
- Utility functions that take pointers to arrays with known sizes now show the size in the argument, e.g. mju_zero3(mjtNum res) instead of the old mju_zero3(mjtNum* res).
- Cholesky factorization now stores the diagonal (which is the standard convention) instead of the inverse of the diagonal as it did before. We used to store the inverse to speed up solve, but now that we are doing rank-one updates, storing the diagonal is better. Also, the 'diag' argument to the Cholesky factorizer was removed.
- 'backsub' has been renamed to 'solve' in all functions that involve solving a linear system given a factorized matrix.
- mj_loadModel no longer calls mju_error when the model file is corrupted. Now it generates a warning instead. This is useful when using a GUI - which is not supposed to exit just because the user selected the wrong binary file from the menu.
- The function mj_saveXML was renamed to mj_saveLastXML, to indicate that we are saving a hidden XML model in memory that was left from the previous mj_loadXML.
- The utility function mju_sqrMat was removed, use mju_sqrMatTD instead.
- The functions mjv_cameraInModel and mjv_cameraInRoom now return the 'up' camera vector.
Bug fixes. All known bugs are fixed. These bugs are as follows.
- Acceleration sensors in mj_forward used to ignore skipsensorenergy, and were omitted from mj_inverse.
- The built-in timers did not work in mj_inverse.
- qfrc_bias was not computed in mj_invVelocity.
- Initialization of dynamic height fields was ignoring the last size parameter.
- The computation of tracking camera frames was inaccurate.
- Site quaternions were not normalized.
- Defaults parsing for sub-classes was ignoring parent information that appeared after the sub-class definition, and some pair defaults were mistakenly parsed as actuator defaults.
- Images loaded from PNGs and used for textures and height fields were flipped in the vertical dimension.
- The license manager did not support hardware-locking on newer Macs. It turns out this is not because of Sierra, but because newer Macs use NVMe instead of regular disks and the protocol for reading the disk serial number is different.
- Models with multiple height fields did not work properly.
- Touch sensors generated unexpected readings when the contact penetrated beyond the sensor zone. This is now fixed thanks to the new ray intersection functions. The touch sensor is activated whenever the ray defined by the contact normal force intersects the 3D volume defined by the site sensor zone.
Code samples. The sample basic.cpp was added to the distribution (previously it only appeared in the documentation). It illustrates minimal simulation and rendering, without the complexity of simulate.cpp. The sample derivative.cpp now uses the new qacc_warmstart for proper warm-start. A new model humanoid100.xml was added, with 100 objects in addition to our standard humanoid. This illustrates the power of the new solvers. The remaining changes are in simulate.cpp as follows.
- There is now a built-in visual profiler, toggled with F8. It shows timing information for different compute stages, dimensionality of various arrays, and solver statistics per iteration. Note that in order to obtain reasonable timings, one has to tell the OS to not lower the CPU frequency - which Windows will normally do because simulate.cpp is sleeping most of the time.
- There is another new data plot that shows sensor data as a bar graph, toggled with F7. The data are normalized by the new sensor attribute 'cuttoff' when positive, and unnormalized otherwize. The plot function always normalizea the entire dataset before rendering.
- The font scale can now be changed at runtime by pressing '-' and '='.
- Instead of always resetting the simulation state to qpos0, we can now reset to one of the keyframes defined in the model. The keys Page Up/Down cycle over the keyframes (now shown in the info window), and Backspace then resets to the selected keyframe.
- Mouse selection is now done with the new ray intersection mechanism. There is no change from the user's perspective, but the code sample illustrates how to use this.
- The left and right mouse buttons can now be swapped by holding down the Alt key. This is useful for laptop trackpads that have issues with right-drag (especially Macs running Windows).
- The solver convergence statistic shown in the info window is the log10 of the last cost improvement in PGS, and the smaller of the improvement and gradient norm in Newton and CG.
Documentation. The entire documentation has been updated to MuJoCo 1.50. The main additions are as follows.
- The Reference chapter in the documentation is now complete. The function definitions are automatically generated from mujoco.h, with some additional text when available.
- A new section Reduced primal problem was added to the Computation chapter. It formulates the unconstrained convex optimization problem being solved by the CG and Newton algorithms.
- A new section Algorithms was added to the Modeling chapter. It provides guidelines on fine-tuning the constraint solver algorithms. Another new section Sensors was also added, summarizing common properties of sensors.
- The section Data layout in the Programming chapter now explains the sparse matrix format used in MuJoCo, as well as the layout of quaternions and spatial vectors.
- A new section CPU or GPU? in the Overview chapter now discusses the merits of CPU vs. GPU computing for physics simulation, and summarizes our preliminary observations with porting MuJoCo to GPUs.
MuJoCo Pro 1.4, released on 8/22/2016
OpenGL rendering. While the underlying renderer is the same, it now works in more scenarios, and the way the user interacts with it is streamlined and enhanced. Headless rendering (on Linux) and offscreen rendering are now supported systematically. The full list of changes is too long to show here; it is best to examine the documentation and code samples.
- On Linux, libmujoco no longer links libGL and libGLEW. Instead the user is expected to link the versions of these libraries for the desired rendering scenario. This makes it possible to use X11, EGL, OSMESA or other GLEW-supported mechanisms for context creation. It is also possible to use the new vendor-independent libOpenGL which does not depend on X11 (replacing libGL which does).
- All GLU functionality is now replaced with native code. This was needed because libGLU depends on X11 which may not be available in headless rendering.
- Multi-sample anti-aliasing is now supported more systematically, including in offscreen rendering. The new model attribute mjModel.vis.quality.offsamples specifies the number of samples for the offscreen buffer. All read pixel, write pixel and blit operations are aware of the existence of multi-sample buffers, and use intermediate resolve buffers as needed.
- There is now an explicit notion of active buffer (window or offscreen) which is set via the new function mjr_setBuffer. All subsequent rendering is directed to the active buffer. All functions work with both the window and offscreen buffers, including text and overlays (which could only be rendered to the window before). Single-buffered window rendering is also detected and handled automatically.
- mjr_makeContext now checks the capability of the window framebuffer (including quad-buffering, double-buffering, multi-sampling) and records it in mjrContext. Subsequent operations automatically take into account these capabilities, so for example user code no longer needs to keep track of whether quad-buffered stereo is available.
- Side-by-side stereo mode is now supported, in addition to the previously available quad-buffered stereo mode. This is needed for VR devices.
- All rendering features now work on all platforms. Previously our internal function availability check was limited to the core OpenGL specification, and so we required 3.2 compatibility context in order to enable all rendering features. We realized however that the functionality we are using is contained within OpenGL 1.5 plus the ARB_framebuffer_object extension, which is more widely supported by existing drivers.
- The option to flip the left and right views in stereo mode was removed, since modern hardware does not suffer from flipping.
- The renderer now uses GLEW 2.0.0 (which is essential for headless rendering) and the code samples use GLFW 3.2. Precompiled versions of these new libraries are included in the software distribution.
- The Intel Ubuntu driver was causing artifacts in cube texture mapping. We traced this to mipmap texture generation, and side-stepped it by using a different method (even though the old method should have worked according to the OpenGL specification, as it does on every other platform).
- The OSX driver was mysteriously returning only the left half of the depth map for multi-sampled windows. This is now fixed (we are not quite sure which change fixed it).
Abstract visualization and mouse interaction. The abstract visualization layer was redesigned so as to streamline it, add support for VR devices, and make the mouse interaction more intuitive. Similar to above, the full list of changes is too long to show here, so look at the documentation and code samples.
- The new data structures mjvScene and mjvPerturb encapsulate multiple objects that previously had to be maintained by user code. The scene is the final result of the abstract visualization stage. It is updated with a single call: mjv_updateScene(). Then it takes one more call to render it: mjr_render().
- The abstract mjvCamera now has cleaner support for free cameras, tracking cameras and model-defined cameras. The low-level mjvCameraPose is removed. Instead we now have a new mjvGLCamera which is embedded in mjvScene, and corresponds directly to an OpenGL camera - one for each eye. The user can omit mjvCamera altogether and specify OpenGL cameras directly, so as to implement head tracking and oblique projections needed for VR headsets.
- We now make a distinction between model space and room space. The latter is needed because new VR headsets have physical presence, so we need to position the model relative to the room. This is done by defining model translation, rotation and scaling within mjvScene, and controlling them interactively via the new function mjv_moveModel(). When mjvCamera is used to update the OpenGL cameras, this transformation is disabled and the camera simply lives in the model space as before.
- A new labeling mode was added, allowing the magnitude of all contact forces to be printed at the base of the corresponding force arrows. The arrows themselves must be enabled for these labels to show up.
- Translational perturbations are now more consistent. The mouse cursor and the end of the string pulling the object are still dislocated, because the translation is happening in a model-aligned rather than a screen-aligned plane. But now returning the mouse to the same place will also return the end of the string to the same place. The other end of the string is now anchored to the inertial body frame and not the regular body frame (the latter usually coincides with the joint).
- The default strength of the rotational perturbation is increased by default, and a new model attribute mjModel.vis.map.stiffnessrot is added so the user can further adjust it. The orientation difference between the selected object and the perturbation reference is now limited to 90 deg. This makes the rotational perturbation a lot more usable. In pose editing mode, the rotation now takes place around the selected object and not the root of the kinematic subtree as before.
Sensors and energy. The sensor simulation and energy computation were redesigned to follow the same stage-wise approach as the main physics computation. Sensor noise, new sensor types and custom sensors were added.
- In addition to sensors that correspond to existing measurement devices, we extended the notion of sensor to include any quantity of interest, so that mjData.sensordata can represent all relevant state-control features for optimization algorithms. This includes new sensor types: the position, velocity and acceleration (both linear and angular) of every MuJoCo object that has a spatial frame (body, site, geom, camera), as well as subtree-related sensors. Custom sensors are now also allowed. The new callback mjcb_sensor is expected to fill in the corresponding fields of mjData.sensordata.
- The functions mj_sensor() and mj_enregy() were separated into mj_sensorPos(), mj_sensorVel(), mj_sensorAcc() and similarly for energy. Each function performs the computations at the corresponding stage, so that for example position and velocity-dependent sensors will be computed before the control callback is called. Importantly, these functions are now called automatically from within the physics pipeline and no longer need to be called by the user (although we still expose them).
- The sensor specification now includes a noise term. This is the standard deviation of zero-mean Gaussian noise that can be added to the simulated sensor reading. Even if this setting is non-zero, noise is not generated by default, but only if the new enable flag "sensornoise" is set. This is because state estimators need to know what the noise amplitude is, but do not normally need to generate noisy sensor readings.
- Sensor scaling was removed. It no longer makes sense when we have so many spatial frames as sensors.
- The order of kinetic and potential energy in mjData.energy was swapped to match the computation states (position, then velocity).
- The enums mjtStage and mjtDataType were added to specify the stage arguments of functions, and to handle spatial frame sensors that can be attached to objects with different MuJoCo type.
- The "skip" versions of mj_forward() and mj_inverse() now have an additional flag to skip the (now automated) computation of sensors and energy.
XML and mjModel changes.
- A new MuJoCo model element was added: a tuple. This is a user-defined list of MuJoCo objects, each with an optional scalar parameter. In the XML, the list is created by referencing the types and names of the desired objects. This can be helpful in user computations that operate on groups of objects - for example custom contact processing that needs a predefined pair of geoms or bodies.
- The XML specification of joints now allows a new "springdamper" attribute. It has the same format as solref: time constant and damping ratio. When specified, the compiler will automatically compute the stiffness and damping coefficients of the joint, by taking into account the joint inertia in the model reference configuration. Only the stiffness and damping coefficients are stored in mjModel, as before.
- The mass of the kinematic subtree rooted at each body is now precomputed by the compiler and stored in the new field mjModel.body_subtreemass.
- The field mjMode.text_size was added, to match the other custom elements. Previously we relied on the 0-terminated strings to extract this information.
- The enable flag "solverstat" was renamed to "fwdinv". It now enables the automated comparison of the forward and inverse dynamics, whose outcome is written in the renamed field mjData.solver_fwdinv.
- Added diagnostic fields maxuse_con and maxuse_efc, in addition to the now-renamed maxuse_stack. These fields are updated internally and contain the maximum stack allocation, maximum number of contacts and maximum number of scalar constraints since the last reset. They can be used to adjust the corresponding static allocations in the XML.
- Added fields subtree_linvel and subtree_angmom, computed by mj_sensorVel(). These are the linear velocity and angular momentum of the kinematic subtree rooted at each body. They correspond to new sensor types. The existing field com_subtree was renamed to subtree_com to match the new convention.
- All solver-related diagnostic fields now start with the prefix "solver_".
- The array solver_trace is now populated automatically by all solvers. This is the norm of the residual gradient at each iteration of the algorithm. Note that this quantity does not have to decrease monotonically.
- Removed the field mocaptime. This is now internal to MuJoCo HAPTIX because it does not make sense in the generic simulator.
- Removed the sensor and energy timers (since these computations are too fast to be of interest in timing), and added a timer for inverse dynamics.
- The field timer_ncall is now int instead of mjtNum.
- The default callback setting is now a NULL pointer, instead of requiring a dummy function that does nothing. The user can still provide dummy functions of course.
- The callbacks mjcb_endstep and mjcb_magnetic were removed (the latter is superseded by the general mjcb_sensor).
- The functions mj_objectVelocity and mj_objectAcceleration now support cameras in addition to geoms, bodies and sites. There is also the new object type mjOBJ_XBODY which refers to the regular frame of the body, as opposed to mjOBJ_BODY which refers to the inertial frame.
- Added a utility function mju_standardNormal() which generates zero-mean unit-variance Gaussian random numbers. This is done by generating numbers with rand() and transforming them; so the user can seed this by seeding rand(). This new function is used to generate sensor noise when enabled.
- Added pose transformation functions mju_poseXXX. A pose is a translation plus a rotation, in the sense of OpenGL, but using quaternions instead of 3-by-3 matrices.
- Added the function mj_resetDataKeyframe(). This does a reset and then sets the state from the specified keyframe.
- The internal function mj_addContact() is now exposed. This allows the user to replace MuJoCo's pair-wise collision detection functions with a library of their choice.
- The function mju_mat2quat() and its analog used by the compiler now support all cases of the conversion. Previously it would generate an error if the trace of the matrix was negative.
- Renamed mju_quatVec2Z() to mju_quatZ2Vec(), reversing a previous name change that was in fact inaccurate.
- Several functions declared in mujoco.h were not exposed by the library; now fixed.
- Added enums mjtFont, mjtFontScale, mjtFramebuffer. These are needed to specify arguments of new functions, and avoid unnamed integer flags previously used in existing functions.
- Added text strings for frame and labeling modes. This is now used in simulate.cpp to show the name of the selected mode instead of showing a number.
Miscellaneous bug fixes.
- Site actuator transmissions now work correctly in local coordinates.
- Camera targeting now works correctly.
- The value of mjMAXCONPAIR was increased to 16. This is the maximum number of contact points between two geoms that any collision function is allowed to return. It turn out that the box-box collider can return more contacts than the previous limit of 8 (causing a crash), and custom collision functions may also want to return more contacts.
- The s_solref and s_solimp fields of mjOption were not previously written to the XML when saving. Now fixed.
- Simulate.cpp was enhanced in several ways; see documentation and code.
- A new sample derivative.cpp was added. It illustrates how to use multi-threaded computation for finite-difference approximations, re-using as many results as possible and utilizing solver warm-starts properly.
- A new sample record.cpp was added. It illustrates offscreen rendering and saving to a raw file, which can then be compressed/converted to a video file with a tool such as ffmpeg. The sample illustrates this in three ways: using an invisible window, using EGL to create a context without X11, and using OSMESA (the last two are Linux-specific). In all cases, it creates an offscreen buffer for rendering and does not rely on the window buffer even if available.
Documentation changes. In addition to being updated, the online documentation was reorganized as follows:
- The Overview chapter was split into Overview and Computation.
- The MuJoCo Pro chapter was split into Programming and Reference.
- The Tutorial chapter (which was not really a tutorial anyway) was converted into a new "Clarification" section at the end of the new Overview chapter.
- The Table of Contents did not seem useful and was removed. Use the links in the left panel instead.
MuJoCo Pro 1.31, released on 4/23/2016
- Added support for 3D magnetometers. This includes the new sensor type 'magnetometer', the new field 'magnetic' in mjOption specifying the global magnetic flux, and the new callback mjcb_magnetic allowing custom magnetic field models to be implemented (e.g. dipoles).
- Added actuator transmission type 'jointinparent'. For free and ball joints, this causes the rotation to be specified in the parent frame, as opposed to the child frame which is what 'joint' does. For hinge and slide joints there is no difference between 'jointinparent' and 'joint'.
- All actuator-related callbacks now take mjModel, mjData and the actuator id as arguments, allowing the callback to access all model parameters.
- The camera and light tracking modes have been renamed to make their meaning more clear. Now they are: 'fixed', 'track', 'trackcom', 'targetbody', 'targetbodycom'. Only the latter two modes use the 'target' attribute.
- The solver warmstart mechanism was modified. Instead of computing constraint signatures and trying to match them between time steps, it now uses qacc from the previous time step and applies inverse dynamics to warm-start the constraint forces. The mjData field efc_signature is removed. The new mechanism leads to slightly faster convergence, and also consistent among all solvers.
- The construction of contact impedance for pyramidal friction cones was modified to better match the underlying elliptic cone model, and also to take into account the parameter 'impratio'. The pyramidal and elliptic models now have matching impedance in friction dimensions. It is not possible to match both friction and normal dimensions, for mathematical reasons which will be explained elsewhere.
- Ball joint limits were problematic - now fixed. The new model imposes a limit on the overall amount of rotation. Only the second range parameter is used to specify the limit. The first range parameter should be zero (now enforced by the compiler).
- The API function mj_camlight was added, to compute the pose of the cameras and lights. Internally it is called after mj_comPos. This fixed a bug with jumping lights and cameras at initialization.
- user_XXX default settings are now properly instantiated in all model elements. Previously they were ignored.
- The activation mechanism was upgraded in support of the new 30-day free trial license which can be obtained online. This license is hardware-locked to a specific Computer id.
- New mechanism for exchanging electronic certificates, allowing user code to demonstrate to a remote server that the user has a valid MuJoCo Pro license. This will be used in future online services. The new API functions are mj_certQuestion, mj_certAnswer, mj_certCheck.
- Cycling over frame rendering and label rendering modes added to simulate.cpp. The new shortcuts are F6 and F7.
- Drag-and-drop of urdf models supported in simulate.cpp. Help text in compile.cpp corrected to say 'compile' instead of 'convert'; the latter is a built-in Windows function.
MuJoCo Pro 1.3, released on 4/6/2016
- The software distribution now has a directory structure: bin, doc, include, model, sample.
The software version number is now incorporated in the name of the library: mujoco130.dll instead of mujoco.dll. The symbol mjVERSION_HEADER is defined in mujoco.h, allowing comparison of the header and library version:
if( mjHEADER_VERSION==mj_version() ) ...
The version numbers are now integers: 130 instead of 1.30, to avoid floating-point comparison complications. This is part of a transition to a new distribution model where multiple software versions will be available for download, facilitating use of older versions while helping avoid version conflicts.
- A new code sample compile.cpp was added. It acts as a command-line compiler for model conversion. All possible conversions are exposed.
- Hardware locking for Trial licenses was implemented. We can now generate personal trial activation keys. Previously trials were limited to institutions because locking to a specific machine was not supported.
- The activation mechanism was upgraded to make sure that each activation key can unlock software versions that are released roughly one year before to one year after the key is issued. This is another part of the transition to facilitating use of older versions.
- We now use the Clang compiler on OSX, because the necessary runtime libraries are pre-installed and up to date (unlike GCC which has limited support on OSX). We still use GCC on Linux, and Visual Studio on Windows.
- mj_loadXML now supports URDF model files in addition to MJCF model files. The file extension can be either '.urdf' or '.xml', however the file format is determined by the top-level element ('robot' or 'mujoco') rather than the file extension. Note that mj_saveXML still saves in MJCF even if the model was loaded from URDF.
- mj_loadXML now has the additional argument 'xmlstring'. If this argument is not NULL, the model is loaded from the specified memory string and the 'filename' argument is ignored.
- A new sparse solver was added, based on preconditioned conjugate gradient descent. It supports both pyramidal and elliptic friction cones ('CG' and 'CGelliptic'). This solver is experimental for now, but shows a lot of promise. The keywords for the remaining solvers were adjusted.
- A new 'tolerance' parameter was added to mjOption and affects all solvers. It causes early termination when the relative norm of the residual gradient (of the quantity being minimized by the solver) falls below this parameter. The 'iterations' parameter now corresponds to the maximum number of iterations and is rarely reached. This new mechanism yields a substantial increase in average simulation speed.
- The 'solverstat' field of mjData now contains the number of iterations, residual gradient norm at termination, and comparisons between forward and inverse dynamics when the 'solverstat' enable flag is set. These numbers are now printed in the info text in simulate.cpp.
- A new 'impratio' parameter was added to mjOption. It determines the ratio of constraint impedance in frictional vs. normal contact dimensions. Increasing this parameter above its default value of 1 makes contact friction 'harder' than contact normal forces.
- A safety feature was added, internally setting solref = max(solref, 2*timestep). It prevents integrator instabilities that were previously caused when the constraint recovery time constant solref was small relative to the simulation time step. This new mechanism can be disabled with the 'saferef' disable flag.
- New sensor types were added: 'sitepos' and 'sitequat'. They can be used to model the output of motion capture markers. The output of 'sitepos' is a 3D position and can be scaled (like all other sensors). The output of 'sitequat' is a 4D quaternion and cannot be scaled.
- The simulation of touch sensors was improved in situations where softness causes the contact point to penetrate so much that it moves out of the touch sensor zone. The contact point is now projected on the sensor zone, and this artifact is avoided.
- New actuator transmissions were added, allowing actuation of ball joints, free joints and sites. The 'gear' parameter was generalized, so as to specify a 3D rotation axis for ball joints and a 6D wrench axis for free joints and sites. This allows modeling of jet engines, propellers, and other more complex transmission mechanisms.
- The tolerance and iteration parameters of the MPR algorithm for mesh collisions were exposed as new fields of mjOption. Previously they were fixed internally. Adjusting these parameters may be needed for geoms with large aspect ratios.
- Cameras and lights are no longer limited to being fixed to their parent body. Four new modes are implemented: 'trackbody', 'trackcom', 'targetbody' and 'targetcom', together with a 'target' parameter for specifying the target body. Tracking refers to keeping global orientation fixed while maintaining fixed global offset from the parent body (or center of mass of the kinematic subtree starting at the parent body). Targeting refers to rotating the camera/light to point at the target body, while moving with the parent body.
- Cameras and lights can now be visualized, similar to joints and other decor elements. The new keyboard shortcuts are 'Q' and 'Z'. Camera and light frames can also be visualized. The constants mjFRAME_CAMERA and mjFRAME_LIGHT were added, and the new constant mjNFRAME is the number of frame types that can be visualized.
- The attribute 'texscale' was renamed to 'texrepeat', and now correctly specifies the number of times the texture is repeated over the (z-facing side of the) object. If 'texuniform' is true, 'texrepeat' specifies how many times the texture is repeated over one spatial unit, independent of the object size. The center of the texture now always coincides with the center of the object, regardless of the number of repetitions.
- The API functions mjr_uploadMesh and mjr_uploadHField were added. They can be used to modify a mesh or height field in mjModel and re-upload it to the GPU at runtime, without re-creating the custom rendering context. Previously this was only possible for textures via mjr_uploadTexture.
- The API function mjr_lines was added, allowing 2D plots to be rendered in a user-specified viewport over the 3D rendering.
- The 'flg_init' argument of mjr_rectangle was removed. Now the 2D rendering options are initialized internally for every call.
- Added functions mj_resetDataDebug, mjr_getError, mju_sqrMatTD; renamed mju_quatZ2Vec to mju_quatVec2Z.
- Changed all enum-type arguments in mujoco.h from mjtXXX to int. This is because enums do not have a well-defined integer type and different compilers can in principle implement them with different number of bits.
- When possible, moved the mjNXXX size-related constants into the corresponding enum definitions (as the last item) so that their values are automatically adjusted when changes are made.
- Added the length of the error string buffer as argument to all API functions that expect this buffer.
- For consistency with the new error string arguments, the order of the 'szbuffer' and 'buffer' arguments to mj_loadModel and mj_saveModels was reversed.
- mju_error now writes the error messages at the end of MUJOCO_LOG.TXT even if a user error handler is installed.
- Error and warning messages are now more informative. In particular, warnings now contain the index of the offending DOF or the size of the insufficient buffer. A new field 'warning_info' is added to mjData, which contains this new information.
- The total mass of all bodies in the model is now included when the model is saved as plain text file. This can be useful for deciding whether to scale the body masses.
- A number of bugs were fixed, including incorrect rendering of frictionless contact forces, margin handling in broadphase collisions, writing of default sizes in XML, random texture generation, 2D texture mapping.
MuJoCo Pro 1.22, released on 11/26/2015
- The Overview and MJCF Models chapters in the documentation are now complete and up to date, and correspond to the latest version of the software. We will keep them up to date with future releases.
- A new code sample was added: test.cpp. It is a command-line tool that simulates a model for specified duration and print various statistics. It also performs end-to-end unit testing of the parser and compiler; if you see discrepancies greater than 1e-4 please let us know.
- The libglfw.3.dylib library on OSX can now be used from the executable directory (we got rid of the absolute paths that are normally embedded in dynamic libraries on OSX).
- Joint and tendon equality constraints are now 4th-order polynomials instead of 3rd-order. The length of the coefficient vector "polycoef" is now enforced by the parser.
- Rotational torques due to material density are now included in the passive forces.
- A number of defaults were adjusted; see MJCF Models chapter for current values. These are njmax, nconmax, nstack, coordinate, camera ipd, various colors, joint pos and axis, geom and site type, geom and site size, tendon width, solimp.
- The IMU sensor was split into accelerometer and gyro. Similarly, the FT sensor was split into force and torque. The latter are now defined through a site rather than a body. The outputs of all sensors can now be scaled (so as to change units).
- The XML element "flags" was renamed to "flag" to make it consistent with our naming convention. The attribute "tau" of element "cylinder" was renamed to "timeconst". Internally, the mjModel field "actuator_trnprm" was split into "actuator_gear" and "actuator_cranklength". The visual fields "near" and "far" were renamed to "znear" and "zfar" to avoid name conflicts on Windows.
- The number of keyframes allocated in the model is now the maximum of the number of explicitly defined keyframes, and the "key" attribute of "size".
- Some changes were made in the rendering: skyboxes are now rendered as solid even in wireframe mode, only the first reflective surface is now rendered as such (to avoid artifacts due to the lack of ray-tracing), local rgba specifications now override material properties.
- Several parsing and compilation rules were changed, to improve the logic and internal consistency. We do not list them here but the changes will be obvious if an older model fails to load.
- Multiple bugs were fixed.
MuJoCo 1.21, released on 9/21/2015
- MuJoCo Pro now has a built-in activation manager and requires an activation key. This is a plain text file which will be sent to licensed users. Add "mj_activate(filename);" before calling any other MuJoCo functions. At the end call "mj_deactivate();" to free the memory allocated for activation data. See updated simulate.cpp for an example.
- mjfCallback was renamed mjfGeneric, because many of the generic MuJoCo functions have the same format.
- Plane geoms are no longer allowed in sites.
MuJoCo 1.2, released on 9/8/2015
- The software distribution now includes the OSX version, in addition to the Windows and Linux versions.
- The texture mapping mechanism is substantially extended and improved. This includes procedural textures, explicit control over 2d vs cube textures, loading of cube textures from separate as well as composite PNG files, mip-mapping, additional scaling options, built-in mesh generation that results in better texture mapping.
- A number of rendering artifacts were fixed. This includes shadow artifacts on transparent surfaces (which are no longer shaded) as well as glowing objects (as in the the selected object), and issues with directional lights.
- Added support for fog as well as more systematic skybox rendering. Note that fog usually hides the skybox so there is no point enabling both. By default fog is disabled and skybox is enabled.
- Added a "statistic" element to the XML, allowing override of the default model statistics - which in turn affect the scaling of various visual elements.
- Several changes were made to the XML convention in an effort to streamline and finalize it. The material default rgba is now (1,1,1,1) which is suitable for texture mapping. The compiler option "strippath" is now disabled by default. The type of geoms and sites is now required. Plane and hfield geoms are now only allowed in the world body. Positive mass and inertia are no longer required for bodies welded to the world. The experimental CIO mechanism was removed (it will be replaced with a more general mechanism later).
- The top-level body is now called "worldbody". All bodies under it are still called "body".
- Several XML elements and attributes were renamed: ft to forcetorque, act-motor to motor (and similarly for the other actuator defaults), islimited to limited, disable flag friction to frictionloss. The makeactuator and actuatorclass atributes of tendons were removed (they were not being used).
- Moved the call to mj_warning after the call to mj_checkXXX, so that if the simulation becomes unstable and is reset, the warning will not be cleared by the reset function.
- Added fields to mjxmacro.h to facilitate development of MEX and other wrappers.
- Tabs in header files were replaced with 4 spaces.
- Fixed parsing bug in geom and site sizes. Now a geom or site-specific size definition fully overrides the default definition, even if the default has longer array size.
MuJoCo 1.1, released on 8/24/2015
- Constraint solver parameters have been redefined and scaled better. Instead of solprm we now have solref and solimp, as well as solmix for geoms.
- Added callbacks mjcb_sol_ref and mjcb_sol_imp which can override the default interpretation of the new solref and solimp parameters, and thereby modify the behavior of the constraint model.
- Added "Solverstat" option which runs inverse dynamics after forward dynamics in mj_step, and compares the results. This can be used to monitor solver convergence.
- Added specialized collision functions (courtesy of Svet Kolev) for box-sphere, box-capsule and box-box. The latter allows more stable box stacking, at the expense of generating extra contacts. Use the new "Boxconvex" option to revert to the convex box-box collider which returns a single contact.
- Geoms, sites and tendons can now be made invisible by setting alpha=0; previously this made the object invisible but did not remove its reflection.
- Additional contact pruning and code refinements made the solver faster, up to 30% for large models.
- Constraints that do not affect any DOFs are now filtered out. This avoids solving for constraint forces that cannot affect the simulation (e.g. length limits on tendons connecting stationary bodies).
- Local coordinates are now the default in the XML. Use coordinate="global" in the compiler section to define models in global coordinates.
- xfrc_applied now contains force followed by torque for each body; previously it was the other way around.
- mj_step no longer clears xfrc_applied, meaning that xfrc_applied can now be used as persistent user input, just like ctrl and qfrc_applied.
- mj_sensor and mj_energy are now called outside mj_forward and mj_inverse, so user code should call them directly if needed for custom computations. mj_sensor now calls mj_rnePostConstraint to compute cacc, cfrc_int, cfrc_ext - which are features that are not needed in the main computation. Apart from the semantic improvement, this makes the RK4 integrator generate correct sensor readings.
- XML files can now have repeated sections, allowing model files to be merged using the include element.
- All fields of mjVisual (i.e. the visualization options which are part of mjModel) are now exposed in the XML.
- The XML keywords for setting option bitflags are now enable/disable instead of true/false.
- mj_loadXML and mj_saveXML are now protected by an internal mutex and are thread-safe.
- Abstract visualization objects (geoms and lights) organized into new structure mjvObjects.
- New fields in mjVisual to control the near and far clipping planes and size of the offscreen rendering buffer.
- Functions for extended access to the OpenGL buffers, including depth map rendering as illustrated in the updated simulate.cpp.
- Bug fixes in the processing of size parameters of height fields and sites. Height field sizes are now defined in the asset section and not in the referencing geom, and include a new "base" size parameter.
- Height fields can now be loaded from PNG files in addition to the custom format. For collision purposes they are treated as a union of prisms, including the bottom part of the prisms.
- Planes and boxes are now rendered as multiple quads, improving lighting calculations and wireframe rendering.
- The positive Z axis of boxes can now be made reflective by using a reflective material. Note however that each reflective surface adds an entire rendering pass - so use reflective materials only when needed.
- 2D texture mapping is now allowed for planes and heightfields, in addition to cube texture mapping for all other shapes. A new "texscale" field in material determines the 2D texture scaling. The first texture loaded can be used as a skybox.
- Fixed bug in IMU simulation. The acceleration component was previously missing a term quadratic in the angular velocity.
- The inertial element now requires the pos attribute.
- Renamed efc_A, fc_A, e_Achol to efc_AR, fc_AR, e_ARchol respectively, because these matrices have the R matrix added to them.