diff --git a/doc/APIreference.rst b/doc/APIreference.rst index d4cbbe3c..b13b9468 100644 --- a/doc/APIreference.rst +++ b/doc/APIreference.rst @@ -1,7 +1,3 @@ - -.. include:: includes/macros.rst -.. include:: includes/roles.rst - ============= API Reference ============= @@ -3205,8 +3201,8 @@ Virtual file system | Virtual file system (VFS) functionality was introduced in MuJoCo 1.50. It enables the user to load all necessary files in memory, including MJB binary model files, XML files (MJCF, URDF and included files), STL meshes, PNGs for textures and height fields, and HF files in our custom height field format. Model and resource files in the VFS can also be - constructed programmatically (say using an XML library that writes to memory). Once all desired files are in the VFS, - the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When + constructed programmatically (say using a Python library that writes to memory). Once all desired files are in the + VFS, the user can call :ref:`mj_loadModel` or :ref:`mj_loadXML` with a pointer to the VFS. When this pointer is not NULL, the loaders will first check the VFS for any file they are about to load, and only access the disk if the file is not found in the VFS. The file names stored in the VFS have their name and extension but the path information is stripped; this can be bypassed however by using a custom path symbol in the file names, say @@ -5254,7 +5250,7 @@ mjui_add Add definitions to UI. mjui_addToSection -~~~~~~~~ +~~~~~~~~~~~~~~~~~ .. code-block:: C @@ -6426,7 +6422,7 @@ Insertion sort, resulting list is in increasing order. .. _mju_insertionSortInt: mju_insertionSortInt -~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~ .. code-block:: C diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index ceb727b1..beb104cd 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -1,7 +1,3 @@ - -.. include:: includes/macros.rst -.. include:: includes/roles.rst - ============= XML Reference ============= @@ -1512,7 +1508,7 @@ any effect. The settings here are global and apply to the entire model. hull computation is the slowest operation performed by the compiler). However once model design is finished, this feature should be enabled, because the availability of convex hulls substantially speeds up collision detection with large meshes. -:at:`userthread`: :at-val:`[false, true], "true"` +:at:`usethread`: :at-val:`[false, true], "true"` If this attribute is "true", the model compiler will run in multi-threaded mode. Currently multi-threading is only used when computing the length ranges of actuators, but in the future additional compiler phases may be multi-threaded. diff --git a/doc/changelog.rst b/doc/changelog.rst index b5785231..3b053b75 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -1,12 +1,111 @@ -.. include:: includes/macros.rst -.. include:: includes/roles.rst - ========= Changelog ========= -Version 2.1 (Oct. 18, 2021) ---------------------------- +Version 2.1.1 (Dec. 16, 2021) +----------------------------- + +API changes +^^^^^^^^^^^ + +1. Added ``mj_printFormattedModel``, which accepts a format string for floating point numbers, for example to increase + precision. +#. Added ``mj_versionString``, which returns human-readable string that represents the version of the MuJoCo binary. +#. Converted leading underscores to trailing underscores in private instances of API struct definitions, to conform to + reserved identifier directive, see + `C standard: Section 7.1.3 `__. + + .. attention:: + This is a minor breaking change. Code which references private instances will break. To fix, replace leading + underscores with trailing underscores, e.g. ``_mjModel`` |rarr| ``mjModel_``. + +General +^^^^^^^ + +4. Safer string handling: replaced ``strcat``, ``strcpy``, and ``sprintf`` with ``strncat``, ``strncpy``, and + ``snprintf`` respectively. +#. Changed indentation from 4 spaces to 2 spaces everywhere. + +Bug Fixes +^^^^^^^^^ + +6. Fixed reading from uninitialized memory in PGS solver. +#. Computed capsule inertias are now exact. Until this change, capsule masses and inertias computed by the + :ref:`compiler `'s :at:`inertiafromgeom` mechanism were approximated by a cylinder, formed by the + capsule's cylindrical middle section, extended on both ends by half the capsule radius. Capsule inertias are now + computed with the `Parallel Axis theorem `_, applied to the two + hemispherical end-caps. + + .. attention:: + This is a minor breaking change. Simulation of a model with automatically-computed capsule inertias will be + numerically different, leading to, for example, breakage of golden-value tests. +#. Fixed bug related to :ref:`force ` and :ref:`torque ` sensors. Until this change, forces + torques reported by F/T sensors ignored out-of-tree constraint wrenches except those produced by contacts. Force and + and torque sensors now correctly take into account the effects of :ref:`connect ` and + :ref:`weld ` constraints. + + .. note:: + Forces generated by :ref:`spatial tendons ` which are outside the kinematic tree (i.e. between bodies + which have no ancestral relationship) are still not taken into account by force and torque sensors. This remains a + future work item. + +Code samples +^^^^^^^^^^^^ + +9. ``testspeed``: Added injection of pseudo-random control noise, turned on by default. This is to avoid settling into + some fixed contact configuration and providing an unrealistic timing measure. +#. ``simulate``: + + a. Added slower-than-real-time functionality, which is controlled via the '+' and '-' keys. + #. Added sliders for injecting Brownian noise into the controls. + #. Added "Print Camera" button to print an MJCF clause with the pose of the current camera. + #. The camera pose is not reset when reloading the same model file. + +Updated dependencies +^^^^^^^^^^^^^^^^^^^^ + +11. ``TinyXML`` was replaced with ``TinyXML2`` 6.2.0. +#. ``qhull`` was upgraded to version 8.0.2. +#. ``libCCD`` was upgraded to version 1.4. +#. On Linux, ``libstdc++`` was replaced with ``libc++``. + +Binary build +^^^^^^^^^^^^ + +15. MacOS packaging. We now ship Universal binaries that natively support both Apple Silicon and Intel CPUs. + + a. MuJoCo library is now packaged as a + `Framework Bundle `_, + allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers are + encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files and + the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework. + #. Sample applications are now packaged into an Application Bundle called ``MuJoCo.app``. When launched via GUI, + the bundle launches the ``simulate`` executable. Other precompiled sample programs are shipped inside that bundle + (in ``MuJoCo.app/Contents/MacOS``) and can be launched via command line. + #. Binaries are now signed and the disk image is notarized. + +#. Windows binaries and libraries are now signed. +#. Link-time optimization is enabled on Linux and macOS, leading to an average of \~20% speedup when benchmarked on + three test models (``cloth.xml``, ``humanoid.xml``, and ``humanoid100.xml``). +#. Linux binaries are now built with LLVM/Clang instead of GCC. +#. An AArch64 (aka ARM64) Linux build is also provided. +#. Private symbols are no longer stripped from shared libraries on Linux and MacOS. + +Sample models +^^^^^^^^^^^^^ +21. Clean-up of the ``model/`` directory. + + a. Rearranged into subdirectories which include all dependencies. + #. Added descriptions in XML comments, cleaned up XMLs. + #. Deleted some composite models: ``grid1``, ``grid1pin``, ``grid2``, ``softcylinder``, ``softellipsoid``. + +#. Added descriptive animations in ``docs/images/models/`` : + +|humanoid| |particle| + + +Version 2.1.0 (Oct. 18, 2021) +----------------------------- New features ^^^^^^^^^^^^ @@ -63,3 +162,8 @@ Earlier Versions ---------------- For changelogs of earlier versions please see `roboti.us `_. + +.. |humanoid| image:: images/models/humanoid.gif + :width: 270px +.. |particle| image:: images/models/particle.gif + :width: 270px diff --git a/doc/conf.py b/doc/conf.py index 490b8f29..702268cf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -60,6 +60,12 @@ redirects = { 'index': 'overview.html', } +rst_prolog = """ +.. include:: includes/macros.rst +.. include:: includes/roles.rst +.. include:: +""" + # -- Options for autodoc ----------------------------------------------------- autodoc_default_options = { diff --git a/doc/images/models/flag.gif b/doc/images/models/flag.gif new file mode 100644 index 00000000..aff7896c Binary files /dev/null and b/doc/images/models/flag.gif differ diff --git a/doc/images/models/hammock.gif b/doc/images/models/hammock.gif new file mode 100644 index 00000000..de5a052d Binary files /dev/null and b/doc/images/models/hammock.gif differ diff --git a/doc/images/models/humanoid.gif b/doc/images/models/humanoid.gif new file mode 100644 index 00000000..485e8c65 Binary files /dev/null and b/doc/images/models/humanoid.gif differ diff --git a/doc/images/models/humanoid100.gif b/doc/images/models/humanoid100.gif new file mode 100644 index 00000000..75fa66ad Binary files /dev/null and b/doc/images/models/humanoid100.gif differ diff --git a/doc/images/models/particle.gif b/doc/images/models/particle.gif new file mode 100644 index 00000000..f5b31678 Binary files /dev/null and b/doc/images/models/particle.gif differ diff --git a/doc/images/models/softbox.gif b/doc/images/models/softbox.gif new file mode 100644 index 00000000..b71fa414 Binary files /dev/null and b/doc/images/models/softbox.gif differ diff --git a/doc/modeling.rst b/doc/modeling.rst index 3fa8fb97..1e74736c 100644 --- a/doc/modeling.rst +++ b/doc/modeling.rst @@ -1,7 +1,3 @@ - -.. include:: includes/macros.rst -.. include:: includes/roles.rst - ======== Modeling ======== @@ -94,7 +90,7 @@ MJCF Mechanisms MJCF uses several mechanisms for model creation which span multiple model elements. To avoid repetition we describe them in detail only once in this section. These mechanisms do not correspond to new simulation concepts beyond those -introduced in the Computation chapter. Their role is to simplify the creation of MJFC models, and to enable the use of +introduced in the Computation chapter. Their role is to simplify the creation of MJCF models, and to enable the use of different data formats without need for manual conversion to a canonical format. .. _CTree: @@ -144,7 +140,7 @@ the model. We start with an example. - + @@ -189,7 +185,7 @@ Some attributes, such as body position in models defined in global coordinates, This instructs the compiler to infer the corresponding value from other information, in this case the positions of the geoms attached to the body. The undefined state cannot be entered in the XML file. Therefore once an attribute is defined in a given class, it cannot be undefined in that class or in any of its child classes. So if the goal is to -leave a certain attribute undefined in a given model element, in must be undefined in the active defaults class. +leave a certain attribute undefined in a given model element, it must be undefined in the active defaults class. A final twist here are actuators. They are different because some of the actuator-related elements are actually shortcuts, and shortcuts interact with the defaults setting mechanism in a non-obvious way. This is explained in the @@ -236,7 +232,7 @@ When this model is compiled and saved as MJCF (in local coordinates) the same fr The body position was set to the geom position (1 0 0), while the geom and inertial positions were set to (0 0 0) relative to the body. -In principle the user always has a choice between local and global coordinates, but in practice this choice if viable +In principle the user always has a choice between local and global coordinates, but in practice this choice is viable only when using geometric primitives rather than meshes. For meshes, the 3D vertex positions are expressed in either local and global coordinates depending on how the mesh was designed - effectively forcing the user to adopt the same convention for the entire model. The alternative would be to pre-process the mesh data outside MuJoCo so as to change @@ -298,7 +294,7 @@ contact-related solver parameters at runtime, so as to experiment interactively continuation methods for numerical optimization. Here we focus on a single scalar constraint. Using slightly different notation from the Computation chapter, let a1 -denote the acceleration, v the velocity, r the position or residual (defined as 0 in friction dimensions), b and k the +denote the acceleration, v the velocity, r the position or residual (defined as 0 in friction dimensions), k and b the stiffness and damping of the virtual spring used to define the reference acceleration aref = -b*v - k*r. Let d be the constraint impedance, and a0 the acceleration in the absence of constraint force. Our earlier analysis revealed that the dynamics in constraint space are approximately @@ -405,7 +401,7 @@ friction function always generates contact frames oriented in the same way - which we do not describe here but it can be seen in the visualizer. For individual geoms however, we do not know which other geoms they might collide with and what their geom types might be, so there is no way to know how the contact tangent plane will be oriented when specifying - an individual geom. This is why MuJoCo does now allow anisotropic friction in the individual geom specifications, but + an individual geom. This is why MuJoCo does not allow anisotropic friction in the individual geom specifications, but only in the explicit contact pair specifications. margin, gap The maximum of the two geom margins (or gaps respectively) is used. The geom priority is ignored here, because the @@ -794,14 +790,13 @@ range. Pennation angle (i.e. the angle between the muscle and the line of force) is not modeled in MuJoCo and is assumed to be 0. This effect can be approximated by scaling down the muscle force and also adjusting the operating range. -Tendon wrapping is also more limited in MuJoCo. We allow spheres and infinite cylinders as wrapping objects, and -require two wrapping objects to be separated by a fixed site in the tendon path. This is to avoid the need for -iterative computations of tendon paths. As of MuJoCo 2.0 we also allow "side sites" to be placed inside the sphere or -cylinder, which causes an inverse wrap: the tendon path is constrained to pass through the object instead of go around -it. This can replace torus wrapping objects used in OpenSim to keep the tendon path within a given area. Overall, -tendon wrapping is the most challenging part of converting an OpenSim model to a MuJoCo model, and requires some -manual work. On the bright side, there is a small number of high-quality OpenSim models in use, so once they are -converted we are done. +Tendon wrapping is also more limited in MuJoCo. We allow spheres and infinite cylinders as wrapping objects, and require +two wrapping objects to be separated by a fixed site in the tendon path. This is to avoid the need for iterative +computations of tendon paths. As of MuJoCo 2.0 we also allow "side sites" to be placed inside the sphere or cylinder, +which causes an inverse wrap: the tendon path is constrained to pass through the object instead of going around it. This +can replace torus wrapping objects used in OpenSim to keep the tendon path within a given area. Overall, tendon wrapping +is the most challenging part of converting an OpenSim model to a MuJoCo model, and requires some manual work. On the +bright side, there is a small number of high-quality OpenSim models in use, so once they are converted we are done. Below we illustrate the four types of tendon wrapping available in MuJoCo 2.0. Note that the curved sections of the wrapping tendons are rendered as straight, but the geometry pipeline works with the actual curves and computes their @@ -848,17 +843,17 @@ of regular model elements that were automatically generated. So think of it as a compiler. Composite objects are made up of regular MuJoCo bodies, which we call "element bodies" in this context. The element -bodies are created as children of the body within which :el:`composite` appears; thus a composite object appears in -the same place in the XML where a regular child body may have been defined. Each automatically-generated element body -has a single geom attached to it, usually a sphere but could also be capsule or ellipsoid. Thus the composite object -is essentially a particle system, however the particles can be constrained to move together in ways that simulate -various flexible objects. The initial positions of the element bodies form a regular grid in 1D, 2D or 3D. They could -all be children of the parent body (which can be the world or another regular body; composite objects cannot be -nested) and have joints allowing motion relative to the parent, or they could form a kinematic tree with joints -between the element bodies. They can also be connected with tendons with soft equality constraints on the tendon -length, creating the necessary coupling. Joint equality constraints are also used in some cases. The :at:`solref` -and :at:`solimp` attributes of these equality constraints can be adjusted by the user, thereby adjusting the -softness and flexibility of the composite objects. +bodies are created as children of the body within which :el:`composite` appears; thus a composite object appears in the +same place in the XML where a regular child body may have been defined. Each automatically-generated element body has a +single geom attached to it, usually a sphere but could also be a capsule or an ellipsoid. Thus the composite object is +essentially a particle system, however the particles can be constrained to move together in ways that simulate various +flexible objects. The initial positions of the element bodies form a regular grid in 1D, 2D or 3D. They could all be +children of the parent body (which can be the world or another regular body; composite objects cannot be nested) and +have joints allowing motion relative to the parent, or they could form a kinematic tree with joints between the element +bodies. They can also be connected with tendons with soft equality constraints on the tendon length, creating the +necessary coupling. Joint equality constraints are also used in some cases. The :at:`solref` and :at:`solimp` attributes +of these equality constraints can be adjusted by the user, thereby adjusting the softness and flexibility of the +composite objects. In addition to setting up the physics, the composite object generator creates suitable rendering. 2D and 3D objects can be rendered as :ref:`skins ` which are also new in MuJoCo 2.0. The skin is generated @@ -1046,7 +1041,7 @@ points to the outside, thus creating a thicker shell which is harder to penetrat -Cylinders and ellipsoids are created in the same was as boxes. The only difference is that the reference positions of +Cylinders and ellipsoids are created in the same way as boxes. The only difference is that the reference positions of the element bodies (relative to the parent) are projected on a cylinder or ellipsoid, with size implied by the :at:`count` attribute. The automatic skin generator is aware of the smooth surfaces, and adjusts the skin normals accordingly. In the plots we have used the capsule probe to press on each body, then paused the simulation and moved the @@ -1129,7 +1124,7 @@ modeled. This is why we have implemented support for URDF even though it can onl elements available in MuJoCo. In addition to standard URDF files, MuJoCo can load files that have a custom (from the viewpoint of URDF) :el:`mujoco` element as a child of the top-level element :el:`robot`. This custom element can have sub-elements :ref:`compiler `, :ref:`option