Version 2.1.2: Python bindings, OBJ assets support, bugfixes.

PiperOrigin-RevId: 434731612
Change-Id: I0cfda3e7a3d1c72036764986efc252ffa1b8c6b0

Author: saran-t

doc/APIreference.rst

@@ -2,6 +2,83 @@
 Changelog
 =========
 
+Version 2.1.2 (Date TBD, 2022)
+------------------------------
+
+New modules
+^^^^^^^^^^^
+
+1. Added new :doc:`Python bindings<python>`, which can be installed via ``pip install mujoco``,
+   and imported as ``import mujoco``.
+#. Added new :doc:`Unity plug-in<unity>`.
+#. Added a new ``introspect`` module, which provides reflection-like capability for MuJoCo's public API, currently
+   describing functions and enums. While implemented in Python, this module is expected to be generally useful for
+   automatic code generation targeting multiple languages. (This is not shipped as part of the ``mujoco`` Python
+   bindings package.)
+
+API changes
+^^^^^^^^^^^
+
+4. Moved definition of ``mjtNum`` floating point type into a new header
+   `mjtnum.h <https://github.com/deepmind/mujoco/blob/main/include/mjtnum.h>`_.
+#. Renamed header `mujoco_export.h` to :ref:`mjexport.h<inHeader>`.
+#. Added ``mj_printFormattedData``, which accepts a format string for floating point numbers, for example to increase
+   precision.
+
+General
+^^^^^^^
+
+7. MuJoCo can load `OBJ <https://en.wikipedia.org/wiki/Wavefront_.obj_file>`_ mesh files.
+
+   a. Meshes containing polygons with more than 4 vertices are not supported.
+   #. In OBJ files containing multiple object groups, any groups after the first one will be ignored.
+
+#. Added optional frame-of-reference specification to :ref:`framepos<sensor-framepos>`,
+   :ref:`framequat<sensor-framequat>`, :ref:`framexaxis<sensor-framexaxis>`, :ref:`frameyaxis<sensor-frameyaxis>`,
+   :ref:`framezaxis<sensor-framezaxis>`, :ref:`framelinvel<sensor-framelinvel>`, and
+   :ref:`frameangvel<sensor-frameangvel>` sensors. The frame-of-reference is specified by new :at:`reftype` and
+   :at:`refname` attributes.
+
+#. Sizes of :ref:`user parameters <CUser>` are now automatically inferred.
+
+   a. Declarations of user parameters in the top-level :ref:`size <size>` clause (e.g. :at:`nuser_body`,
+      :at:`nuser_jnt`, etc.) now accept a value of -1, which is the default. This will automatically set the value to
+      the length of the maximum associated :at:`user` attribute defined in the model.
+   #. Setting a value smaller than -1 will lead to a compiler error (previously a segfault).
+   #. Setting a value to a length smaller than some :at:`user` attribute defined in the model will lead to an error
+      (previously additional values were ignored).
+
+#. Increased the maximum number of lights in an :ref:`mjvScene` from 8 to 100.
+
+#. Saved XML files only contain explicit :ref:`inertial <inertial>` elements if the original XML included them. Inertias
+   that were automatically inferred by the compiler's :ref:`inertiafromgeom <compiler>` mechanism remain unspecified.
+
+#. User-selected geoms are always rendered as opaque. This is useful in interactive visualizers.
+
+#. Static geoms now respect their :ref:`geom group<geom>` for visualisation. Until this change rendering of static geoms
+   could only be toggled using the :ref:`mjVIS_STATIC<mjtVisFlag>` visualisation flag . After this change, both the geom
+   group and the visualisation flag need to be enabled for the geom to be rendered.
+
+#. Pointer parameters in function declarations in :ref:`mujoco.h<inHeader>` that are supposed to represent fixed-length
+   arrays are now spelled as arrays with extents, e.g. ``mjtNum quat[4]`` rather than ``mjtNum* quat``. From the
+   perspective of C and C++, this is a non-change since array types in function signatures decay to pointer types.
+   However, it allows autogenerated code to be aware of expected input shapes.
+
+Bug Fixes
+^^^^^^^^^
+
+15. ``mj_loadXML`` and ``mj_saveLastXML`` are now locale-independent. The Unity plugin should now work correctly for
+    users whose system locales use commas as decimal separators.
+#.  XML assets in VFS no longer need to end in a null character. Instead, the file size is determined by the size
+    parameter of the corresponding VFS entry.
+#.  Fix a vertex buffer object memory leak in ``mjrContext`` when skins are used.
+#.  Camera quaternions are now normalized during XML compilation.
+
+Binary build
+^^^^^^^^^^^^
+
+18. Windows binaries are now built with Clang.
+
 Version 2.1.1 (Dec. 16, 2021)
 -----------------------------
 
@@ -45,7 +122,7 @@ Bug Fixes
    :ref:`weld <equality-weld>` constraints.
 
    .. note::
