Version 2.1.1: Binaries for ARM64, proper macOS bundles, minor bugfixes.

Closes #2
Closes #42
Closes #59

PiperOrigin-RevId: 416794598
Change-Id: I1306df1127d6acecf2323873c0da0910f35d31a0

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
 

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.

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 <www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf>`__.
+
+   .. 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 <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 <https://en.wikipedia.org/wiki/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 <sensor-force>` and :ref:`torque <sensor-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 <equality-connect>` and
+   :ref:`weld <equality-weld>` constraints.
+
+   .. note::
+      Forces generated by :ref:`spatial tendons <spatial>` 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 <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html>`_,
+       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 <https://www.roboti.us/download.html>`_.
+
+.. |humanoid| image:: images/models/humanoid.gif
+   :width: 270px
+.. |particle| image:: images/models/particle.gif
+   :width: 270px

doc/conf.py

@@ -60,6 +60,12 @@ redirects = {
     'index': 'overview.html',
 }
 
+rst_prolog = """
+.. include:: includes/macros.rst
+.. include:: includes/roles.rst
+.. include:: <isonum.txt>
+"""
+
 # -- Options for autodoc -----------------------------------------------------
 
 autodoc_default_options = {

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.
                <geom type="ellipsoid"/>
                <geom type="sphere" rgba="0 0 1 0"/>
                <geom type="cylinder" class="main"/>
-           </geom>
+           </body>
        </worldbody>
    </mujoco>
 
@@ -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 <skin>` 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
        </composite>
    </body>
 
-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 <compiler>`, :ref:`option <option>`,
-:ref:`size <size>` with the same functionality as in MJFC, except that the default compiler settings
+:ref:`size <size>` with the same functionality as in MJCF, except that the default compiler settings
 are modified so as to accomodate the URDF modeling convention. The :ref:`compiler <compiler>` extension
 in particular has proven very useful, and indeed several of its attributes were introduced because a number of
 existing URDF models have non-physical dynamics parameters which MuJoCo's built-in compiler will reject if left
@@ -1300,10 +1295,10 @@ virtual objects cannot push on your physical hand, so your hand (and thereby the
 violate the simulated physics. But at the same time we want the resulting simulation to be reasonable. How do we do
 this?
 
-The first step is to define a mocap body in the MJCF model, and at implement code that reads the data stream at
-runtime and sets mjModel.mocap_pos and mjModel.mocap_quat to the position and orientation received from the motion
-capture system. The `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ code sample uses
-the mouse as a motion capture device, allowing the user to move mocap bodies around.
+The first step is to define a mocap body in the MJCF model, and implement code that reads the data stream at runtime and
+sets mjModel.mocap_pos and mjModel.mocap_quat to the position and orientation received from the motion capture system.
+The `simulate.cc <https://github.com/deepmind/mujoco/blob/main/sample/simulate.cc>`_ code sample uses the mouse as a
+motion capture device, allowing the user to move mocap bodies around.
 
 The key thing to understand about mocap bodies is that the simulator treats them as being fixed. We are causing them
 to move from one simulation time step to the next by updating their position and orientation directly, but as far as

doc/programming.rst

@@ -1,7 +1,3 @@
-
-.. include:: includes/macros.rst
-.. include:: includes/roles.rst
-
 ===========
 Programming
 ===========