-      Forces generated by :ref:`spatial tendons <spatial>` which are outside the kinematic tree (i.e. between bodies
+      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.
 
@@ -118,7 +195,7 @@ New features
 General
 ^^^^^^^
 
-3. The pre-allocated sizes in the virtual file system (VFS) increased to 2000 and 1000, to allow for larger projects.
+3. The preallocated sizes in the virtual file system (VFS) increased to 2000 and 1000, to allow for larger projects.
 #. The C structs in the ``mjuiItem`` union are now named, for compatibility.
 #. Fixed: ``mjcb_contactfilter`` type is ``mjfConFilt`` (was ``mjfGeneric``).
 #. Fixed: The array of sensors in ``mjCModel`` was not cleared.

doc/XMLreference.rst

@@ -189,7 +189,7 @@ change at runtime. In that case there is still a fixed enumeration order (corres
 elements appear in ``mjModel``) but any inactive constraints are omitted.
 
 The number of position coordinates :math:`n_Q` is larger than the number of degrees of freedom :math:`n_V` whenever
-quaternions are used to represent 3D orientations. This occurs when the model contains ball joints or free joints (i.e.
+quaternions are used to represent 3D orientations. This occurs when the model contains ball joints or free joints (i.e.,
 in most models). In that case :math:`\dot{q}` does not equal :math:`v`, at least not in the usual sense. Instead one has
 to consider the group of rigid body orientations :math:`SO(3)` - which has the geometry of a unit sphere in 4D space.
 Velocities live in the 3D tangent space to this sphere. This is taken into account by all internal computations. For
@@ -326,7 +326,7 @@ Passive forces
 Passive forces are defined as forces that depend only on position and velocity, and not on control in forward dynamics
 or acceleration in inverse dynamics. As a result, such forces are inputs to both the forward and inverse dynamics
 computations, and are identical in both cases. They are stored in ``mjData.qfrc_passive``. The passive forces computed
-by MuJoCo are also passive in the sense of physics, i.e. they do not increase energy, however the user can install the
+by MuJoCo are also passive in the sense of physics, i.e., they do not increase energy, however the user can install the
 callback :ref:`mjcb_passive` and add forces to ``mjData.qfrc_passive`` that may increase energy. This will not interfere
 with MuJoCo's operation as long as such user forces depend only on position and velocity.
 
@@ -460,7 +460,7 @@ constraint contributes :math:`\dim(r)` elements to the total constraint count :m
 properties of quaternions, differentiation with respect to :math:`q` produces vectors of size :math:`n_V` rather than
 :math:`n_Q`.
 
-Among other applications, equality constraints can be used to create "loop joints", i.e. joints that cannot be modeled
+Among other applications, equality constraints can be used to create "loop joints", i.e., joints that cannot be modeled
 via the kinematic tree. Gaming engines represent all joints in this way. The same can be done in MuJoCo but is not
 recommended - because it leads to both slower and less accurate simulation, effectively turning MuJoCo into a gaming
 engine. The only reason to represent joints with equality constraints would be to model soft joints - which can be done
@@ -562,7 +562,7 @@ with a 1 at the joint address. For tendons this is known as the moment arm vecto
    spatial tendons this could be used to model friction between the tendon and the surfaces it wraps around. Such
    friction will be load-independent though. To construct a more detailed model of this phenomenon, create several small
    floating spheres and connect them with tendons in series. Then the contacts between the spheres and the surrounding
-   surfaces will have load-dependent (i.e. Coulomb) friction, but this is less efficient to simulate.
+   surfaces will have load-dependent (i.e., Coulomb) friction, but this is less efficient to simulate.
 
 .. _coLimit:
 
@@ -588,7 +588,7 @@ because solving for equality constraint forces is generally faster.
 ``joint`` : 1 or 2
    Limits can be defined for scalar joints (hinge and slide) as well as for ball joints. Scalar joints are treated as
    described above. Ball joint limits are applied to the exponential-map or angle-axis representation of the joint
-   quaternion, i.e. the vector :math:`(\theta x, \theta y, \theta z)` where :math:`\theta` is the rotation angle and
+   quaternion, i.e., the vector :math:`(\theta x, \theta y, \theta z)` where :math:`\theta` is the rotation angle and
    :math:`(x, y, z)` is the unit vector corresponding to the rotation axis. The limit is applied to the absolute value
    of the rotation angle :math:`\theta`. At runtime the limit is determined by the larger of the two range parameters.
    For semantic clarity however, one should use the second range parameter to specify the limit and set the first range
@@ -1022,7 +1022,7 @@ compute it.
 
 Note that the quadratic term in the inverse problem is weighted by :math:`R` instead of :math:`A+R`. This tells us two
 things. First, in the limit :math:`R \to 0` corresponding to hard constraints the inverse is no longer defined, as one
-would expect. Second and more useful, the inverse problem is diagonal, i.e. it decouples into independent optimization
+would expect. Second and more useful, the inverse problem is diagonal, i.e., it decouples into independent optimization
 problems over the individual constraint forces. The only remaining coupling is due to the constraint set :math:`\Omega`,
 but that set is also decoupled over the conceptual constraints discussed earlier. It turns out that all these
 independent optimization problems can be solved analytically. The only non-trivial case is the elliptic friction cone
@@ -1110,7 +1110,7 @@ Substituting :math:`f^+` in the constraint dynamics :eq:`eq:identity` and rearra
 
 Thus the constrained acceleration interpolates between the unconstrained and the reference acceleration. In particular,
 in the limit :math:`R \to 0` we have a hard constraint and :math:`a^1 = a^*`, while in the limit :math:`R \to \infty` we
-have have an infinitely soft constraint (i.e. no constraint) and :math:`a^1 = a^0`. It is then natural to introduce a
+have have an infinitely soft constraint (i.e., no constraint) and :math:`a^1 = a^0`. It is then natural to introduce a
 model parameter which directly controls the interpolation. We call this parameter *impedance* and denote it :math:`d`.
 It is a vector with dimensionality :math:`n_C` satisfying :math:`0<d<1` element-wise. Once it is specified, we compute
 the diagonal elements of the regularizer as

doc/changelog.rst

@@ -1,4 +1,4 @@
-## Copyright 2021 DeepMind Technologies Limited
+# Copyright 2021 DeepMind Technologies Limited
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -8,13 +8,11 @@
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or  implied.
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Configuration file for the Sphinx documentation builder."""
 
-import doctest
-import inspect
 import os
 import sys
 

doc/computation.rst

@@ -13,5 +13,6 @@
    XMLreference
    programming
    APIreference
+   python
    unity
    changelog