Merge branch 'usd-integration' of github.com:awesome-aj0123/mujoco into usd-integration

.github/workflows/build.yml

@@ -25,23 +25,31 @@ jobs:
       matrix:
         include:
           - os: ubuntu-22.04
-            additional_label: "with GCC 11"
+            additional_label: "-gcc-12"
+            cmake_args: >-
+              -G Ninja
+              -DCMAKE_C_COMPILER:STRING=gcc-12
+              -DCMAKE_CXX_COMPILER:STRING=g++-12
+              -DCMAKE_EXE_LINKER_FLAGS:STRING=-Wl,--no-as-needed
+            tmpdir: "/tmp"
+          - os: ubuntu-22.04
+            additional_label: "-gcc-11"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=gcc-11
               -DCMAKE_CXX_COMPILER:STRING=g++-11
               -DCMAKE_EXE_LINKER_FLAGS:STRING=-Wl,--no-as-needed
             tmpdir: "/tmp"
-          - os: ubuntu-20.04
+          - os: ubuntu-22.04
-            additional_label: "with GCC 10"
+            additional_label: "-gcc-10"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=gcc-10
               -DCMAKE_CXX_COMPILER:STRING=g++-10
               -DCMAKE_EXE_LINKER_FLAGS:STRING=-Wl,--no-as-needed
             tmpdir: "/tmp"
-          - os: ubuntu-20.04
+          - os: ubuntu-22.04
-            additional_label: "with GCC 9"
+            additional_label: "-gcc-9"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=gcc-9
@@ -49,7 +57,7 @@ jobs:
               -DCMAKE_EXE_LINKER_FLAGS:STRING=-Wl,--no-as-needed
             tmpdir: "/tmp"
           - os: ubuntu-22.04
-            additional_label: "with Clang 14"
+            additional_label: "-clang-14"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=clang-14
@@ -57,15 +65,15 @@ jobs:
               -DMUJOCO_HARDEN:BOOL=ON
             tmpdir: "/tmp"
           - os: ubuntu-22.04
-            additional_label: "with Clang 13"
+            additional_label: "-clang-13"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=clang-13
               -DCMAKE_CXX_COMPILER:STRING=clang++-13
               -DMUJOCO_HARDEN:BOOL=ON
             tmpdir: "/tmp"
-          - os: ubuntu-22.04
+          - os: ubuntu-20.04
-            additional_label: "with Clang 12"
+            additional_label: "-clang-12"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=clang-12
@@ -73,7 +81,7 @@ jobs:
               -DMUJOCO_HARDEN:BOOL=ON
             tmpdir: "/tmp"
           - os: ubuntu-20.04
-            additional_label: "with Clang 11"
+            additional_label: "-clang-11"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=clang-11
@@ -81,7 +89,7 @@ jobs:
               -DMUJOCO_HARDEN:BOOL=ON
             tmpdir: "/tmp"
           - os: ubuntu-20.04
-            additional_label: "with Clang 10"
+            additional_label: "-clang-10"
             cmake_args: >-
               -G Ninja
               -DCMAKE_C_COMPILER:STRING=clang-10
@@ -98,13 +106,8 @@ jobs:
               -DCMAKE_SYSTEM_VERSION="10.0.22621.0"
             cmake_build_args: "-- -m"
             tmpdir: "C:/Temp"
-          - os: windows-2019
-            cmake_args: >-
-              -DCMAKE_SYSTEM_VERSION="10.0.22621.0"
-            cmake_build_args: "-- -m"
-            tmpdir: "C:/Temp"
 
-    name: "MuJoCo on ${{ matrix.os }} ${{ matrix.additional_label }}"
+    name: "${{ matrix.os }}${{ matrix.additional_label }}"
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -216,7 +219,7 @@ jobs:
       working-directory: python/dist
       run: >
         source ${{ matrix.tmpdir }}/venv/bin/activate &&
-        pip install mujoco-*.whl
+        pip install --no-deps --no-index mujoco-*.whl
     - name: Test Python bindings
       if: ${{ runner.os != 'Windows' }}
       shell: bash
@@ -225,3 +228,23 @@ jobs:
       run: >
         source ${{ matrix.tmpdir }}/venv/bin/activate &&
         pytest -v --pyargs mujoco
+    - name: Notify team chat
+      shell: bash
+      env:
+        GCHAT_API: ${{ secrets.GCHAT_API }}
+        JOB_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/\
+          ${{ github.run_id }}"
+      if: ${{ failure() && github.event_name == 'push' && env.GCHAT_API != '' }}
+      run: >
+        curl
+        "$GCHAT_API&threadKey=$GITHUB_SHA&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
+        -X POST
+        -H "Content-Type: application/json"
+        -d "{
+        'text': '<$JOB_URL|*FAILURE*>:
+        job \`${{ matrix.os }}${{ matrix.additional_label }}\`
+        commit \`$(echo $GITHUB_SHA | head -c6)\`\n
+        \`\`\`Author: ${{ github.event.head_commit.author.name }}
+        <${{ github.event.head_commit.author.email }}>
+        \n\n${{ github.event.head_commit.message }}\`\`\`
+        '}"

cmake/MujocoDependencies.cmake

@@ -39,22 +39,22 @@ set(MUJOCO_DEP_VERSION_qhull
     CACHE STRING "Version of `qhull` to be fetched."
 )
 set(MUJOCO_DEP_VERSION_Eigen3
-    211c5dfc6741a5570ad007983c113ef4d144f9f3
+    e8515f78ac098329ab9f8cab21c87caede090a3f
     CACHE STRING "Version of `Eigen3` to be fetched."
 )
 
 set(MUJOCO_DEP_VERSION_abseil
-    c2435f8342c2d0ed8101cb43adfd605fdc52dca2 # LTS 20230125.3
+    fb3621f4f897824c0dbe0615fa94543df6192f30 # LTS 20230802.1
     CACHE STRING "Version of `abseil` to be fetched."
 )
 
 set(MUJOCO_DEP_VERSION_gtest
-    b796f7d44681514f58a683a3a71ff17c94edb0c1 # v1.13.0
+    f8d7d77c06936315286eb55f8de22cd23c188571 # v1.14.0
     CACHE STRING "Version of `gtest` to be fetched."
 )
 
 set(MUJOCO_DEP_VERSION_benchmark
-    2dd015dfef425c866d9a43f2c67d8b52d709acb6 # v1.8.0
+    344117638c8ff7e239044fd0fa7085839fc03021 # v1.8.3
     CACHE STRING "Version of `benchmark` to be fetched."
 )
 

cmake/sdflib-optional-dependencies.patch

@@ -1,8 +1,8 @@
 diff --git a/CMakeLists.txt b/CMakeLists.txt
-index 20551cf..9145032 100644
+index 20551cf..0d2a364 100644
 --- a/CMakeLists.txt
 +++ b/CMakeLists.txt
-@@ -70,14 +70,21 @@ add_custom_target(copyShaders ALL SOURCES ${SHADER_FILES})
+@@ -70,15 +70,25 @@ add_custom_target(copyShaders ALL SOURCES ${SHADER_FILES})
  # Add dependencies
  add_subdirectory(libs)
  
@@ -16,19 +16,25 @@ index 20551cf..9145032 100644
 +    target_link_libraries(${PROJECT_NAME} PUBLIC assimp)
 +    target_compile_definitions(${PROJECT_NAME} PUBLIC -DASSIMP_AVAILABLE)
 +endif()
++
++if(SDFLIB_BUILD_APPS OR SDFLIB_BUILD_DEBUG_APPS)
++    target_link_libraries(${PROJECT_NAME} PUBLIC args)
++    target_link_libraries(${PROJECT_NAME} PUBLIC stb_image)
++endif()
 +    
  target_link_libraries(${PROJECT_NAME} PUBLIC glm)
 -target_link_libraries(${PROJECT_NAME} PUBLIC assimp)
- target_link_libraries(${PROJECT_NAME} PUBLIC args)
+-target_link_libraries(${PROJECT_NAME} PUBLIC args)
  target_link_libraries(${PROJECT_NAME} PUBLIC spdlog)
  target_link_libraries(${PROJECT_NAME} PUBLIC cereal)
 -target_link_libraries(${PROJECT_NAME} PUBLIC enoki)
 -target_link_libraries(${PROJECT_NAME} PUBLIC eigen)
 -target_link_libraries(${PROJECT_NAME} PUBLIC fcpw)
- target_link_libraries(${PROJECT_NAME} PUBLIC stb_image)
+-target_link_libraries(${PROJECT_NAME} PUBLIC stb_image)
  target_link_libraries(${PROJECT_NAME} PUBLIC icg)
  
-@@ -86,17 +93,22 @@ if(CMAKE_CXX_COMPILER_ID MATCHES GNU)
+ if(CMAKE_CXX_COMPILER_ID MATCHES GNU)
+@@ -86,17 +96,22 @@ if(CMAKE_CXX_COMPILER_ID MATCHES GNU)
  endif()
  
  # Add openMP
@@ -62,7 +68,7 @@ index 20551cf..9145032 100644
  
  # Add executable
  if (NOT UNIX)
-@@ -160,6 +172,7 @@ if(SDFLIB_BUILD_DEBUG_APPS)
+@@ -160,6 +175,7 @@ if(SDFLIB_BUILD_DEBUG_APPS)
      add_executable(GJKtest src/tools/GJKtest/main.cpp)
      target_link_libraries(GJKtest PUBLIC ${PROJECT_NAME})
  
@@ -269,10 +275,10 @@ index 9f930ed..6ee2304 100644
 \ No newline at end of file
 +#endif
 diff --git a/libs/CMakeLists.txt b/libs/CMakeLists.txt
-index b48bf39..3f143c8 100644
+index b48bf39..ea22b9a 100644
 --- a/libs/CMakeLists.txt
 +++ b/libs/CMakeLists.txt
-@@ -14,23 +14,25 @@ if(NOT glm_lib_POPULATED)
+@@ -14,37 +14,41 @@ if(NOT glm_lib_POPULATED)
  endif()
  
  # assimp
@@ -314,7 +320,34 @@ index b48bf39..3f143c8 100644
  endif()
  
  # args
-@@ -76,43 +78,47 @@ if(NOT cereal_lib_POPULATED)
+-FetchContent_Declare(args_lib
+-  GIT_REPOSITORY https://github.com/Taywee/args.git
+-  GIT_TAG a48e1f880813b367d2354963a58dedbf2b708584 # 6.3.0
+-)
+-
+-FetchContent_GetProperties(args_lib)
+-if(NOT args_lib_POPULATED)
+-	FetchContent_Populate(args_lib)
+-	add_library(args INTERFACE)
+-	target_include_directories(args INTERFACE ${args_lib_SOURCE_DIR})
+-endif()
++if(SDFLIB_BUILD_APPS OR SDFLIB_BUILD_DEBUG_APPS)
++	FetchContent_Declare(args_lib
++	  GIT_REPOSITORY https://github.com/Taywee/args.git
++	  GIT_TAG a48e1f880813b367d2354963a58dedbf2b708584 # 6.3.0
++	)
++	
++	FetchContent_GetProperties(args_lib)
++	if(NOT args_lib_POPULATED)
++		FetchContent_Populate(args_lib)
++		add_library(args INTERFACE)
++		target_include_directories(args INTERFACE ${args_lib_SOURCE_DIR})
++	endif()
++ endif()
+ 
+ # spdlog
+ FetchContent_Declare(spdlog_lib
+@@ -76,47 +80,53 @@ if(NOT cereal_lib_POPULATED)
  endif()
  
  # Enoki
@@ -395,7 +428,15 @@ index b48bf39..3f143c8 100644
 + endif()
  
  # stb
- add_library(stb_image INTERFACE)
+-add_library(stb_image INTERFACE)
+-target_include_directories(stb_image INTERFACE stb)
++if(SDFLIB_BUILD_APPS OR SDFLIB_BUILD_DEBUG_APPS)
++	add_library(stb_image INTERFACE)
++	target_include_directories(stb_image INTERFACE stb)
++ endif()
+ 
+ # icg
+ add_library(icg INTERFACE)
 diff --git a/src/sdf/OctreeSdf.cpp b/src/sdf/OctreeSdf.cpp
 index ef8ed4d..0e1eb97 100644
 --- a/src/sdf/OctreeSdf.cpp

doc/APIreference/APIglobals.rst

@@ -489,6 +489,10 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr
      - 1000
      - Maximum number of textures allowed.
        Defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_.
+   * - ``mjMAXTHREADS``
+     - 128
+     - Maximum number OS threads that can be used in a thread pool.
+       Defined in `mjthread.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjthread.h>`_.
    * - ``mjMAXUISECT``
      - 10
      - Maximum number of UI sections.

doc/APIreference/APItypes.rst

@@ -174,18 +174,6 @@ Numerical integrator types. These values are used in ``m->opt.integrator``.
 
 .. mujoco-include:: mjtIntegrator
 
-
-.. _mjtCollision:
-
-mjtCollision
-~~~~~~~~~~~~
-
-Collision modes specifying how candidate geom pairs are generated for near-phase collision checking. These values are
-used in ``m->opt.collision``.
-
-.. mujoco-include:: mjtCollision
-
-
 .. _mjtCone:
 
 mjtCone
@@ -514,6 +502,18 @@ These are the possible framebuffers. They are used as an argument to the functio
 .. mujoco-include:: mjtFramebuffer
 
 
+.. _mjtDepthMap:
+
+mjtDepthMap
+~~~~~~~~~~~
+
+These are the depth mapping options. They are used as a value for the ``readPixelDepth`` attribute of the
+:ref:`mjrContext` struct, to control how the depth returned by :ref:`mjr_readPixels` is mapped from
+``znear`` to ``zfar``.
+
+.. mujoco-include:: mjtDepthMap
+
+
 .. _mjtFontScale:
 
 mjtFontScale

doc/APIreference/functions.rst

@@ -413,7 +413,7 @@ mj_differentiatePos
 This function subtracts two vectors in the format of qpos (and divides the result by dt), while respecting the
 properties of quaternions. Recall that unit quaternions represent spatial orientations. They are points on the unit
 sphere in 4D. The tangent to that sphere is a 3D plane of rotational velocities. Thus when we subtract two quaternions
-in the right way, the result is a 3D vector and not a 4D vector. This the output qvel has dimensionality nv while the
+in the right way, the result is a 3D vector and not a 4D vector. Thus the output qvel has dimensionality nv while the
 inputs have dimensionality nq.
 
 .. _mj_integratePos:
@@ -724,6 +724,15 @@ mj_camlight
 
 Compute camera and light positions and orientations.
 
+.. _mj_flex:
+
+mj_flex
+~~~~~~~
+
+.. mujoco-include:: mj_flex
+
+Compute flex-related quantities.
+
 .. _mj_tendon:
 
 mj_tendon
@@ -948,6 +957,16 @@ mju_rayGeom
 
 Intersect ray with pure geom, return nearest distance or -1 if no intersection.
 
+.. _mju_rayFlex:
+
+mju_rayFlex
+~~~~~~~~~~~
+
+.. mujoco-include:: mju_rayFlex
+
+Intersect ray with flex, return nearest distance or -1 if no intersection,
+and also output nearest vertex id.
+
 .. _mju_raySkin:
 
 mju_raySkin
@@ -1251,12 +1270,12 @@ mj_freeStack
 Free the current :ref:`mjData` stack frame. All pointers returned by mj_stackAlloc since the last call
 to mj_markStack must no longer be used afterwards.
 
-.. _mj_stackAlloc:
+.. _mj_stackAllocByte:
 
-mj_stackAlloc
+mj_stackAllocByte
-~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 
-.. mujoco-include:: mj_stackAlloc
+.. mujoco-include:: mj_stackAllocByte
 
 Allocate a number of bytes on :ref:`mjData` stack at a specific alignment.
 Call mju_error on stack overflow.
@@ -3256,6 +3275,9 @@ These matrices and their dimensions are:
 - All outputs are optional (can be NULL).
 - ``eps`` is the finite-differencing epsilon.
 - ``flg_centered`` denotes whether to use forward (0) or centered (1) differences.
+- Accuracy can be somewhat improved if solver :ref:`iterations<option-iterations>` are set to a
+  fixed (small) value and solver :ref:`tolerance<option-tolerance>` is set to 0. This insures that
+  all calls to the solver will perform exactly the same number of iterations.
 
 .. _mjd_inverseFD:
 
@@ -3446,6 +3468,15 @@ mju_threadPoolCreate
 
 Create a thread pool with the specified number of threads running.
 
+.. _mju_bindThreadPool:
+
+mju_bindThreadPool
+~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_bindThreadPool
+
+Adds a thread pool to :ref:`mjData` and configures it for multi-threaded use.
+
 .. _mju_threadPoolEnqueue:
 
 mju_threadPoolEnqueue

doc/APIreference/functions_override.rst

@@ -159,7 +159,7 @@ we want to add the result to a different vector.
 This function subtracts two vectors in the format of qpos (and divides the result by dt), while respecting the
 properties of quaternions. Recall that unit quaternions represent spatial orientations. They are points on the unit
 sphere in 4D. The tangent to that sphere is a 3D plane of rotational velocities. Thus when we subtract two quaternions
-in the right way, the result is a 3D vector and not a 4D vector. This the output qvel has dimensionality nv while the
+in the right way, the result is a 3D vector and not a 4D vector. Thus the output qvel has dimensionality nv while the
 inputs have dimensionality nq.
 
 .. _mj_integratePos:
@@ -463,6 +463,9 @@ These matrices and their dimensions are:
 - All outputs are optional (can be NULL).
 - ``eps`` is the finite-differencing epsilon.
 - ``flg_centered`` denotes whether to use forward (0) or centered (1) differences.
+- Accuracy can be somewhat improved if solver :ref:`iterations<option-iterations>` are set to a
+  fixed (small) value and solver :ref:`tolerance<option-tolerance>` is set to 0. This insures that
+  all calls to the solver will perform exactly the same number of iterations.
 
 .. _mjd_inverseFD:
 

doc/XMLreference.rst

@@ -146,13 +146,12 @@ any effect. The settings here are global and apply to the entire model.
 
 .. _compiler-autolimits:
 
-:at:`autolimits`: :at-val:`[false, true], "false"`
+:at:`autolimits`: :at-val:`[false, true], "true"`
    This attribute affects the behavior of attributes such as "limited" (on <body-joint> or <tendon>), "forcelimited",
    "ctrllimited", and "actlimited" (on <actuator>). If "true", these attributes are unnecessary and their value
    will be inferred from the presence of their corresponding "range" attribute.
    If "false", no such inference will happen: For a joint to be limited, both limited="true" and range="min max" must
    be specified. In this mode, it is an error to specify a range without a limit.
-   |br| The default for this option will be set to "true" in an upcoming release.
 
 .. _compiler-boundmass:
 
@@ -1322,9 +1321,9 @@ also known as terrain map, is a 2D matrix of elevation data. The data can be spe
 
 .. _asset-hfield-content_type:
 
-:at:`content_type`: :at-val:`string, optional`
+:at:`content_type`: :at-val: `string, optional`
    If the file attribute is specified, then this sets the
-   `Media Type <https://www.iana.org/assignments/media-types/media-types.xhtml>`__ (formerly known as MIME types) of the
+   `Media Type <https://www.iana.org/assignments/media-types/media-types.xhtml>`_ (formerly known as MIME types) of the
    file to be loaded. Any filename extensions will be overloaded.  Currently ``image/png`` and
    ``image/vnd.mujoco.hfield`` are supported.
 
@@ -1562,7 +1561,7 @@ The full list of processing steps applied by the compiler to each mesh is as fol
 .. _mesh-plugin:
 
 :el-prefix:`mesh/` |-| **plugin** (?)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+'''''''''''''''''''''''''''''''''''''
 
 Associate this mesh with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.
 
@@ -1578,6 +1577,7 @@ Associate this mesh with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin`
 
 
 
+.. _deformable-skin:
 .. _asset-skin:
 
 :el-prefix:`asset/` |-| **skin** (*)
@@ -1641,11 +1641,13 @@ Similar to the other custom binary formats used in MuJoCo, the file size in byte
 compiler. The skin file format has subelements so the overall file size formula is difficult to write down, but should
 be clear from the above specification.
 
+.. _deformable-skin-name:
 .. _asset-skin-name:
 
 :at:`name`: :at-val:`string, optional`
    Name of the skin.
 
+.. _deformable-skin-file:
 .. _asset-skin-file:
 
 :at:`file`: :at-val:`string, optional`
@@ -1653,11 +1655,13 @@ be clear from the above specification.
    :ref:`compiler <compiler>`. If the file is omitted, the skin specification must be provided in the XML using the
    attributes below.
 
+.. _deformable-skin-vertex:
 .. _asset-skin-vertex:
 
 :at:`vertex`: :at-val:`real(3*nvert), optional`
    Vertex 3D positions, in the global bind pose where the skin is defined.
 
+.. _deformable-skin-texcoord:
 .. _asset-skin-texcoord:
 
 :at:`texcoord`: :at-val:`real(2*nvert), optional`
@@ -1667,22 +1671,26 @@ be clear from the above specification.
    skin using this attribute. Otherwise the texture will appear to be stationary in the world while the skin moves
    around (creating an interesting effect but probably not as intended).
 
+.. _deformable-skin-face:
 .. _asset-skin-face:
 
 :at:`face`: :at-val:`int(3*nface), optional`
    Trinagular skin faces. Each face is a triple of vertex indices, which are integers between zero and nvert-1.
 
+.. _deformable-skin-inflate:
 .. _asset-skin-inflate:
 
 :at:`inflate`: :at-val:`real, "0"`
    If this number is not zero, the position of vertex during updating will be offset along the vertex normal, but the
    distance specified in this attribute. This is particularly useful for skins representing flexible 2D shapes.
 
+.. _deformable-skin-material:
 .. _asset-skin-material:
 
 :at:`material`: :at-val:`string, optional`
    If specified, this attribute applies a material to the skin.
 
+.. _deformable-skin-rgba:
 .. _asset-skin-rgba:
 
 :at:`rgba`: :at-val:`real(4), "0.5 0.5 0.5 1"`
@@ -1690,6 +1698,7 @@ be clear from the above specification.
    only. This is not as flexible as the material mechanism, but is more convenient and is often sufficient. If the value
    of this attribute is different from the internal default, it takes precedence over the material.
 
+.. _deformable-skin-group:
 .. _asset-skin-group:
 
 :at:`group`: :at-val:`int, "0"`
@@ -1919,9 +1928,11 @@ adjust it properly through the XML.
 
 .. _option-o_solimp:
 
-:at:`o_solref`, :at:`o_solimp`
+.. _option-o_friction:
-   These attributes replace the solref and solimp parameters of all active contact pairs when contact override is
+
-   enabled. See :ref:`CSolver` for details.
+:at:`o_solref`, :at:`o_solimp`, :at:`o_friction`
+   These attributes replace the solref, solimp, and friction parameters of all active contact pairs when contact
+   override is enabled. See :ref:`CSolver` for details.
 
 .. _option-integrator:
 
@@ -1931,14 +1942,6 @@ adjust it properly through the XML.
    Implicit-in-velocity Euler method, and :at:`implicitfast`, which drops the Coriolis and centrifugal terms. See
    :ref:`Numerical Integration<geIntegration>` for more details.
 
-.. _option-collision:
-
-:at:`collision`: :at-val:`[all, predefined, dynamic], "all"`
-   This attribute specifies which geom pairs should be checked for collision; recall :ref:`Collision` in the Computation
-   chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs <contact-pair>` are checked.
-   "dynamic" means that only the contact pairs generated dynamically are checked. "all" means that the contact pairs
-   from both sources are checked.
-
 .. _option-cone:
 
 :at:`cone`: :at-val:`[pyramidal, elliptic], "pyramidal"`
@@ -2246,24 +2249,6 @@ defined. Its body name is automatically defined as "world".
    See :ref:`CUser`.
 
 
-.. _body-plugin:
-
-:el-prefix:`body/` |-| **plugin** (?)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Associate this body with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.
-
-.. _body-plugin-plugin:
-
-:at:`plugin`: :at-val:`string, optional`
-   Plugin identifier, used for implicit plugin instantiation.
-
-.. _body-plugin-instance:
-
-:at:`instance`: :at-val:`string, optional`
-   Instance name, used for explicit plugin instantiation.
-
-
 .. _body-inertial:
 
 :el-prefix:`body/` |-| **inertial** (?)
@@ -2864,31 +2849,48 @@ helps clarify the role of bodies and geoms in MuJoCo.
 .. _body-geom-fluidshape:
 
 :at:`fluidshape`: :at-val:`[none, ellipsoid], "none"`
-   "ellipsoid" Activates geom-level stateless fluid interaction model based on an ellipsoidal approximation of the geom
+   "ellipsoid" activates the geom-level fluid interaction model based on an ellipsoidal approximation of the geom
-   shape. When active, the model based on :ref:`body inertia sizes <gePassive>` is disabled for the parent body.
+   shape. When active, the model based on :ref:`body inertia sizes <flInertia>` is disabled for the parent body.
+   See section on :ref:`ellipsoid-based<flEllipsoid>` fluid interaction model for details.
 
 .. _body-geom-fluidcoef:
 
 :at:`fluidcoef`: :at-val:`real(5), "0.5 0.25 1.5 1.0 1.0"`
    Dimensionless coefficients of fluid interaction model, as follows.
+   See section on :ref:`ellipsoid-based<flEllipsoid>` fluid interaction model for details.
 
 
-.. table::
+.. list-table::
+   :width: 60%
    :align: left
+   :widths: 1 5 2 1
+   :header-rows: 1
+
+   * - Index
+     - Description
+     - Symbol
+     - Default
+   * - 0
+     - Blunt drag coefficient
+     - :math:`C_{D, \text{blunt}}`
+     - 0.5
+   * - 1
+     - Slender drag coeficient
+     - :math:`C_{D, \text{slender}}`
+     - 0.25
+   * - 2
+     - Angular drag coeficient
+     - :math:`C_{D, \text{angular}}`
+     - 1.5
+   * - 3
+     - Kutta lift coeficient
+     - :math:`C_K`
+     - 1.0
+   * - 4
+     - Magnus lift coeficient
+     - :math:`C_M`
+     - 1.0
 
-   +--------+-----------------------------+----------+
-   | Index  | Description                 | Default  |
-   +========+=============================+==========+
-   | 0      | Blunt drag coefficient.     | 0.5      |
-   +--------+-----------------------------+----------+
-   | 1      | Slender drag coeficient.    | 0.25     |
-   +--------+-----------------------------+----------+
-   | 2      | Angular drag coefficient.   | 1.5      |
-   +--------+-----------------------------+----------+
-   | 3      | Kutta lift coeficient.      | 1.0      |
-   +--------+-----------------------------+----------+
-   | 4      | Magnus lift coeficient.     | 1.0      |
-   +--------+-----------------------------+----------+
 
 .. _body-geom-user:
 
@@ -2898,7 +2900,7 @@ helps clarify the role of bodies and geoms in MuJoCo.
 .. _geom-plugin:
 
 :el-prefix:`geom/` |-| **plugin** (?)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+'''''''''''''''''''''''''''''''''''''
 
 Associate this geom with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.
 
@@ -3062,6 +3064,35 @@ and the +Y axis points up. Thus the frame position and orientation are the key a
    dimensions are determined by the size of the rendering context. This attribute serves as a convenient
    location to save the required resolution when creating a context.
 
+.. _body-camera-focal:
+
+:at:`focal`: :at-val:`real(2), "0 0"`
+   Focal length of the camera in length units. It is mutually exclusive with :ref:`fovy <body-camera-fovy>`.
+   See :ref:`CCamera` for details.
+
+.. _body-camera-focalpixel:
+
+:at:`focalpixel`: :at-val:`int(2), "0 0"`
+   Focal length of the camera in pixel units. If both :at:`focal`: and :at:`focalpixel`: are specified, the former is
+   ignored.
+
+.. _body-camera-principal:
+
+:at:`principal`: :at-val:`real(2), "0 0"`
+   Principal point of the camera in length units. It is mutually exclusive with :ref:`fovy <body-camera-fovy>`.
+
+.. _body-camera-principalpixel:
+
+:at:`principalpixel`: :at-val:`real(2), "0 0"`
+   Principal point of the camera in pixel units. If both :at:`principal`: and :at:`principalpixel`: are specified, the
+   former is ignored.
+
+.. _body-camera-sensorsize:
+
+:at:`sensorsize`: :at-val:`real(2), "0 0"`
+   Size of the camera sensor in length units. It is mutually exclusive with :ref:`fovy <body-camera-fovy>`. If
+   specified, :ref:`resolution <body-camera-resolution>` and :ref:`focal <body-camera-focal>` are required.
+
 .. _body-camera-ipd:
 
 :at:`ipd`: :at-val:`real, "0.068"`
@@ -3200,6 +3231,24 @@ the direction specified by the dir attribute. It does not have a full spatial fr
    The specular color of the light.
 
 
+.. _body-plugin:
+
+:el-prefix:`body/` |-| **plugin** (?)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Associate this body with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.
+
+.. _body-plugin-plugin:
+
+:at:`plugin`: :at-val:`string, optional`
+   Plugin identifier, used for implicit plugin instantiation.
+
+.. _body-plugin-instance:
+
+:at:`instance`: :at-val:`string, optional`
+   Instance name, used for explicit plugin instantiation.
+
+
 .. _body-composite:
 
 :el-prefix:`body/` |-| **composite** (*)
@@ -3337,7 +3386,7 @@ coordinates results in compiler error. See :ref:`CComposite` in the modeling gui
 .. _body-composite-vertex:
 
 :at:`vertex`: :at-val:`real(3*nvert), optional`
-   Vertex 3D positions in global coordinates (cable only).
+   Vertex 3D positions in global coordinates (cable and shell).
 
 .. _body-composite-face:
 
@@ -3650,7 +3699,7 @@ handle where the composite object is attached. For other composite types this su
 .. _composite-plugin:
 
 :el-prefix:`composite/` |-| **plugin** (?)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+''''''''''''''''''''''''''''''''''''''''''
 
 Associate this composite with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.
 
@@ -3664,6 +3713,158 @@ Associate this composite with an :ref:`engine plugin<exPlugin>`. Either :at:`plu
 :at:`instance`: :at-val:`string, optional`
    Instance name, used for explicit plugin instantiation.
 
+
+.. _body-flexcomp:
+
+:el-prefix:`body/` |-| **flex** (*)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _body-flexcomp-name:
+
+.. _body-flexcomp-class:
+
+.. _body-flexcomp-type:
+
+.. _body-flexcomp-dim:
+
+.. _body-flexcomp-count:
+
+.. _body-flexcomp-spacing:
+
+.. _body-flexcomp-radius:
+
+.. _body-flexcomp-rigid:
+
+.. _body-flexcomp-mass:
+
+.. _body-flexcomp-inertiabox:
+
+.. _body-flexcomp-scale:
+
+.. _body-flexcomp-file:
+
+.. _body-flexcomp-point:
+
+.. _body-flexcomp-element:
+
+.. _body-flexcomp-material:
+
+.. _body-flexcomp-rgba:
+
+.. _body-flexcomp-texcoord:
+
+.. _body-flexcomp-pos:
+
+.. _body-flexcomp-quat:
+
+.. _body-flexcomp-axisangle:
+
+.. _body-flexcomp-xyaxes:
+
+.. _body-flexcomp-zaxis:
+
+.. _body-flexcomp-euler:
+
+.. _body-flexcomp-selfcollide:
+
+.. _body-flexcomp-flatskin:
+
+.. _flex-edge:
+.. _flexcomp-edge:
+
+.. _flex-edge-equality:
+.. _flexcomp-edge-equality:
+
+.. _flex-edge-solref:
+.. _flexcomp-edge-solref:
+
+.. _flex-edge-solimp:
+.. _flexcomp-edge-solimp:
+
+.. _flex-edge-stiffness:
+.. _flexcomp-edge-stiffness:
+
+.. _flex-edge-damping:
+.. _flexcomp-edge-damping:
+
+.. _flex-contact:
+.. _flexcomp-contact:
+
+.. _flex-contact-contype:
+.. _flexcomp-contact-contype:
+
+.. _flex-contact-conaffinity:
+.. _flexcomp-contact-conaffinity:
+
+.. _flex-contact-condim:
+.. _flexcomp-contact-condim:
+
+.. _flex-contact-priority:
+.. _flexcomp-contact-priority:
+
+.. _flex-contact-friction:
+.. _flexcomp-contact-friction:
+
+.. _flex-contact-solmix:
+.. _flexcomp-contact-solmix:
+
+.. _flex-contact-solref:
+.. _flexcomp-contact-solref:
+
+.. _flex-contact-solimp:
+.. _flexcomp-contact-solimp:
+
+.. _flex-contact-margin:
+.. _flexcomp-contact-margin:
+
+.. _flex-contact-gap:
+.. _flexcomp-contact-gap:
+
+.. _flexcomp-pin:
+
+.. _flexcomp-pin-id:
+
+.. _flexcomp-pin-range:
+
+.. _flexcomp-pin-grid:
+
+.. _flexcomp-pin-gridrange:
+
+
+.. _deformable:
+
+.. _deformable-flex:
+
+.. _deformable-flex-name:
+
+.. _deformable-flex-group:
+
+.. _deformable-flex-material:
+
+.. _deformable-flex-radius:
+
+.. _deformable-flex-rgba:
+
+.. _deformable-flex-texcoord:
+
+.. _deformable-flex-flatskin:
+
+.. _deformable-flex-selfcollide:
+
+.. _deformable-flex-dim:
+
+.. _deformable-flex-body:
+
+.. _deformable-flex-vertex:
+
+.. _deformable-flex-element:
+
+
+
+**deformable** (*)
+~~~~~~~~~~~~~~~~~~
+
+
 .. _contact:
 
 **contact** (*)
@@ -3816,8 +4017,8 @@ geoms volumes of either body. This constraint can be used to define ball joints
 
 :at:`active`: :at-val:`[false, true], "true"`
    If this attribute is set to "true", the constraint is active and the constraint solver will try to enforce it. The
-   corresponding field in mjModel is mjData.eq_active. This field can be used at runtime to turn specific constraints on
+   field :ref:`mjModel.eq_active0<mjModel>` corresponds to this value, and is used to initialize
-   an off.
+   :ref:`mjData.eq_active<mjData>`, which is user-settable at runtime.
 
 .. _equality-connect-solref:
 
@@ -3882,7 +4083,8 @@ of the other body, without any joint elements in the child body.
 
 :at:`body2`: :at-val:`string, optional`
    Name of the second body. If this attribute is omitted, the second body is the world body. Welding a body to the world
-   and changing the corresponding component of mjModel.eq_active at runtime can be used to fix the body temporarily.
+   and changing the corresponding component of :ref:`mjData.eq_active<mjData>` at runtime can be used to fix the body
+   temporarily.
 
 .. _equality-weld-relpose:
 
@@ -3988,6 +4190,24 @@ This element constrains the length of one tendon to be a quartic polynomial of a
    positions.
 
 
+.. _equality-flex:
+
+:el-prefix:`equality/` |-| **flex** (*)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _equality-flex-name:
+
+.. _equality-flex-class:
+
+.. _equality-flex-flex:
+
+.. _equality-flex-active:
+
+.. _equality-flex-solref:
+
+.. _equality-flex-solimp:
+
+
 .. _equality-distance:
 
 :el-prefix:`equality/` |-| **distance** (*)
@@ -6691,8 +6911,6 @@ if omitted.
 | All site attributes are available here except: name, class.
 
 
-.. _default-camera:
-
 .. _default-camera-fovy:
 
 .. _default-camera-resolution:
@@ -6715,11 +6933,24 @@ if omitted.
 
 .. _default-camera-user:
 
+.. _default-camera-focal:
+
+.. _default-camera-focalpixel:
+
+.. _default-camera-principal:
+
+.. _default-camera-principalpixel:
+
+.. _default-camera-sensorsize:
+
+.. _default-camera:
+
+
 :el-prefix:`default/` |-| **camera** (?)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 | This element sets the attributes of the dummy :ref:`camera <body-camera>` element of the defaults class.
-| All camera attributes are available here except: name, class.
+| All camera attributes are available here except: name, class, mode, target.
 
 
 .. _default-light:
@@ -7115,6 +7346,44 @@ tendon, slidersite, cranksite.
 All :ref:`adhesion <actuator-adhesion>` attributes are available here except: name, class, body.
 
 
+.. _default-flex:
+
+.. _default-flex-contype:
+
+.. _default-flex-conaffinity:
+
+.. _default-flex-condim:
+
+.. _default-flex-priority:
+
+.. _default-flex-material:
+
+.. _default-flex-friction:
+
+.. _default-flex-solmix:
+
+.. _default-flex-solref:
+
+.. _default-flex-solimp:
+
+.. _default-flex-margin:
+
+.. _default-flex-gap:
+
+.. _default-flex-stiffness:
+
+.. _default-flex-damping:
+
+.. _default-flex-radius:
+
+.. _default-flex-rgba:
+
+.. _default-flex-dim:
+
+:el-prefix:`default/` |-| **flex** (?)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
 .. _custom:
 
 **custom** (*)

doc/XMLschema.rst

@@ -222,9 +222,9 @@
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 |                                    |    |    | :ref:`wind<option-wind>`                                        | :ref:`magnetic<option-magnetic>`                                | :ref:`density<option-density>`                                  | :ref:`viscosity<option-viscosity>`                              | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`o_margin<option-o_margin>`                                | :ref:`o_solref<option-o_solref>`                                | :ref:`o_solimp<option-o_solimp>`                                | :ref:`integrator<option-integrator>`                            | |
+|                                    |    |    | :ref:`o_margin<option-o_margin>`                                | :ref:`o_solref<option-o_solref>`                                | :ref:`o_solimp<option-o_solimp>`                                | :ref:`o_friction<option-o_friction>`                            | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`collision<option-collision>`                              | :ref:`cone<option-cone>`                                        | :ref:`jacobian<option-jacobian>`                                | :ref:`solver<option-solver>`                                    | |
+|                                    |    |    | :ref:`integrator<option-integrator>`                            | :ref:`cone<option-cone>`                                        | :ref:`jacobian<option-jacobian>`                                | :ref:`solver<option-solver>`                                    | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 |                                    |    |    | :ref:`iterations<option-iterations>`                            | :ref:`ls_iterations<option-ls_iterations>`                      | :ref:`noslip_iterations<option-noslip_iterations>`              | :ref:`mpr_iterations<option-mpr_iterations>`                    | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
@@ -260,20 +260,6 @@
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
-| :ref:`plugin                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
-| <body-plugin>`                     |    |                                                                                                                                                                                                                                                                              |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`plugin<body-plugin-plugin>`                               | :ref:`instance<body-plugin-instance>`                           |                                                                 |                                                                 | |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| |_2| plugin |br| |_2| |L|          |    | .. table::                                                                                                                                                                                                                                                                   |
-| :ref:`config                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
-| <plugin-config>`                   |    |                                                                                                                                                                                                                                                                              |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`key<plugin-config-key>`                                   | :ref:`value<plugin-config-value>`                               |                                                                 |                                                                 | |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
 | :ref:`inertial                     | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
 | <body-inertial>`                   |    |                                                                                                                                                                                                                                                                              |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
@@ -368,7 +354,9 @@
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 |                                    |    |    | :ref:`xyaxes<body-camera-xyaxes>`                               | :ref:`zaxis<body-camera-zaxis>`                                 | :ref:`euler<body-camera-euler>`                                 | :ref:`mode<body-camera-mode>`                                   | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`target<body-camera-target>`                               | :ref:`user<body-camera-user>`                                   |                                                                 |                                                                 | |
+|                                    |    |    | :ref:`target<body-camera-target>`                               | :ref:`focal<body-camera-focal>`                                 | :ref:`focalpixel<body-camera-focalpixel>`                       | :ref:`principal<body-camera-principal>`                         | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`principalpixel<body-camera-principalpixel>`               | :ref:`sensorsize<body-camera-sensorsize>`                       | :ref:`user<body-camera-user>`                                   |                                                                 | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
@@ -385,6 +373,20 @@
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`plugin                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <body-plugin>`                     |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`plugin<body-plugin-plugin>`                               | :ref:`instance<body-plugin-instance>`                           |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| plugin |br| |_2| |L|          |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`config                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <plugin-config>`                   |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`key<plugin-config-key>`                                   | :ref:`value<plugin-config-value>`                               |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
 | :ref:`composite                    | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
 | <body-composite>`                  |    |                                                                                                                                                                                                                                                                              |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
@@ -398,20 +400,6 @@
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | |_2| composite |br| |_2| |L|       |    | .. table::                                                                                                                                                                                                                                                                   |
-| :ref:`plugin                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
-| <composite-plugin>`                |    |                                                                                                                                                                                                                                                                              |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`plugin<composite-plugin-plugin>`                          | :ref:`instance<composite-plugin-instance>`                      |                                                                 |                                                                 | |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| |_3| plugin |br| |_3| |L|          |    | .. table::                                                                                                                                                                                                                                                                   |
-| :ref:`config                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
-| <plugin-config>`                   |    |                                                                                                                                                                                                                                                                              |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`key<plugin-config-key>`                                   | :ref:`value<plugin-config-value>`                               |                                                                 |                                                                 | |
-|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| |_2| composite |br| |_2| |L|       |    | .. table::                                                                                                                                                                                                                                                                   |
 | :ref:`joint                        | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
 | <composite-joint>`                 |    |                                                                                                                                                                                                                                                                              |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
@@ -479,6 +467,118 @@
 |                                    |    |    | :ref:`coord<composite-pin-coord>`                               |                                                                 |                                                                 |                                                                 | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| composite |br| |_2| |L|       |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`plugin                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <composite-plugin>`                |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`plugin<composite-plugin-plugin>`                          | :ref:`instance<composite-plugin-instance>`                      |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_3| plugin |br| |_3| |L|          |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`config                       | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <plugin-config>`                   |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`key<plugin-config-key>`                                   | :ref:`value<plugin-config-value>`                               |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_| body |br| |_| |L|              |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`flexcomp                     | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <body-flexcomp>`                   |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`name<body-flexcomp-name>`                                 | :ref:`class<body-flexcomp-class>`                               | :ref:`type<body-flexcomp-type>`                                 | :ref:`dim<body-flexcomp-dim>`                                   | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`flatskin<body-flexcomp-flatskin>`                         | :ref:`count<body-flexcomp-count>`                               | :ref:`spacing<body-flexcomp-spacing>`                           | :ref:`radius<body-flexcomp-radius>`                             | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`rigid<body-flexcomp-rigid>`                               | :ref:`mass<body-flexcomp-mass>`                                 | :ref:`inertiabox<body-flexcomp-inertiabox>`                     | :ref:`scale<body-flexcomp-scale>`                               | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`file<body-flexcomp-file>`                                 | :ref:`point<body-flexcomp-point>`                               | :ref:`element<body-flexcomp-element>`                           | :ref:`texcoord<body-flexcomp-texcoord>`                         | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`material<body-flexcomp-material>`                         | :ref:`rgba<body-flexcomp-rgba>`                                 | :ref:`selfcollide<body-flexcomp-selfcollide>`                   | :ref:`flatskin<body-flexcomp-flatskin>`                         | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`pos<body-flexcomp-pos>`                                   | :ref:`quat<body-flexcomp-quat>`                                 | :ref:`axisangle<body-flexcomp-axisangle>`                       | :ref:`xyaxes<body-flexcomp-xyaxes>`                             | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`zaxis<body-flexcomp-zaxis>`                               | :ref:`euler<body-flexcomp-euler>`                               |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| flexcomp |br| |_2| |L|        |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`edge                         | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <flexcomp-edge>`                   |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`equality<flexcomp-edge-equality>`                         | :ref:`solref<flexcomp-edge-solref>`                             | :ref:`solimp<flexcomp-edge-solimp>`                             | :ref:`stiffness<flexcomp-edge-stiffness>`                       | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`damping<flexcomp-edge-damping>`                           |                                                                 |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| flexcomp |br| |_2| |L|        |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`contact                      | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <flexcomp-contact>`                |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`contype<flexcomp-contact-contype>`                        | :ref:`conaffinity<flexcomp-contact-conaffinity>`                | :ref:`condim<flexcomp-contact-condim>`                          | :ref:`priority<flexcomp-contact-priority>`                      | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`friction<flexcomp-contact-friction>`                      | :ref:`solmix<flexcomp-contact-solmix>`                          | :ref:`solref<flexcomp-contact-solref>`                          | :ref:`solimp<flexcomp-contact-solimp>`                          | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`margin<flexcomp-contact-margin>`                          | :ref:`gap<flexcomp-contact-gap>`                                |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| flexcomp |br| |_2| |L|        |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`pin                          | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <flexcomp-pin>`                    |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`id<flexcomp-pin-id>`                                      | :ref:`range<flexcomp-pin-range>`                                | :ref:`grid<flexcomp-pin-grid>`                                  | :ref:`gridrange<flexcomp-pin-gridrange>`                        | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| mujoco |br| |L|                    |    | *no attributes*                                                                                                                                                                                                                                                              |
+| :ref:`deformable<deformable>`      |    |                                                                                                                                                                                                                                                                              |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_| deformable |br| |_| |L|        |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`flex                         | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <deformable-flex>`                 |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`name<deformable-flex-name>`                               | :ref:`group<deformable-flex-group>`                             | :ref:`dim<deformable-flex-dim>`                                 | :ref:`radius<deformable-flex-radius>`                           | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`material<deformable-flex-material>`                       | :ref:`rgba<deformable-flex-rgba>`                               | :ref:`flatskin<deformable-flex-flatskin>`                       | :ref:`selfcollide<deformable-flex-selfcollide>`                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`body<deformable-flex-body>`                               | :ref:`vertex<deformable-flex-vertex>`                           | :ref:`element<deformable-flex-element>`                         | :ref:`texcoord<deformable-flex-texcoord>`                       | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| flex |br| |_2| |L|            |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`contact                      | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <flex-contact>`                    |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`contype<flex-contact-contype>`                            | :ref:`conaffinity<flex-contact-conaffinity>`                    | :ref:`condim<flex-contact-condim>`                              | :ref:`priority<flex-contact-priority>`                          | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`friction<flex-contact-friction>`                          | :ref:`solmix<flex-contact-solmix>`                              | :ref:`solref<flex-contact-solref>`                              | :ref:`solimp<flex-contact-solimp>`                              | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`margin<flex-contact-margin>`                              | :ref:`gap<flex-contact-gap>`                                    |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| flex |br| |_2| |L|            |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`edge                         | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <flex-edge>`                       |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`stiffness<flex-edge-stiffness>`                           | :ref:`damping<flex-edge-damping>`                               |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_| deformable |br| |_| |L|        |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`skin                         | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <deformable-skin>`                 |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`name<deformable-skin-name>`                               | :ref:`file<deformable-skin-file>`                               | :ref:`material<deformable-skin-material>`                       | :ref:`rgba<deformable-skin-rgba>`                               | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`inflate<deformable-skin-inflate>`                         | :ref:`vertex<deformable-skin-vertex>`                           | :ref:`texcoord<deformable-skin-texcoord>`                       | :ref:`face<deformable-skin-face>`                               | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`group<deformable-skin-group>`                             |                                                                 |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_2| skin |br| |_2| |L|            |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`bone                         | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <skin-bone>`                       |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`body<skin-bone-body>`                                     | :ref:`bindpos<skin-bone-bindpos>`                               | :ref:`bindquat<skin-bone-bindquat>`                             | :ref:`vertid<skin-bone-vertid>`                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`vertweight<skin-bone-vertweight>`                         |                                                                 |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | mujoco |br| |L|                    |    | *no attributes*                                                                                                                                                                                                                                                              |
 | :ref:`contact<contact>`            |    |                                                                                                                                                                                                                                                                              |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -541,6 +641,15 @@
 |                                    |    |    | :ref:`polycoef<equality-tendon-polycoef>`                       | :ref:`active<equality-tendon-active>`                           | :ref:`solref<equality-tendon-solref>`                           | :ref:`solimp<equality-tendon-solimp>`                           | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| |_| equality |br| |_| |L|          |    | .. table::                                                                                                                                                                                                                                                                   |
+| :ref:`flex                         | \* |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
+| <equality-flex>`                   |    |                                                                                                                                                                                                                                                                              |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`name<equality-flex-name>`                                 | :ref:`class<equality-flex-class>`                               | :ref:`flex<equality-flex-flex>`                                 | :ref:`active<equality-flex-active>`                             | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`solref<equality-flex-solref>`                             | :ref:`solimp<equality-flex-solimp>`                             |                                                                 |                                                                 | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | mujoco |br| |L|                    |    | *no attributes*                                                                                                                                                                                                                                                              |
 | :ref:`tendon<tendon>`              |    |                                                                                                                                                                                                                                                                              |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -1230,11 +1339,13 @@
 | :ref:`camera                       | ?  |    :class: mjcf-attributes                                                                                                                                                                                                                                                   |
 | <default-camera>`                  |    |                                                                                                                                                                                                                                                                              |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`fovy<default-camera-fovy>`                                | :ref:`ipd<default-camera-ipd>`                                  | :ref:`pos<default-camera-pos>`                                  | :ref:`quat<default-camera-quat>`                                | |
+|                                    |    |    | :ref:`fovy<default-camera-fovy>`                                | :ref:`ipd<default-camera-ipd>`                                  | :ref:`resolution<default-camera-resolution>`                    | :ref:`pos<default-camera-pos>`                                  | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`resolution<default-camera-resolution>`                    | :ref:`axisangle<default-camera-axisangle>`                      | :ref:`xyaxes<default-camera-xyaxes>`                            | :ref:`zaxis<default-camera-zaxis>`                              | |
+|                                    |    |    | :ref:`quat<default-camera-quat>`                                | :ref:`axisangle<default-camera-axisangle>`                      | :ref:`xyaxes<default-camera-xyaxes>`                            | :ref:`zaxis<default-camera-zaxis>`                              | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
-|                                    |    |    | :ref:`euler<default-camera-euler>`                              | :ref:`mode<default-camera-mode>`                                | :ref:`user<default-camera-user>`                                |                                                                 | |
+|                                    |    |    | :ref:`euler<default-camera-euler>`                              | :ref:`mode<default-camera-mode>`                                | :ref:`focal<default-camera-focal>`                              | :ref:`focalpixel<default-camera-focalpixel>`                    | |
+|                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+|                                    |    |    | :ref:`principal<default-camera-principal>`                      | :ref:`principalpixel<default-camera-principalpixel>`            | :ref:`sensorsize<default-camera-sensorsize>`                    | :ref:`user<default-camera-user>`                                | |
 |                                    |    |    +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
 +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | |_| default |br| |_| |L|           |    | .. table::                                                                                                                                                                                                                                                                   |

doc/changelog.rst

@@ -29,7 +29,27 @@ New features
      gradient at query points. See the :ref:`documentation<exWriting>` for more details.
 
 3. Added :ref:`mjThreadPool` and :ref:`mjTask` which allow for multi-threaded operations within the MuJoCo engine
-   pipeline.
+   pipeline. If engine-internal threading is enabled, the following operations will be multi-threaded:
+
+   - Island constraint resolution, if island discovery is :ref:`enabled<option-flag-island>` and the
+     :ref:`CG solver<option-solver>` is selected. The
+     `22 humanoids <https://github.com/deepmind/mujoco/blob/main/model/humanoid/22_humanoids.xml>`__ model shows a 3x
+     speedup compared to the single threaded simulation.
+   - Inertia-related computations and collision detection will happen in parallel.
+
+   Engine-internal threading is a work in progress and currently only available in first-party code via the
+   :ref:`testspeed<saTestspeed>` utility, exposed with the ``npoolthread`` flag.
+
+.. youtube:: ra2bTiZHGlw
+   :align: right
+   :width: 240px
+
+4. Added capability to initialize :ref:`composite<body-composite>` particles with arbitrary positions.
+
+5. Added `shell <https://github.com/deepmind/mujoco/blob/main/plugin/elasticity/shell.cc>`__ passive force plugin:
+
+   - Collisions use spheres located at mesh vertices.
+   - Stretching as tendon constraints and bending using a constant precomputed Hessian (cotangent operator).
 
 General
 ^^^^^^^
@@ -37,21 +57,21 @@ General
 .. admonition:: Breaking API changes
    :class: attention
 
-   4. Removed the macros ``mjMARKSTACK`` and ``mjFREESTACK``.
+   6. Removed the macros ``mjMARKSTACK`` and ``mjFREESTACK``.
 
       **Migration:** These macros have been replaced by new functions :ref:`mj_markStack` and
       :ref:`mj_freeStack`. These functions manage the :ref:`mjData stack<siStack>` in a fully encapsulated way (i.e.,
       without introducing a local variable at the call site).
 
-   5. Changed the function :ref:`mj_stackAlloc` to allocate an arbitrary number of bytes, rather than in multiples of
+   7. Renamed ``mj_stackAlloc`` to :ref:`mj_stackAllocNum`. The new function :ref:`mj_stackAllocByte` allocates an
-      ``sizeof(mjtNum)``, and added an additional argument for specifying the alignment of the returned pointer.
+      arbitrary number of bytes and has an additional argument for specifying the alignment of the returned pointer.
 
-      **Migration:** The functionality for allocating ``mjtNum`` arrays is available via :ref:`mj_stackAllocNum`.
+      **Migration:** The functionality for allocating ``mjtNum`` arrays is now available via :ref:`mj_stackAllocNum`.
 
-   6. Renamed the ``nstack`` field in :ref:`mjModel` and :ref:`mjData` to ``narena``. Changed ``narena``, ``pstack``,
+   8. Renamed the ``nstack`` field in :ref:`mjModel` and :ref:`mjData` to ``narena``. Changed ``narena``, ``pstack``,
       and ``maxuse_stack`` to count number of bytes rather than number of :ref:`mjtNum` |-| s.
 
-   7. Changed :ref:`mjData.solver<mjData>`, the array used to collect solver diagnostic information.
+   9. Changed :ref:`mjData.solver<mjData>`, the array used to collect solver diagnostic information.
       This array of :ref:`mjSolverStat` structs is now of length ``mjNISLAND * mjNSOLVER``, interpreted as as a matrix.
       Each row of length ``mjNSOLVER`` contains separate solver statistics for each constraint island.
       If the solver does not use islands, only row 0 is filled.
@@ -62,37 +82,101 @@ General
       - Renamed ``mjData.solver_iter`` to ``solver_niter``. Both this member and ``mjData.solver_nnz`` are now integer
         vectors of length ``mjNISLAND``.
 
-8. Added a new :ref:`dyntype<actuator-general-dyntype>`, ``filterexact``, which updates first-order filter states with
+   10. Removed ``mjOption.collision`` and the associated ``option/collision`` attribute.
-   the exact formula rather than with Euler integration.
+
-9. Added an actuator attribute, :ref:`actearly<actuator-general-actearly>`, which uses semi-implicit integration for
+       **Migration:**
-   actuator forces: using the next step's actuator state to compute the current actuator forces at the current timestep.
+
-10. Renamed ``actuatorforcerange`` and ``actuatorforcelimited``, introduced in the previous version to
+       - For models which have ``<option collision="all"/>``, delete the attribute.
+       - For models which have ``<option collision="dynamic"/>``, delete all :ref:`pair<contact-pair>` elements.
+       - For models which have ``<option collision="pair"/>``, disable all dynamic collisions (determined
+         via contype/conaffinity) by first deleting all :ref:`contype<body-geom-contype>` and
+         :ref:`conaffinity<body-geom-conaffinity>` attributes in the model and then setting them globally to ``0`` using
+         |br| ``<default> <geom contype="0" conaffinity="0"/> </default>``.
+
+   11. Removed the :at:`rope` and :at:`cloth` composite objects.
+
+       **Migration:** Users should use the :at:`cable` and :at:`shell` elasticity plugins.
+
+   12. Added :ref:`mjData.eq_active<mjData>` user input variable, for enabling/disabling the state of equality
+       constraints. Renamed ``mjModel.eq_active`` to :ref:`mjModel.eq_active0<mjModel>`, which now has the semantic of
+       "initial value of ``mjData.eq_active``".
+       Fixes `#876 <https://github.com/google-deepmind/mujoco/discussions/876>`__
+
+       **Migration:** Replace uses of ``mjModel.eq_active`` with ``mjData.eq_active``.
+
+   13. Changed the default of :ref:`autolimits<compiler-autolimits>` from "false" to "true". This is a minor breaking
+       change. The potential breakage applies to models which have elements with "range" defined and "limited" not set.
+       Such models cannot be loaded since version 2.2.2 (July 2022).
+
+14. Added a new :ref:`dyntype<actuator-general-dyntype>`, ``filterexact``, which updates first-order filter states with
+    the exact formula rather than with Euler integration.
+15. Added an actuator attribute, :ref:`actearly<actuator-general-actearly>`, which uses semi-implicit integration for
+    actuator forces: using the next step's actuator state to compute the current actuator forces.
+16. Renamed ``actuatorforcerange`` and ``actuatorforcelimited``, introduced in the previous version to
     :ref:`actuatorfrcrange<body-joint-actuatorfrcrange>` and
     :ref:`actuatorfrclimited<body-joint-actuatorfrclimited>`, respectively.
-11. Added the flag :ref:`eulerdamp<option-flag-eulerdamp>`, which disables implicit integration of joint damping in the
+17. Added the flag :ref:`eulerdamp<option-flag-eulerdamp>`, which disables implicit integration of joint damping in the
     Euler integrator. See the :ref:`Numerical Integration<geIntegration>` section for more details.
-12. Added the flag :ref:`invdiscrete<option-flag-invdiscrete>`, which enables discrete-time inverse dynamics for all
+18. Added the flag :ref:`invdiscrete<option-flag-invdiscrete>`, which enables discrete-time inverse dynamics for all
     :ref:`integrators<option-integrator>` other than ``RK4``. See the flag documentation for more details.
-13. Added :ref:`ls_iterations<option-ls_iterations>` and :ref:`ls_tolerance<option-ls_tolerance>` options for adjusting
+19. Added :ref:`ls_iterations<option-ls_iterations>` and :ref:`ls_tolerance<option-ls_tolerance>` options for adjusting
     linesearch stopping criteria in CG and Newton solvers. These can be useful for performance tuning.
-14. Added ``mesh_pos`` and ``mesh_quat`` fields to :ref:`mjModel` to store the normalizing transformation applied to
+20. Added ``mesh_pos`` and ``mesh_quat`` fields to :ref:`mjModel` to store the normalizing transformation applied to
     mesh assets. Fixes `#409 <https://github.com/google-deepmind/mujoco/issues/409>`__ .
-15. Added camera :ref:`resolution<body-camera-resolution>` attribute and :ref:`camprojection<sensor-camprojection>`
+21. Added camera :ref:`resolution<body-camera-resolution>` attribute and :ref:`camprojection<sensor-camprojection>`
     sensor. If camera resolution is set to positive values, the camera projection sensor will report the location of a
     target site, projected onto the camera image, in pixel coordinates.
+22. Added :ref:`camera<body-camera>` calibration attributes:
+
+    - The new attributes are :ref:`resolution<body-camera-resolution>`, :ref:`focal<body-camera-focal>`,
+      :ref:`focalpixel<body-camera-focalpixel>`, :ref:`principal<body-camera-principal>`,
+      :ref:`principalpixel<body-camera-principalpixel>` and :ref:`sensorsize<body-camera-sensorsize>`.
+    - Visualize the calibrated frustum using the :ref:`mjVIS_CAMERA<mjtVisFlag>` visualization flag when these
+      attributes are specified. See the following
+      `example model <https://github.com/deepmind/mujoco/blob/main/test/engine/testdata/vis_visualize/frustum.xml>`__.
+    - Note that these attributes only take effect for offline rendering and do not affect interactive visualisation.
+23. Implemented reversed Z rendering for better depth precision. An enum :ref:`mjtDepthMap` was added with values
+    ``mjDEPTH_ZERONEAR`` and ``mjDEPTH_ZEROFAR``, which can be used to set the new ``readDepthMap`` attribute in
+    :ref:`mjrContext` to control how the depth returned by :ref:`mjr_readPixels` is mapped from ``znear`` to ``zfar``.
+    `Contribution <https://github.com/google-deepmind/mujoco/pull/978>`__ by
+    `Levi Burner <https://github.com/aftersomemath>`__.
+24. Deleted the code sample ``testxml``. The functionality provided by this utility is implemented in the
+    `WriteReadCompare <https://github.com/google-deepmind/mujoco/blob/main/test/xml/xml_native_writer_test.cc>`__ test.
+25. Deleted the code sample ``derivative``. Functionality provided by :ref:`mjd_transitionFD`.
 
 Python bindings
 ^^^^^^^^^^^^^^^
 
-16. Fixed `#870 <https://github.com/google-deepmind/mujoco/issues/870>`__ where calling ``update_scene`` with an invalid
+26. Fixed `#870 <https://github.com/google-deepmind/mujoco/issues/870>`__ where calling ``update_scene`` with an invalid
     camera name used the default camera.
+27. Added ``user_scn`` to the :ref:`passive viewer<PyViewerPassive>` handle, which allows users to add custom
+    visualization geoms (`#1023 <https://github.com/google-deepmind/mujoco/issues/870>`__).
+28. Added optional boolean keyword arguments ``show_left_ui`` and ``show_right_ui`` to the functions ``viewer.launch``
+    and ``viewer.launch_passive``, which allow users to launch a viewer with UI panels hidden.
+
+Simulate
+^^^^^^^^
+
+.. youtube:: YSvWn_poqWs
+   :align: right
+   :width: 240px
+
+29. Added **state history** mechanism to :ref:`simulate<saSimulate>` and the managed
+    :ref:`Python viewer<PyViewerManaged>`. State history can be viewed by scrubbing the History slider and (more
+    precisely) with the left and right arrow keys. See screen capture:
+
+30. The ``LOADING...`` label is now shown correctly.
+    `Contribution <https://github.com/google-deepmind/mujoco/pull/1070>`__ by
+    `Levi Burner <https://github.com/aftersomemath>`__.
 
 Bug fixes
 ^^^^^^^^^
 
-17. Fixed a bug that was causing :ref:`geom margin<body-geom-margin>` to be ignored during the construction of
+31. Fixed a bug that was causing :ref:`geom margin<body-geom-margin>` to be ignored during the construction of
     midphase collision trees.
 
+32. Fixed a bug that was generating incorrect values in ``efc_diagApprox`` for weld equality constraints.
+
 
 Version 2.3.7 (July 20, 2023)
 -----------------------------
@@ -107,8 +191,8 @@ General
    :ref:`Cartesian actuator<actuator-general-refsite>` forces are realizable by individual motors at the joints.
    See :ref:`CForceRange` for details.
 #. Added an optional ``content_type`` attribute to hfield, texture, and mesh assets. This attribute supports a formatted
-   `Media Type <https://www.iana.org/assignments/media-types/media-types.xhtml>`__ (previously known as MIME type)
+   `Media Type <https://www.iana.org/assignments/media-types/media-types.xhtml>`_ (previously known as MIME type) string
-   string used to determine the type of the asset file without resorting to pulling the type from the file extension.
+   used to determine the type of the asset file without resorting to pulling the type from the file extension.
 #. Added analytic derivatives for quaternion :ref:`subtraction<mjd_subQuat>` and :ref:`integration<mjd_quatIntegrate>`
    (rotation with an angular velocity). Derivatives are in the 3D tangent space.
 #. Added :ref:`mjv_connector` which has identical functionality to :ref:`mjv_makeConnector`, but with more convenient
@@ -171,9 +255,9 @@ Bug fixes
 Plugins
 ^^^^^^^
 
-5. Added touch-grid sensor plugin. See `documentation <https://github.com/google-deepmind/mujoco/blob/main/plugin/sensor/README.md>`_
+5. Added touch-grid sensor plugin. See `documentation <https://github.com/google-deepmind/mujoco/blob/main/plugin/sensor/README.md>`__
-   for details, and associated `touch_grid.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/sensor/touch_grid.xml>`_
+   for details, and associated `touch_grid.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/sensor/touch_grid.xml>`__
-   example model. The plugin includes `in-scene visualisation <https://youtu.be/0LOJ3WMnqeA>`_.
+   example model. The plugin includes `in-scene visualisation <https://youtu.be/0LOJ3WMnqeA>`__.
 
 Simulate
 ^^^^^^^^
@@ -296,8 +380,8 @@ Python bindings
 #. Fixed a race condition in ``viewer.launch_passive`` and  ``viewer.launch_repl``. These functions could previously
    return before an internal call to ``mj_forward``. This allows user code to continue and potentially modify physics
    state concurrently with the internal ``mj_forward``, resulting in e.g.
-   `MuJoCo stack overflow error <https://github.com/google-deepmind/mujoco/issues/783>`_
+   `MuJoCo stack overflow error <https://github.com/google-deepmind/mujoco/issues/783>`__
-   or `segmentation fault <https://github.com/google-deepmind/mujoco/issues/790>`_.
+   or `segmentation fault <https://github.com/google-deepmind/mujoco/issues/790>`__.
 #. The ``viewer.launch_passive`` function now returns a handle which can be used to interact with the viewer. The
    passive viewer now also requires an explicit call to ``sync`` on its handle to pick up any update to the physics
    state. This is to avoid race conditions that can result in visual artifacts. See
@@ -310,9 +394,9 @@ Bug fixes
 
 12. Fixed bug in the handling of ellipsoid-based fluid model forces in the new implicitfast integrator.
 #.  Removed spurious whole-arena copying in `mj_copyData`, which can considerably
-    `slow down <https://github.com/google-deepmind/mujoco/issues/568>`_ the copying operation.
+    `slow down <https://github.com/google-deepmind/mujoco/issues/568>`__ the copying operation.
 #.  Make :ref:`shellinertia<body-geom-shellinertia>` ignore :ref:`exactmeshinertia<compiler-exactmeshinertia>`, which is
-    only used for legacy volume computations (`#759 <https://github.com/google-deepmind/mujoco/issues/759>`_).
+    only used for legacy volume computations (`#759 <https://github.com/google-deepmind/mujoco/issues/759>`__).
 
 
 Version 2.3.3 (March 20, 2023)
@@ -331,7 +415,7 @@ General
      become the default integrator in a future version.
 
    The table below shows the compute cost of the 627-DoF `humanoid100
-   <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`_ model using different
+   <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`__ model using different
    integrators. "implicit (old)" uses dense RNE derivatives, "implicit (new)" is after the sparsification mentioned
    above. Timings were measured on a single core of an AMD 3995WX CPU.
 
@@ -349,14 +433,14 @@ General
 
 2. Added a collision mid-phase for pruning geoms in body pairs, see :ref:`documentation<coSelection>` for more details.
    This is based on static AABB bounding volume hierarchy (a BVH binary tree) in the body inertial frame. The GIF on
-   the right is cut from `this longer video <https://youtu.be/e0babIM8hBo>`_.
+   the right is cut from `this longer video <https://youtu.be/e0babIM8hBo>`__.
 #. The ``mjd_transitionFD`` function no longer triggers sensor calculation unless explicitly requested.
 #. Corrected the spelling of the ``inteval`` attribute to ``interval`` in the :ref:`mjLROpt` struct.
 #. Mesh texture and normal mappings are now 3-per-triangle rather than 1-per-vertex. Mesh vertices are no longer
    duplicated in order to circumvent this limitation as they previously were.
 #. The non-zeros for the sparse constraint Jacobian matrix are now precounted and used for matrix memory allocation.
    For instance, the constraint Jacobian matrix from the `humanoid100
-   <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`_ model, which previously
+   <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`__ model, which previously
    required ~500,000 ``mjtNum``'s, now only requires ~6000. Very large models can now load and run with the CG solver.
 #. Modified :ref:`mju_error` and :ref:`mju_warning` to be variadic functions (support for printf-like arguments). The
    functions :ref:`mju_error_i`, :ref:`mju_error_s`, :ref:`mju_warning_i`, and :ref:`mju_warning_s` are now deprecated.
@@ -383,7 +467,7 @@ Python bindings
 Simulate
 ^^^^^^^^
 
-15. Implemented a workaround for `broken VSync <https://github.com/glfw/glfw/issues/2249>`_ on macOS so that the frame
+15. Implemented a workaround for `broken VSync <https://github.com/glfw/glfw/issues/2249>`__ on macOS so that the frame
     rate is correctly capped when the Vertical Sync toggle is enabled.
 
 .. image:: images/changelog/contactlabel.png
@@ -404,7 +488,7 @@ General
 
 1. A more performant mju_transposeSparse has been implemented that doesn't require dense memory allocation.
    For a constraint Jacobian matrix from the
-   `humanoid100.xml <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`_ model,
+   `humanoid100.xml <https://github.com/google-deepmind/mujoco/blob/main/model/humanoid100/humanoid100.xml>`__ model,
    this function is 35% faster.
 #. The function :ref:`mj_name2id` is now implemented using a hash function instead of a linear search for better
    performance.
@@ -454,18 +538,18 @@ Python bindings
 ^^^^^^^^^^^^^^^
 
 1. The ``simulate`` GUI is now available through the ``mujoco`` Python package as ``mujoco.viewer``.
-   See :ref:`documentation<PyViewer>` for details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`_.)
+   See :ref:`documentation<PyViewer>` for details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`__.)
 #. The ``Renderer`` class from the MuJoCo tutorial Colab is now available directly in the native Python bindings.
 
 General
 ^^^^^^^
 
 3. The tendon :at:`springlength` attribute can now take two values. Given two non-decreasing values, `springlength`
-   specifies a `deadband  <https://en.wikipedia.org/wiki/Deadband>`_ range for spring stiffness. If the tendon length is
+   specifies a `deadband  <https://en.wikipedia.org/wiki/Deadband>`__ range for spring stiffness. If the tendon length is
    between the two values, the force is 0. If length is outside this range, the force behaves like a regular spring, with
    the spring resting length corresponding to the nearest :at:`springlength` value. This can be used to create tendons
    whose limits are enforced by springs rather than constraints, which are cheaper and easier to analyse. See
-   `tendon_springlength.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/tendon_springlength.xml>`_
+   `tendon_springlength.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/tendon_springlength.xml>`__
    example model.
 
    .. attention::
@@ -479,22 +563,22 @@ General
 #. Removed the requirement that stateless actuators come before stateful actuators.
 #. Added :ref:`mju_fill`, :ref:`mju_symmetrize` and :ref:`mju_eye` utility functions.
 #. Added :at:`gravcomp` attribute to :ref:`body<body>`, implementing gravity compensation and buoyancy.
-   See `balloons.xml <https://github.com/google-deepmind/mujoco/blob/main/model/balloons/balloons.xml>`_ example model.
+   See `balloons.xml <https://github.com/google-deepmind/mujoco/blob/main/model/balloons/balloons.xml>`__ example model.
 #. Renamed the ``cable`` plugin library to ``elasticity``.
 #. Added :at:`actdim` attribute to :ref:`general actuators<actuator-general>`. Values greater than 1 are only allowed
    for dyntype :at-val:`user`, as native activation dynamics are all scalar. Added example test implementing 2nd-order
    activation dynamics to
-   `engine_forward_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/engine/engine_forward_test.cc>`_.
+   `engine_forward_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/engine/engine_forward_test.cc>`__.
 #. Improved particle :ref:`composite<body-composite>` type, which now permits a user-specified geometry and multiple
    joints. See the two new examples:
-   `particle_free.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free.xml>`_ and
+   `particle_free.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free.xml>`__ and
-   `particle_free2d.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free2d.xml>`_.
+   `particle_free2d.xml <https://github.com/google-deepmind/mujoco/blob/main/model/composite/particle_free2d.xml>`__.
 #. Performance improvements for non-AVX configurations:
 
-   - 14% faster ``mj_solveLD`` using `restrict <https://en.wikipedia.org/wiki/Restrict>`_. See `engine_core_smooth_benchmark_test
+   - 14% faster ``mj_solveLD`` using `restrict <https://en.wikipedia.org/wiki/Restrict>`__. See `engine_core_smooth_benchmark_test
-     <https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_core_smooth_benchmark_test.cc>`_.
+     <https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_core_smooth_benchmark_test.cc>`__.
    - 50% faster ``mju_dotSparse`` using manual loop unroll. See `engine_util_sparse_benchmark_test
-     <https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_util_sparse_benchmark_test.cc>`_.
+     <https://github.com/google-deepmind/mujoco/blob/main/test/benchmark/engine_util_sparse_benchmark_test.cc>`__.
 #. Added new :at:`solid` passive force plugin:
 
    .. youtube:: AGcTGHbbze4
@@ -518,9 +602,9 @@ General
    unspecified, the objtype is now :ref:`mjOBJ_UNKNOWN<mjtObj>`. ``user`` sensors :at:`datatype` default is now
    :at-val:`"real"`, :at:`needstage` default is now :at-val:`"acc"`.
 #. Added support for capsules in URDF import.
-#. On macOS, issue an informative error message when run under `Rosetta 2 <https://support.apple.com/en-gb/HT211861>`_
+#. On macOS, issue an informative error message when run under `Rosetta 2 <https://support.apple.com/en-gb/HT211861>`__
    translation on an Apple Silicon machine. Pre-built MuJoCo binaries make use of
-   `AVX <https://en.wikipedia.org/wiki/Advanced_Vector_Extensions>`_ instructions on x86-64 machines, which is not
+   `AVX <https://en.wikipedia.org/wiki/Advanced_Vector_Extensions>`__ instructions on x86-64 machines, which is not
    supported by Rosetta 2. (Before this version, users only get a cryptic "Illegal instruction" message.)
 
 Bug fixes
@@ -573,7 +657,7 @@ General
 
       x^* = \text{argmin} \; \tfrac{1}{2} x^T H x + x^T g \quad \text{s.t.} \quad l \le x \le u
 
-   The algorithm, introduced in `Tassa et al. 2014 <https://doi.org/10.1109/ICRA.2014.6907001>`_,
+   The algorithm, introduced in `Tassa et al. 2014 <https://doi.org/10.1109/ICRA.2014.6907001>`__,
    converges after 2-5 Cholesky factorisations, independent of problem size.
 
 #. Added :ref:`mju_mulVecMatVec` to multiply a square matrix :math:`M` with vectors :math:`x` and :math:`y` on both
@@ -603,11 +687,11 @@ General
 
    - Twist and bending stiffness can be set separately with the parameters :at:`twist` and :at:`bend`.
    - The stress-free configuration can be set to be the initial one or flat with the flag :at:`flat`.
-   - New `cable.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/cable.xml>`_ example
+   - New `cable.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/cable.xml>`__ example
      showing the formation of plectoneme.
-   - New `coil.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/coil.xml>`_  example
+   - New `coil.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/coil.xml>`__  example
      showing a curved equilibrium configuration.
-   - New `belt.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/belt.xml>`_  example
+   - New `belt.xml <https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/belt.xml>`__  example
      showing interaction between twist and anisotropy.
    - Added test using cantilever exact solution.
 
@@ -620,14 +704,14 @@ General
 Python bindings
 ^^^^^^^^^^^^^^^
 11. Added ``id`` and ``name`` properties to
-    `named accessor <https://mujoco.readthedocs.io/en/latest/python.html#named-access>`_ objects.
+    `named accessor <https://mujoco.readthedocs.io/en/latest/python.html#named-access>`__ objects.
     These provide more Pythonic API access to ``mj_name2id`` and ``mj_id2name`` respectively.
 
 #. The length of ``MjData.contact`` is now ``ncon`` rather than ``nconmax``, allowing it to be straightforwardly used as
    an iterator without needing to check ``ncon``.
 
 #. Fix a memory leak when a Python callable is installed as callback
-   (`#527 <https://github.com/google-deepmind/mujoco/issues/527>`_).
+   (`#527 <https://github.com/google-deepmind/mujoco/issues/527>`__).
 
 
 Version 2.2.2 (September 7, 2022)
@@ -641,7 +725,7 @@ General
    :height: 150px
 
 1. Added :ref:`adhesion actuators<actuator-adhesion>` mimicking vacuum grippers and adhesive biomechanical appendages.
-#. Added related `example model <https://github.com/google-deepmind/mujoco/tree/main/model/adhesion>`_ and video:
+#. Added related `example model <https://github.com/google-deepmind/mujoco/tree/main/model/adhesion>`__ and video:
 #. Added :ref:`mj_jacSubtreeCom` for computing the translational Jacobian of the center-of-mass of a subtree.
 #. Added :at:`torquescale` and :at:`anchor` attributes to :el:`weld` constraints. :at:`torquescale` sets the
    torque-to-force ratio exerted by the constraint, :at:`anchor` sets the point at which the weld wrench is
@@ -649,7 +733,7 @@ General
 #. Increased ``mjNEQDATA``, the row length of equality constraint parameters in ``mjModel.eq_data``, from 7 to 11.
 #. Added visualisation of anchor points for both :el:`connect` and :el:`weld` constraints (activated by the 'N' key in
    ``simulate``).
-#. Added `weld.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/weld.xml>`_ showing
+#. Added `weld.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/weld.xml>`__ showing
    different uses of new weld attributes.
 
    .. youtube:: s-0JHanqV1A
@@ -658,7 +742,7 @@ General
 
 #. Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site`
    transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<actuator-general>` documentation
-   and `refsite.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/actuation/refsite.xml>`_
+   and `refsite.xml <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/actuation/refsite.xml>`__
    example model.
 
 #. Added :at:`autolimits` compiler option. If ``true``, joint and tendon :at:`limited` attributes and actuator
@@ -685,7 +769,7 @@ General
       :height: 150px
 
 #. Added catenary visualisation for hanging tendons. The model seen in the video can be found
-   `here <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/catenary.xml>`_.
+   `here <https://github.com/google-deepmind/mujoco/blob/main/test/engine/testdata/catenary.xml>`__.
 #. Added ``azimuth`` and ``elevation`` attributes to :ref:`visual/global<visual-global>`, defining the initial
    orientation of the free camera at model load time.
 #. Added ``mjv_defaultFreeCamera`` which sets the default free camera, respecting the above attributes.
@@ -733,7 +817,7 @@ General
    and `Memory Sanitizer (MSAN) <https://clang.llvm.org/docs/MemorySanitizer.html>`__. This allows ASAN to
    detect reads and writes to regions in ``mjModel.buffer`` and ``mjData.buffer`` that do not lie within an array, and
    for MSAN to detect reads from uninitialised fields in ``mjData`` following ``mj_resetData``.
-#. Added a `slider-crank example model <https://github.com/google-deepmind/mujoco/tree/main/model/slider_crank>`_.
+#. Added a `slider-crank example model <https://github.com/google-deepmind/mujoco/tree/main/model/slider_crank>`__.
 
 Bug fixes
 ^^^^^^^^^
@@ -779,8 +863,8 @@ Open Sourcing
 
    c. ``dist/``: Files related to packaging and binary distribution.
 
-#. Added `contributor's guide <https://github.com/google-deepmind/mujoco/blob/main/CONTRIBUTING.md>`_ and
+#. Added `contributor's guide <https://github.com/google-deepmind/mujoco/blob/main/CONTRIBUTING.md>`__ and
-   `style guide <https://github.com/google-deepmind/mujoco/blob/main/STYLEGUIDE.md>`_.
+   `style guide <https://github.com/google-deepmind/mujoco/blob/main/STYLEGUIDE.md>`__.
 
 General
 ^^^^^^^
@@ -911,7 +995,7 @@ Bug fixes
 ^^^^^^^^^
 
 5. Fixed rendering bug for planes, introduced in 2.1.2. This broke maze environments in
-   `dm_control <https://github.com/google-deepmind/dm_control>`_.
+   `dm_control <https://github.com/google-deepmind/dm_control>`__.
 
 
 Version 2.1.2 (Mar. 15, 2022)
@@ -932,7 +1016,7 @@ API changes
 ^^^^^^^^^^^
 
 4. Moved definition of ``mjtNum`` floating point type into a new header
-   `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/3577e2cf8bf841475b489aefff52276a39f24d51/include/mjtnum.h>`_.
+   `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/3577e2cf8bf841475b489aefff52276a39f24d51/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.
@@ -940,12 +1024,12 @@ API changes
 General
 ^^^^^^^
 
-7. MuJoCo can load `OBJ <https://en.wikipedia.org/wiki/Wavefront_.obj_file>`_ mesh files.
+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 (post-release, not included in the 2.1.2 archive) textured
-      `mug <https://github.com/google-deepmind/mujoco/blob/main/model/mug/mug.xml>`_ example model:
+      `mug <https://github.com/google-deepmind/mujoco/blob/main/model/mug/mug.xml>`__ example model:
 
       .. image:: images/changelog/mug.png
          :width: 300px
@@ -1035,7 +1119,7 @@ Bug Fixes
 #. 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
+   computed with the `Parallel Axis theorem <https://en.wikipedia.org/wiki/Parallel_axis_theorem>`__, applied to the two
    hemispherical end-caps.
 
    .. attention::
@@ -1078,7 +1162,7 @@ Binary build
 
     a. MuJoCo library is now packaged as a `Framework Bundle
        <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnato
-       my.html>`_, allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers
+       my.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,
@@ -1126,7 +1210,7 @@ General
 #. Fixed: The array of sensors in ``mjCModel`` was not cleared.
 #. Cleaned up cross-platform code (internal changes, not visible via the API).
 #. Fixed a bug in parsing of XML ``texcoord`` data (related to number of vertices).
-#. Fixed a bug in `simulate.cc <https://github.com/google-deepmind/mujoco/blob/main/simulate/simulate.cc>`_ related to
+#. Fixed a bug in `simulate.cc <https://github.com/google-deepmind/mujoco/blob/main/simulate/simulate.cc>`__ related to
    ``nkey`` (the number of keyframes).
 #. Accelerated collision detection in the presence of large numbers of non-colliding geoms (with ``contype==0 and
    conaffinity==0``).
@@ -1163,7 +1247,7 @@ License manager
 Earlier versions
 ----------------
 
-For changelogs of earlier versions please see `roboti.us <https://www.roboti.us/download.html>`_.
+For changelogs of earlier versions please see `roboti.us <https://www.roboti.us/download.html>`__.
 
 .. |humanoid| image:: images/models/humanoid.gif
    :width: 270px

doc/computation/fluid.rst

@@ -0,0 +1,572 @@
+Fluid forces
+============
+
+Proper simulation of fluid dynamics is beyond the scope of MuJoCo, and would be too slow for the applications we aim to
+facilitate. Nevertheless we provide two phenomenological models which are sufficient for simulating behaviors
+such as flying and swimming. These models are *stateless*, in the sense that no additional states are assigned to the
+surrounding fluid, yet are able to capture the salient features of rigid bodies moving through a fluid medium.
+
+Both models are enabled by setting the :ref:`density<option-density>` and :ref:`viscosity<option-viscosity>` attributes
+to positive values. These parameters correspond to the density :math:`\rho` and viscosity :math:`\beta` of the medium.
+
+1. The :ref:`Inertia-based model<flInertia>`, uses only viscosity and density, inferring geometry from body
+   equivalent-inertia boxes.
+2. The :ref:`Ellipsoid-based model <flEllipsoid>` is more elaborate, using an ellipsoid approximation of geoms.
+   In addition to the global viscosity and density of the medium, this model exposes 5 tunable parameters per
+   interacting geom.
+
+.. tip::
+   As detailed in the :ref:`Numerical Integration<geIntegration>` section, implicit integration significantly improves
+   simulation stability in the presence of velocity-dependent forces. Both of the fluid-force models described below
+   exhibit this property, so the ``implicit`` or ``implicitfast`` :ref:`intergrators<option-integrator>` are
+   recommended when using fluid forces. The required analytic derivatives for both models are fully implemented.
+
+.. _flInertia:
+
+Inertia model
+-------------
+
+In this model, the shape of each body, for fluid dynamics purposes, is assumed to be the *equivalent inertia box*,
+which can also be visualized. Each forward-facing (relative to the linear velocity) face of the box experiences force
+along its normal direction. All faces also experience torque due to the angular velocity; this torque is obtained by
+integrating the force resulting from the rotation over the surface area. In this sub-section, let :math:`v` and
+:math:`\omega` denote the linear and angular body velocity in the body local frame (aligned with the equivalent
+inertia box), and :math:`s` the 3D vector of box sizes. When the contributions from all faces are added, the resulting
+force and torque applied to the body by a fluid of density :math:`\rho`, in local body coordinates, have the
+:math:`i`-th component
+
+.. math::
+   \begin{aligned}
+   \text{density force} : \quad &- {1 \over 2} \rho s_j s_k |v_i| v_i \\
+   \text{density torque} : \quad &- {1 \over 64} \rho s_i \left(s_j^4 + s_k^4 \right) |\omega_i| \omega_i \\
+   \end{aligned}
+
+This model implicitly assumes high Reynolds numbers, with lift-to-drag ratio equal to the tangent of the angle of
+attack. One can also specify a non-zero :ref:`wind<option-wind>`, which is a 3D vector subtracted from the body linear
+velocity in the fluid dynamics computation.
+
+Each body also experiences a force and a torque proportional to the viscosity :math:`\beta` and opposite to its linear and
+angular velocity. Note that viscosity can be used independent of density, to make the simulation more damped. We use the
+formulas for a sphere at low Reynolds numbers, with diameter :math:`d` equal to the average of the equivalent inertia
+box sizes. The resulting 3D force and torque in local body coordinates are
+
+.. math::
+   \begin{aligned}
+   \text{viscosity force} : \quad &- 3 \beta \pi d v \\
+   \text{viscosity torque} : \quad &- \beta \pi d^3 \omega \\
+   \end{aligned}
+
+.. _flEllipsoid:
+
+Ellipsoid model
+---------------
+
+.. cssclass:: caption-small
+.. figure:: ../images/computation/fruitfly.png
+   :figwidth: 50%
+   :align: right
+
+   The flight-capable Drosophila Melanogaster model in this figure will be described in a
+   forthcoming publication.
+
+
+In this section we describe and derive a stateless model of the forces exerted onto a moving rigid body by the
+surrounding fluid, based on an ellipsoidal approximation of geom shape. This model provides finer-grained control of the
+different types of fluid forces than the inertia-based model of the previous section. The motivating use-case for this
+model is insect flight, see figure on the right.
+
+
+Summary
+~~~~~~~
+
+The model is activated per-geom by setting the :ref:`fluidshape<body-geom-fluidshape>` attribute to ``ellipsoid``, which
+also disables the inertia-based model for the parent body. The
+5 numbers in the :ref:`fluidcoef<body-geom-fluidcoef>` attribute correspond to the following semantics
+
+
+.. list-table::
+   :width: 60%
+   :align: left
+   :widths: 1 5 2 1
+   :header-rows: 1
+
+   * - Index
+     - Description
+     - Symbol
+     - Default
+   * - 0
+     - Blunt drag coefficient
+     - :math:`C_{D, \text{blunt}}`
+     - 0.5
+   * - 1
+     - Slender drag coeficient
+     - :math:`C_{D, \text{slender}}`
+     - 0.25
+   * - 2
+     - Angular drag coeficient
+     - :math:`C_{D, \text{angular}}`
+     - 1.5
+   * - 3
+     - Kutta lift coeficient
+     - :math:`C_K`
+     - 1.0
+   * - 4
+     - Magnus lift coeficient
+     - :math:`C_M`
+     - 1.0
+
+Elements of the model are a generalization of :cite:t:`andersen2005b` to 3 dimensions.
+The force :math:`\mathbf{f}_{\text{fluid}\rightarrow \text{solid}}` and torque
+:math:`\mathbf{g}_{\text{fluid} \rightarrow \text{solid}}` exerted by the fluid onto the solid are
+the sum of of the terms
+
+.. math::
+   \begin{align*}
+   \mathbf{f}_{\text{fluid} \rightarrow \text{solid}} &= \mathbf{f}_A + \mathbf{f}_D + \mathbf{f}_M + \mathbf{f}_K  \\
+   \mathbf{g}_{\text{fluid} \rightarrow \text{solid}} &= \mathbf{g}_A + \mathbf{g}_D
+   \end{align*}
+
+Where subscripts :math:`A`, :math:`D`, :math:`M` and :math:`K`, denote Added mass, viscous Drag, Magnus lift and
+Kutta lift, respectively. The :math:`D`, :math:`M` and :math:`K` terms are scaled by the respective
+:math:`C_D`, :math:`C_M` and :math:`C_K` coefficients above, while the added mass term cannot be scaled.
+
+Notation
+~~~~~~~~
+
+We describe the motion of the object in an inviscid, incompressible quiescent fluid of density :math:`\rho`. The
+arbitrarily-shaped object is described in the model as the equivalent ellipsoid of semi-axes
+:math:`\mathbf{d} = \{d_x, d_y, d_z\}`.
+The problem is described in a reference frame aligned with the sides of the ellipsoid and moving with it. The
+body has velocity :math:`\mathbf{v} = \{v_x, v_y, v_z\}` and angular velocity
+:math:`\boldsymbol{\omega} = \{\omega_x, \omega_y, \omega_z\}`. We will also use
+
+.. math::
+   \begin{align*}
+       d_\text{max} &= \max(d_x, d_y, d_z) \\
+       d_\text{min} &= \min(d_x, d_y, d_z) \\
+       d_\text{mid} &= d_x + d_y + d_z - d_\text{max} - d_\text{min}
+   \end{align*}
+
+The Reynolds number is the ratio between inertial and viscous forces within a flow and is defined as :math:`Re=u~l/\beta`, where
+:math:`\beta` is the kinematic viscosity of the fluid, :math:`u` is the characteristic speed of the flow (or, by change of frame, the
+speed of the body), and :math:`l` is a characteristic size of the flow or the body.
+
+We will use :math:`\Gamma` to denote circulation, which is the line integral of the velocity field around a closed curve
+:math:`\Gamma = \oint \mathbf{v} \cdot \textrm{d} \mathbf{l}` and, due to Stokes' Theorem,
+:math:`\Gamma = \int_S \nabla \times \mathbf{v} \cdot \textrm{d}\mathbf{s}`.
+In fluid dynamics notation the symbol :math:`\boldsymbol{\omega}` is often used for the
+vorticity, defined as :math:`\nabla \times \mathbf{v}`, rather than the angular velocity. For a rigid-body motion, the
+vorticity is twice the angular velocity.
+
+Finally, we use the subscripts :math:`i, j, k` to denote triplets of equations that apply symmetrically to
+:math:`x, y, z`. For example :math:`a_i = b_j + b_k` is shorthand for the 3 equations
+
+.. math::
+   \begin{align*}
+       a_x &= b_y + b_z \\
+       a_y &= b_x + b_z \\
+       a_z &= b_x + b_y
+   \end{align*}
+
+.. _flProjection:
+
+Ellipsoid projection
+~~~~~~~~~~~~~~~~~~~~
+
+We present the following result.
+
+.. admonition:: Lemma
+   :class: note
+
+   Given an ellipsoid with semi-axes :math:`(d_x, d_y, d_z)` aligned with the coordinate axes :math:`(x, y, z)`, and a
+   unit vector :math:`\mathbf{u} = (u_x, u_y, u_z)`, the area projected by the ellipsoid onto the plane normal to
+   :math:`\mathbf{u}` is
+
+   .. math::
+      A^{\mathrm{proj}}_{\mathbf{u}} = \pi \sqrt{\frac{d_y^4 d_z^4 u_x^2 + d_z^4 d_x^4 u_y^2 + d_x^4 d_y^4 u_z^2}{d_y^2 d_z^2 u_x^2 + d_z^2 d_x^2 u_y^2 + d_x^2 d_y^2 u_z^2}}
+
+.. collapse:: Expand for derivation
+
+   .. admonition:: Derivation of lemma
+      :class: tip
+
+      **Area of an ellipse**
+         Any ellipse centered at the origin can be described in terms of a quadratic form a
+         :math:`\mathbf{x}^T Q \mathbf{x} = 1`, where :math:`Q` is a real, symmetric, positive-definite 2x2 matrix that
+         defines the orientation and  semi-axis lengths of the ellipse, and :math:`\mathbf{x} = (x, y)` are points on the
+         ellipse. The area of the ellipse is given by
+
+         .. math::
+            A = \frac{\pi}{\sqrt{\det Q}} .
+
+      **Ellipsoid cross-section**
+         We begin by computing the area of the ellipse formed by intersecting an ellipsoid centered at the origin with the
+         plane :math:`\Pi_{\mathbf{n}}` through the origin with unit normal :math:`\mathbf{n} = (n_x, n_y, n_z)`. Let
+         :math:`(d_x, d_y, d_z)` be the semi-axis lengths of the ellipsoid. Without loss of generality, it is sufficient to
+         assume that the axes of the ellipsoid are aligned with the coordinate axes. The ellipsoid can then be described as
+         :math:`\mathbf{x}^T Q \mathbf{x} = 1`, where
+         :math:`Q = \textrm{diag}\mathopen{}\left( \left. 1 \middle/ d_x^2 \right., \left. 1 \middle/ d_y^2 \right., \left. 1 \middle/ d_z^2 \right. \right)\mathclose{}`
+         and :math:`\mathbf{x} = (x, y, z)` are the points on the ellipsoid.
+
+         We proceed by rotating the plane :math:`\Pi_{\mathbf{n}}` together with the ellipsoid so that the normal of the
+         rotated plane points along the :math:`z` axis. This would then allow us to get the desired intersection by setting
+         the :math:`z` coordinate to zero. Writing :math:`\mathbf{\hat{z}}` for the unit vector along the :math:`z` axis, we
+         have
+
+         .. math::
+            \begin{align*}
+            \mathbf{n} \times \mathbf{\hat{z}} &= \sin\theta \, \mathbf{m}, \\
+            \mathbf{n} \cdot \mathbf{\hat{z}} &= \cos\theta ,
+            \end{align*}
+
+         where :math:`\mathbf{m}` is the unit vector that defines the rotation axis and :math:`\theta` is the rotation
+         angle. We can rearrange these to get quantities that we need to form a rotation quaternion, namely
+
+         .. math::
+            \begin{align*}
+            \cos\frac{\theta}{2}
+            &= \sqrt{\frac{1+\cos\theta}{2}}
+            &= \sqrt{\frac{1 + \mathbf{n} \cdot \mathbf{\hat{z}}}{2}}, \\
+            \sin\frac{\theta}{2}\,\mathbf{m}
+            &= \frac{\mathbf{n} \times \mathbf{\hat{z}}}{2\cos\frac{\theta}{2}}
+            &= \frac{\mathbf{n} \times \mathbf{\hat{z}}}{\sqrt{2 (1 + \mathbf{n} \cdot \mathbf{\hat{z}})}} .
+            \end{align*}
+
+         The rotation quaternion :math:`q = q_r + q_x \mathbf{i} + q_y \mathbf{j} + q_z \mathbf{k}` is therefore given by
+
+         .. math::
+            q_r = \sqrt{\frac{1 + n_z}{2}}, \quad
+            q_x = \frac{n_y}{\sqrt{2 \left(1+n_z\right)}},  \quad
+            q_y = \frac{-n_x}{\sqrt{2 \left(1+n_z\right)}}, \quad
+            q_z = 0 .
+
+         From this, the rotation matrix is given by
+
+         .. math::
+            \def\arraystretch{1.33}
+            \begin{align*}
+            R &= \begin{pmatrix}
+            1 - 2 q_y^2 - 2 q_z^2 & 2 \left(q_x q_y - q_r q_z\right) & 2 \left(q_x q_z + q_r q_y\right) \\
+            2 \left(q_x q_y + q_r q_z\right) & 1 - 2 q_x^2 - 2 q_z^2 & 2 \left(q_y q_z - q_r q_x\right) \\
+            2 \left(q_x q_z - q_r q_y\right) & 2 \left(q_y q_z + q_r q_x\right) & 1 - 2 q_x^2 - 2 q_y^2
+            \end{pmatrix} \\
+            &= \begin{pmatrix}
+            1 - \left. n_x^2 \middle/ \left( 1+n_z \right) \right. & \left. -n_x n_y \middle/ \left( 1+n_z \right) \right. & -n_x \\
+            \left. -n_x n_y \middle/ \left( 1+n_z \right) \right. & 1 - \left. n_y^2 \middle/ \left( 1+n_z \right) \right. & -n_y \\
+            n_x & n_y & 1 - \left. \left( n_x^2 + n_y^2 \right) \middle/ \left( \vphantom{n_x^2} 1+n_z \right) \right.
+            \end{pmatrix},
+            \end{align*}
+
+         and the rotated ellipsoid is described via the transformed quadratic form
+
+         .. math::
+            \mathbf{x}^T Q' \mathbf{x} = \mathbf{x}^T \left( R^T Q R \right) \mathbf{x} = 1 .
+
+         From the formula for ellipse area above, for the area of the ellipse at :math:`z=0`, we need
+
+         .. math::
+            \begin{align*}
+            Q'_{xx} &= \frac{1}{d_x^2} R_{xx}^2 + \frac{1}{d_y^2} R_{yx}^2 + \frac{1}{d_z^2} R_{zx}^2 , \\
+            Q'_{yy} &= \frac{1}{d_x^2} R_{xy}^2 + \frac{1}{d_y^2} R_{yy}^2 + \frac{1}{d_z^2} R_{zy}^2 , \\
+            Q'_{xy} &= \frac{1}{d_x^2} R_{xx} R_{xy} + \frac{1}{d_y^2} R_{yx} R_{yy} + \frac{1}{d_z^2} R_{zx} R_{zy} ,
+            \end{align*}
+
+         and the desired area is given by
+
+         .. math::
+            A^{\cap}_{\mathbf{n}}
+            = \frac{\pi}{\sqrt{\vphantom{Q'^2_{xy}} \det Q'}}
+            = \frac{\pi}{\sqrt{Q'_{xx} Q'_{yy} - Q'^2_{xy}}}
+            = \frac{\pi d_x d_y d_z}{\sqrt{d_x^2 n_x^2 + d_y^2 n_y^2 + d_z^2 n_z^2}},
+
+         where the superscript :math:`\cap` denotes that the area pertains to the ellipse at the *intersection*
+         with :math:`\Pi_{\mathbf{n}}`.
+
+      **Projected ellipse**
+         Let :math:`\mathbf{u} = (u_x, u_y, u_z)` be some unit vector (in our context, it is the direction of the velocity
+         of the fluid impinging on an ellipsoid) and let :math:`\Pi_{\mathbf{u}}` be the plane normal to :math:`\mathbf{u}`.
+         In general, the ellipse formed by projecting an ellipsoid :math:`\mathcal{E}` onto :math:`\Pi_{\mathbf{u}}`
+         (denoted :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}`) is different from the one formed by intersecting
+         :math:`\mathcal{E}` with :math:`\Pi_{\mathbf{u}}` (denoted :math:`\mathcal{E}^{\cap}_{\mathbf{u}}`).
+
+         An important property of :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}` is that :math:`\mathbf{u}` is tangent
+         tangent to the ellipsoid :math:`\mathcal{E}` at every point on :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}`.
+
+         We can regard :math:`\mathcal{E}` as the image of the unit sphere :math:`\mathcal{S}` under a stretching
+         transformation :math:`T = \mathrm{diag}(d_x, d_y, d_z)`. Furthermore, if :math:`\mathbf{\tilde{u}}` is a vector
+         tangent to :math:`\mathcal{S}`, then its image
+         :math:`\mathbf{u}=T\mathbf{\tilde{u}}=(d_x \tilde{u}_x, d_y \tilde{u}_y, d_z \tilde{u}_z)` is tangent to the
+         ellipsoid. The ellipse :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}` is therefore the image
+         under :math:`T` of the circle :math:`\mathcal{C}^{\cap}_{\mathbf{\tilde{u}}}` at the intersection between
+         :math:`\mathcal{S}` and :math:`\Pi_{\mathbf{\tilde{u}}}` (for spheres :math:`\mathcal{C}^{\cap}` and
+         :math:`\mathcal{C}^{\mathrm{proj}}` do coincide).
+
+         Let :math:`\mathbf{\tilde{v}}` and :math:`\mathbf{\tilde{w}}` be some orthogonal pair of vectors in the plane
+         :math:`\Pi_{\mathbf{\tilde{u}}}`, then :math:`\mathbf{\tilde{u}} = \mathbf{\tilde{v}} \times \mathbf{\tilde{w}}`.
+         Their images under :math:`T` are :math:`\mathbf{v} = (d_x \tilde{v}_x, d_y \tilde{v}_y, d_z \tilde {v}_z)` and
+         :math:`\mathbf{w} = (d_x \tilde{w}_x, d_y \tilde{w}_y, d_z \tilde {w}_z)` respectively, and they remain orthogonal
+         vectors in the plane of :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}`. A (non-unit) normal to the ellipse
+         :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}` is therefore given by
+
+         .. math::
+            \mathbf{N} = \mathbf{v} \times \mathbf{w}
+            = (d_y d_z \tilde{u}_x, d_z d_x \tilde{u}_y, d_x d_y \tilde{u}_z)
+            = \left( \frac{d_y d_z}{d_x} u_x, \frac{d_z d_x}{d_y} u_y, \frac{d_x d_y}{d_z} u_z \right).
+
+         This shows that :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}} = \mathcal{E}^{\cap}_{\mathbf{n}}`, where
+         :math:`\mathbf{n} = \mathbf{N} / \left\Vert\mathbf{N}\right\Vert`. Its area is given by the formula derived in the
+         previous section, leading to the result stated above.
+
+Added mass
+~~~~~~~~~~
+
+For a body moving in a fluid, added mass or virtual mass measures the inertia of the fluid that is moved due to the
+body's motion. It can be derived from potential flow theory (i.e. it is present also for inviscid flows).
+
+Following Chapter 5 of :cite:t:`lamb1932`, the forces :math:`\mathbf{f}_{V}` and torques :math:`\mathbf{g}_{V}` exerted
+onto a moving body due to generation of motion in the fluid from rest can be written as:
+
+.. math::
+   \begin{align*}
+       \mathbf{f}_{A} &= - \frac{\textrm{d}}{\textrm{d} t} \nabla_{\mathbf{v}} \mathcal{T} + \nabla_{\mathbf{v}} \mathcal{T} \times \boldsymbol{\omega} \\
+       \mathbf{g}_{A} &= - \frac{\textrm{d}}{\textrm{d} t} \nabla_{\boldsymbol{\omega}} \mathcal{T} + \nabla_{\mathbf{v}} \mathcal{T} \times \mathbf{v} + \boldsymbol{\omega} \times \nabla_{\boldsymbol{\omega}} \mathcal{T}
+   \end{align*}
+
+where :math:`\mathcal{T}` is the kinetic energy of the fluid alone. These forces are often described as added or
+virtual mass because they are due to the inertia of the fluid that is to moved or deflected by the accelerating body. In
+fact, for a body with constant linear velocity these forces reduce to zero. We consider the body as having three planes
+of symmetry because under this assumption the kinetic energy greatly simplifies and can be written as:
+
+.. math::
+   2 \mathcal{T} = m_{A, x} v_x^2 + m_{A, y} v_y^2 + m_{A, z} v_z^2 +
+                 I_{A, x} \omega_x^2 + I_ {A, y} \omega_y^2 + I_{A, y} \omega_z^2
+
+
+For convenience we introduce the added-mass vector :math:`\mathbf{m}_A = \{m_{A, x}, m_{A, y}, m_{A, z}\}` and added-moment of
+inertia vector :math:`\mathbf{I}_A = \{I_{A, x}, I_{A, y}, I_{A, z}\}`. Each of these quantities should estimate the inertia
+of the moved fluid due the motion of the body in the corresponding direction and can be derived from potential flow
+theory for some simple geometries.
+
+For a body with three planes of symmetry, we can write in compact form the forces and torques due to added inertia:
+
+.. math::
+   \begin{align*}
+       \mathbf{f}_{A} &= - \mathbf{m}_A \circ \dot{\mathbf{v}} + \left(\mathbf{m}_A \circ \mathbf{v} \right) \times \boldsymbol{\omega} \\
+       \mathbf{g}_{A} &= - \mathbf{I}_A \circ \dot{\boldsymbol{\omega}} + \left(\mathbf{m}_A \circ \mathbf{v} \right) \times \mathbf{v} + \left(\mathbf{I}_A \circ \boldsymbol{\omega} \right) \times \boldsymbol{\omega}
+   \end{align*}
+
+Here :math:`\circ` denotes an element-wise product, :math:`\dot{\mathbf{v}}` is the linear acceleration and
+:math:`\dot{\boldsymbol{\omega}}` is the angular acceleration. :math:`\mathbf{m}_A \circ \mathbf{v}` and
+:math:`\mathbf{I}_A \circ \boldsymbol{\omega}` are the virtual linear and angular momentum respectively.
+
+For an ellipsoid of semi-axis :math:`\mathbf{d} = \{d_x, d_y, d_z\}` and volume :math:`V = 4 \pi d_x d_y d_z / 3`, the
+virtual inertia coefficients were derived by :cite:t:`tuckerman1925`. Let:
+
+.. math::
+   \kappa_i = \int_0^\infty \frac{d_i d_j d_k}{\sqrt{(d_i^2 + \lambda)^3 (d_j^2 + \lambda) (d_k^2 + \lambda)}} \textrm{d} \lambda
+
+
+It should be noted that these coefficients are non-dimensional (i.e. if all semi-axes are multiplied by the same scalar
+the coefficients remain the same). The virtual masses of the ellipsoid are:
+
+.. math::
+   m_{A, i} = \rho V \frac{\kappa_i}{2 - \kappa_i}
+
+And the virtual moments of inertia are:
+
+.. math::
+   I_{A, i} = \frac{\rho V}{5} \frac{(d_j^2 - d_k^2)^2 (\kappa_k-\kappa_j)}{2(d_j^2 - d_k^2) + (d_j^2 + d_k^2) (\kappa_j-\kappa_k)}
+
+Viscous drag
+~~~~~~~~~~~~
+
+The drag force acts to oppose the motion of the body relative to the surrounding flow. We found that viscous forces
+serve also to reduce the stiffness of the equations of motion extended with the fluid dynamic terms. For this reason, we
+opted to err on the conservative side and chose approximations of the viscous terms that may overestimate dissipation.
+
+Despite being ultimately caused by viscous dissipation, for high Reynolds numbers the drag is independent of the
+viscosity and scales with the second power of the velocity. It can be written as:
+
+.. math::
+   \begin{align*}
+   \mathbf{f}_\text{D} = - C_D~\rho~ A_D ~ \|\mathbf{v}\|~ \mathbf{v}\\
+   \mathbf{g}_\text{D} = - C_D \rho~ I_D ~ \|\boldsymbol{\omega}\| ~ \boldsymbol{\omega}
+   \end{align*}
+
+Where :math:`C_D` is a drag coefficient, and :math:`A_D` is a reference surface area (e.g. a measure of the projected
+area on the plane normal to the flow), and :math:`I_D` a reference moment of inertia.
+
+.. youtube:: nljr0X79vI0
+   :align: right
+   :width: 50%
+
+Even for simple shapes, the terms :math:`C_D`, :math:`A_D` and :math:`I_D` need to be tuned to the problem-specific
+physics and dynamical scales :cite:p:`duan2015`. For example, the drag coefficient :math:`C_D` generally decreases with
+increasing Reynolds numbers, and a single reference area :math:`A_D` may not be sufficient to account for the skin
+drag for highly irregular or slender bodies. For example, experimental fits are derived from problems ranging from
+falling playing cards :cite:p:`wang2004,andersen2005a,andersen2005b` to particle transport :cite:p:`loth2008,
+bagheri2016`. See screen capture of the
+`cards.xml <https://github.com/deepmind/mujoco/blob/main/model/card/cards.xml>`__ model on the right.
+
+We derive a formula for :math:`\mathbf{f}_\text{D}` based on two surfaces :math:`A^\text{proj}_\mathbf{v}` and
+:math:`A_\text{max}`. The first, :math:`A^\text{proj}_\mathbf{v}`, is the cylindrical projection of the body onto a
+plane normal to the velocity :math:`\mathbf{v}`. The second is the maximum projected surface
+:math:`A_\text{max} = 4 \pi d_{max} d_{min}`.
+
+.. math::
+   \mathbf{f}_\text{D} = - \rho~ \big[  C_{D, \text{blunt}} ~ A^\text{proj}_\mathbf{v} ~ +
+   C_{D, \text{slender}}\left(A_\text{max} - A^\text{proj}_\mathbf{v} \right) \big] ~ \|\mathbf{v}\|~ \mathbf{v}
+
+The formula and derivation for :math:`A^\text{proj}_\mathbf{v}` is given in the :ref:`lemma<flProjection>` above.
+
+We propose an analogous model for the angular drag. For each Cartesian axis we consider the moment of inertia of the
+maximum swept ellipsoid obtained by the rotation of the body around the axis. The resulting diagonal entries of the
+moment of inertia are:
+
+.. math::
+   \mathbf{I}_{D,ii} = \frac{8\pi}{15} ~d_i ~\max(d_j, ~d_k)^4 .
+
+Given this reference moment of inertia, the angular drag torque is computed as:
+
+.. math::
+   \mathbf{g}_\text{D} = - \rho ~ \boldsymbol{\omega} ~ \Big( \big[ C_{D, \text{angular}} ~ \mathbf{I}_D ~ +
+   C_{D, \text{slender}} \left(\mathbf{I}_\text{max} - \mathbf{I}_D \right) \big] \cdot \boldsymbol{\omega} \Big)
+
+
+Here :math:`\mathbf{I}_\text{max}` is a vector with each entry equal to the maximal component of :math:`\mathbf{I}_D`.
+
+The viscosity :math:`\beta`
+For Reynolds numbers around or below :math:`O(10)`, the drag is best approximated as linear in the flow velocity
+(e.g. Stokes' law). For example, for a sphere the drag force :cite:p:`stokes1850` and torque :cite:p:`lamb1932` are:
+
+.. math::
+   \begin{align*}
+   \mathbf{f}_\text{S} &= - 6 \pi r_D \rho ~ \beta \mathbf{v}\\
+   \mathbf{g}_\text{S} &= - 8 \pi r_D^3 \rho ~ \beta \boldsymbol{\omega}
+   \end{align*}
+
+Here, :math:`r_D` is the radius of the sphere and :math:`\beta` is the kinematic viscosity of the medium (e.g.
+:math:`1.48~\times 10^{-5}~m^2/s` for ambient-temperature air and :math:`0.89 \times 10^{-4}~m^2/s` for water). Here,
+for simplicity, we estimate the radius of the equivalent sphere as :math:`r_D = (d_x + d_y + d_z)/3`. To make a
+quantitative example, Stokes' law become accurate for room-temperature air if
+:math:`u\cdot l \lesssim 2 \times 10^{-4}~m^2/s`, where :math:`u` is the speed and :math:`l` a characteristic length of
+the body.
+
+Viscous lift
+~~~~~~~~~~~~
+
+The Kutta-Joukowski theorem calculates the lift :math:`L` of a two-dimensional body translating in a uniform flow with
+speed `u` as :math:`L = \rho u \Gamma`. Here, :math:`\Gamma` is the circulation around the body. In the next
+subsections we define two sources of circulation and the resulting lift forces.
+
+Magnus force
+^^^^^^^^^^^^
+
+.. cssclass:: caption-small
+.. figure:: ../images/computation/magnus.png
+   :figwidth: 45%
+   :align: right
+
+   Smoke flow visualization of the flow past a rotating cylinder (WikiMedia Commons, CC BY-SA 4.0). Due to viscosity,
+   the rotating cylinder deflects the incoming flow upward and receives a downwards force (red arrow).
+
+The Magnus effect describes the motion of a rotating object moving through a fluid. Through viscous effects, a spinning
+object induces rotation in the surrounding fluid. This rotation deflects the trajectory of the fluid past the object
+(i.e. it causes linear acceleration), and the object receives an equal an opposite reaction. For a cylinder, the Magnus
+force per unit length of the cylinder can be computed as :math:`F_\text{M} / L = \rho v \Gamma`, where :math:`\Gamma`
+is the circulation of the flow caused by the rotation and :math:`v` the velocity of the object. We estimate this force
+for an arbitrary body as:
+
+.. math::
+   \mathbf{f}_{\text{M}} = C_M ~\rho~ V~ \boldsymbol{\omega}\times\mathbf{v} ,
+
+where :math:`V` is the volume of the body and :math:`C_M` is a coefficient for the force, typically set to 1.
+
+It's worth making an example. To reduce the number of variables, suppose a body rotating in only one direction, e.g.
+:math:`\boldsymbol{\omega} = \{0, 0, \omega_z\}`, translating along the other two, e.g. :math:`\mathbf{v} = \{v_x, v_y, 0\}`. The
+sum of the force due to added mass and the force due to the Magnus effect along, for example, :math:`x` is:
+
+.. math::
+   \frac{f}{\pi \rho d_z} = v_y \omega_z \left(2 d_x \min\{d_x, d_z\} - (d_x + d_z)^2\right)
+
+Note that the two terms have opposite signs.
+
+Kutta condition
+^^^^^^^^^^^^^^^
+
+A stagnation point is a location in the flow field where the velocity is zero. For a body moving in a flow (in 2D, in
+the frame moving with the body) there are two stagnation points: in the front, where the stream-lines separate to either
+sides of the body, and in the rear, where they reconnect. A moving body with a sharp trailing (rear) edge will generate
+in the surrounding flow a circulation of sufficient strength to hold the rear stagnation point at the trailing edge.
+This is the Kutta condition, a fluid dynamic phenomenon that can be observed for solid bodies with sharp corners, such
+as slender bodies or the trailing edges of airfoils.
+
+.. cssclass:: caption-small
+.. figure:: ../images/computation/kutta_cond_plate.svg
+   :figwidth: 95%
+   :align: left
+
+   Sketch of the Kutta condition. Blue lines are streamlines and the two magenta points are the stagnation points. The
+   dividing streamline, which connects the two stagnation points, is marked in green. The dividing streamline and the
+   body inscribe an area where the flow is said to be "separated" and recirculates within. This circulation produces an
+   upward force acting on the plate.
+
+For a two-dimensional flow sketched in the figure above, the circulation due to the Kutta condition can be estimated as:
+:math:`\Gamma_\text{K} = C_K ~ d_x ~ \| \mathbf{v}\| ~ \sin(2\alpha)`,
+where :math:`C_K` is a lift coefficient, and :math:`\alpha` is the angle between the velocity vector and its projection
+onto the surface. The lift force per unit length can be computed with the Kutta–Joukowski theorem as
+:math:`\mathbf{f}_K / L = \rho \Gamma_\text{K} \times \mathbf{v}`.
+
+In order to extend the lift force equation to three-dimensional motions, we consider the normal
+:math:`\mathbf{n}_{s, \mathbf{v}} = \{\frac{d_y d_z}{d_x}v_x, \frac{d_z d_x}{d_y}v_y, \frac{d_x d_x}{d_z}v_z\}`
+to the cross-section of the body which generates the body's projection :math:`A^\text{proj}_\mathbf{v}` onto a plane
+normal to the velocity given in the :ref:`lemma<flProjection>` above and the corresponding unit vector
+:math:`\hat{\mathbf{n}}_{s, \mathbf{v}}`.
+We use this direction to decompose :math:`\mathbf{v} = \mathbf{v}_\parallel ~+~ \mathbf{v}_\perp` with
+:math:`\mathbf{v}_\perp = \left(\mathbf{v} \cdot \hat{\mathbf{n}}_{s, \mathbf{v}}\right) \hat{\mathbf{n}}_{s, \mathbf{v}}`.
+We write the lift force as:
+
+.. math::
+   \begin{align*}
+       \mathbf{f}_\text{K} &= \frac{C_K~\rho~ A^\text{proj}_\mathbf{v}}{\|\mathbf{v}\|}
+                                 \left( \mathbf{v} \times \mathbf{v}_\parallel\right)\times \mathbf{v} \\
+       &= C_K~\rho~ A^\text{proj}_\mathbf{v} \left(\hat{\mathbf{v}} \cdot \hat{\mathbf{n}}_{s, \mathbf{v}}\right)
+                                 \left( \hat{\mathbf{n}}_{s, \mathbf{v}} \times \mathbf{v} \right)\times \mathbf{v}
+   \end{align*}
+
+Here, :math:`\hat{\mathbf{v}}` is the unit-normal along :math:`\mathbf{v}`. Note that the direction of :math:`\hat{\mathbf{n}}_{s,
+\mathbf{v}}` differs from :math:`\hat{\mathbf{v}}` only on the planes where the semi-axes of the body are unequal. So for
+example, for spherical bodies :math:`\hat{\mathbf{n}}_{s, \mathbf{v}} \equiv \hat{\mathbf{v}}` and by construction
+:math:`\mathbf{f}_\text{K} = 0`.
+
+Let's unpack the relation with an example. Suppose a body with :math:`d_x = d_y` and :math:`d_z \ll d_x`. Note that the vector
+:math:`\hat{\mathbf{n}}_{s, \mathbf{v}} \times \hat{\mathbf{v}}` gives the direction of the circulation induced by the
+deflection of the flow by the solid body. Along :math:`z`, the circulation will be proportional to :math:`\frac{d_y d_z}{d_x}v_x v_y
+- \frac{d_z d_x}{d_y}v_x v_y = 0` (due to :math:`d_x = d_y`). Therefore, on the plane where the solid is blunt, the motion
+produces no circulation.
+
+Now, for simplicity, let :math:`v_x = 0`. In this case also the circulation along :math:`y`, proportional
+to :math:`\frac{d_y d_z}{d_x}v_x v_z - \frac{d_y d_x}{d_y}v_x v_z`, is zero. The only non-zero component of the circulation
+will be along :math:`x` and be proportional to :math:`\left(\frac{d_x d_z}{d_y} - \frac{d_x d_y}{d_z}\right) v_y v_z \approx
+\frac{d_x^2}{d_z} v_y v_z`.
+
+We would have :math:`\mathbf{v}_\parallel = \{v_x, 0, v_z\}` and
+:math:`\Gamma \propto \{d_z v_y v_z, ~ 0,~ - d_x v_x v_y \} / \|\mathbf{v}\|`.
+The motion produces no circulation on the plane where the solid is blunt, and on the other two planes
+the circulation is
+:math:`\Gamma \propto r_\Gamma ~ \|\mathbf{v}\|~ \sin(2 \alpha) ~ = ~2 r_\Gamma ~\|\mathbf{v}\| ~\sin(\alpha)~\cos(\alpha)`
+with :math:`\alpha` the angle between the velocity and its projection on the body on the plane (e.g. on the plane
+orthogonal to :math:`x` we have :math:`\sin(\alpha) = v_y/\|\mathbf{v}\|` and
+:math:`\cos(\alpha) = v_z/\|\mathbf{v}\|`), and :math:`r_\Gamma`, the lift surface on the plane (e.g. :math:`d_z` for
+the plane orthogonal to :math:`x`). Furthermore, the direction of the circulation is given by the cross product (because
+the solid boundary "rotates" the incoming flow velocity towards its projection on the body).
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+
+The design and implementation of the model in this section are the work of Guido Novati.
+
+References
+~~~~~~~~~~
+
+.. bibliography::

doc/computation/index.rst

@@ -1,6 +1,12 @@
 Computation
 ===========
 
+.. toctree::
+    :hidden:
+
+    fluid
+
+
 Introduction
 ------------
 
@@ -389,59 +395,16 @@ by MuJoCo are also passive in the sense of physics, i.e., they do not increase e
 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.
 
-MuJoCo can compute three types of passive forces: spring-dampers in joints and tendons, gravity compensation forces, and
+MuJoCo can compute three types of passive forces:
-fluid dynamics.
 
-When Euler or the implicit integator are used, joint damping is integrated implicitly which significantly increases
+- Spring-dampers in joints and tendons. See the following attribues for details.
-stability. Thus, even though damping can be modeled as an actuator property, it is better to model it as a joint
+  |br| **Joints:**
-property. Note also the XML :ref:`joint <body-joint>` attribute springdamper which automates the creation of mass-
+  :ref:`stiffness<body-joint-stiffness>`, :ref:`springref<body-joint-springref>`,
-spring-dampers with desired time constants and damping ratios; in that case the compiler computes the stiffness and
+  :ref:`damping<body-joint-damping>`, :ref:`springdamper<body-joint-springdamper>`.
-damping coefficients of the joint by taking the joint inertia into account.
+  |br| **Tendons:** :ref:`stiffness<tendon-spatial-stiffness>`,
-
+  :ref:`springlength<tendon-spatial-springlength>`, :ref:`damping<tendon-spatial-damping>`.
-Gravity compensation is a force applied to a body's center of mass opposing gravity, see :ref:`body gravcomp<body>` for
+- Gravity compensation forces. See the body :ref:`gravcomp<body-gravcomp>` attribute for details.
-details.
+- Fluid forces exerted by the surrounding medium. See the :doc:`Fluid forces <fluid>` chapter for details.
-
-Proper simulation of fluid dynamics is beyond the scope of MuJoCo, and would be too slow for the applications we aim to
-facilitate. Nevertheless we provide a phenomenological model which is sufficient for simulating behaviors such as flying
-and swimming. It is enabled by setting ``mjModel.opt.viscosity`` and ``mjModel.opt.density`` to positive values (they
-are zero by default). These parameters specify the viscosity :math:`\beta` and density :math:`\rho` of the medium and
-apply to all bodies. The shape of each body for fluid dynamics purposes is assumed to be the equivalent inertia box,
-which can also be visualized. Each forward-facing (relative to the linear velocity) face of the box experiences force
-along its normal direction. All faces also experience torque due to the angular velocity; this torque is obtained by
-integrating the force resulting from the rotation over the surface area. In this sub-section only, let :math:`v` and
-:math:`\omega` denote the linear and angular body velocity in its local frame (which is aligned with the equivalent
-inertia box), and :math:`s` the 3D vector of box sizes. When the contributions from all faces are added, the resulting
-force and torque in local body coordinates have :math:`i`-th component
-
-.. math::
-   \begin{aligned}
-   \text{density force} : \quad &- {1 \over 2} \rho s_j s_k |v_i| v_i \\
-   \text{density torque} : \quad &- {1 \over 64} \rho s_i \left(s_j^4 + s_k^4 \right) |\omega_i| \omega_i \\
-   \end{aligned}
-
-This model implicitly assumes high Reynolds numbers, with lift-to-drag ratio equal to the tangent of the angle of
-attack. One can also specify a non-zero ``mjModel.opt.wind``, which is a 3D vector subtracted from the body linear
-velocity in the fluid dynamics computation.
-
-Each body also experiences a force and a torque proportional to viscosity and opposite to its linear and angular
-velocity. Note that viscosity can be used independent of density, to make the simulation more damped. We use the
-formulas for a sphere at low Reynolds numbers, with diameter :math:`d` equal to the average of the equivalent inertia
-box sizes. The resulting 3D force and torque in local body coordinates are
-
-.. math::
-   \begin{aligned}
-   \text{viscosity force} : \quad &- 3 \beta \pi d v \\
-   \text{viscosity torque} : \quad &- \beta \pi d^3 \omega \\
-   \end{aligned}
-
-Existing phenomenological models of fluid dynamics tend to be valid for one regime (e.g. flat vs. spherical objects) and
-it is difficult to construct a model which can be simulated efficiently and is broadly valid. For example, drag forces
-are known to transition from being linear in velocity at low Reynolds numbers, to being quadratic in velocity at high
-Reynolds numbers. However it is not clear how this transition should occur for lift forces. This motivated the above
-separation, using density to compute all quadratic forces and viscosity to compute all linear forces. Users who need a
-more detailed simulation of fluid dynamics should leave the density and viscosity parameters set to zero so as to
-disable the built-in mechanism. A custom model of fluid dynamics (or any other force field that depends only on position
-and velocity) can be implemented in the callback :ref:`mjcb_passive`.
 
 .. _geIntegration:
 
@@ -786,7 +749,6 @@ dimensionality of the constraint residual in each case.
    computed by the compiler in the initial model configuration ``mjModel.qpos0``.
 
 ``distance`` : 1
-
    .. attention::
       Distance equality constraints were removed in MuJoCo version 2.2.2. If you are using an earlier version, please
       switch to the corresponding version of the documentation.
@@ -968,7 +930,7 @@ each component of :math:`f`. The basis vectors are spatial vectors: 3D force fol
 vectors into the columns of a matrix :math:`E`, the force/torque generated by the constraint force in the contact frame
 is :math:`E f`. The matrix of basis vectors is constructed as follows.
 
-.. image:: images/computation/contact_frame.svg
+.. image:: ../images/computation/contact_frame.svg
    :width: 700px
    :align: center
 
@@ -1330,7 +1292,7 @@ representations of the constraint Jacobian and related matrices.
    the computational complexity of one matrix-vector multiplication (although the constants are larger). It has
    first-order convergence but nevertheless makes rapid progress in a few iterations.
 
-   .. image:: images/computation/gPGS.svg
+   .. image:: ../images/computation/gPGS.svg
       :width: 500px
       :align: center
 
@@ -1435,7 +1397,7 @@ coefficients varying from left to right. Mathematically, the penalty in the pyra
 the penalty in the elliptic case contains pieces that are quadratics minus square roots of quadratics - allowing
 circular contours around the tip of the cone.
 
-.. image:: images/computation/softcontact.png
+.. image:: ../images/computation/softcontact.png
    :width: 600px
    :align: center
 

doc/conf.py

@@ -42,6 +42,7 @@ master_doc = 'index'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinxcontrib.bibtex',
     'sphinxcontrib.katex',
     'sphinxcontrib.youtube',
     'sphinx_copybutton',
@@ -51,6 +52,9 @@ extensions = [
     'mujoco_include',
 ]
 
+# Bibtex references for sphinxcontrib.bibtex
+bibtex_bibfiles = ['references.bib']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['templates']
 
@@ -70,6 +74,9 @@ exclude_patterns = [
 redirects = {
     # index.rst just contains the table of contents definition.
     'index': 'overview.html',
+    'computation': 'computation/index.html',
+    'programming': 'programming/index.html',
+    'APIreference': 'APIreference/index.html',
 }
 
 rst_prolog = """

doc/css/theme_overrides.css

@@ -18,10 +18,19 @@ body {
   color: var(--body-color);
 }
 
+/* Make the search bar query text readable in dark theme. */
+body:not([data-theme="light"]) {
+  --color-sidebar-search-foreground: white;
+}
+
 .schema-small {
   font-size: 93%;
 }
 
+.caption-small {
+  font-size: 85%;
+}
+
 .sidebar-brand-text {
   display: none;
 }

doc/images/computation/kutta_cond_plate.svg

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="771.87997pt" height="238.96292pt" viewBox="0 0 771.87997 238.96292">
+<defs>
+<clipPath id="clip_0">
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M0 0H1920V1080H0Z"/>
+</clipPath>
+<clipPath id="clip_1">
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1106.002 576.4439H1122.823V591.0093H1106.002Z"/>
+</clipPath>
+</defs>
+<g clip-path="url(#clip_0)">
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M0 0H1920V1080H0Z" fill="#ffffff"/>
+<path transform="matrix(.9580353,-.2866502,.2866502,.9580353,137.0238,198.89972)" stroke-width="16" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#000000" d="M0 0H528.2787"/>
+<path transform="matrix(.9999944,-.003351985,.003351985,.9999944,135.55829,26.180298)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#007b76" d="M501.7182 14.89341C432.7024-50.42863 108.474 117.5608 0 163.1673"/>
+<path transform="matrix(1,0,0,1,-16.150513,6.1448976)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M792.5561 47.68689C753.3962 47.0543 713.0286 46.27591 678.7394 27.16879 667.3651 20.83055 657.0775 12.581 645.1292 7.376457 624.4572-1.628081 602.7061-.8732544 580.6685 1.71949 410.6574 21.72136 262.6907 139.3051 96.37235 177.6597 64.72086 184.9589 32.47417 189.2054 0 189.9195"/>
+<path transform="matrix(1,0,0,1,-11.400818,73.43042)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M783.3193 .7884597C748.5002-1.851793 713.668 2.487631 679.3967 9.075733 653.5863 14.03738 628.0432 20.27122 602.6815 27.16604 448.6335 69.04565 300.6064 135.3603 141.6754 152.7233 94.62809 157.8632 47.24892 158.5936 0 161.1963"/>
+<path transform="matrix(-1,-0,0,-1,766.6359,53.89514)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H6.864602-1.735398"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1367.619 641.5311 1358.019 636.7311 1367.619 631.9311Z" fill="#0076ba"/>
+<path transform="matrix(-1,-0,0,-1,762.2249,73.24945)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H6.864602-1.735398"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1363.209 622.1768 1353.609 617.3768 1363.209 612.5768Z" fill="#0076ba"/>
+<path transform="matrix(-1,-0,0,-1,12.190674,194.73282)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H8.184024-.4159761"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M611.8548 500.6934 602.2548 495.8934 611.8548 491.0934Z" fill="#0076ba"/>
+<path transform="matrix(-1,-0,0,-1,5.006714,233.62622)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H1-7.6"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M611.8548 461.8 602.2548 457 611.8548 452.2Z" fill="#0076ba"/>
+<path transform="matrix(-1,-0,0,-1,597.72689,6.1013185)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H8.184024-.4159761"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1197.391 689.3249 1187.791 684.5249 1197.391 679.7249Z" fill="#0076ba"/>
+<path transform="matrix(-.9126669,.4087042,-.4087042,-.9126669,335.68159,82.305728)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H1.684309 2.684309"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M930.4307 612.0129 923.6309 603.7085 934.3543 603.2513Z" fill="#0076ba"/>
+<path transform="matrix(-.9448149,.3276048,-.3276048,-.9448149,461.72688,31.125794)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H1.684309 2.684309"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1056.811 663.4838 1049.313 655.8036 1059.956 654.4135Z" fill="#0076ba"/>
+<path transform="matrix(-.9389535,.3440442,-.3440442,-.9389535,178.89917,152.30274)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H1.684309 2.684309"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M773.9144 542.251 766.5518 534.4412 777.2172 533.2371Z" fill="#0076ba"/>
+<path transform="matrix(-.9669135,.2551046,-.2551046,-.9669135,597.5909,99.05774)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H8.184024-.4159761"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1195.984 596.5709 1187.926 589.4807 1198.433 587.2885Z" fill="#0076ba"/>
+<path transform="matrix(-.9669135,.2551046,-.2551046,-.9669135,427.16389,151.98743)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H8.184024-.4159761"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1025.556 543.6412 1017.498 536.551 1028.005 534.3588Z" fill="#0076ba"/>
+<path transform="matrix(-.9823533,.1870347,-.1870347,-.9823533,195.22657,216.43653)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M0 0H8.184024-.4159761"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M793.968 479.1698 785.4351 472.659 795.7635 469.7392Z" fill="#0076ba"/>
+<path transform="matrix(1,0,0,1,389.18428,39.2666)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#0076ba" d="M147.6963 21.83868C158.9935 15.38295 183.9471 9.066525 170.0279 1.104305 152.7453-8.781958-11.57757 50.70998 .6491816 60.18663 9.170442 66.79125 47.41993 54.16165 72.9151 45.28126L73.86098 44.95004"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1061.936 601.5488 1069.41 609.2519 1058.763 610.6093Z" fill="#0076ba"/>
+<path transform="matrix(1,0,0,1,389.7519,123.6391)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#000000" d="M0 0H218.4522 219.4522"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1206.452 562.1871 1216.052 566.9871 1206.452 571.7871Z"/>
+<text xml:space="preserve" transform="matrix(1 0 -0 1 620.9029 132.77613)" font-size="32" font-family="LatinModernMath"><tspan y="0" x="0">v</tspan></text>
+<path transform="matrix(.9578225,-.2873605,.2873605,.9578225,125.16272,158.26215)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#000000" d="M0 0H40.47911 41.47911"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M763.5619 539.3986 771.3777 546.7548 760.8033 548.5937Z"/>
+<path transform="matrix(-.2873605,-.9578225,.9578225,-.2873605,125.14148,159.08972)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#000000" d="M0 0H40.47911 41.47911"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M716.3551 571.6877 708.9989 579.5034 707.16 568.929Z"/>
+<text xml:space="preserve" transform="matrix(1 0 -0 1 118.88617 108.28851)" font-size="32" font-family="LatinModernMath"><tspan y="0" x="0">y</tspan></text>
+<text xml:space="preserve" transform="matrix(1 0 -0 1 165.3255 132.77613)" font-size="32" font-family="LatinModernMath"><tspan y="0" x="0">x</tspan></text>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M1254.748 634.4438C1256.779 632.4717 1256.779 629.2742 1254.748 627.3021 1252.717 625.33 1249.425 625.33 1247.394 627.3021 1245.364 629.2742 1245.364 632.4717 1247.394 634.4438 1249.425 636.416 1252.717 636.416 1254.748 634.4438ZM1254.748 634.4438" fill="#99195e"/>
+<path transform="matrix(1,0,0,-1,-598.2481,690.6262)" d="M729.2592 492.4438C731.2899 490.4717 731.2899 487.2742 729.2592 485.3021 727.2285 483.33 723.936 483.33 721.9053 485.3021 719.8746 487.2742 719.8746 490.4717 721.9053 492.4438 723.936 494.416 727.2285 494.416 729.2592 492.4438ZM729.2592 492.4438" fill="#99195e"/>
+<path transform="matrix(1,0,0,1,478.9959,91.54443)" stroke-width="2" stroke-linecap="butt" stroke-miterlimit="4" stroke-linejoin="miter" fill="none" stroke="#000000" d="M12.88579 31.99126C13.61055 12.25828 9.315282 1.59453 0 0"/>
+</g>
+<g clip-path="url(#clip_1)">
+<text xml:space="preserve" transform="matrix(1 0 -0 1 506.88386 139.8006)" font-size="32.2243" font-family="STIXGeneral" font-style="italic"><tspan y="-25.97284" x="0">&#x03b1;</tspan></text>
+</g>
+</svg>

doc/includes/references.h

@@ -25,18 +25,20 @@ typedef enum mjtState_ {          // state elements
   mjSTATE_CTRL          = 1<<5,   // control
   mjSTATE_QFRC_APPLIED  = 1<<6,   // applied generalized force
   mjSTATE_XFRC_APPLIED  = 1<<7,   // applied Cartesian force/torque
-  mjSTATE_MOCAP_POS     = 1<<8,   // positions of mocap bodies
+  mjSTATE_EQ_ACTIVE     = 1<<8,   // enable/disable constraints
-  mjSTATE_MOCAP_QUAT    = 1<<9,   // orientations of mocap bodies
+  mjSTATE_MOCAP_POS     = 1<<9,   // positions of mocap bodies
-  mjSTATE_USERDATA      = 1<<10,  // user data
+  mjSTATE_MOCAP_QUAT    = 1<<10,  // orientations of mocap bodies
-  mjSTATE_PLUGIN        = 1<<11,  // plugin state
+  mjSTATE_USERDATA      = 1<<11,  // user data
+  mjSTATE_PLUGIN        = 1<<12,  // plugin state
 
-  mjNSTATE              = 12,     // number of state elements
+  mjNSTATE              = 13,     // number of state elements
 
   // convenience values for commonly used state specifications
   mjSTATE_PHYSICS       = mjSTATE_QPOS | mjSTATE_QVEL | mjSTATE_ACT,
   mjSTATE_FULLPHYSICS   = mjSTATE_PHYSICS | mjSTATE_TIME | mjSTATE_PLUGIN,
   mjSTATE_USER          = mjSTATE_CTRL | mjSTATE_QFRC_APPLIED | mjSTATE_XFRC_APPLIED |
-                          mjSTATE_MOCAP_POS | mjSTATE_MOCAP_QUAT | mjSTATE_USERDATA,
+                          mjSTATE_EQ_ACTIVE | mjSTATE_MOCAP_POS | mjSTATE_MOCAP_QUAT |
+                          mjSTATE_USERDATA,
   mjSTATE_INTEGRATION   = mjSTATE_FULLPHYSICS | mjSTATE_USER | mjSTATE_WARMSTART
 } mjtState;
 typedef enum mjtWarning_ {   // warning types
@@ -71,10 +73,15 @@ typedef enum mjtTimer_ {     // internal timers
   mjTIMER_POS_MAKE,          // make constraints
   mjTIMER_POS_PROJECT,       // project constraints
 
+  // breakdown of mj_collision
+  mjTIMER_COL_BROAD,         // broadphase
+  mjTIMER_COL_MID,           // midphase
+  mjTIMER_COL_NARROW,        // narrowphase
+
   mjNTIMER                   // number of timers
 } mjtTimer;
 struct mjContact_ {                // result of collision detection functions
-  // contact parameters set by geom-specific collision detector
+  // contact parameters set by near-phase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
   mjtNum  frame[9];                // normal is in [0-2]
@@ -90,12 +97,16 @@ struct mjContact_ {                // result of collision detection functions
   mjtNum  mu;                      // friction of regularized cone, set by mj_makeConstraint
   mjtNum  H[36];                   // cone Hessian, set by mj_updateConstraint
 
-  // contact descriptors set by mj_collideGeoms
+  // contact descriptors set by mj_collideXXX
   int     dim;                     // contact space dimensionality: 1, 3, 4 or 6
   int     geom1;                   // id of geom 1
   int     geom2;                   // id of geom 2
+  int     geom[2];                 // geom ids; -1 for flex
+  int     flex[2];                 // flex ids; -1 for geom
+  int     elem[2];                 // element ids; -1 for geom or flex vertex
+  int     vert[2];                 // vertex ids;  -1 for geom or flex element
 
-  // flag set by mj_instantianteEquality
+  // flag set by mj_setContact or mj_instantiateContact
   int     exclude;                 // 0: include, 1: in gap, 2: fused, 3: no dofs
 
   // address computed by mj_instantiateContact
@@ -136,10 +147,11 @@ struct mjData_ {
   size_t  parena;            // first available byte in arena
 
   // memory utilization stats
-  size_t  maxuse_stack;      // maximum stack allocation
+  size_t  maxuse_stack;                      // maximum stack allocation in bytes
-  size_t  maxuse_arena;      // maximum arena allocation
+  size_t  maxuse_threadstack[mjMAXTHREADS];  // maximum stack allocation per thread in bytes
-  int     maxuse_con;        // maximum number of contacts
+  size_t  maxuse_arena;                      // maximum arena allocation in bytes
-  int     maxuse_efc;        // maximum number of scalar constraints
+  int     maxuse_con;                        // maximum number of contacts
+  int     maxuse_efc;                        // maximum number of scalar constraints
 
   // diagnostics
   mjWarningStat warning[mjNWARNING];  // warning statistics
@@ -152,12 +164,6 @@ struct mjData_ {
   int     solver_nnz[mjNISLAND];    // number of non-zeros in Hessian or efc_AR, per island
   mjtNum  solver_fwdinv[2];         // forward-inverse comparison: qfrc, efc
 
-  // collision statistics
-  int     nbodypair_broad;   // number of body pairs in collision according to the broad-phase
-  int     nbodypair_narrow;  // number of body pairs actually in collision in the narrow-phase
-  int     ngeompair_mid;     // number of geom pairs in collision according to the mid-phase
-  int     ngeompair_narrow;  // number of geom pairs actually in collision in the narrow-phase
-
   // variable sizes
   int     ne;                // number of equality constraints
   int     nf;                // number of friction constraints
@@ -190,6 +196,7 @@ struct mjData_ {
   mjtNum* ctrl;              // control                                          (nu x 1)
   mjtNum* qfrc_applied;      // applied generalized force                        (nv x 1)
   mjtNum* xfrc_applied;      // applied Cartesian force/torque                   (nbody x 6)
+  mjtByte* eq_active;        // enable/disable constraints                       (neq x 1)
 
   // mocap data
   mjtNum* mocap_pos;         // positions of mocap bodies                        (nmocap x 3)
@@ -206,8 +213,8 @@ struct mjData_ {
   mjtNum* sensordata;        // sensor data array                                (nsensordata x 1)
 
   // plugins
-  int*        plugin;        // copy of m->plugin, required for deletion         (nplugin x 1)
+  int*       plugin;         // copy of m->plugin, required for deletion         (nplugin x 1)
-  uintptr_t*  plugin_data;   // pointer to plugin-managed data structure         (nplugin x 1)
+  uintptr_t* plugin_data;    // pointer to plugin-managed data structure         (nplugin x 1)
 
   //-------------------- POSITION dependent
 
@@ -233,14 +240,23 @@ struct mjData_ {
   mjtNum* cdof;              // com-based motion axis of each dof                (nv x 6)
   mjtNum* cinert;            // com-based body inertia and mass                  (nbody x 10)
 
+  // computed by mj_fwdPosition/mj_flex
+  mjtNum* flexvert_xpos;     // Cartesian flex vertex positions                  (nflexvert x 3)
+  mjtNum* flexelem_aabb;     // flex element bounding boxes (center, size)       (nflexelem x 6)
+  int*    flexedge_J_rownnz; // number of non-zeros in Jacobian row              (nflexedge x 1)
+  int*    flexedge_J_rowadr; // row start address in colind array                (nflexedge x 1)
+  int*    flexedge_J_colind; // column indices in sparse Jacobian                (nflexedge x nv)
+  mjtNum* flexedge_J;        // flex edge Jacobian                               (nflexedge x nv)
+  mjtNum* flexedge_length;   // flex edge lengths                                (nflexedge x 1)
+
   // computed by mj_fwdPosition/mj_tendon
   int*    ten_wrapadr;       // start address of tendon's path                   (ntendon x 1)
   int*    ten_wrapnum;       // number of wrap points in path                    (ntendon x 1)
   int*    ten_J_rownnz;      // number of non-zeros in Jacobian row              (ntendon x 1)
   int*    ten_J_rowadr;      // row start address in colind array                (ntendon x 1)
   int*    ten_J_colind;      // column indices in sparse Jacobian                (ntendon x nv)
-  mjtNum* ten_length;        // tendon lengths                                   (ntendon x 1)
   mjtNum* ten_J;             // tendon Jacobian                                  (ntendon x nv)
+  mjtNum* ten_length;        // tendon lengths                                   (ntendon x 1)
   int*    wrap_obj;          // geom id; -1: site; -2: pulley                    (nwrap*2 x 1)
   mjtNum* wrap_xpos;         // Cartesian 3D points in all path                  (nwrap*2 x 3)
 
@@ -258,11 +274,13 @@ struct mjData_ {
   mjtNum* qLDiagSqrtInv;     // 1/sqrt(diag(D))                                  (nv x 1)
 
   // computed by mj_collisionTree
+  mjtNum*  bvh_aabb_dyn;     // global bounding box (center, size)               (nbvhdynamic x 6)
   mjtByte* bvh_active;       // volume has been added to collisions              (nbvh x 1)
 
   //-------------------- POSITION, VELOCITY dependent
 
   // computed by mj_fwdVelocity
+  mjtNum* flexedge_velocity; // flex edge velocities                             (nflexedge x 1)
   mjtNum* ten_velocity;      // tendon velocities                                (ntendon x 1)
   mjtNum* actuator_velocity; // actuator velocities                              (nu x 1)
 
@@ -281,8 +299,8 @@ struct mjData_ {
   mjtNum* subtree_angmom;    // angular momentum about subtree com               (nbody x 3)
 
   // computed by mj_Euler or mj_implicit
-  mjtNum*   qH;              // L'*D*L factorization of modified M               (nM x 1)
+  mjtNum* qH;                // L'*D*L factorization of modified M               (nM x 1)
-  mjtNum*   qHDiagInv;       // 1/diag(D) of modified M                          (nv x 1)
+  mjtNum* qHDiagInv;         // 1/diag(D) of modified M                          (nv x 1)
 
   // computed by mj_resetData
   int*    D_rownnz;          // non-zeros in each row                            (nv x 1)
@@ -437,8 +455,10 @@ typedef enum mjtGeom_ {           // type of geometric shape
   mjGEOM_ARROW1,                  // arrow without wedges
   mjGEOM_ARROW2,                  // arrow in both directions
   mjGEOM_LINE,                    // line
+  mjGEOM_FLEX,                    // flex
   mjGEOM_SKIN,                    // skin
   mjGEOM_LABEL,                   // text label
+  mjGEOM_TRIANGLE,                // triangle connecting a frame
 
   mjGEOM_NONE         = 1001      // missing geom type
 } mjtGeom;
@@ -460,11 +480,6 @@ typedef enum mjtIntegrator_ {     // integrator mode
   mjINT_IMPLICIT,                 // implicit in velocity
   mjINT_IMPLICITFAST              // implicit in velocity, no rne derivative
 } mjtIntegrator;
-typedef enum mjtCollision_ {      // collision mode for selecting geom pairs
-  mjCOL_ALL           = 0,        // test precomputed and dynamic pairs
-  mjCOL_PAIR,                     // test predefined pairs only
-  mjCOL_DYNAMIC                   // test dynamic pairs only
-} mjtCollision;
 typedef enum mjtCone_ {           // type of friction cone
   mjCONE_PYRAMIDAL     = 0,       // pyramidal
   mjCONE_ELLIPTIC                 // elliptic
@@ -484,6 +499,7 @@ typedef enum mjtEq_ {             // type of equality constraint
   mjEQ_WELD,                      // fix relative position and orientation of two bodies
   mjEQ_JOINT,                     // couple the values of two scalar joints with cubic
   mjEQ_TENDON,                    // couple the lengths of two tendons with cubic
+  mjEQ_FLEX,                      // fix all edge lengths of a flex
   mjEQ_DISTANCE                   // unsupported, will cause an error if used
 } mjtEq;
 typedef enum mjtWrap_ {           // type of tendon wrap object
@@ -534,6 +550,7 @@ typedef enum mjtObj_ {            // type of MujoCo object
   mjOBJ_SITE,                     // site
   mjOBJ_CAMERA,                   // camera
   mjOBJ_LIGHT,                    // light
+  mjOBJ_FLEX,                     // flex
   mjOBJ_MESH,                     // mesh
   mjOBJ_SKIN,                     // skin
   mjOBJ_HFIELD,                   // heightfield
@@ -645,6 +662,13 @@ typedef enum mjtLRMode_ {         // mode for actuator length range computation
   mjLRMODE_MUSCLEUSER,            // process muscle and user actuators
   mjLRMODE_ALL                    // process all actuators
 } mjtLRMode;
+typedef enum mjtFlexSelf_ {       // mode for flex selfcollide
+  mjFLEXSELF_NONE   = 0,          // no self-collisions
+  mjFLEXSELF_NARROW,              // skip midphase, go directly to narrowphase
+  mjFLEXSELF_BVH,                 // use BVH in midphase (if midphase enabled)
+  mjFLEXSELF_SAP,                 // use SAP in midphase
+  mjFLEXSELF_AUTO                 // choose between BVH and SAP automatically
+} mjtFlexSelf;
 struct mjLROpt_ {                 // options for mj_setLengthRange()
   // flags
   int mode;                       // which actuators to process (mjtLRMode)
@@ -691,10 +715,10 @@ struct mjOption_ {                // physics options
   mjtNum o_margin;                // margin
   mjtNum o_solref[mjNREF];        // solref
   mjtNum o_solimp[mjNIMP];        // solimp
+  mjtNum o_friction[5];           // friction
 
   // discrete settings
   int integrator;                 // integration mode (mjtIntegrator)
-  int collision;                  // collision mode (mjtCollision)
   int cone;                       // type of friction cone (mjtCone)
   int jacobian;                   // type of Jacobian (mjtJacobian)
   int solver;                     // solver algorithm (mjtSolver)
@@ -719,9 +743,9 @@ struct mjVisual_ {                // visualization options
     float linewidth;              // line width for wireframe and ray rendering
     float glow;                   // glow coefficient for selected body
     float realtime;               // initial real-time factor (1: real time)
-    int offwidth;                 // width of offscreen buffer
+    int   offwidth;               // width of offscreen buffer
-    int offheight;                // height of offscreen buffer
+    int   offheight;              // height of offscreen buffer
-    int ellipsoidinertia;         // geom for inertia visualization (0: box, 1: ellipsoid)
+    int   ellipsoidinertia;       // geom for inertia visualization (0: box, 1: ellipsoid)
   } global;
 
   struct {                        // rendering quality
@@ -817,12 +841,22 @@ struct mjModel_ {
   int nu;                         // number of actuators/controls = dim(ctrl)
   int na;                         // number of activation states = dim(act)
   int nbody;                      // number of bodies
-  int nbvh;                       // number of bounding volumes in all bodies
+  int nbvh;                       // number of total bounding volumes in all bodies
+  int nbvhstatic;                 // number of static bounding volumes (aabb stored in mjModel)
+  int nbvhdynamic;                // number of dynamic bounding volumes (aabb stored in mjData)
   int njnt;                       // number of joints
   int ngeom;                      // number of geoms
   int nsite;                      // number of sites
   int ncam;                       // number of cameras
   int nlight;                     // number of lights
+  int nflex;                      // number of flexes
+  int nflexvert;                  // number of vertices in all flexes
+  int nflexedge;                  // number of edges in all flexes
+  int nflexelem;                  // number of elements in all flexes
+  int nflexelemdata;              // number of element vertex ids in all flexes
+  int nflexshelldata;             // number of shell fragment vertex ids in all flexes
+  int nflexevpair;                // number of element-vertex pairs in all flexes
+  int nflextexcoord;              // number of vertices with texture coordinates
   int nmesh;                      // number of meshes
   int nmeshvert;                  // number of vertices in all meshes
   int nmeshnormal;                // number of normals in all meshes
@@ -866,6 +900,7 @@ struct mjModel_ {
   int nuser_sensor;               // number of mjtNums in sensor_user
   int nnames;                     // number of chars in all names
   int nnames_map;                 // number of slots in the names hash map
+  int npaths;                     // number of chars in all paths
 
   // sizes set after mjModel construction (only affect mjData)
   int nM;                         // number of non-zeros in sparse inertia matrix
@@ -909,7 +944,7 @@ struct mjModel_ {
   int*      body_treeid;          // id of body's kinematic tree; -1: static  (nbody x 1)
   int*      body_geomnum;         // number of geoms                          (nbody x 1)
   int*      body_geomadr;         // start addr of geoms; -1: no geoms        (nbody x 1)
-  mjtByte*  body_simple;          // body is simple (has diagonal M)          (nbody x 1)
+  mjtByte*  body_simple;          // 1: diagonal M; 2: diag M, no rotations   (nbody x 1)
   mjtByte*  body_sameframe;       // inertial frame is same as body frame     (nbody x 1)
   mjtNum*   body_pos;             // position offset rel. to parent body      (nbody x 3)
   mjtNum*   body_quat;            // orientation offset rel. to parent body   (nbody x 4)
@@ -920,16 +955,19 @@ struct mjModel_ {
   mjtNum*   body_inertia;         // diagonal inertia in ipos/iquat frame     (nbody x 3)
   mjtNum*   body_invweight0;      // mean inv inert in qpos0 (trn, rot)       (nbody x 2)
   mjtNum*   body_gravcomp;        // antigravity force, units of body weight  (nbody x 1)
+  mjtNum*   body_margin;          // MAX over all geom margins                (nbody x 1)
   mjtNum*   body_user;            // user data                                (nbody x nuser_body)
   int*      body_plugin;          // plugin instance id; -1: not in use       (nbody x 1)
+  int*      body_contype;         // OR over all geom contypes                (nbody x 1)
+  int*      body_conaffinity;     // OR over all geom conaffinities           (nbody x 1)
   int*      body_bvhadr;          // address of bvh root                      (nbody x 1)
   int*      body_bvhnum;          // number of bounding volumes               (nbody x 1)
 
   // bounding volume hierarchy
   int*      bvh_depth;            // depth in the bounding volume hierarchy   (nbvh x 1)
   int*      bvh_child;            // left and right children in tree          (nbvh x 2)
-  int*      bvh_geomid;           // geom id of the node; -1: non-leaf        (nbvh x 1)
+  int*      bvh_nodeid;           // geom or elem id of node; -1: non-leaf    (nbvh x 1)
-  mjtNum*   bvh_aabb;             // bounding box of node (center, size)      (nbvh x 6)
+  mjtNum*   bvh_aabb;             // local bounding box (center, size)        (nbvhstatic x 6)
 
   // joints
   int*      jnt_type;             // type of joint (mjtJoint)                 (njnt x 1)
@@ -1014,6 +1052,8 @@ struct mjModel_ {
   mjtNum*   cam_mat0;             // global orientation in qpos0              (ncam x 9)
   int*      cam_resolution;       // [width, height] in pixels                (ncam x 2)
   mjtNum*   cam_fovy;             // y-field of view (deg)                    (ncam x 1)
+  float*    cam_intrinsic;        // [focal length; principal point]          (ncam x 4)
+  float*    cam_sensorsize;       // sensor size                              (ncam x 2)
   mjtNum*   cam_ipd;              // inter-pupilary distance                  (ncam x 1)
   mjtNum*   cam_user;             // user data                                (ncam x nuser_cam)
 
@@ -1036,6 +1076,59 @@ struct mjModel_ {
   float*    light_diffuse;        // diffuse rgb (alpha=1)                    (nlight x 3)
   float*    light_specular;       // specular rgb (alpha=1)                   (nlight x 3)
 
+  // flexes: contact properties
+  int*      flex_contype;         // flex contact type                        (nflex x 1)
+  int*      flex_conaffinity;     // flex contact affinity                    (nflex x 1)
+  int*      flex_condim;          // contact dimensionality (1, 3, 4, 6)      (nflex x 1)
+  int*      flex_priority;        // flex contact priority                    (nflex x 1)
+  mjtNum*   flex_solmix;          // mix coef for solref/imp in contact pair  (nflex x 1)
+  mjtNum*   flex_solref;          // constraint solver reference: contact     (nflex x mjNREF)
+  mjtNum*   flex_solimp;          // constraint solver impedance: contact     (nflex x mjNIMP)
+  mjtNum*   flex_friction;        // friction for (slide, spin, roll)         (nflex x 3)
+  mjtNum*   flex_margin;          // detect contact if dist<margin            (nflex x 1)
+  mjtNum*   flex_gap;             // include in solver if dist<margin-gap     (nflex x 1)
+  mjtByte*  flex_internal;        // internal flex collision enabled          (nflex x 1)
+  int*      flex_selfcollide;     // self collision mode (mjtFlexSelf)        (nflex x 1)
+  int*      flex_activelayers;    // number of active element layers, 3D only (nflex x 1)
+
+  // flexes: other properties
+  int*      flex_dim;             // 1: lines, 2: triangles, 3: tetrahedra    (nflex x 1)
+  int*      flex_matid;           // material id for rendering                (nflex x 1)
+  int*      flex_group;           // group for visibility                     (nflex x 1)
+  int*      flex_vertadr;         // first vertex address                     (nflex x 1)
+  int*      flex_vertnum;         // number of vertices                       (nflex x 1)
+  int*      flex_edgeadr;         // first edge address                       (nflex x 1)
+  int*      flex_edgenum;         // number of edges                          (nflex x 1)
+  int*      flex_elemadr;         // first element address                    (nflex x 1)
+  int*      flex_elemnum;         // number of elements                       (nflex x 1)
+  int*      flex_elemdataadr;     // first element vertex id address          (nflex x 1)
+  int*      flex_shellnum;        // number of shells                         (nflex x 1)
+  int*      flex_shelldataadr;    // first shell data address                 (nflex x 1)
+  int*      flex_evpairadr;       // first evpair address                     (nflex x 1)
+  int*      flex_evpairnum;       // number of evpairs                        (nflex x 1)
+  int*      flex_texcoordadr;     // address in flex_texcoord; -1: none       (nflex x 1)
+  int*      flex_vertbodyid;      // vertex body ids                          (nflexvert x 1)
+  int*      flex_edge;            // edge vertex ids (2 per edge)             (nflexedge x 2)
+  int*      flex_elem;            // element vertex ids (dim+1 per elem)      (nflexelemdata x 1)
+  int*      flex_elemlayer;       // element distance from surface, 3D only   (nflexelem x 1)
+  int*      flex_shell;           // shell fragment vertex ids (dim per frag) (nflexshelldata x 1)
+  int*      flex_evpair;          // (element, vertex) collision pairs        (nflexevpair x 2)
+  mjtNum*   flex_vert;            // vertex positions in local body frames    (nflexvert x 3)
+  mjtNum*   flex_xvert0;          // Cartesian vertex positions in qpos0      (nflexvert x 3)
+  mjtNum*   flexedge_length0;     // edge lengths in qpos0                    (nflexedge x 1)
+  mjtNum*   flexedge_invweight0;  // edge inv. weight in qpos0                (nflexedge x 1)
+  mjtNum*   flex_radius;          // radius around primitive element          (nflex x 1)
+  mjtNum*   flex_edgestiffness;   // edge stiffness                           (nflex x 1)
+  mjtNum*   flex_edgedamping;     // edge damping                             (nflex x 1)
+  mjtByte*  flex_edgeequality;    // is edge equality constraint defined      (nflex x 1)
+  mjtByte*  flex_rigid;           // are all verices in the same body         (nflex x 1)
+  mjtByte*  flex_centered;        // are all vertex coordinates (0,0,0)       (nflex x 1)
+  mjtByte*  flex_flatskin;        // render flex skin with flat shading       (nflex x 1)
+  int*      flex_bvhadr;          // address of bvh root; -1: no bvh          (nflex x 1)
+  int*      flex_bvhnum;          // number of bounding volumes               (nflex x 1)
+  float*    flex_rgba;            // rgba when material is omitted            (nflex x 4)
+  float*    flex_texcoord;        // vertex texture coordinates               (nflextexcoord x 2)
+
   // meshes
   int*      mesh_vertadr;         // first vertex address                     (nmesh x 1)
   int*      mesh_vertnum;         // number of vertices                       (nmesh x 1)
@@ -1057,6 +1150,7 @@ struct mjModel_ {
   int*      mesh_facenormal;      // normal face data                         (nmeshface x 3)
   int*      mesh_facetexcoord;    // texture face data                        (nmeshface x 3)
   int*      mesh_graph;           // convex graph data                        (nmeshgraph x 1)
+  int*      mesh_pathadr;         // address of asset path for mesh; -1: none (nmesh x 1)
 
   // skins
   int*      skin_matid;           // skin material id; -1: none               (nskin x 1)
@@ -1109,7 +1203,7 @@ struct mjModel_ {
   int*      pair_dim;             // contact dimensionality                   (npair x 1)
   int*      pair_geom1;           // id of geom1                              (npair x 1)
   int*      pair_geom2;           // id of geom2                              (npair x 1)
-  int*      pair_signature;       // (body1+1) << 16 + body2+1                (npair x 1)
+  int*      pair_signature;       // body1 << 16 + body2                      (npair x 1)
   mjtNum*   pair_solref;          // solver reference: contact normal         (npair x mjNREF)
   mjtNum*   pair_solreffriction;  // solver reference: contact friction       (npair x mjNREF)
   mjtNum*   pair_solimp;          // solver impedance: contact                (npair x mjNIMP)
@@ -1118,13 +1212,13 @@ struct mjModel_ {
   mjtNum*   pair_friction;        // tangent1, 2, spin, roll1, 2              (npair x 5)
 
   // excluded body pairs for collision detection
-  int*      exclude_signature;    // (body1+1) << 16 + body2+1                (nexclude x 1)
+  int*      exclude_signature;    // body1 << 16 + body2                      (nexclude x 1)
 
   // equality constraints
   int*      eq_type;              // constraint type (mjtEq)                  (neq x 1)
   int*      eq_obj1id;            // id of object 1                           (neq x 1)
   int*      eq_obj2id;            // id of object 2                           (neq x 1)
-  mjtByte*  eq_active;            // enable/disable constraint                (neq x 1)
+  mjtByte*  eq_active0;           // initial enable/disable constraint state  (neq x 1)
   mjtNum*   eq_solref;            // constraint solver reference              (neq x mjNREF)
   mjtNum*   eq_solimp;            // constraint solver impedance              (neq x mjNIMP)
   mjtNum*   eq_data;              // numeric data for constraint              (neq x mjNEQDATA)
@@ -1238,6 +1332,7 @@ struct mjModel_ {
   int*      name_siteadr;         // site name pointers                       (nsite x 1)
   int*      name_camadr;          // camera name pointers                     (ncam x 1)
   int*      name_lightadr;        // light name pointers                      (nlight x 1)
+  int*      name_flexadr;         // flex name pointers                       (nflex x 1)
   int*      name_meshadr;         // mesh name pointers                       (nmesh x 1)
   int*      name_skinadr;         // skin name pointers                       (nskin x 1)
   int*      name_hfieldadr;       // hfield name pointers                     (nhfield x 1)
@@ -1256,6 +1351,9 @@ struct mjModel_ {
   int*      name_pluginadr;       // plugin instance name pointers            (nplugin x 1)
   char*     names;                // names of all objects, 0-terminated       (nnames x 1)
   int*      names_map;            // internal hash map of names               (nnames_map x 1)
+
+  // paths
+  char*     paths;                // paths to assets, 0-terminated            (npaths x 1)
 };
 typedef struct mjModel_ mjModel;
 struct mjResource_ {
@@ -1335,12 +1433,20 @@ typedef enum mjtGridPos_ {        // grid position for overlay
   mjGRID_TOPLEFT      = 0,        // top left
   mjGRID_TOPRIGHT,                // top right
   mjGRID_BOTTOMLEFT,              // bottom left
-  mjGRID_BOTTOMRIGHT              // bottom right
+  mjGRID_BOTTOMRIGHT,             // bottom right
+  mjGRID_TOP,                     // top center
+  mjGRID_BOTTOM,                  // bottom center
+  mjGRID_LEFT,                    // left center
+  mjGRID_RIGHT                    // right center
 } mjtGridPos;
 typedef enum mjtFramebuffer_ {    // OpenGL framebuffer option
   mjFB_WINDOW         = 0,        // default/window buffer
   mjFB_OFFSCREEN                  // offscreen buffer
 } mjtFramebuffer;
+typedef enum mjtDepthMap_ {       // depth mapping for `mjr_readPixels`
+  mjDEPTH_ZERONEAR    = 0,        // standard depth map; 0: znear, 1: zfar
+  mjDEPTH_ZEROFAR     = 1         // reversed depth map; 1: znear, 0: zfar
+} mjtDepthMap;
 typedef enum mjtFontScale_ {      // font scale, used at context creation
   mjFONTSCALE_50      = 50,       // 50% scale, suitable for low-res rendering
   mjFONTSCALE_100     = 100,      // normal scale, suitable in the absence of DPI scaling
@@ -1444,6 +1550,9 @@ struct mjrContext_ {              // custom OpenGL context
 
   // pixel output format
   int     readPixelFormat;        // default color pixel format for mjr_readPixels
+
+  // depth output format
+  int     readDepthMap;           // depth mapping: mjDEPTH_ZERONEAR or mjDEPTH_ZEROFAR
 };
 typedef struct mjrContext_ mjrContext;
 typedef enum mjtTaskStatus_ {  // status values for mjTask
@@ -1717,6 +1826,7 @@ typedef enum mjtLabel_ {          // object labeling
   mjLABEL_TENDON,                 // tendon labels
   mjLABEL_ACTUATOR,               // actuator labels
   mjLABEL_CONSTRAINT,             // constraint labels
+  mjLABEL_FLEX,                   // flex labels
   mjLABEL_SKIN,                   // skin labels
   mjLABEL_SELECTION,              // selected object
   mjLABEL_SELPNT,                 // coordinates of selection point
@@ -1763,7 +1873,12 @@ typedef enum mjtVisFlag_ {        // flags enabling model element visualization
   mjVIS_SELECT,                   // selection point
   mjVIS_STATIC,                   // static bodies
   mjVIS_SKIN,                     // skin
-  mjVIS_MIDPHASE,                 // mid-phase bounding volume hierarchy
+  mjVIS_FLEXVERT,                 // flex vertices
+  mjVIS_FLEXEDGE,                 // flex edges
+  mjVIS_FLEXFACE,                 // flex element faces
+  mjVIS_FLEXSKIN,                 // flex smooth skin (disables the rest)
+  mjVIS_BODYBVH,                  // body bounding volume hierarchy
+  mjVIS_FLEXBVH,                  // flex bounding volume hierarchy
   mjVIS_MESHBVH,                  // mesh bounding volume hierarchy
   mjVIS_SDFITER,                  // iterations of SDF gradient descent
 
@@ -1790,6 +1905,7 @@ typedef enum mjtStereo_ {         // type of stereo rendering
 } mjtStereo;
 struct mjvPerturb_ {              // object selection and perturbation
   int      select;                // selected body id; non-positive: none
+  int      flexselect;            // selected flex id; negative: none
   int      skinselect;            // selected skin id; negative: none
   int      active;                // perturbation bitmask (mjtPertBit)
   int      active2;               // secondary perturbation bitmask (mjtPertBit)
@@ -1822,6 +1938,7 @@ struct mjvGLCamera_ {             // OpenGL camera
 
   // camera projection
   float    frustum_center;        // hor. center (left,right set to match aspect)
+  float    frustum_width;         // width (not used for rendering)
   float    frustum_bottom;        // bottom
   float    frustum_top;           // top
   float    frustum_near;          // near
@@ -1837,7 +1954,7 @@ struct mjvGeom_ {                 // abstract geom
   int      category;              // visual category
   int      texid;                 // texture id; -1: no texture
   int      texuniform;            // uniform cube mapping
-  int      texcoord;              // mesh geom has texture coordinates
+  int      texcoord;              // mesh or flex geom has texture coordinates
   int      segid;                 // segmentation id; -1: not shown
 
   // OpenGL info
@@ -1880,9 +1997,11 @@ struct mjvOption_ {                  // abstract visualization options
   mjtByte  jointgroup[mjNGROUP];     // joint visualization by group
   mjtByte  tendongroup[mjNGROUP];    // tendon visualization by group
   mjtByte  actuatorgroup[mjNGROUP];  // actuator visualization by group
+  mjtByte  flexgroup[mjNGROUP];      // flex visualization by group
   mjtByte  skingroup[mjNGROUP];      // skin visualization by group
   mjtByte  flags[mjNVISFLAG];        // visualization flags (indexed by mjtVisFlag)
-  int bvh_depth;                     // depth of the bounding volume hierarchy to be visualized
+  int      bvh_depth;                // depth of the bounding volume hierarchy to be visualized
+  int      flex_layer;               // element layer to be visualized for 3D flex
 };
 typedef struct mjvOption_ mjvOption;
 struct mjvScene_ {                // abstract scene passed to OpenGL renderer
@@ -1892,13 +2011,32 @@ struct mjvScene_ {                // abstract scene passed to OpenGL renderer
   mjvGeom* geoms;                 // buffer for geoms (ngeom)
   int*     geomorder;             // buffer for ordering geoms by distance to camera (ngeom)
 
+  // flex data
+  int      nflex;                 // number of flexes
+  int*     flexedgeadr;           // address of flex edges (nflex)
+  int*     flexedgenum;           // number of edges in flex (nflex)
+  int*     flexvertadr;           // address of flex vertices (nflex)
+  int*     flexvertnum;           // number of vertices in flex (nflex)
+  int*     flexfaceadr;           // address of flex faces (nflex)
+  int*     flexfacenum;           // number of flex faces allocated (nflex)
+  int*     flexfaceused;          // number of flex faces currently in use (nflex)
+  int*     flexedge;              // flex edge data (2*nflexedge)
+  float*   flexvert;              // flex vertices (3*nflexvert)
+  float*   flexface;              // flex faces vertices (9*sum(flexfacenum))
+  float*   flexnormal;            // flex face normals (9*sum(flexfacenum))
+  float*   flextexcoord;          // flex face texture coordinates (6*sum(flexfacenum))
+  mjtByte  flexvertopt;           // copy of mjVIS_FLEXVERT mjvOption flag
+  mjtByte  flexedgeopt;           // copy of mjVIS_FLEXEDGE mjvOption flag
+  mjtByte  flexfaceopt;           // copy of mjVIS_FLEXFACE mjvOption flag
+  mjtByte  flexskinopt;           // copy of mjVIS_FLEXSKIN mjvOption flag
+
   // skin data
   int      nskin;                 // number of skins
   int*     skinfacenum;           // number of faces in skin (nskin)
   int*     skinvertadr;           // address of skin vertices (nskin)
   int*     skinvertnum;           // number of vertices in skin (nskin)
-  float*   skinvert;              // skin vertex data (nskin)
+  float*   skinvert;              // skin vertex data (3*nskinvert)
-  float*   skinnormal;            // skin normal data (nskin)
+  float*   skinnormal;            // skin normal data (3*nskinvert)
 
   // OpenGL lights
   int      nlight;                // number of lights currently in buffer
@@ -1973,7 +2111,7 @@ struct mjvSceneState_ {
   int nbuffer;                     // size of the buffer in bytes
   void* buffer;                    // heap-allocated memory for all arrays in this struct
   int maxgeom;                     // maximum number of mjvGeom supported by this state object
-  mjvScene plugincache;            // scratch space for vis geoms inserted by plugins
+  mjvScene scratch;                // scratch space for vis geoms inserted by the user and plugins
 
   // fields in mjModel that are necessary to re-render a scene
   struct {
@@ -1982,6 +2120,7 @@ struct mjvSceneState_ {
     int na;
     int nbody;
     int nbvh;
+    int nbvhstatic;
     int njnt;
     int ngeom;
     int nsite;
@@ -1989,6 +2128,8 @@ struct mjvSceneState_ {
     int nlight;
     int nmesh;
     int nskin;
+    int nflex;
+    int nflexvert;
     int nskinvert;
     int nskinface;
     int nskinbone;
@@ -2000,6 +2141,7 @@ struct mjvSceneState_ {
     int nwrap;
     int nsensor;
     int nnames;
+    int npaths;
     int nsensordata;
 
     mjOption opt;
@@ -2024,7 +2166,7 @@ struct mjvSceneState_ {
 
     int* bvh_depth;
     int* bvh_child;
-    int* bvh_geomid;
+    int* bvh_nodeid;
     mjtNum* bvh_aabb;
 
     int* jnt_type;
@@ -2052,6 +2194,7 @@ struct mjvSceneState_ {
 
     mjtNum* cam_fovy;
     mjtNum* cam_ipd;
+    float* cam_sensorsize;
 
     mjtByte* light_directional;
     mjtByte* light_castshadow;
@@ -2063,10 +2206,29 @@ struct mjvSceneState_ {
     float* light_diffuse;
     float* light_specular;
 
+    mjtByte* flex_flatskin;
+    int* flex_dim;
+    int* flex_matid;
+    int* flex_group;
+    int* flex_vertadr;
+    int* flex_vertnum;
+    int* flex_elem;
+    int* flex_elemadr;
+    int* flex_elemnum;
+    int* flex_elemdataadr;
+    int* flex_shell;
+    int* flex_shellnum;
+    int* flex_shelldataadr;
+    int* flex_bvhadr;
+    int* flex_bvhnum;
+    mjtNum* flex_radius;
+    float* flex_rgba;
+
     int* mesh_bvhadr;
     int* mesh_bvhnum;
     int* mesh_texcoordadr;
     int* mesh_graphadr;
+    int* mesh_pathadr;
 
     int* skin_matid;
     int* skin_group;
@@ -2101,7 +2263,6 @@ struct mjvSceneState_ {
     int* eq_type;
     int* eq_obj1id;
     int* eq_obj2id;
-    mjtByte* eq_active;
     mjtNum* eq_data;
 
     int* tendon_num;
@@ -2142,6 +2303,7 @@ struct mjvSceneState_ {
     int* name_tendonadr;
     int* name_actuatoradr;
     char* names;
+    char* paths;
   } model;
 
   // fields in mjData that are necessary to re-render a scene
@@ -2158,6 +2320,7 @@ struct mjvSceneState_ {
 
     mjtNum* ctrl;
     mjtNum* xfrc_applied;
+    mjtByte* eq_active;
 
     mjtNum* sensordata;
 
@@ -2192,6 +2355,8 @@ struct mjvSceneState_ {
     int* efc_island;
     int* tendon_efcadr;
 
+    mjtNum* flexvert_xpos;
+
     mjContact* contact;
     mjtNum* efc_force;
   } data;
@@ -2233,7 +2398,7 @@ void mj_resetDataDebug(const mjModel* m, mjData* d, unsigned char debug_value);
 void mj_resetDataKeyframe(const mjModel* m, mjData* d, int key);
 void mj_markStack(mjData* d);
 void mj_freeStack(mjData* d);
-void* mj_stackAlloc(mjData* d, size_t bytes, size_t alignment);
+void* mj_stackAllocByte(mjData* d, size_t bytes, size_t alignment);
 mjtNum* mj_stackAllocNum(mjData* d, int size);
 int* mj_stackAllocInt(mjData* d, int size);
 void mj_deleteData(mjData* d);
@@ -2271,6 +2436,7 @@ void mj_checkAcc(const mjModel* m, mjData* d);
 void mj_kinematics(const mjModel* m, mjData* d);
 void mj_comPos(const mjModel* m, mjData* d);
 void mj_camlight(const mjModel* m, mjData* d);
+void mj_flex(const mjModel* m, mjData* d);
 void mj_tendon(const mjModel* m, mjData* d);
 void mj_transmission(const mjModel* m, mjData* d);
 void mj_crb(const mjModel* m, mjData* d);
@@ -2345,6 +2511,9 @@ mjtNum mj_rayMesh(const mjModel* m, const mjData* d, int geomid,
                   const mjtNum pnt[3], const mjtNum vec[3]);
 mjtNum mju_rayGeom(const mjtNum pos[3], const mjtNum mat[9], const mjtNum size[3],
                    const mjtNum pnt[3], const mjtNum vec[3], int geomtype);
+mjtNum mju_rayFlex(const mjModel* m, const mjData* d, int flex_layer, mjtByte flg_vert,
+                   mjtByte flg_edge, mjtByte flg_face, mjtByte flg_skin, int flexid,
+                   const mjtNum* pnt, const mjtNum* vec, int vertid[1]);
 mjtNum mju_raySkin(int nface, int nvert, const int* face, const float* vert,
                    const mjtNum pnt[3], const mjtNum vec[3], int vertid[1]);
 void mjv_defaultCamera(mjvCamera* cam);
@@ -2379,7 +2548,8 @@ void mjv_applyPerturbForce(const mjModel* m, mjData* d, const mjvPerturb* pert);
 mjvGLCamera mjv_averageCamera(const mjvGLCamera* cam1, const mjvGLCamera* cam2);
 int mjv_select(const mjModel* m, const mjData* d, const mjvOption* vopt,
                mjtNum aspectratio, mjtNum relx, mjtNum rely,
-               const mjvScene* scn, mjtNum selpnt[3], int geomid[1], int skinid[1]);
+               const mjvScene* scn, mjtNum selpnt[3],
+               int geomid[1], int flexid[1], int skinid[1]);
 void mjv_defaultOption(mjvOption* opt);
 void mjv_defaultFigure(mjvFigure* fig);
 void mjv_initGeom(mjvGeom* geom, int type, const mjtNum size[3],
@@ -2598,6 +2768,7 @@ int mjp_resourceProviderCount(void);
 const mjpResourceProvider* mjp_getResourceProvider(const char* resource_name);
 const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
 mjThreadPool* mju_threadPoolCreate(size_t number_of_threads);
+void mju_bindThreadPool(mjData* d, void* thread_pool);
 void mju_threadPoolEnqueue(mjThreadPool* thread_pool, mjTask* task);
 void mju_threadPoolDestroy(mjThreadPool* thread_pool);
 void mju_defaultTask(mjTask* task);

doc/index.rst

@@ -8,7 +8,7 @@
    :hidden:
 
    overview
-   computation
+   computation/index.rst
    modeling
    XMLreference
    programming/index.rst

doc/modeling.rst

@@ -973,6 +973,31 @@ Here we describe the XML attributes common to all sensor types, so as to avoid r
 :at:`user`: :at-val:`real(nuser_sensor), "0 0 ..."`
    See :ref:`User parameters <CUser>`.
 
+.. _CCamera:
+
+Cameras
+~~~~~~~
+
+Besides the default, user-controllable, free camera, "fixed" cameras can be attached to the kinematic tree.
+
+Extrinsics
+   By default, camera frames are attached to the parent body. The optional :ref:`mode<body-camera-mode>` and
+   :ref:`target<body-camera-target>` attributes can be used to specify camera that track (move with) or target (look at)
+   a body or subtree. Cameras look towards the negative Z axis of the camera frame, while positive X and Y correspond to
+   *right* and *up* in the image plane, respectively.
+
+Intrinsics
+   Camera intrinsics are specified using :ref:`ipd<body-camera-ipd>` (inter-pupilary distance, required for
+   stereoscopic rendering and VR) and :ref:`fovy<body-camera-fovy>` (vertical field of view, in degrees).
+
+   The above specification implies a perfect point camera with no aberrations. However when calibrating real cameras,
+   two types of linear aberration can be expressed using standard rendering pipelines. The first is different focal
+   lengths in the vertical and horizontal directions (axis-aligned astigmatism). The second is a non-centered principal
+   point. These can be specified using the :ref:`focal<body-camera-focal>` and :ref:`principal<body-camera-principal>`
+   attributes. When these calibration-related attributes are used, the physical
+   :ref:`sensor size<body-camera-sensorsize>` and camera :ref:`resolution<body-camera-resolution>` must also be
+   specified. In this case, the rendering frustum can be visualized.
+
 .. _CComposite:
 
 Composite objects

doc/overview.rst

@@ -48,11 +48,12 @@ Soft, convex and analytically-invertible contact dynamics
    In the modern approach to contact dynamics, the forces or impulses caused by frictional contacts are usually defined
    as the solution to a linear or non-linear complementarity problem (LCP or NCP), both of which are NP-hard. MuJoCo is
    based on a different formulation of the physics of contact which reduces to a convex optimization problem, as
-   explained in detail in the :doc:`computation` chapter. Our model allows soft contacts and other constraints, and has
+   explained in detail in the :doc:`computation/index` chapter. Our model allows soft contacts and other constraints,
-   a uniquely-defined inverse facilitating data analysis and control applications. There is a choice of optimization
+   and has a uniquely-defined inverse facilitating data analysis and control applications. There is a choice of
-   algorithms, including a generalization to the projected Gauss-Seidel method that can handle elliptic friction cones.
+   optimization algorithms, including a generalization to the projected Gauss-Seidel method that can handle elliptic
-   The solver provides unified treatment of frictional contacts including torsional and rolling friction, frictionless
+   friction cones. The solver provides unified treatment of frictional contacts including torsional and rolling
-   contacts, joint and tendon limits, dry friction in joints and tendons, as well as a variety of equality constraints.
+   friction, frictionless contacts, joint and tendon limits, dry friction in joints and tendons, as well as a variety of
+   equality constraints.
 
 Tendon geometry
    MuJoCo can model the 3D geometry of tendons - which are minimum-path-length strings obeying wrapping and via-point
@@ -97,7 +98,7 @@ Separation of model and data
    :ref:`mjModel` is constructed by the compiler. :ref:`mjData` is constructed at runtime, given
    :ref:`mjModel`. This separation makes it easy to simulate multiple models as well as multiple states and controls for
    each model, in turn facilitating :ref:`multi-threading <siMultithread>` for sampling and :ref:`finite
-   differences <saDerivative>`. The top-level API functions reflect this basic separation, and have
+   differences <mjd_transitionFD>`. The top-level API functions reflect this basic separation, and have
    the format:
 
    .. code:: C
@@ -514,8 +515,10 @@ Camera
 Multiple cameras can be defined in a model. There is always a default camera which the user can freely move with the
 mouse in the interactive visualizer. However it is often convenient to define additional cameras that are either
 fixed to the world, or are attached to one of the bodies and move with it. In addition to the camera position and
-orientation, the user can adjust the field of view and the inter-pupilary distance for stereoscopic rendering, as
+orientation, the user can adjust the vertical field of view and the inter-pupilary distance for stereoscopic rendering,
-well as create oblique projections needed for stereoscopic virtual environments.
+as well as create oblique projections needed for stereoscopic virtual environments. When modeling real cameras with
+imperfect optics, it is possible to specify separate focal lengths for the horizontal and vertical directions and a
+non-centered principal point.
 
 Light
 ^^^^^
@@ -746,13 +749,13 @@ multi-threading, but we do so in a way that is different from how object-oriente
 Softness and slip
 ~~~~~~~~~~~~~~~~~
 
-As we will explain at length in the :doc:`computation` chapter, MuJoCo is based on a mathematical model of the physics
+As we will explain at length in the :doc:`computation/index` chapter, MuJoCo is based on a mathematical model of the
-of contact and other constraints. This model is inherently soft, in the sense that pushing harder against a constraint
+physics of contact and other constraints. This model is inherently soft, in the sense that pushing harder against a
-will always result in larger acceleration, and so the inverse dynamics can be uniquely defined. This is desirable
+constraint will always result in larger acceleration, and so the inverse dynamics can be uniquely defined. This is
-because it yields a convex optimization problem and enables analyses that rely on inverse dynamics, and furthermore,
+desirable because it yields a convex optimization problem and enables analyses that rely on inverse dynamics, and
-most contacts that we need to model in practice have some softness. However once we allow soft constraints, we are
+furthermore, most contacts that we need to model in practice have some softness. However once we allow soft constraints,
-effectively creating a new type of dynamics -- namely deformation dynamics -- and now we must specify how these dynamics
+we are effectively creating a new type of dynamics -- namely deformation dynamics -- and now we must specify how these
-behave. This calls for elaborate parameterization of contacts and other constraints, involving the attributes
+dynamics behave. This calls for elaborate parameterization of contacts and other constraints, involving the attributes
 :at:`solref` and :at:`solimp` that can be set per constraints and will be described later.
 
 An often confusing aspect of this soft model is that gradual contact slip cannot be avoided. Similarly, frictional

doc/programming/index.rst

@@ -165,7 +165,7 @@ links below, to make this documentation self-contained.
 `mjxmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`__
    This file is optional and is not included by mujoco.h. It defines :ref:`X Macros <tyXMacro>` that can
    automate the mapping of mjModel and mjData into scripting languages, as well as other operations that require
-   accessing all fields of mjModel and mjData. See code sample :ref:`testxml.cc <saTestXML>`.
+   accessing all fields of mjModel and mjData.
 `mjexport.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjexport.h>`__
    Macros used for exporting public symbols from the MuJoCo library. This header should not be used directly by client
    code.

doc/programming/samples.rst

@@ -12,41 +12,66 @@ with the library.
 `testspeed <https://github.com/google-deepmind/mujoco/blob/main/sample/testspeed.cc>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This code sample tests the simulation speed for a given model. The command line arguments are the model file, the
+This code sample times the simulation of a given model. The timing is straightforward: the simulation of the passive
-number of time steps to simulate, the number of parallel threads to use, and a flag to enable internal profiling (the
+dynamics (with optional control noise) is rolled-out for the specified number of steps, while collecting statistics
-last two are optional). When N threads are specified with N>1, the code allocates a single mjModel and per-thread
+about the number of contacts, scalar constraints, and CPU times from internal profiling. The results are then printed to
-mjData, and runs N identical simulations in parallel. The idea is to test performance with all cores active, similar
+the console. To simulate controlled dynamics instead of passive dynamics one can either install a control callback
-to Reinforcement Learning scenarios where samples are collected in parallel. The optimal N usually equals the number
+:ref:`mjcb_control`, or modify the code to set control signals explicitly, as explained in the :ref:`simulation loop
-of logical cores. By default the simulation starts from the model reference configuration qpos0 and qvel=0. However if
+<siSimulation>` section below. This command-line utility is run with
-a keyframe named "test" is present in the model, it is used as the initial state state.
 
-The timing code is straightforward: the simulation of the passive dynamics is advanced for the specified number of
+.. code-block:: Shell
-steps, while collecting statistics about the number of contacts, scalar constraints, and CPU times from internal
-profiling. The results are then printed in the console. To simulate controlled dynamics instead of passive dynamics
-one can either install the control callback :ref:`mjcb_control`, or set control signals
-explicitly as explained in the :ref:`simulation loop <siSimulation>` section below.
 
-.. _saTestXML:
+   testspeed modelfile [nstep nthread ctrlnoise npoolthread]
 
-`testxml <https://github.com/google-deepmind/mujoco/blob/main/sample/testxml.cc>`_
+Where the command line arguments are
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This code sample tests the parser, compiler and XML writer. The testing code does the following:
+.. list-table::
+   :width: 95%
+   :align: left
+   :widths: 1 1 5
+   :header-rows: 1
 
--  Parse and compile a specified XML model in MJCF or URDF. This yields an mjModel structure ready for simulation;
+   * - Argument
--  Save the model as a temporary MJCF file, using a "canonical" subset of MJCF where a number of conversions have
+     - Default
-   already been performed by the compiler;
+     - Meaning
--  Parse and compile the temporary MJCF file. This yields a second mjModel structure ready for simulation;
+   * - ``modelfile``
--  Compare the two mjModel structures field by field, and print the field with the largest numerical difference. Since
+     - (required)
-   MJCF is a text format, the real-valued numbers saved in it have lower precision than the double precision used
+     - path to model
-   internally, thus we cannot expect the two models to be identical on the bit level. But we can expect the largest
+   * - ``nstep``
-   difference to be on the order of 1e-6. A substantially larger difference indicates a bug in the parser, compiler or
+     - 10000
-   XML writer - and should be reported.
+     - number of steps per rollout
+   * - ``nthread``
+     - 1
+     - number of threads running parallel rollouts
+   * - ``ctrlnoise``
+     - 0.01
+     - scale of pseudo-random noise injected into actuators
+   * - ``npoolthread``
+     - 1
+     - number of threads in engine-internal threadpool
 
-The code uses the :ref:`X Macros <tyXMacro>` described in the Reference chapter. This is a convenient way
+**Notes:**
-to apply the same operation to all fields in mjModel, without explicitly typing their names. The code sample
+
-:ref:`simulate.cc <saSimulate>` also uses X Macros to implement a watch, where the user can type the name of any mjData
+- When ``nthread > 1`` is specified, the code allocates a single mjModel and per-thread mjData, and runs ``nthread``
-field which is resolved at runtime.
+  identical simulations in parallel. This tests performance with all cores active, as in Reinforcement
+  Learning scenarios where samples are collected in parallel. The optimal ``nthread`` usually equals the number of
+  logical cores.
+- By default, the simulation starts from the model reference configuration with zero velocities. However, if a
+  keyframe named "test" is present in the model, it is used as the initial state.
+- The ``ctrlnoise`` argument prevents models from settling into a static state where, due to warmstarts, one can
+  measure artificially faster simulation.
+- When ``npoolthread > 1`` is specified, an engine-internal :ref:`mjThreadPool` is created with the specified number of
+  threads, to speed up simulation of large scenes. Note that while it is possible to to use both ``nthread`` and
+  ``npoolthread``, the scenarios for which one would want these different type of multithreading are usually mutually
+  exclusive.
+- For more repeatable performance statistics, run the tool with the ``performance``
+  `governor <https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt>`__ on Linux, or the
+  ``High Performance`` power plan on Windows, to reduce noise from CPU scaling.
+- Many modern CPUs contain a mixture of "performance" and "efficiency" cores. Users should consider restricting the
+  process to only run on the same type of cores for more interpretable performance statistics. This can be done via the
+  `taskset <https://man7.org/linux/man-pages/man1/taskset.1.html>`__ command on Linux, or the
+  `start /affinity <https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/start>`__
+  command on Windows (processor affinity cannot be specified through documented API means on macOS).
 
 .. _saCompile:
 
@@ -152,69 +177,3 @@ proliferation of overlapping technologies, which differ not only between platfor
 case of Linux. The addition of a couple of extra functions (such as those provided by OSMesa for example) could have
 avoided a lot of confusion. EGL is a newer standard from Khronos which aims to do this, and it is gaining popularity.
 But we cannot yet assume that all users have it installed.
-
-.. _saDerivative:
-
-`derivative <https://github.com/google-deepmind/mujoco/blob/main/sample/derivative.cc>`_
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This code sample illustrates the numerical approximation of forward and inverse dynamics derivatives via finite
-differences. The process involves a number of epochs. In each epoch the simulation is advanced for a specified number
-of steps, derivatives are computed at the last state, and timing and accuracy statistics are collected. The averages
-over epochs are printed at the end.
-
-The code can be incorporated in user projects where derivatives are needed, and can also be used as a stand-alone tool
-for estimating CPU time and numerical accuracy. Accuracy is estimated in the function ``checkderiv()`` using several
-mathematical identities about the derivatives of inverse functions; the residuals being computed would be zero if the
-derivatives were exact. Note that these identities involve matrix multiplications which may affect the accuracy
-estimates. Timing tests are applied only to the parallel section, where the function ``worker()`` is executed in
-multiple threads using OpenMP. There are fewer threads than forward/inverse dynamics evaluations, thus each thread
-executes multiple evaluations. For a more general discussion of parallel processing in MuJoCo see
-:ref:`multi-threading <siMultithread>` below.
-
-Recall than for a differentiable function ``f(x)`` the derivative can be approximated as
-
-.. code-block:: Text
-
-     df/dx = (f(x+eps)-f(x))/eps
-
-where ``eps`` is a small number. One can also use the centered finite difference method, which is two times slower but
-more accurate. Here ``f`` is one of the functions
-
-.. code-block:: Text
-
-     forward dynamics:  qacc(qfrc_applied, qvel, qpos)
-     inverse dynamics:  qfrc_inverse(qacc, qvel, qpos)
-
-The code sample computes six Jacobian matrices, containing the derivative of each function with respect to its three
-arguments. The results are stored in the array ``deriv``. All six Jacobian matrices are square, with dimensionality
-equal to the number of degrees of freedom ``mjModel.nv``. When the model configuration includes quaternion joints,
-mjData.qpos has larger dimensionality than the other vectors, however the derivative is only defined in the tangent
-space to the configuration manifold. This is why, when differentiating with respect to the elements of ``mjData.qpos``,
-we do not directly add ``eps`` but instead use the function :ref:`mju_quatIntegrate` to perturb the quaternion in the
-tangent space, keeping it normalized. This technique should also be used in any other situation where quaternions need
-to be perturbed.
-
-There are some important subtleties in this code that improve speed as well as accuracy. To speed up the computation,
-we re-use intermediate results whenever possible. This relies on the skip mechanism described under :ref:`forward
-dynamics <siForward>` and :ref:`inverse dynamics <siInverse>` below. We first perturb force dimensions, keeping
-position and velocity fixed. In this way we avoid recomputing results that depend on position and velocity but not on
-force. Then we perturb velocity dimensions, and avoid recomputing results that depend on position but not on velocity
-or force. Finally we perturb position dimensions - which requires full computation because everything depends on
-position.
-
-Accuracy depends on the value of ``eps`` which is user-adjustable, as well as the shape of the function. In the case
-of forward dynamics however, the function evaluation involves an iterative constraint solver, and this must be handled
-with care. In general, the difference between ``f(x+eps)`` and ``f(x)`` is very small, thus any noise affecting the
-two function evaluations differently can make the resulting derivatives meaningless. Different warm-starts or
-different number of solver iterations can act as such noise here. Therefore we fix the warm-start ``mjData.qacc`` to a
-value pre-computed at the center point, using ``nwarmup`` extra major iterations to obtain a more accurate warm-start.
-We also fix the number of solver iterations to ``niter`` and set ``mjModel.opt.tolerance = 0``; this disables the early
-termination mechanism. Note that the original simulation options are restored in the serial code which advances the
-state.
-
-We emphasize that the above subtleties are not high-order corrections that can be incorporated later. In the presence
-of unilateral constraints, numerical derivatives are hard to compute and there is no shortcut around it; indeed they
-would not even be defined if it wasn't for our soft-constraint model. Making the constraints softer results in more
-accurate results. This effect is so strong that in some situations it makes sense to intentionally work with the wrong
-model, i.e., a model that is softer than desired, so as to obtain more accurate derivatives.

doc/programming/simulation.rst

@@ -428,9 +428,7 @@ However, MuJoCo is designed not only for simulation but also for more advanced a
 optimization, machine learning etc. In such settings one often needs to sample the dynamics at a cloud of nearby
 states, or approximate derivatives via finite differences - which is another form of sampling. If the samples are
 arranged on a grid, where only the position or only the velocity or only the control is different from the center
-point, then the above mechanism can improve performance by about a factor of 2. The code sample :ref:`derivative.cc
+point, then the above mechanism can improve performance by about a factor of 2.
-<saDerivative>` illustrates this approach, and also shows how :ref:`multi-threading <siMultithread>` can be used for
-additional speedup.
 
 .. _siInverse:
 
@@ -494,10 +492,7 @@ bodies, we may eventually implement within-step multi-threading, but for now thi
 Rather than speed up a single simulation, we prefer to use multi-threading to speed up sampling operations that are
 common in more advanced applications. Simulation is inherently serial over time (the output of one mj_step is the
 input to the next), while in sampling many calls to either forward or inverse dynamics can be executed in parallel
-since there are no dependencies among them, except perhaps for a common initial state. The code sample
+since there are no dependencies among them, except perhaps for a common initial state.
-:ref:`derivative.cc <saDerivative>` illustrates one important example of sampling, namely the approximation of
-dynamics derivatives via finite differences. Here we will not repeat the material from that section, but will instead
-explain MuJoCo's general approach to parallel processing.
 
 MuJoCo was designed for multi-threading from its beginning. Unlike most existing simulators where the notion of
 dynamical system state is difficult to map to the software state and is often distributed among multiple objects, in
@@ -515,7 +510,7 @@ management.
 
    // allocate per-thread mjData
    mjData* d[64];
-   for( int n=0; n<nthread; n++ )
+   for( int n=0; n < nthread; n++ )
        d[n] = mj_makeData(m);
 
    // ... serial code, perhaps using its own mjData* dmain
@@ -541,8 +536,8 @@ writes to its own mjData. Therefore no further synchronization among threads is
 The above template reflects a particular style of parallel processing. Instead of creating a large number of threads,
 one for each work item, and letting OpenMP distribute them among processors, we rely on manual scheduling. More
 precisely, we create as many threads as there are processors, and then within the ``worker`` function we distribute the
-work explicitly among threads (not shown here, but see :ref:`derivative.cc <saDerivative>` for an example). This
+work explicitly among threads. This approach is more efficient because the thread-specific mjData is large compared to
-approach is more efficient because the thread-specific mjData is large compared to the processor cache.
+the processor cache.
 
 We also use a shared mjModel for cache-efficiency. In some situations it may not be possible to use the same mjModel
 for all threads. One obvious reason is that mjModel may need to be modified within the thread function. Another reason
@@ -676,10 +671,7 @@ correct way to do it is the hard way:
    mju_copy(myqposqvel, d->qpos, m->nq + m->nv);
 
 The :ref:`X Macros <tyXMacro>` defined in the optional header file ``mjxmacro.h`` can be used to automate allocation of
-data structure that match mjModel and mjData, for example when writing a MuJoCo wrapper for a scripting language. In
+data structure that match mjModel and mjData, for example when writing a MuJoCo wrapper for a scripting language.
-the code sample :ref:`testxml.cc <saTestXML>` we use these unusual macros to compare all data arrays from two instances
-of mjModel and find the one with the largest difference. Apparently X Macros were invented in the 1960's for assembly
-language, and remain a great idea.
 
 .. _siStack:
 
@@ -721,7 +713,7 @@ The function :ref:`mj_stackAllocNum` checks if there is enough space, and if so
 otherwise it triggers an error. It also keeps track of the maximum stack allocation;
 see :ref:`diagnostics <siDiagnostics>` below. Note that :ref:`mj_stackAllocNum` is only used for allocating
 ``mjtNum`` arrays, the most common type of array. :ref:`mj_stackAllocInt` is provided for integer array allocation,
-and :ref:`mj_stackAlloc` is provided for allocation of arbitrary number of bytes and alignment.
+and :ref:`mj_stackAllocByte` is provided for allocation of arbitrary number of bytes and alignment.
 
 .. _siError:
 
@@ -841,13 +833,6 @@ forces are disabled) the underlying physical system is energy-conserving. In tha
 the total energy indicate inaccuracies in numerical integration. For such systems the Runge-Kutta integrator has much
 better performance than the default semi-implicit Euler integrator.
 
-Finally, the user can implement additional diagnostics as needed. Two examples were provided in the code samples
-``testxml.cc`` and ``derivative.cc``, where we computed model mismatches after save and load, and assessed the accuracy
-of the numerical derivatives respectively. Key to such diagnostics is to implement two different algorithms or
-simulation paths that compute the same quantity, and compare the results numerically. This type of sanity check is
-essential when dealing with complex dynamical systems where we do not really know what the numerical output should be;
-if we knew that, we would not be using a simulator in the first place.
-
 .. _siJacobian:
 
 Jacobians
@@ -888,8 +873,8 @@ function is essentially free in terms of CPU cost; so do not hesitate to use thi
 Contacts
 ~~~~~~~~
 
-Collision detection and solving for contact forces were explained in detail in the :doc:`../computation` chapter. Here
+Collision detection and solving for contact forces were explained in detail in the :doc:`../computation/index` chapter.
-we further clarify contact processing from a programming perspective.
+Here we further clarify contact processing from a programming perspective.
 
 The collision detection stage finds contacts between geoms, and records them in the array ``mjData.contact`` of
 :ref:`mjContact` data structures. They are sorted such that multiple contacts between the same pair of bodies are

doc/python.rst

@@ -96,13 +96,13 @@ perturbations will not work unless the user explicitly synchronizes incoming eve
 The ``launch_passive`` function returns a handle which can be used to interact with the viewer. It has the following
 attributes:
 
-- ``scn``, ``cam``, ``opt``, and ``pert`` properties: correspond to :ref:`mjvScene`, :ref:`mjvCamera`,
+- ``cam``, ``opt``, and ``pert`` properties: correspond to :ref:`mjvCamera`, :ref:`mjvOption`, and :ref:`mjvPerturb`
-  :ref:`mjvOption`, and :ref:`mjvPerturb` structs, respectively.
+  structs, respectively.
 
 - ``lock()``: provides a mutex lock for the viewer as a context manager. Since the viewer operates its own
   thread, user code must ensure that it is holding the viewer lock before modifying any physics or visualization
-  state. These include the ``mjModel`` and ``mjData`` instance passed to ``launch_passive``, and also the ``scn``,
+  state. These include the ``mjModel`` and ``mjData`` instance passed to ``launch_passive``, and also the ``cam``,
-  ``cam``, ``opt``, and ``pert`` properties of the viewer handle.
+  ``opt``, and ``pert`` properties of the viewer handle.
 
 - ``sync()``: synchronizes state between ``mjModel``, ``mjData``, and GUI user inputs since the previous call to
   ``sync``. In order to allow user scripts to make arbitrary modifications to ``mjModel`` and ``mjData`` without
@@ -124,6 +124,37 @@ attributes:
 - ``is_running()``: returns ``True`` if the viewer window is running and ``False`` if it is closed.
   This method can be safely called without locking.
 
+- ``user_scn``: an :ref:`mjvScene` object that allows users to add custom visualization geoms to the rendered scene.
+  This is separate from the ``mjvScene`` that the viewer uses internally to render the final scene, and is entirely
+  under the user's control. User scripts can call e.g. :ref:`mjv_initGeom` or :ref:`mjv_makeConnector` to add
+  visualization geoms to ``user_scn``, and upon the next call to ``sync()``, the viewer will incorporate
+  these geoms to future rendered images. For example:
+
+  .. code-block:: python
+
+    with mujoco.viewer.launch_passive(m, d, key_callback=key_callback) as viewer:
+      while viewer.is_running():
+        ...
+        # Step the physics.
+        mujoco.mj_step(m, d)
+
+        # Add a 3x3x3 grid of variously colored spheres to the middle of the scene.
+        viewer.user_scn.ngeom = 0
+        i = 0
+        for x, y, z in itertools.product(*((range(-1, 2),) * 3)):
+          mujoco.mjv_initGeom(
+              viewer.user_scn.geoms[i],
+              type=mujoco.mjtGeom.mjGEOM_SPHERE,
+              size=[0.02, 0, 0],
+              pos=0.1*np.array([x, y, z]),
+              mat=np.eye(3).flatten(),
+              rgba=0.5*np.array([x + 1, y + 1, z + 1, 2])
+          )
+          i += 1
+        viewer.user_scn.ngeom = i
+        viewer.sync()
+        ...
+
 The viewer handle can also be used as a context manager which calls ``close()`` automatically upon exit. A minimal
 example of a user script that uses ``launch_passive`` might look like the following. (Note that example is a simple
 illustrative example that does **not** necessarily keep the physics ticking at the correct wallclock rate.)
@@ -160,29 +191,33 @@ illustrative example that does **not** necessarily keep the physics ticking at t
       if time_until_next_step > 0:
         time.sleep(time_until_next_step)
 
-Optionally, ``viewer.launch_passive`` also accepts a callable as a keyword argument ``key_callback``, which gets called
+Optionally, ``viewer.launch_passive`` accepts the following keyword arguments.
-each time a keyboard event occurs in the viewer window. This allows user scripts to react to various key presses, e.g.,
-pause or resume the run loop when the spacebar is pressed.
 
-.. code-block:: python
+- ``key_callback``: A callable which gets called each time a keyboard event occurs in the viewer window. This allows
+  user scripts to react to various key presses, e.g., pause or resume the run loop when the spacebar is pressed.
 
-  paused = False
+  .. code-block:: python
 
-  def key_callback(keycode):
+    paused = False
-    if chr(keycode) == ' ':
-      nonlocal paused
-      paused = not paused
 
-  ...
+    def key_callback(keycode):
+      if chr(keycode) == ' ':
+        nonlocal paused
+        paused = not paused
 
-  with mujoco.viewer.launch_passive(m, d, key_callback=key_callback) as viewer:
+    ...
-    while viewer.is_running():
-      ...
-      if not paused:
-        mujoco.mj_step(m, d)
-        viewer.sync()
-      ...
 
+    with mujoco.viewer.launch_passive(m, d, key_callback=key_callback) as viewer:
+      while viewer.is_running():
+        ...
+        if not paused:
+          mujoco.mj_step(m, d)
+          viewer.sync()
+        ...
+
+- ``show_left_ui_panel`` and ``show_right_ui_panel``: Boolean arguments indicating whether UI panels should be visible
+  or hidden when the viewer is launched. Note that regardless of the values specified, the user can still toggle the
+  visibility of these panels after launch by pressing Tab or Shift+Tab.
 
 .. _PyUsage:
 

doc/references.bib

@@ -0,0 +1,90 @@
+@book{lamb1932,
+  title={Hydrodynamics. Sixth edition.},
+  author={Lamb, Horace},
+  year={1932},
+  publisher={Cambridge University Press}
+}
+
+@book{kennard1967,
+  title={Irrotational Flow of Frictionless Fluids: Mostly of Invariable Density},
+  author={Kennard, Earle Hesse},
+  volume={2299},
+  year={1967},
+  publisher={US Government Printing Office}
+}
+
+@book{tuckerman1925,
+  title={Inertia factors of ellipsoids for use in airship design},
+  author={Tuckerman, LB},
+  year={1925},
+  publisher={US Government Printing Office}
+}
+
+@article{wang2004,
+  title={Unsteady forces and flows in low Reynolds number hovering flight: two-dimensional computations vs robotic wing experiments},
+  author={Wang, Z Jane and Birch, James M and Dickinson, Michael H},
+  journal={Journal of Experimental Biology},
+  volume={207},
+  number={3},
+  pages={449--460},
+  year={2004},
+  publisher={Company of Biologists}
+}
+@article{andersen2005a,
+  title={Unsteady aerodynamics of fluttering and tumbling plates},
+  author={Andersen, A and Pesavento, U and Wang, Z Jane},
+  journal={Journal of Fluid Mechanics},
+  volume={541},
+  pages={65--90},
+  year={2005},
+  publisher={Cambridge University Press}
+}
+@article{andersen2005b,
+  title={Analysis of transitions between fluttering, tumbling and steady descent of falling cards},
+  author={Andersen, Anders and Pesavento, Umberto and Wang, Z Jane},
+  journal={Journal of Fluid Mechanics},
+  volume={541},
+  pages={91--104},
+  year={2005},
+  publisher={Cambridge University Press}
+}
+
+@article{stokes1850,
+  title={On the effect of internal friction of fluids on the motion of pendulums},
+  author={Stokes, GG},
+  journal={Trans. Camb. phi1. S0c},
+  volume={9},
+  number={8},
+  pages={106},
+  year={1850}
+}
+
+@article{loth2008,
+  title={Drag of non-spherical solid particles of regular and irregular shape},
+  author={Loth, E},
+  journal={Powder Technology},
+  volume={182},
+  number={3},
+  pages={342--353},
+  year={2008},
+  publisher={Elsevier}
+}
+@article{bagheri2016,
+  title={On the drag of freely falling non-spherical particles},
+  author={Bagheri, Gholamhossein and Bonadonna, Costanza},
+  journal={Powder Technology},
+  volume={301},
+  pages={526--544},
+  year={2016},
+  publisher={Elsevier}
+}
+@article{duan2015,
+  title={Sphere drag and heat transfer},
+  author={Duan, Zhipeng and He, Boshu and Duan, Yuanyuan},
+  journal={Scientific reports},
+  volume={5},
+  number={1},
+  pages={1--7},
+  year={2015},
+  publisher={Nature Publishing Group}
+}

doc/requirements.txt

@@ -1,5 +1,6 @@
 Sphinx==4.5.0
 furo==2022.9.29
+sphinxcontrib-bibtex==2.6.1
 sphinxcontrib-katex==0.9.4
 sphinxcontrib-youtube==1.2.0
 sphinx-copybutton==0.5.2

include/mujoco/mjdata.h

@@ -20,6 +20,7 @@
 
 #include <mujoco/mjtnum.h>
 #include <mujoco/mjmodel.h>
+#include <mujoco/mjthread.h>
 
 //---------------------------------- primitive types (mjt) -----------------------------------------
 
@@ -32,18 +33,20 @@ typedef enum mjtState_ {          // state elements
   mjSTATE_CTRL          = 1<<5,   // control
   mjSTATE_QFRC_APPLIED  = 1<<6,   // applied generalized force
   mjSTATE_XFRC_APPLIED  = 1<<7,   // applied Cartesian force/torque
-  mjSTATE_MOCAP_POS     = 1<<8,   // positions of mocap bodies
+  mjSTATE_EQ_ACTIVE     = 1<<8,   // enable/disable constraints
-  mjSTATE_MOCAP_QUAT    = 1<<9,   // orientations of mocap bodies
+  mjSTATE_MOCAP_POS     = 1<<9,   // positions of mocap bodies
-  mjSTATE_USERDATA      = 1<<10,  // user data
+  mjSTATE_MOCAP_QUAT    = 1<<10,  // orientations of mocap bodies
-  mjSTATE_PLUGIN        = 1<<11,  // plugin state
+  mjSTATE_USERDATA      = 1<<11,  // user data
+  mjSTATE_PLUGIN        = 1<<12,  // plugin state
 
-  mjNSTATE              = 12,     // number of state elements
+  mjNSTATE              = 13,     // number of state elements
 
   // convenience values for commonly used state specifications
   mjSTATE_PHYSICS       = mjSTATE_QPOS | mjSTATE_QVEL | mjSTATE_ACT,
   mjSTATE_FULLPHYSICS   = mjSTATE_PHYSICS | mjSTATE_TIME | mjSTATE_PLUGIN,
   mjSTATE_USER          = mjSTATE_CTRL | mjSTATE_QFRC_APPLIED | mjSTATE_XFRC_APPLIED |
-                          mjSTATE_MOCAP_POS | mjSTATE_MOCAP_QUAT | mjSTATE_USERDATA,
+                          mjSTATE_EQ_ACTIVE | mjSTATE_MOCAP_POS | mjSTATE_MOCAP_QUAT |
+                          mjSTATE_USERDATA,
   mjSTATE_INTEGRATION   = mjSTATE_FULLPHYSICS | mjSTATE_USER | mjSTATE_WARMSTART
 } mjtState;
 
@@ -82,6 +85,11 @@ typedef enum mjtTimer_ {     // internal timers
   mjTIMER_POS_MAKE,          // make constraints
   mjTIMER_POS_PROJECT,       // project constraints
 
+  // breakdown of mj_collision
+  mjTIMER_COL_BROAD,         // broadphase
+  mjTIMER_COL_MID,           // midphase
+  mjTIMER_COL_NARROW,        // narrowphase
+
   mjNTIMER                   // number of timers
 } mjtTimer;
 
@@ -89,7 +97,7 @@ typedef enum mjtTimer_ {     // internal timers
 //---------------------------------- mjContact -----------------------------------------------------
 
 struct mjContact_ {                // result of collision detection functions
-  // contact parameters set by geom-specific collision detector
+  // contact parameters set by near-phase collision function
   mjtNum  dist;                    // distance between nearest points; neg: penetration
   mjtNum  pos[3];                  // position of contact point: midpoint between geoms
   mjtNum  frame[9];                // normal is in [0-2]
@@ -105,12 +113,16 @@ struct mjContact_ {                // result of collision detection functions
   mjtNum  mu;                      // friction of regularized cone, set by mj_makeConstraint
   mjtNum  H[36];                   // cone Hessian, set by mj_updateConstraint
 
-  // contact descriptors set by mj_collideGeoms
+  // contact descriptors set by mj_collideXXX
   int     dim;                     // contact space dimensionality: 1, 3, 4 or 6
   int     geom1;                   // id of geom 1
   int     geom2;                   // id of geom 2
+  int     geom[2];                 // geom ids; -1 for flex
+  int     flex[2];                 // flex ids; -1 for geom
+  int     elem[2];                 // element ids; -1 for geom or flex vertex
+  int     vert[2];                 // vertex ids;  -1 for geom or flex element
 
-  // flag set by mj_instantianteEquality
+  // flag set by mj_setContact or mj_instantiateContact
   int     exclude;                 // 0: include, 1: in gap, 2: fused, 3: no dofs
 
   // address computed by mj_instantiateContact
@@ -163,10 +175,11 @@ struct mjData_ {
   size_t  parena;            // first available byte in arena
 
   // memory utilization stats
-  size_t  maxuse_stack;      // maximum stack allocation
+  size_t  maxuse_stack;                      // maximum stack allocation in bytes
-  size_t  maxuse_arena;      // maximum arena allocation
+  size_t  maxuse_threadstack[mjMAXTHREADS];  // maximum stack allocation per thread in bytes
-  int     maxuse_con;        // maximum number of contacts
+  size_t  maxuse_arena;                      // maximum arena allocation in bytes
-  int     maxuse_efc;        // maximum number of scalar constraints
+  int     maxuse_con;                        // maximum number of contacts
+  int     maxuse_efc;                        // maximum number of scalar constraints
 
   // diagnostics
   mjWarningStat warning[mjNWARNING];  // warning statistics
@@ -179,12 +192,6 @@ struct mjData_ {
   int     solver_nnz[mjNISLAND];    // number of non-zeros in Hessian or efc_AR, per island
   mjtNum  solver_fwdinv[2];         // forward-inverse comparison: qfrc, efc
 
-  // collision statistics
-  int     nbodypair_broad;   // number of body pairs in collision according to the broad-phase
-  int     nbodypair_narrow;  // number of body pairs actually in collision in the narrow-phase
-  int     ngeompair_mid;     // number of geom pairs in collision according to the mid-phase
-  int     ngeompair_narrow;  // number of geom pairs actually in collision in the narrow-phase
-
   // variable sizes
   int     ne;                // number of equality constraints
   int     nf;                // number of friction constraints
@@ -217,6 +224,7 @@ struct mjData_ {
   mjtNum* ctrl;              // control                                          (nu x 1)
   mjtNum* qfrc_applied;      // applied generalized force                        (nv x 1)
   mjtNum* xfrc_applied;      // applied Cartesian force/torque                   (nbody x 6)
+  mjtByte* eq_active;        // enable/disable constraints                       (neq x 1)
 
   // mocap data
   mjtNum* mocap_pos;         // positions of mocap bodies                        (nmocap x 3)
@@ -233,8 +241,8 @@ struct mjData_ {
   mjtNum* sensordata;        // sensor data array                                (nsensordata x 1)
 
   // plugins
-  int*        plugin;        // copy of m->plugin, required for deletion         (nplugin x 1)
+  int*       plugin;         // copy of m->plugin, required for deletion         (nplugin x 1)
-  uintptr_t*  plugin_data;   // pointer to plugin-managed data structure         (nplugin x 1)
+  uintptr_t* plugin_data;    // pointer to plugin-managed data structure         (nplugin x 1)
 
   //-------------------- POSITION dependent
 
@@ -260,14 +268,23 @@ struct mjData_ {
   mjtNum* cdof;              // com-based motion axis of each dof                (nv x 6)
   mjtNum* cinert;            // com-based body inertia and mass                  (nbody x 10)
 
+  // computed by mj_fwdPosition/mj_flex
+  mjtNum* flexvert_xpos;     // Cartesian flex vertex positions                  (nflexvert x 3)
+  mjtNum* flexelem_aabb;     // flex element bounding boxes (center, size)       (nflexelem x 6)
+  int*    flexedge_J_rownnz; // number of non-zeros in Jacobian row              (nflexedge x 1)
+  int*    flexedge_J_rowadr; // row start address in colind array                (nflexedge x 1)
+  int*    flexedge_J_colind; // column indices in sparse Jacobian                (nflexedge x nv)
+  mjtNum* flexedge_J;        // flex edge Jacobian                               (nflexedge x nv)
+  mjtNum* flexedge_length;   // flex edge lengths                                (nflexedge x 1)
+
   // computed by mj_fwdPosition/mj_tendon
   int*    ten_wrapadr;       // start address of tendon's path                   (ntendon x 1)
   int*    ten_wrapnum;       // number of wrap points in path                    (ntendon x 1)
   int*    ten_J_rownnz;      // number of non-zeros in Jacobian row              (ntendon x 1)
   int*    ten_J_rowadr;      // row start address in colind array                (ntendon x 1)
   int*    ten_J_colind;      // column indices in sparse Jacobian                (ntendon x nv)
-  mjtNum* ten_length;        // tendon lengths                                   (ntendon x 1)
   mjtNum* ten_J;             // tendon Jacobian                                  (ntendon x nv)
+  mjtNum* ten_length;        // tendon lengths                                   (ntendon x 1)
   int*    wrap_obj;          // geom id; -1: site; -2: pulley                    (nwrap*2 x 1)
   mjtNum* wrap_xpos;         // Cartesian 3D points in all path                  (nwrap*2 x 3)
 
@@ -285,11 +302,13 @@ struct mjData_ {
   mjtNum* qLDiagSqrtInv;     // 1/sqrt(diag(D))                                  (nv x 1)
 
   // computed by mj_collisionTree
+  mjtNum*  bvh_aabb_dyn;     // global bounding box (center, size)               (nbvhdynamic x 6)
   mjtByte* bvh_active;       // volume has been added to collisions              (nbvh x 1)
 
   //-------------------- POSITION, VELOCITY dependent
 
   // computed by mj_fwdVelocity
+  mjtNum* flexedge_velocity; // flex edge velocities                             (nflexedge x 1)
   mjtNum* ten_velocity;      // tendon velocities                                (ntendon x 1)
   mjtNum* actuator_velocity; // actuator velocities                              (nu x 1)
 
@@ -308,8 +327,8 @@ struct mjData_ {
   mjtNum* subtree_angmom;    // angular momentum about subtree com               (nbody x 3)
 
   // computed by mj_Euler or mj_implicit
-  mjtNum*   qH;              // L'*D*L factorization of modified M               (nM x 1)
+  mjtNum* qH;                // L'*D*L factorization of modified M               (nM x 1)
-  mjtNum*   qHDiagInv;       // 1/diag(D) of modified M                          (nv x 1)
+  mjtNum* qHDiagInv;         // 1/diag(D) of modified M                          (nv x 1)
 
   // computed by mj_resetData
   int*    D_rownnz;          // non-zeros in each row                            (nv x 1)

include/mujoco/mjmodel.h

@@ -109,8 +109,10 @@ typedef enum mjtGeom_ {           // type of geometric shape
   mjGEOM_ARROW1,                  // arrow without wedges
   mjGEOM_ARROW2,                  // arrow in both directions
   mjGEOM_LINE,                    // line
+  mjGEOM_FLEX,                    // flex
   mjGEOM_SKIN,                    // skin
   mjGEOM_LABEL,                   // text label
+  mjGEOM_TRIANGLE,                // triangle connecting a frame
 
   mjGEOM_NONE         = 1001      // missing geom type
 } mjtGeom;
@@ -140,13 +142,6 @@ typedef enum mjtIntegrator_ {     // integrator mode
 } mjtIntegrator;
 
 
-typedef enum mjtCollision_ {      // collision mode for selecting geom pairs
-  mjCOL_ALL           = 0,        // test precomputed and dynamic pairs
-  mjCOL_PAIR,                     // test predefined pairs only
-  mjCOL_DYNAMIC                   // test dynamic pairs only
-} mjtCollision;
-
-
 typedef enum mjtCone_ {           // type of friction cone
   mjCONE_PYRAMIDAL     = 0,       // pyramidal
   mjCONE_ELLIPTIC                 // elliptic
@@ -172,6 +167,7 @@ typedef enum mjtEq_ {             // type of equality constraint
   mjEQ_WELD,                      // fix relative position and orientation of two bodies
   mjEQ_JOINT,                     // couple the values of two scalar joints with cubic
   mjEQ_TENDON,                    // couple the lengths of two tendons with cubic
+  mjEQ_FLEX,                      // fix all edge lengths of a flex
   mjEQ_DISTANCE                   // unsupported, will cause an error if used
 } mjtEq;
 
@@ -234,6 +230,7 @@ typedef enum mjtObj_ {            // type of MujoCo object
   mjOBJ_SITE,                     // site
   mjOBJ_CAMERA,                   // camera
   mjOBJ_LIGHT,                    // light
+  mjOBJ_FLEX,                     // flex
   mjOBJ_MESH,                     // mesh
   mjOBJ_SKIN,                     // skin
   mjOBJ_HFIELD,                   // heightfield
@@ -359,6 +356,15 @@ typedef enum mjtLRMode_ {         // mode for actuator length range computation
 } mjtLRMode;
 
 
+typedef enum mjtFlexSelf_ {       // mode for flex selfcollide
+  mjFLEXSELF_NONE   = 0,          // no self-collisions
+  mjFLEXSELF_NARROW,              // skip midphase, go directly to narrowphase
+  mjFLEXSELF_BVH,                 // use BVH in midphase (if midphase enabled)
+  mjFLEXSELF_SAP,                 // use SAP in midphase
+  mjFLEXSELF_AUTO                 // choose between BVH and SAP automatically
+} mjtFlexSelf;
+
+
 //---------------------------------- mjLROpt -------------------------------------------------------
 
 struct mjLROpt_ {                 // options for mj_setLengthRange()
@@ -414,10 +420,10 @@ struct mjOption_ {                // physics options
   mjtNum o_margin;                // margin
   mjtNum o_solref[mjNREF];        // solref
   mjtNum o_solimp[mjNIMP];        // solimp
+  mjtNum o_friction[5];           // friction
 
   // discrete settings
   int integrator;                 // integration mode (mjtIntegrator)
-  int collision;                  // collision mode (mjtCollision)
   int cone;                       // type of friction cone (mjtCone)
   int jacobian;                   // type of Jacobian (mjtJacobian)
   int solver;                     // solver algorithm (mjtSolver)
@@ -446,9 +452,9 @@ struct mjVisual_ {                // visualization options
     float linewidth;              // line width for wireframe and ray rendering
     float glow;                   // glow coefficient for selected body
     float realtime;               // initial real-time factor (1: real time)
-    int offwidth;                 // width of offscreen buffer
+    int   offwidth;               // width of offscreen buffer
-    int offheight;                // height of offscreen buffer
+    int   offheight;              // height of offscreen buffer
-    int ellipsoidinertia;         // geom for inertia visualization (0: box, 1: ellipsoid)
+    int   ellipsoidinertia;       // geom for inertia visualization (0: box, 1: ellipsoid)
   } global;
 
   struct {                        // rendering quality
@@ -552,12 +558,22 @@ struct mjModel_ {
   int nu;                         // number of actuators/controls = dim(ctrl)
   int na;                         // number of activation states = dim(act)
   int nbody;                      // number of bodies
-  int nbvh;                       // number of bounding volumes in all bodies
+  int nbvh;                       // number of total bounding volumes in all bodies
+  int nbvhstatic;                 // number of static bounding volumes (aabb stored in mjModel)
+  int nbvhdynamic;                // number of dynamic bounding volumes (aabb stored in mjData)
   int njnt;                       // number of joints
   int ngeom;                      // number of geoms
   int nsite;                      // number of sites
   int ncam;                       // number of cameras
   int nlight;                     // number of lights
+  int nflex;                      // number of flexes
+  int nflexvert;                  // number of vertices in all flexes
+  int nflexedge;                  // number of edges in all flexes
+  int nflexelem;                  // number of elements in all flexes
+  int nflexelemdata;              // number of element vertex ids in all flexes
+  int nflexshelldata;             // number of shell fragment vertex ids in all flexes
+  int nflexevpair;                // number of element-vertex pairs in all flexes
+  int nflextexcoord;              // number of vertices with texture coordinates
   int nmesh;                      // number of meshes
   int nmeshvert;                  // number of vertices in all meshes
   int nmeshnormal;                // number of normals in all meshes
@@ -601,6 +617,7 @@ struct mjModel_ {
   int nuser_sensor;               // number of mjtNums in sensor_user
   int nnames;                     // number of chars in all names
   int nnames_map;                 // number of slots in the names hash map
+  int npaths;                     // number of chars in all paths
 
   // sizes set after mjModel construction (only affect mjData)
   int nM;                         // number of non-zeros in sparse inertia matrix
@@ -644,7 +661,7 @@ struct mjModel_ {
   int*      body_treeid;          // id of body's kinematic tree; -1: static  (nbody x 1)
   int*      body_geomnum;         // number of geoms                          (nbody x 1)
   int*      body_geomadr;         // start addr of geoms; -1: no geoms        (nbody x 1)
-  mjtByte*  body_simple;          // body is simple (has diagonal M)          (nbody x 1)
+  mjtByte*  body_simple;          // 1: diagonal M; 2: diag M, no rotations   (nbody x 1)
   mjtByte*  body_sameframe;       // inertial frame is same as body frame     (nbody x 1)
   mjtNum*   body_pos;             // position offset rel. to parent body      (nbody x 3)
   mjtNum*   body_quat;            // orientation offset rel. to parent body   (nbody x 4)
@@ -655,16 +672,19 @@ struct mjModel_ {
   mjtNum*   body_inertia;         // diagonal inertia in ipos/iquat frame     (nbody x 3)
   mjtNum*   body_invweight0;      // mean inv inert in qpos0 (trn, rot)       (nbody x 2)
   mjtNum*   body_gravcomp;        // antigravity force, units of body weight  (nbody x 1)
+  mjtNum*   body_margin;          // MAX over all geom margins                (nbody x 1)
   mjtNum*   body_user;            // user data                                (nbody x nuser_body)
   int*      body_plugin;          // plugin instance id; -1: not in use       (nbody x 1)
+  int*      body_contype;         // OR over all geom contypes                (nbody x 1)
+  int*      body_conaffinity;     // OR over all geom conaffinities           (nbody x 1)
   int*      body_bvhadr;          // address of bvh root                      (nbody x 1)
   int*      body_bvhnum;          // number of bounding volumes               (nbody x 1)
 
   // bounding volume hierarchy
   int*      bvh_depth;            // depth in the bounding volume hierarchy   (nbvh x 1)
   int*      bvh_child;            // left and right children in tree          (nbvh x 2)
-  int*      bvh_geomid;           // geom id of the node; -1: non-leaf        (nbvh x 1)
+  int*      bvh_nodeid;           // geom or elem id of node; -1: non-leaf    (nbvh x 1)
-  mjtNum*   bvh_aabb;             // bounding box of node (center, size)      (nbvh x 6)
+  mjtNum*   bvh_aabb;             // local bounding box (center, size)        (nbvhstatic x 6)
 
   // joints
   int*      jnt_type;             // type of joint (mjtJoint)                 (njnt x 1)
@@ -749,6 +769,8 @@ struct mjModel_ {
   mjtNum*   cam_mat0;             // global orientation in qpos0              (ncam x 9)
   int*      cam_resolution;       // [width, height] in pixels                (ncam x 2)
   mjtNum*   cam_fovy;             // y-field of view (deg)                    (ncam x 1)
+  float*    cam_intrinsic;        // [focal length; principal point]          (ncam x 4)
+  float*    cam_sensorsize;       // sensor size                              (ncam x 2)
   mjtNum*   cam_ipd;              // inter-pupilary distance                  (ncam x 1)
   mjtNum*   cam_user;             // user data                                (ncam x nuser_cam)
 
@@ -771,6 +793,59 @@ struct mjModel_ {
   float*    light_diffuse;        // diffuse rgb (alpha=1)                    (nlight x 3)
   float*    light_specular;       // specular rgb (alpha=1)                   (nlight x 3)
 
+  // flexes: contact properties
+  int*      flex_contype;         // flex contact type                        (nflex x 1)
+  int*      flex_conaffinity;     // flex contact affinity                    (nflex x 1)
+  int*      flex_condim;          // contact dimensionality (1, 3, 4, 6)      (nflex x 1)
+  int*      flex_priority;        // flex contact priority                    (nflex x 1)
+  mjtNum*   flex_solmix;          // mix coef for solref/imp in contact pair  (nflex x 1)
+  mjtNum*   flex_solref;          // constraint solver reference: contact     (nflex x mjNREF)
+  mjtNum*   flex_solimp;          // constraint solver impedance: contact     (nflex x mjNIMP)
+  mjtNum*   flex_friction;        // friction for (slide, spin, roll)         (nflex x 3)
+  mjtNum*   flex_margin;          // detect contact if dist<margin            (nflex x 1)
+  mjtNum*   flex_gap;             // include in solver if dist<margin-gap     (nflex x 1)
+  mjtByte*  flex_internal;        // internal flex collision enabled          (nflex x 1)
+  int*      flex_selfcollide;     // self collision mode (mjtFlexSelf)        (nflex x 1)
+  int*      flex_activelayers;    // number of active element layers, 3D only (nflex x 1)
+
+  // flexes: other properties
+  int*      flex_dim;             // 1: lines, 2: triangles, 3: tetrahedra    (nflex x 1)
+  int*      flex_matid;           // material id for rendering                (nflex x 1)
+  int*      flex_group;           // group for visibility                     (nflex x 1)
+  int*      flex_vertadr;         // first vertex address                     (nflex x 1)
+  int*      flex_vertnum;         // number of vertices                       (nflex x 1)
+  int*      flex_edgeadr;         // first edge address                       (nflex x 1)
+  int*      flex_edgenum;         // number of edges                          (nflex x 1)
+  int*      flex_elemadr;         // first element address                    (nflex x 1)
+  int*      flex_elemnum;         // number of elements                       (nflex x 1)
+  int*      flex_elemdataadr;     // first element vertex id address          (nflex x 1)
+  int*      flex_shellnum;        // number of shells                         (nflex x 1)
+  int*      flex_shelldataadr;    // first shell data address                 (nflex x 1)
+  int*      flex_evpairadr;       // first evpair address                     (nflex x 1)
+  int*      flex_evpairnum;       // number of evpairs                        (nflex x 1)
+  int*      flex_texcoordadr;     // address in flex_texcoord; -1: none       (nflex x 1)
+  int*      flex_vertbodyid;      // vertex body ids                          (nflexvert x 1)
+  int*      flex_edge;            // edge vertex ids (2 per edge)             (nflexedge x 2)
+  int*      flex_elem;            // element vertex ids (dim+1 per elem)      (nflexelemdata x 1)
+  int*      flex_elemlayer;       // element distance from surface, 3D only   (nflexelem x 1)
+  int*      flex_shell;           // shell fragment vertex ids (dim per frag) (nflexshelldata x 1)
+  int*      flex_evpair;          // (element, vertex) collision pairs        (nflexevpair x 2)
+  mjtNum*   flex_vert;            // vertex positions in local body frames    (nflexvert x 3)
+  mjtNum*   flex_xvert0;          // Cartesian vertex positions in qpos0      (nflexvert x 3)
+  mjtNum*   flexedge_length0;     // edge lengths in qpos0                    (nflexedge x 1)
+  mjtNum*   flexedge_invweight0;  // edge inv. weight in qpos0                (nflexedge x 1)
+  mjtNum*   flex_radius;          // radius around primitive element          (nflex x 1)
+  mjtNum*   flex_edgestiffness;   // edge stiffness                           (nflex x 1)
+  mjtNum*   flex_edgedamping;     // edge damping                             (nflex x 1)
+  mjtByte*  flex_edgeequality;    // is edge equality constraint defined      (nflex x 1)
+  mjtByte*  flex_rigid;           // are all verices in the same body         (nflex x 1)
+  mjtByte*  flex_centered;        // are all vertex coordinates (0,0,0)       (nflex x 1)
+  mjtByte*  flex_flatskin;        // render flex skin with flat shading       (nflex x 1)
+  int*      flex_bvhadr;          // address of bvh root; -1: no bvh          (nflex x 1)
+  int*      flex_bvhnum;          // number of bounding volumes               (nflex x 1)
+  float*    flex_rgba;            // rgba when material is omitted            (nflex x 4)
+  float*    flex_texcoord;        // vertex texture coordinates               (nflextexcoord x 2)
+
   // meshes
   int*      mesh_vertadr;         // first vertex address                     (nmesh x 1)
   int*      mesh_vertnum;         // number of vertices                       (nmesh x 1)
@@ -792,6 +867,7 @@ struct mjModel_ {
   int*      mesh_facenormal;      // normal face data                         (nmeshface x 3)
   int*      mesh_facetexcoord;    // texture face data                        (nmeshface x 3)
   int*      mesh_graph;           // convex graph data                        (nmeshgraph x 1)
+  int*      mesh_pathadr;         // address of asset path for mesh; -1: none (nmesh x 1)
 
   // skins
   int*      skin_matid;           // skin material id; -1: none               (nskin x 1)
@@ -844,7 +920,7 @@ struct mjModel_ {
   int*      pair_dim;             // contact dimensionality                   (npair x 1)
   int*      pair_geom1;           // id of geom1                              (npair x 1)
   int*      pair_geom2;           // id of geom2                              (npair x 1)
-  int*      pair_signature;       // (body1+1) << 16 + body2+1                (npair x 1)
+  int*      pair_signature;       // body1 << 16 + body2                      (npair x 1)
   mjtNum*   pair_solref;          // solver reference: contact normal         (npair x mjNREF)
   mjtNum*   pair_solreffriction;  // solver reference: contact friction       (npair x mjNREF)
   mjtNum*   pair_solimp;          // solver impedance: contact                (npair x mjNIMP)
@@ -853,13 +929,13 @@ struct mjModel_ {
   mjtNum*   pair_friction;        // tangent1, 2, spin, roll1, 2              (npair x 5)
 
   // excluded body pairs for collision detection
-  int*      exclude_signature;    // (body1+1) << 16 + body2+1                (nexclude x 1)
+  int*      exclude_signature;    // body1 << 16 + body2                      (nexclude x 1)
 
   // equality constraints
   int*      eq_type;              // constraint type (mjtEq)                  (neq x 1)
   int*      eq_obj1id;            // id of object 1                           (neq x 1)
   int*      eq_obj2id;            // id of object 2                           (neq x 1)
-  mjtByte*  eq_active;            // enable/disable constraint                (neq x 1)
+  mjtByte*  eq_active0;           // initial enable/disable constraint state  (neq x 1)
   mjtNum*   eq_solref;            // constraint solver reference              (neq x mjNREF)
   mjtNum*   eq_solimp;            // constraint solver impedance              (neq x mjNIMP)
   mjtNum*   eq_data;              // numeric data for constraint              (neq x mjNEQDATA)
@@ -973,6 +1049,7 @@ struct mjModel_ {
   int*      name_siteadr;         // site name pointers                       (nsite x 1)
   int*      name_camadr;          // camera name pointers                     (ncam x 1)
   int*      name_lightadr;        // light name pointers                      (nlight x 1)
+  int*      name_flexadr;         // flex name pointers                       (nflex x 1)
   int*      name_meshadr;         // mesh name pointers                       (nmesh x 1)
   int*      name_skinadr;         // skin name pointers                       (nskin x 1)
   int*      name_hfieldadr;       // hfield name pointers                     (nhfield x 1)
@@ -991,6 +1068,9 @@ struct mjModel_ {
   int*      name_pluginadr;       // plugin instance name pointers            (nplugin x 1)
   char*     names;                // names of all objects, 0-terminated       (nnames x 1)
   int*      names_map;            // internal hash map of names               (nnames_map x 1)
+
+  // paths
+  char*     paths;                // paths to assets, 0-terminated            (npaths x 1)
 };
 typedef struct mjModel_ mjModel;
 

include/mujoco/mjrender.h

@@ -30,7 +30,11 @@ typedef enum mjtGridPos_ {        // grid position for overlay
   mjGRID_TOPLEFT      = 0,        // top left
   mjGRID_TOPRIGHT,                // top right
   mjGRID_BOTTOMLEFT,              // bottom left
-  mjGRID_BOTTOMRIGHT              // bottom right
+  mjGRID_BOTTOMRIGHT,             // bottom right
+  mjGRID_TOP,                     // top center
+  mjGRID_BOTTOM,                  // bottom center
+  mjGRID_LEFT,                    // left center
+  mjGRID_RIGHT                    // right center
 } mjtGridPos;
 
 
@@ -39,6 +43,10 @@ typedef enum mjtFramebuffer_ {    // OpenGL framebuffer option
   mjFB_OFFSCREEN                  // offscreen buffer
 } mjtFramebuffer;
 
+typedef enum mjtDepthMap_ {       // depth mapping for `mjr_readPixels`
+  mjDEPTH_ZERONEAR    = 0,        // standard depth map; 0: znear, 1: zfar
+  mjDEPTH_ZEROFAR     = 1         // reversed depth map; 1: znear, 0: zfar
+} mjtDepthMap;
 
 typedef enum mjtFontScale_ {      // font scale, used at context creation
   mjFONTSCALE_50      = 50,       // 50% scale, suitable for low-res rendering
@@ -151,6 +159,9 @@ struct mjrContext_ {              // custom OpenGL context
 
   // pixel output format
   int     readPixelFormat;        // default color pixel format for mjr_readPixels
+
+  // depth output format
+  int     readDepthMap;           // depth mapping: mjDEPTH_ZERONEAR or mjDEPTH_ZEROFAR
 };
 typedef struct mjrContext_ mjrContext;
 

include/mujoco/mjthread.h

@@ -15,6 +15,8 @@
 #ifndef MUJOCO_INCLUDE_MJTHREAD_H_
 #define MUJOCO_INCLUDE_MJTHREAD_H_
 
+#define mjMAXTHREADS 128       // maximum number of threads in a thread pool
+
 typedef enum mjtTaskStatus_ {  // status values for mjTask
   mjTASK_NEW = 0,              // newly created
   mjTASK_QUEUED,               // enqueued in a thread pool

include/mujoco/mjvisualize.h

@@ -74,6 +74,7 @@ typedef enum mjtLabel_ {          // object labeling
   mjLABEL_TENDON,                 // tendon labels
   mjLABEL_ACTUATOR,               // actuator labels
   mjLABEL_CONSTRAINT,             // constraint labels
+  mjLABEL_FLEX,                   // flex labels
   mjLABEL_SKIN,                   // skin labels
   mjLABEL_SELECTION,              // selected object
   mjLABEL_SELPNT,                 // coordinates of selection point
@@ -124,7 +125,12 @@ typedef enum mjtVisFlag_ {        // flags enabling model element visualization
   mjVIS_SELECT,                   // selection point
   mjVIS_STATIC,                   // static bodies
   mjVIS_SKIN,                     // skin
-  mjVIS_MIDPHASE,                 // mid-phase bounding volume hierarchy
+  mjVIS_FLEXVERT,                 // flex vertices
+  mjVIS_FLEXEDGE,                 // flex edges
+  mjVIS_FLEXFACE,                 // flex element faces
+  mjVIS_FLEXSKIN,                 // flex smooth skin (disables the rest)
+  mjVIS_BODYBVH,                  // body bounding volume hierarchy
+  mjVIS_FLEXBVH,                  // flex bounding volume hierarchy
   mjVIS_MESHBVH,                  // mesh bounding volume hierarchy
   mjVIS_SDFITER,                  // iterations of SDF gradient descent
 
@@ -159,6 +165,7 @@ typedef enum mjtStereo_ {         // type of stereo rendering
 
 struct mjvPerturb_ {              // object selection and perturbation
   int      select;                // selected body id; non-positive: none
+  int      flexselect;            // selected flex id; negative: none
   int      skinselect;            // selected skin id; negative: none
   int      active;                // perturbation bitmask (mjtPertBit)
   int      active2;               // secondary perturbation bitmask (mjtPertBit)
@@ -199,6 +206,7 @@ struct mjvGLCamera_ {             // OpenGL camera
 
   // camera projection
   float    frustum_center;        // hor. center (left,right set to match aspect)
+  float    frustum_width;         // width (not used for rendering)
   float    frustum_bottom;        // bottom
   float    frustum_top;           // top
   float    frustum_near;          // near
@@ -218,7 +226,7 @@ struct mjvGeom_ {                 // abstract geom
   int      category;              // visual category
   int      texid;                 // texture id; -1: no texture
   int      texuniform;            // uniform cube mapping
-  int      texcoord;              // mesh geom has texture coordinates
+  int      texcoord;              // mesh or flex geom has texture coordinates
   int      segid;                 // segmentation id; -1: not shown
 
   // OpenGL info
@@ -269,9 +277,11 @@ struct mjvOption_ {                  // abstract visualization options
   mjtByte  jointgroup[mjNGROUP];     // joint visualization by group
   mjtByte  tendongroup[mjNGROUP];    // tendon visualization by group
   mjtByte  actuatorgroup[mjNGROUP];  // actuator visualization by group
+  mjtByte  flexgroup[mjNGROUP];      // flex visualization by group
   mjtByte  skingroup[mjNGROUP];      // skin visualization by group
   mjtByte  flags[mjNVISFLAG];        // visualization flags (indexed by mjtVisFlag)
-  int bvh_depth;                     // depth of the bounding volume hierarchy to be visualized
+  int      bvh_depth;                // depth of the bounding volume hierarchy to be visualized
+  int      flex_layer;               // element layer to be visualized for 3D flex
 };
 typedef struct mjvOption_ mjvOption;
 
@@ -285,13 +295,32 @@ struct mjvScene_ {                // abstract scene passed to OpenGL renderer
   mjvGeom* geoms;                 // buffer for geoms (ngeom)
   int*     geomorder;             // buffer for ordering geoms by distance to camera (ngeom)
 
+  // flex data
+  int      nflex;                 // number of flexes
+  int*     flexedgeadr;           // address of flex edges (nflex)
+  int*     flexedgenum;           // number of edges in flex (nflex)
+  int*     flexvertadr;           // address of flex vertices (nflex)
+  int*     flexvertnum;           // number of vertices in flex (nflex)
+  int*     flexfaceadr;           // address of flex faces (nflex)
+  int*     flexfacenum;           // number of flex faces allocated (nflex)
+  int*     flexfaceused;          // number of flex faces currently in use (nflex)
+  int*     flexedge;              // flex edge data (2*nflexedge)
+  float*   flexvert;              // flex vertices (3*nflexvert)
+  float*   flexface;              // flex faces vertices (9*sum(flexfacenum))
+  float*   flexnormal;            // flex face normals (9*sum(flexfacenum))
+  float*   flextexcoord;          // flex face texture coordinates (6*sum(flexfacenum))
+  mjtByte  flexvertopt;           // copy of mjVIS_FLEXVERT mjvOption flag
+  mjtByte  flexedgeopt;           // copy of mjVIS_FLEXEDGE mjvOption flag
+  mjtByte  flexfaceopt;           // copy of mjVIS_FLEXFACE mjvOption flag
+  mjtByte  flexskinopt;           // copy of mjVIS_FLEXSKIN mjvOption flag
+
   // skin data
   int      nskin;                 // number of skins
   int*     skinfacenum;           // number of faces in skin (nskin)
   int*     skinvertadr;           // address of skin vertices (nskin)
   int*     skinvertnum;           // number of vertices in skin (nskin)
-  float*   skinvert;              // skin vertex data (nskin)
+  float*   skinvert;              // skin vertex data (3*nskinvert)
-  float*   skinnormal;            // skin normal data (nskin)
+  float*   skinnormal;            // skin normal data (3*nskinvert)
 
   // OpenGL lights
   int      nlight;                // number of lights currently in buffer
@@ -374,7 +403,7 @@ struct mjvSceneState_ {
   int nbuffer;                     // size of the buffer in bytes
   void* buffer;                    // heap-allocated memory for all arrays in this struct
   int maxgeom;                     // maximum number of mjvGeom supported by this state object
-  mjvScene plugincache;            // scratch space for vis geoms inserted by plugins
+  mjvScene scratch;                // scratch space for vis geoms inserted by the user and plugins
 
   // fields in mjModel that are necessary to re-render a scene
   struct {
@@ -383,6 +412,7 @@ struct mjvSceneState_ {
     int na;
     int nbody;
     int nbvh;
+    int nbvhstatic;
     int njnt;
     int ngeom;
     int nsite;
@@ -390,6 +420,8 @@ struct mjvSceneState_ {
     int nlight;
     int nmesh;
     int nskin;
+    int nflex;
+    int nflexvert;
     int nskinvert;
     int nskinface;
     int nskinbone;
@@ -401,6 +433,7 @@ struct mjvSceneState_ {
     int nwrap;
     int nsensor;
     int nnames;
+    int npaths;
     int nsensordata;
 
     mjOption opt;
@@ -425,7 +458,7 @@ struct mjvSceneState_ {
 
     int* bvh_depth;
     int* bvh_child;
-    int* bvh_geomid;
+    int* bvh_nodeid;
     mjtNum* bvh_aabb;
 
     int* jnt_type;
@@ -453,6 +486,7 @@ struct mjvSceneState_ {
 
     mjtNum* cam_fovy;
     mjtNum* cam_ipd;
+    float* cam_sensorsize;
 
     mjtByte* light_directional;
     mjtByte* light_castshadow;
@@ -464,10 +498,29 @@ struct mjvSceneState_ {
     float* light_diffuse;
     float* light_specular;
 
+    mjtByte* flex_flatskin;
+    int* flex_dim;
+    int* flex_matid;
+    int* flex_group;
+    int* flex_vertadr;
+    int* flex_vertnum;
+    int* flex_elem;
+    int* flex_elemadr;
+    int* flex_elemnum;
+    int* flex_elemdataadr;
+    int* flex_shell;
+    int* flex_shellnum;
+    int* flex_shelldataadr;
+    int* flex_bvhadr;
+    int* flex_bvhnum;
+    mjtNum* flex_radius;
+    float* flex_rgba;
+
     int* mesh_bvhadr;
     int* mesh_bvhnum;
     int* mesh_texcoordadr;
     int* mesh_graphadr;
+    int* mesh_pathadr;
 
     int* skin_matid;
     int* skin_group;
@@ -502,7 +555,6 @@ struct mjvSceneState_ {
     int* eq_type;
     int* eq_obj1id;
     int* eq_obj2id;
-    mjtByte* eq_active;
     mjtNum* eq_data;
 
     int* tendon_num;
@@ -543,6 +595,7 @@ struct mjvSceneState_ {
     int* name_tendonadr;
     int* name_actuatoradr;
     char* names;
+    char* paths;
   } model;
 
   // fields in mjData that are necessary to re-render a scene
@@ -559,6 +612,7 @@ struct mjvSceneState_ {
 
     mjtNum* ctrl;
     mjtNum* xfrc_applied;
+    mjtByte* eq_active;
 
     mjtNum* sensordata;
 
@@ -593,6 +647,8 @@ struct mjvSceneState_ {
     int* efc_island;
     int* tendon_efcadr;
 
+    mjtNum* flexvert_xpos;
+
     mjContact* contact;
     mjtNum* efc_force;
   } data;

include/mujoco/mjxmacro.h

@@ -34,7 +34,6 @@
 
 #define MJOPTION_INTS               \
     X( int,     integrator        ) \
-    X( int,     collision         ) \
     X( int,     cone              ) \
     X( int,     jacobian          ) \
     X( int,     solver            ) \
@@ -59,7 +58,8 @@
     X( wind,            3       )   \
     X( magnetic,        3       )   \
     X( o_solref,        mjNREF  )   \
-    X( o_solimp,        mjNIMP  )
+    X( o_solimp,        mjNIMP  )   \
+    X( o_friction,      5       )
 
 
 //-------------------------------- mjModel ---------------------------------------------------------
@@ -72,11 +72,21 @@
     XMJV( na )                 \
     XMJV( nbody )              \
     XMJV( nbvh )               \
+    XMJV( nbvhstatic )         \
+    X   ( nbvhdynamic )        \
     XMJV( njnt )               \
     XMJV( ngeom )              \
     XMJV( nsite )              \
     XMJV( ncam )               \
     XMJV( nlight )             \
+    XMJV( nflex )              \
+    XMJV( nflexvert )          \
+    X   ( nflexedge )          \
+    X   ( nflexelem )          \
+    X   ( nflexelemdata )      \
+    X   ( nflexshelldata )     \
+    X   ( nflexevpair )        \
+    X   ( nflextexcoord )      \
     XMJV( nmesh )              \
     X   ( nmeshvert )          \
     X   ( nmeshnormal )        \
@@ -119,6 +129,7 @@
     X   ( nuser_actuator )     \
     X   ( nuser_sensor )       \
     XMJV( nnames )             \
+    XMJV( npaths )             \
     X   ( nnames_map )         \
     X   ( nM )                 \
     X   ( nD )                 \
@@ -133,6 +144,8 @@
     X   ( narena )             \
     X   ( nbuffer )
 
+    /* nbuffer needs to be the final field */
+
 
 // define symbols needed in MJMODEL_POINTERS (corresponding to number of columns)
 #define MJMODEL_POINTERS_PREAMBLE( m )      \
@@ -183,14 +196,17 @@
     XMJV( mjtNum,  body_inertia,          nbody,         3                    ) \
     X   ( mjtNum,  body_invweight0,       nbody,         2                    ) \
     X   ( mjtNum,  body_gravcomp,         nbody,         1                    ) \
+    X   ( mjtNum,  body_margin,           nbody,         1                    ) \
     X   ( mjtNum,  body_user,             nbody,         MJ_M(nuser_body)     ) \
     X   ( int,     body_plugin,           nbody,         1                    ) \
+    X   ( int,     body_contype,          nbody,         1                    ) \
+    X   ( int,     body_conaffinity,      nbody,         1                    ) \
     XMJV( int,     body_bvhadr,           nbody,         1                    ) \
     XMJV( int,     body_bvhnum,           nbody,         1                    ) \
     XMJV( int,     bvh_depth,             nbvh,          1                    ) \
     XMJV( int,     bvh_child,             nbvh,          2                    ) \
-    XMJV( int,     bvh_geomid,            nbvh,          1                    ) \
+    XMJV( int,     bvh_nodeid,            nbvh,          1                    ) \
-    XMJV( mjtNum,  bvh_aabb,              nbvh,          6                    ) \
+    XMJV( mjtNum,  bvh_aabb,              nbvhstatic,    6                    ) \
     XMJV( int,     jnt_type,              njnt,          1                    ) \
     X   ( int,     jnt_qposadr,           njnt,          1                    ) \
     X   ( int,     jnt_dofadr,            njnt,          1                    ) \
@@ -259,6 +275,8 @@
     X   ( int,     cam_bodyid,            ncam,          1                    ) \
     X   ( int,     cam_targetbodyid,      ncam,          1                    ) \
     X   ( int,     cam_resolution,        ncam,          2                    ) \
+    XMJV( float,   cam_sensorsize,        ncam,          2                    ) \
+    X   ( float,   cam_intrinsic,         ncam,          4                    ) \
     X   ( mjtNum,  cam_pos,               ncam,          3                    ) \
     X   ( mjtNum,  cam_quat,              ncam,          4                    ) \
     X   ( mjtNum,  cam_poscom0,           ncam,          3                    ) \
@@ -284,6 +302,55 @@
     XMJV( float,   light_ambient,         nlight,        3                    ) \
     XMJV( float,   light_diffuse,         nlight,        3                    ) \
     XMJV( float,   light_specular,        nlight,        3                    ) \
+    X   ( int,     flex_contype,          nflex,         1                    ) \
+    X   ( int,     flex_conaffinity,      nflex,         1                    ) \
+    X   ( int,     flex_condim,           nflex,         1                    ) \
+    X   ( int,     flex_priority,         nflex,         1                    ) \
+    X   ( mjtNum,  flex_solmix,           nflex,         1                    ) \
+    X   ( mjtNum,  flex_solref,           nflex,         mjNREF               ) \
+    X   ( mjtNum,  flex_solimp,           nflex,         mjNIMP               ) \
+    X   ( mjtNum,  flex_friction,         nflex,         3                    ) \
+    X   ( mjtNum,  flex_margin,           nflex,         1                    ) \
+    X   ( mjtNum,  flex_gap,              nflex,         1                    ) \
+    X   ( mjtByte, flex_internal,         nflex,         1                    ) \
+    X   ( int,     flex_selfcollide,      nflex,         1                    ) \
+    X   ( int,     flex_activelayers,     nflex,         1                    ) \
+    XMJV( int,     flex_dim,              nflex,         1                    ) \
+    XMJV( int,     flex_matid,            nflex,         1                    ) \
+    XMJV( int,     flex_group,            nflex,         1                    ) \
+    XMJV( int,     flex_vertadr,          nflex,         1                    ) \
+    XMJV( int,     flex_vertnum,          nflex,         1                    ) \
+    X   ( int,     flex_edgeadr,          nflex,         1                    ) \
+    X   ( int,     flex_edgenum,          nflex,         1                    ) \
+    XMJV( int,     flex_elemadr,          nflex,         1                    ) \
+    XMJV( int,     flex_elemnum,          nflex,         1                    ) \
+    XMJV( int,     flex_elemdataadr,      nflex,         1                    ) \
+    XMJV( int,     flex_shellnum,         nflex,         1                    ) \
+    XMJV( int,     flex_shelldataadr,     nflex,         1                    ) \
+    X   ( int,     flex_evpairadr,        nflex,         1                    ) \
+    X   ( int,     flex_evpairnum,        nflex,         1                    ) \
+    X   ( int,     flex_texcoordadr,      nflex,         1                    ) \
+    X   ( int,     flex_vertbodyid,       nflexvert,     1                    ) \
+    X   ( int,     flex_edge,             nflexedge,     2                    ) \
+    XMJV( int,     flex_elem,             nflexelemdata, 1                    ) \
+    X   ( int,     flex_elemlayer,        nflexelem,     1                    ) \
+    XMJV( int,     flex_shell,            nflexshelldata,1                    ) \
+    X   ( int,     flex_evpair,           nflexevpair,   2                    ) \
+    X   ( mjtNum,  flex_vert,             nflexvert,     3                    ) \
+    X   ( mjtNum,  flex_xvert0,           nflexvert,     3                    ) \
+    X   ( mjtNum,  flexedge_length0,      nflexedge,     1                    ) \
+    X   ( mjtNum,  flexedge_invweight0,   nflexedge,     1                    ) \
+    XMJV( mjtNum,  flex_radius,           nflex,         1                    ) \
+    X   ( mjtNum,  flex_edgestiffness,    nflex,         1                    ) \
+    X   ( mjtNum,  flex_edgedamping,      nflex,         1                    ) \
+    X   ( mjtByte, flex_edgeequality,     nflex,         1                    ) \
+    X   ( mjtByte, flex_rigid,            nflex,         1                    ) \
+    X   ( mjtByte, flex_centered,         nflex,         1                    ) \
+    XMJV( mjtByte, flex_flatskin,         nflex,         1                    ) \
+    XMJV( int,     flex_bvhadr,           nflex,         1                    ) \
+    XMJV( int,     flex_bvhnum,           nflex,         1                    ) \
+    XMJV( float,   flex_rgba,             nflex,         4                    ) \
+    X   ( float,   flex_texcoord,         nflextexcoord, 2                    ) \
     X   ( int,     mesh_vertadr,          nmesh,         1                    ) \
     X   ( int,     mesh_vertnum,          nmesh,         1                    ) \
     X   ( int,     mesh_normaladr,        nmesh,         1                    ) \
@@ -304,6 +371,7 @@
     X   ( int,     mesh_facenormal,       nmeshface,     3                    ) \
     X   ( int,     mesh_facetexcoord,     nmeshface,     3                    ) \
     X   ( int,     mesh_graph,            nmeshgraph,    1                    ) \
+    XMJV( int,     mesh_pathadr,          nmesh,         1                    ) \
     XMJV( int,     skin_matid,            nskin,         1                    ) \
     XMJV( int,     skin_group,            nskin,         1                    ) \
     XMJV( float,   skin_rgba,             nskin,         4                    ) \
@@ -357,7 +425,7 @@
     XMJV( int,     eq_type,               neq,           1                    ) \
     XMJV( int,     eq_obj1id,             neq,           1                    ) \
     XMJV( int,     eq_obj2id,             neq,           1                    ) \
-    XMJV( mjtByte, eq_active,             neq,           1                    ) \
+    X   ( mjtByte, eq_active0,            neq,           1                    ) \
     X   ( mjtNum,  eq_solref,             neq,           mjNREF               ) \
     X   ( mjtNum,  eq_solimp,             neq,           mjNIMP               ) \
     XMJV( mjtNum,  eq_data,               neq,           mjNEQDATA            ) \
@@ -451,6 +519,7 @@
     XMJV( int,     name_siteadr,          nsite,         1                    ) \
     XMJV( int,     name_camadr,           ncam,          1                    ) \
     XMJV( int,     name_lightadr,         nlight,        1                    ) \
+    X   ( int,     name_flexadr,          nflex,         1                    ) \
     X   ( int,     name_meshadr,          nmesh,         1                    ) \
     X   ( int,     name_skinadr,          nskin,         1                    ) \
     X   ( int,     name_hfieldadr,        nhfield,       1                    ) \
@@ -469,6 +538,7 @@
     X   ( int,     name_pluginadr,        nplugin,       1                    ) \
     XMJV( char,    names,                 nnames,        1                    ) \
     X   ( int,     names_map,             nnames_map,    1                    ) \
+    XMJV( char,    paths,                 npaths,        1                    ) \
 
 //-------------------------------- mjData ----------------------------------------------------------
 
@@ -489,6 +559,7 @@
     XMJV( mjtNum,    ctrl,              nu,          1           ) \
     X   ( mjtNum,    qfrc_applied,      nv,          1           ) \
     XMJV( mjtNum,    xfrc_applied,      nbody,       6           ) \
+    XMJV( mjtByte,   eq_active,         neq,         1           ) \
     X   ( mjtNum,    mocap_pos,         nmocap,      3           ) \
     X   ( mjtNum,    mocap_quat,        nmocap,      4           ) \
     X   ( mjtNum,    qacc,              nv,          1           ) \
@@ -515,6 +586,13 @@
     XMJV( mjtNum,    subtree_com,       nbody,       3           ) \
     X   ( mjtNum,    cdof,              nv,          6           ) \
     X   ( mjtNum,    cinert,            nbody,       10          ) \
+    XMJV( mjtNum,    flexvert_xpos,     nflexvert,   3           ) \
+    X   ( mjtNum,    flexelem_aabb,     nflexelem,   6           ) \
+    X   ( int,       flexedge_J_rownnz, nflexedge,   1           ) \
+    X   ( int,       flexedge_J_rowadr, nflexedge,   1           ) \
+    X   ( int,       flexedge_J_colind, nflexedge,   MJ_M(nv)    ) \
+    X   ( mjtNum,    flexedge_J,        nflexedge,   MJ_M(nv)    ) \
+    X   ( mjtNum,    flexedge_length,   nflexedge,   1           ) \
     XMJV( int,       ten_wrapadr,       ntendon,     1           ) \
     XMJV( int,       ten_wrapnum,       ntendon,     1           ) \
     X   ( int,       ten_J_rownnz,      ntendon,     1           ) \
@@ -531,7 +609,9 @@
     X   ( mjtNum,    qLD,               nM,          1           ) \
     X   ( mjtNum,    qLDiagInv,         nv,          1           ) \
     X   ( mjtNum,    qLDiagSqrtInv,     nv,          1           ) \
+    X   ( mjtNum,    bvh_aabb_dyn,      nbvhdynamic, 6           ) \
     XMJV( mjtByte,   bvh_active,        nbvh,        1           ) \
+    X   ( mjtNum,    flexedge_velocity, nflexedge,   1           ) \
     X   ( mjtNum,    ten_velocity,      ntendon,     1           ) \
     X   ( mjtNum,    actuator_velocity, nu,          1           ) \
     X   ( mjtNum,    cvel,              nbody,       6           ) \
@@ -637,10 +717,6 @@
     X( int,       maxuse_con         ) \
     X( int,       maxuse_efc         ) \
     X( int,       solver_nisland     ) \
-    X( int,       nbodypair_broad    ) \
-    X( int,       nbodypair_narrow   ) \
-    X( int,       ngeompair_mid      ) \
-    X( int,       ngeompair_narrow   ) \
     X( int,       ne                 ) \
     X( int,       nf                 ) \
     X( int,       nl                 ) \
@@ -653,14 +729,15 @@
 
 
 // vector fields of mjData
-#define MJDATA_VECTOR                                              \
+#define MJDATA_VECTOR                                                \
-    X( mjWarningStat,  warning,           mjNWARNING,  1         ) \
+    X( size_t,         maxuse_threadstack, mjMAXTHREADS, 1         ) \
-    X( mjTimerStat,    timer,             mjNTIMER,    1         ) \
+    X( mjWarningStat,  warning,            mjNWARNING,   1         ) \
-    X( mjSolverStat,   solver,            mjNILSAND,   mjNSOLVER ) \
+    X( mjTimerStat,    timer,              mjNTIMER,     1         ) \
-    X( int,            solver_niter,      mjNISLAND,   1         ) \
+    X( mjSolverStat,   solver,             mjNILSAND,    mjNSOLVER ) \
-    X( int,            solver_nnz,        mjNISLAND,   1         ) \
+    X( int,            solver_niter,       mjNISLAND,    1         ) \
-    X( mjtNum,         solver_fwdinv,     2,           1         ) \
+    X( int,            solver_nnz,         mjNISLAND,    1         ) \
-    X( mjtNum,         energy,            2,           1         )
+    X( mjtNum,         solver_fwdinv,      2,            1         ) \
+    X( mjtNum,         energy,             2,            1         )
 
 
 // alias XMJV to be the same as X

include/mujoco/mujoco.h

@@ -194,7 +194,7 @@ MJAPI void mj_freeStack(mjData* d);
 
 // Allocate a number of bytes on mjData stack at a specific alignment.
 // Call mju_error on stack overflow.
-MJAPI void* mj_stackAlloc(mjData* d, size_t bytes, size_t alignment);
+MJAPI void* mj_stackAllocByte(mjData* d, size_t bytes, size_t alignment);
 
 // Allocate array of mjtNums on mjData stack. Call mju_error on stack overflow.
 MJAPI mjtNum* mj_stackAllocNum(mjData* d, int size);
@@ -312,6 +312,9 @@ MJAPI void mj_comPos(const mjModel* m, mjData* d);
 // Compute camera and light positions and orientations.
 MJAPI void mj_camlight(const mjModel* m, mjData* d);
 
+// Compute flex-related quantities.
+MJAPI void mj_flex(const mjModel* m, mjData* d);
+
 // Compute tendon lengths, velocities and moment arms.
 MJAPI void mj_tendon(const mjModel* m, mjData* d);
 
@@ -518,6 +521,12 @@ MJAPI mjtNum mj_rayMesh(const mjModel* m, const mjData* d, int geomid,
 MJAPI mjtNum mju_rayGeom(const mjtNum pos[3], const mjtNum mat[9], const mjtNum size[3],
                          const mjtNum pnt[3], const mjtNum vec[3], int geomtype);
 
+// Intersect ray with flex, return nearest distance or -1 if no intersection,
+// and also output nearest vertex id.
+MJAPI mjtNum mju_rayFlex(const mjModel* m, const mjData* d, int flex_layer, mjtByte flg_vert,
+                         mjtByte flg_edge, mjtByte flg_face, mjtByte flg_skin, int flexid,
+                         const mjtNum* pnt, const mjtNum* vec, int vertid[1]);
+
 // Intersect ray with skin, return nearest distance or -1 if no intersection,
 // and also output nearest vertex id.
 MJAPI mjtNum mju_raySkin(int nface, int nvert, const int* face, const float* vert,
@@ -593,10 +602,11 @@ MJAPI void mjv_applyPerturbForce(const mjModel* m, mjData* d, const mjvPerturb*
 // Return the average of two OpenGL cameras.
 MJAPI mjvGLCamera mjv_averageCamera(const mjvGLCamera* cam1, const mjvGLCamera* cam2);
 
-// Select geom or skin with mouse, return bodyid; -1: none selected.
+// Select geom, flex or skin with mouse, return bodyid; -1: none selected.
 MJAPI int mjv_select(const mjModel* m, const mjData* d, const mjvOption* vopt,
                      mjtNum aspectratio, mjtNum relx, mjtNum rely,
-                     const mjvScene* scn, mjtNum selpnt[3], int geomid[1], int skinid[1]);
+                     const mjvScene* scn, mjtNum selpnt[3],
+                     int geomid[1], int flexid[1], int skinid[1]);
 
 
 //---------------------------------- Visualization -------------------------------------------------
@@ -1310,6 +1320,9 @@ MJAPI const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
 // Create a thread pool with the specified number of threads running.
 MJAPI mjThreadPool* mju_threadPoolCreate(size_t number_of_threads);
 
+// Adds a thread pool to mjData and configures it for multi-threaded use.
+MJAPI void mju_bindThreadPool(mjData* d, void* thread_pool);
+
 // Enqueue a task in a thread pool.
 MJAPI void mju_threadPoolEnqueue(mjThreadPool* thread_pool, mjTask* task);
 

introspect/enums.py

@@ -90,8 +90,10 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjGEOM_ARROW1', 101),
              ('mjGEOM_ARROW2', 102),
              ('mjGEOM_LINE', 103),
-             ('mjGEOM_SKIN', 104),
+             ('mjGEOM_FLEX', 104),
-             ('mjGEOM_LABEL', 105),
+             ('mjGEOM_SKIN', 105),
+             ('mjGEOM_LABEL', 106),
+             ('mjGEOM_TRIANGLE', 107),
              ('mjGEOM_NONE', 1001),
          ]),
      )),
@@ -128,16 +130,6 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjINT_IMPLICITFAST', 3),
          ]),
      )),
-    ('mjtCollision',
-     EnumDecl(
-         name='mjtCollision',
-         declname='enum mjtCollision_',
-         values=dict([
-             ('mjCOL_ALL', 0),
-             ('mjCOL_PAIR', 1),
-             ('mjCOL_DYNAMIC', 2),
-         ]),
-     )),
     ('mjtCone',
      EnumDecl(
          name='mjtCone',
@@ -176,7 +168,8 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjEQ_WELD', 1),
              ('mjEQ_JOINT', 2),
              ('mjEQ_TENDON', 3),
-             ('mjEQ_DISTANCE', 4),
+             ('mjEQ_FLEX', 4),
+             ('mjEQ_DISTANCE', 5),
          ]),
      )),
     ('mjtWrap',
@@ -255,22 +248,23 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjOBJ_SITE', 6),
              ('mjOBJ_CAMERA', 7),
              ('mjOBJ_LIGHT', 8),
-             ('mjOBJ_MESH', 9),
+             ('mjOBJ_FLEX', 9),
-             ('mjOBJ_SKIN', 10),
+             ('mjOBJ_MESH', 10),
-             ('mjOBJ_HFIELD', 11),
+             ('mjOBJ_SKIN', 11),
-             ('mjOBJ_TEXTURE', 12),
+             ('mjOBJ_HFIELD', 12),
-             ('mjOBJ_MATERIAL', 13),
+             ('mjOBJ_TEXTURE', 13),
-             ('mjOBJ_PAIR', 14),
+             ('mjOBJ_MATERIAL', 14),
-             ('mjOBJ_EXCLUDE', 15),
+             ('mjOBJ_PAIR', 15),
-             ('mjOBJ_EQUALITY', 16),
+             ('mjOBJ_EXCLUDE', 16),
-             ('mjOBJ_TENDON', 17),
+             ('mjOBJ_EQUALITY', 17),
-             ('mjOBJ_ACTUATOR', 18),
+             ('mjOBJ_TENDON', 18),
-             ('mjOBJ_SENSOR', 19),
+             ('mjOBJ_ACTUATOR', 19),
-             ('mjOBJ_NUMERIC', 20),
+             ('mjOBJ_SENSOR', 20),
-             ('mjOBJ_TEXT', 21),
+             ('mjOBJ_NUMERIC', 21),
-             ('mjOBJ_TUPLE', 22),
+             ('mjOBJ_TEXT', 22),
-             ('mjOBJ_KEY', 23),
+             ('mjOBJ_TUPLE', 23),
-             ('mjOBJ_PLUGIN', 24),
+             ('mjOBJ_KEY', 24),
+             ('mjOBJ_PLUGIN', 25),
          ]),
      )),
     ('mjtConstraint',
@@ -380,6 +374,28 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjLRMODE_ALL', 3),
          ]),
      )),
+    ('mjtFlexSelf',
+     EnumDecl(
+         name='mjtFlexSelf',
+         declname='enum mjtFlexSelf_',
+         values=dict([
+             ('mjFLEXSELF_NONE', 0),
+             ('mjFLEXSELF_NARROW', 1),
+             ('mjFLEXSELF_BVH', 2),
+             ('mjFLEXSELF_SAP', 3),
+             ('mjFLEXSELF_AUTO', 4),
+         ]),
+     )),
+    ('mjtTaskStatus',
+     EnumDecl(
+         name='mjtTaskStatus',
+         declname='enum mjtTaskStatus_',
+         values=dict([
+             ('mjTASK_NEW', 0),
+             ('mjTASK_QUEUED', 1),
+             ('mjTASK_COMPLETED', 2),
+         ]),
+     )),
     ('mjtState',
      EnumDecl(
          name='mjtState',
@@ -393,15 +409,16 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjSTATE_CTRL', 32),
              ('mjSTATE_QFRC_APPLIED', 64),
              ('mjSTATE_XFRC_APPLIED', 128),
-             ('mjSTATE_MOCAP_POS', 256),
+             ('mjSTATE_EQ_ACTIVE', 256),
-             ('mjSTATE_MOCAP_QUAT', 512),
+             ('mjSTATE_MOCAP_POS', 512),
-             ('mjSTATE_USERDATA', 1024),
+             ('mjSTATE_MOCAP_QUAT', 1024),
-             ('mjSTATE_PLUGIN', 2048),
+             ('mjSTATE_USERDATA', 2048),
-             ('mjNSTATE', 12),
+             ('mjSTATE_PLUGIN', 4096),
+             ('mjNSTATE', 13),
              ('mjSTATE_PHYSICS', 14),
-             ('mjSTATE_FULLPHYSICS', 2063),
+             ('mjSTATE_FULLPHYSICS', 4111),
-             ('mjSTATE_USER', 2016),
+             ('mjSTATE_USER', 4064),
-             ('mjSTATE_INTEGRATION', 4095),
+             ('mjSTATE_INTEGRATION', 8191),
          ]),
      )),
     ('mjtWarning',
@@ -438,7 +455,10 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjTIMER_POS_COLLISION', 10),
              ('mjTIMER_POS_MAKE', 11),
              ('mjTIMER_POS_PROJECT', 12),
-             ('mjNTIMER', 13),
+             ('mjTIMER_COL_BROAD', 13),
+             ('mjTIMER_COL_MID', 14),
+             ('mjTIMER_COL_NARROW', 15),
+             ('mjNTIMER', 16),
          ]),
      )),
     ('mjtCatBit',
@@ -501,13 +521,14 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjLABEL_TENDON', 7),
              ('mjLABEL_ACTUATOR', 8),
              ('mjLABEL_CONSTRAINT', 9),
-             ('mjLABEL_SKIN', 10),
+             ('mjLABEL_FLEX', 10),
-             ('mjLABEL_SELECTION', 11),
+             ('mjLABEL_SKIN', 11),
-             ('mjLABEL_SELPNT', 12),
+             ('mjLABEL_SELECTION', 12),
-             ('mjLABEL_CONTACTPOINT', 13),
+             ('mjLABEL_SELPNT', 13),
-             ('mjLABEL_CONTACTFORCE', 14),
+             ('mjLABEL_CONTACTPOINT', 14),
-             ('mjLABEL_ISLAND', 15),
+             ('mjLABEL_CONTACTFORCE', 15),
-             ('mjNLABEL', 16),
+             ('mjLABEL_ISLAND', 16),
+             ('mjNLABEL', 17),
          ]),
      )),
     ('mjtFrame',
@@ -555,10 +576,15 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjVIS_SELECT', 21),
              ('mjVIS_STATIC', 22),
              ('mjVIS_SKIN', 23),
-             ('mjVIS_MIDPHASE', 24),
+             ('mjVIS_FLEXVERT', 24),
-             ('mjVIS_MESHBVH', 25),
+             ('mjVIS_FLEXEDGE', 25),
-             ('mjVIS_SDFITER', 26),
+             ('mjVIS_FLEXFACE', 26),
-             ('mjNVISFLAG', 27),
+             ('mjVIS_FLEXSKIN', 27),
+             ('mjVIS_BODYBVH', 28),
+             ('mjVIS_FLEXBVH', 29),
+             ('mjVIS_MESHBVH', 30),
+             ('mjVIS_SDFITER', 31),
+             ('mjNVISFLAG', 32),
          ]),
      )),
     ('mjtRndFlag',
@@ -609,6 +635,10 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjGRID_TOPRIGHT', 1),
              ('mjGRID_BOTTOMLEFT', 2),
              ('mjGRID_BOTTOMRIGHT', 3),
+             ('mjGRID_TOP', 4),
+             ('mjGRID_BOTTOM', 5),
+             ('mjGRID_LEFT', 6),
+             ('mjGRID_RIGHT', 7),
          ]),
      )),
     ('mjtFramebuffer',
@@ -620,6 +650,15 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjFB_OFFSCREEN', 1),
          ]),
      )),
+    ('mjtDepthMap',
+     EnumDecl(
+         name='mjtDepthMap',
+         declname='enum mjtDepthMap_',
+         values=dict([
+             ('mjDEPTH_ZERONEAR', 0),
+             ('mjDEPTH_ZEROFAR', 1),
+         ]),
+     )),
     ('mjtFontScale',
      EnumDecl(
          name='mjtFontScale',
@@ -643,16 +682,6 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjFONT_BIG', 2),
          ]),
      )),
-    ('mjtTaskStatus',
-     EnumDecl(
-         name='mjtTaskStatus',
-         declname='enum mjtTaskStatus_',
-         values=dict([
-             ('mjTASK_NEW', 0),
-             ('mjTASK_QUEUED', 1),
-             ('mjTASK_COMPLETED', 2),
-         ]),
-     )),
     ('mjtButton',
      EnumDecl(
          name='mjtButton',

introspect/enums_test.py

@@ -61,6 +61,7 @@ class EnumsTest(absltest.TestCase):
     self.assertEqual(enum_decl.values['mjGEOM_ARROW'], 100)
     self.assertEqual(enum_decl.values['mjGEOM_ARROW1'], 101)
     self.assertEqual(enum_decl.values['mjGEOM_ARROW2'], 102)
+    self.assertEqual(enum_decl.values['mjGEOM_TRIANGLE'], 107)
     # Skip a few...
 
     self.assertEqual(enum_decl.values['mjGEOM_NONE'], 1001)

introspect/functions.py

@@ -705,9 +705,9 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
          ),
          doc='Free the current mjData stack frame. All pointers returned by mj_stackAlloc since the last call to mj_markStack must no longer be used afterwards.',  # pylint: disable=line-too-long
      )),
-    ('mj_stackAlloc',
+    ('mj_stackAllocByte',
      FunctionDecl(
-         name='mj_stackAlloc',
+         name='mj_stackAllocByte',
          return_type=PointerType(
              inner_type=ValueType(name='void'),
          ),
@@ -1456,6 +1456,26 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
          ),
          doc='Compute camera and light positions and orientations.',
      )),
+    ('mj_flex',
+     FunctionDecl(
+         name='mj_flex',
+         return_type=ValueType(name='void'),
+         parameters=(
+             FunctionParameterDecl(
+                 name='m',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjModel', is_const=True),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='d',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjData'),
+                 ),
+             ),
+         ),
+         doc='Compute flex-related quantities.',
+     )),
     ('mj_tendon',
      FunctionDecl(
          name='mj_tendon',
@@ -3161,6 +3181,69 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
          ),
          doc='Intersect ray with pure geom, return nearest distance or -1 if no intersection.',  # pylint: disable=line-too-long
      )),
+    ('mju_rayFlex',
+     FunctionDecl(
+         name='mju_rayFlex',
+         return_type=ValueType(name='mjtNum'),
+         parameters=(
+             FunctionParameterDecl(
+                 name='m',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjModel', is_const=True),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='d',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjData', is_const=True),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='flex_layer',
+                 type=ValueType(name='int'),
+             ),
+             FunctionParameterDecl(
+                 name='flg_vert',
+                 type=ValueType(name='mjtByte'),
+             ),
+             FunctionParameterDecl(
+                 name='flg_edge',
+                 type=ValueType(name='mjtByte'),
+             ),
+             FunctionParameterDecl(
+                 name='flg_face',
+                 type=ValueType(name='mjtByte'),
+             ),
+             FunctionParameterDecl(
+                 name='flg_skin',
+                 type=ValueType(name='mjtByte'),
+             ),
+             FunctionParameterDecl(
+                 name='flexid',
+                 type=ValueType(name='int'),
+             ),
+             FunctionParameterDecl(
+                 name='pnt',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjtNum', is_const=True),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='vec',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjtNum', is_const=True),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='vertid',
+                 type=ArrayType(
+                     inner_type=ValueType(name='int'),
+                     extents=(1,),
+                 ),
+             ),
+         ),
+         doc='Intersect ray with flex, return nearest distance or -1 if no intersection, and also output nearest vertex id.',  # pylint: disable=line-too-long
+     )),
     ('mju_raySkin',
      FunctionDecl(
          name='mju_raySkin',
@@ -3815,6 +3898,13 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                      extents=(1,),
                  ),
              ),
+             FunctionParameterDecl(
+                 name='flexid',
+                 type=ArrayType(
+                     inner_type=ValueType(name='int'),
+                     extents=(1,),
+                 ),
+             ),
              FunctionParameterDecl(
                  name='skinid',
                  type=ArrayType(
@@ -3823,7 +3913,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                  ),
              ),
          ),
-         doc='Select geom or skin with mouse, return bodyid; -1: none selected.',  # pylint: disable=line-too-long
+         doc='Select geom, flex or skin with mouse, return bodyid; -1: none selected.',  # pylint: disable=line-too-long
      )),
     ('mjv_defaultOption',
      FunctionDecl(
@@ -8271,6 +8361,26 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
          ),
          doc='Create a thread pool with the specified number of threads running.',  # pylint: disable=line-too-long
      )),
+    ('mju_bindThreadPool',
+     FunctionDecl(
+         name='mju_bindThreadPool',
+         return_type=ValueType(name='void'),
+         parameters=(
+             FunctionParameterDecl(
+                 name='d',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjData'),
+                 ),
+             ),
+             FunctionParameterDecl(
+                 name='thread_pool',
+                 type=PointerType(
+                     inner_type=ValueType(name='void'),
+                 ),
+             ),
+         ),
+         doc='Adds a thread pool to mjData and configures it for multi-threaded use.',  # pylint: disable=line-too-long
+     )),
     ('mju_threadPoolEnqueue',
      FunctionDecl(
          name='mju_threadPoolEnqueue',

model/cards/assets/card.obj

@@ -0,0 +1,232 @@
+# Blender 3.5.1
+# www.blender.org
+mtllib playing_card_tris.mtl
+o playing_card_tris
+v -0.047000 0.027461 -0.000125
+v -0.042461 0.032000 -0.000125
+v -0.046654 0.029198 -0.000125
+v -0.045670 0.030670 -0.000125
+v -0.044198 0.031654 -0.000125
+v -0.042461 -0.032000 -0.000125
+v -0.047000 -0.027461 -0.000125
+v -0.044198 -0.031654 -0.000125
+v -0.045670 -0.030670 -0.000125
+v -0.046654 -0.029198 -0.000125
+v 0.047000 0.027461 -0.000125
+v 0.042461 0.032000 -0.000125
+v 0.046654 0.029198 -0.000125
+v 0.045670 0.030670 -0.000125
+v 0.044198 0.031654 -0.000125
+v 0.047000 -0.027461 -0.000125
+v 0.042461 -0.032000 -0.000125
+v 0.046654 -0.029198 -0.000125
+v 0.045670 -0.030670 -0.000125
+v 0.044198 -0.031654 -0.000125
+v 0.042461 0.032000 0.000125
+v -0.042461 0.032000 0.000125
+v -0.044198 0.031654 0.000125
+v -0.045670 0.030670 0.000125
+v -0.046654 0.029198 0.000125
+v -0.047000 0.027461 0.000125
+v -0.047000 -0.027461 0.000125
+v -0.046654 -0.029198 0.000125
+v -0.045670 -0.030670 0.000125
+v -0.044198 -0.031654 0.000125
+v -0.042461 -0.032000 0.000125
+v 0.042461 -0.032000 0.000125
+v 0.044198 -0.031654 0.000125
+v 0.045670 -0.030670 0.000125
+v 0.046654 -0.029198 0.000125
+v 0.047000 -0.027461 0.000125
+v 0.047000 0.027461 0.000125
+v 0.046654 0.029198 0.000125
+v 0.045670 0.030670 0.000125
+v 0.044198 0.031654 0.000125
+vn -0.0000 -1.0000 -0.0000
+vn -0.8315 0.5556 -0.0000
+vn 0.5556 0.8315 -0.0000
+vn 0.1951 -0.9808 -0.0000
+vn -0.9808 0.1951 -0.0000
+vn 0.1951 0.9808 -0.0000
+vn 0.5556 -0.8315 -0.0000
+vn -1.0000 -0.0000 -0.0000
+vn 0.8315 -0.5556 -0.0000
+vn -0.9808 -0.1951 -0.0000
+vn 0.9808 -0.1951 -0.0000
+vn -0.8315 -0.5556 -0.0000
+vn -0.0000 1.0000 -0.0000
+vn 1.0000 -0.0000 -0.0000
+vn -0.5556 -0.8315 -0.0000
+vn -0.1951 0.9808 -0.0000
+vn 0.9808 0.1951 -0.0000
+vn -0.1951 -0.9808 -0.0000
+vn -0.5556 0.8315 -0.0000
+vn 0.8315 0.5556 -0.0000
+vn -0.0000 -0.0000 -1.0000
+vn -0.0000 -0.0000 1.0000
+vt 0.316411 0.713926
+vt 0.440347 0.005985
+vt 0.372514 0.714185
+vt 0.473507 0.039144
+vt 0.325338 0.713926
+vt 0.453037 0.008509
+vt 0.332906 0.713926
+vt 0.356018 0.714185
+vt 0.463794 0.015697
+vt 0.363586 0.714185
+vt 0.470982 0.026454
+vt 0.372514 0.716173
+vt 0.005985 0.039144
+vt 0.034156 0.713926
+vt 0.039144 0.005985
+vt 0.363586 0.716173
+vt 0.008509 0.026454
+vt 0.356018 0.716173
+vt 0.015697 0.015697
+vt 0.017661 0.713926
+vt 0.025229 0.713926
+vt 0.026455 0.008509
+vt 0.316410 0.715914
+vt 0.440347 0.692657
+vt 0.808945 0.714185
+vt 0.473507 0.659498
+vt 0.325338 0.715914
+vt 0.453037 0.690133
+vt 0.825440 0.714185
+vt 0.332906 0.715914
+vt 0.463794 0.682945
+vt 0.817872 0.714185
+vt 0.470982 0.672188
+vt 0.034156 0.715914
+vt 0.039144 0.692657
+vt 0.808945 0.716173
+vt 0.005985 0.659498
+vt 0.025229 0.715914
+vt 0.026454 0.690133
+vt 0.017661 0.715914
+vt 0.825440 0.716173
+vt 0.015697 0.682945
+vt 0.817872 0.716173
+vt 0.008509 0.672188
+vt 0.808945 0.705893
+vt 0.952998 0.039144
+vt 0.372514 0.705893
+vt 0.952998 0.659498
+vt 0.363586 0.705893
+vt 0.950474 0.672188
+vt 0.332906 0.705634
+vt 0.356018 0.705893
+vt 0.943286 0.682945
+vt 0.325338 0.705634
+vt 0.932528 0.690133
+vt 0.316411 0.705634
+vt 0.919839 0.692657
+vt 0.034156 0.705634
+vt 0.518635 0.692657
+vt 0.025229 0.705634
+vt 0.505946 0.690133
+vt 0.017661 0.705634
+vt 0.356018 0.724465
+vt 0.495188 0.682945
+vt 0.363586 0.724465
+vt 0.488000 0.672188
+vt 0.372514 0.724465
+vt 0.485476 0.659498
+vt 0.808945 0.724465
+vt 0.485476 0.039144
+vt 0.817872 0.724465
+vt 0.488000 0.026454
+vt 0.825440 0.724465
+vt 0.017661 0.724206
+vt 0.495188 0.015697
+vt 0.025229 0.724206
+vt 0.505946 0.008509
+vt 0.034156 0.724206
+vt 0.518635 0.005985
+vt 0.316410 0.724206
+vt 0.919839 0.005985
+vt 0.325338 0.724206
+vt 0.932528 0.008509
+vt 0.825440 0.705893
+vt 0.332906 0.724206
+vt 0.943286 0.015697
+vt 0.817872 0.705893
+vt 0.950474 0.026454
+s 0
+usemtl Material
+f 17/36/1 31/67/1 6/12/1
+f 3/5/2 24/51/2 4/7/2
+f 15/32/3 39/84/3 14/29/3
+f 20/43/4 32/69/4 17/36/4
+f 1/1/5 25/54/5 3/5/5
+f 12/25/6 40/87/6 15/32/6
+f 19/41/7 33/71/7 20/43/7
+f 7/14/8 26/56/8 1/1/8
+f 18/38/9 34/74/9 19/40/9
+f 10/21/10 27/58/10 7/14/10
+f 16/34/11 35/76/11 18/38/11
+f 9/20/12 28/60/12 10/21/12
+f 2/3/13 21/45/13 12/25/13
+f 11/23/14 36/78/14 16/34/14
+f 8/16/15 29/63/15 9/18/15
+f 5/10/16 22/47/16 2/3/16
+f 13/27/17 37/80/17 11/23/17
+f 6/12/18 30/65/18 8/16/18
+f 4/8/19 23/49/19 5/10/19
+f 14/30/20 38/82/20 13/27/20
+f 8/17/21 9/19/21 10/22/21
+f 17/36/1 32/69/1 31/67/1
+f 3/5/2 25/54/2 24/51/2
+f 15/32/3 40/87/3 39/84/3
+f 20/43/4 33/71/4 32/69/4
+f 1/1/5 26/56/5 25/54/5
+f 12/25/6 21/45/6 40/87/6
+f 19/41/7 34/73/7 33/71/7
+f 7/14/8 27/58/8 26/56/8
+f 18/38/9 35/76/9 34/74/9
+f 10/21/10 28/60/10 27/58/10
+f 16/34/11 36/78/11 35/76/11
+f 9/20/12 29/62/12 28/60/12
+f 2/3/13 22/47/13 21/45/13
+f 11/23/14 37/80/14 36/78/14
+f 8/16/15 30/65/15 29/63/15
+f 5/10/16 23/49/16 22/47/16
+f 13/27/17 38/82/17 37/80/17
+f 6/12/18 31/67/18 30/65/18
+f 4/8/19 24/52/19 23/49/19
+f 14/30/20 39/85/20 38/82/20
+f 25/55/22 23/50/22 24/53/22
+f 31/68/22 28/61/22 30/66/22
+f 35/77/22 33/72/22 34/75/22
+f 22/48/22 25/55/22 26/57/22
+f 29/64/22 30/66/22 28/61/22
+f 40/88/22 38/83/22 39/86/22
+f 32/70/22 35/77/22 36/79/22
+f 36/79/22 21/46/22 32/70/22
+f 37/81/22 40/88/22 21/46/22
+f 31/68/22 26/57/22 27/59/22
+f 32/70/22 22/48/22 31/68/22
+f 13/28/21 15/33/21 14/31/21
+f 17/37/21 2/4/21 12/26/21
+f 2/4/21 1/2/21 3/6/21
+f 6/13/21 1/2/21 2/4/21
+f 8/17/21 7/15/21 6/13/21
+f 17/37/21 18/39/21 20/44/21
+f 19/42/21 20/44/21 18/39/21
+f 17/37/21 11/24/21 16/35/21
+f 12/26/21 13/28/21 11/24/21
+f 31/68/22 27/59/22 28/61/22
+f 22/48/22 23/50/22 25/55/22
+f 32/70/22 33/72/22 35/77/22
+f 36/79/22 37/81/22 21/46/22
+f 37/81/22 38/83/22 40/88/22
+f 31/68/22 22/48/22 26/57/22
+f 32/70/22 21/46/22 22/48/22
+f 17/37/21 6/13/21 2/4/21
+f 4/9/21 5/11/21 3/6/21
+f 5/11/21 2/4/21 3/6/21
+f 6/13/21 7/15/21 1/2/21
+f 8/17/21 10/22/21 7/15/21
+f 17/37/21 16/35/21 18/39/21
+f 17/37/21 12/26/21 11/24/21
+f 12/26/21 15/33/21 13/28/21

model/cards/cards.xml

@@ -0,0 +1,518 @@
+<mujoco>
+  <compiler assetdir="assets"/>
+
+  <size memory="5M"/>
+
+  <statistic extent="0.5" center="0 -.5 0"/>
+
+  <visual>
+    <map znear="0.1" zfar="10"/>
+    <quality shadowsize="8192"/>
+  </visual>
+
+  <option density="1.225" viscosity="1.8e-5" timestep="1e-3" integrator="implicitfast"/>
+
+  <asset>
+    <texture name="grid" type="2d" builtin="checker" rgb1=".1 .2 .3" rgb2=".2 .3 .4" width="100" height="100"/>
+    <material name="grid" texture="grid" texrepeat="8 8" texuniform="true" reflectance=".2"/>
+
+    <mesh file="card.obj"/>
+
+    <texture type="2d" file="2_of_clubs.png"/>
+    <material name="2_of_clubs" texture="2_of_clubs"/>
+
+    <texture type="2d" file="2_of_diamonds.png"/>
+    <material name="2_of_diamonds" texture="2_of_diamonds"/>
+
+    <texture type="2d" file="2_of_hearts.png"/>
+    <material name="2_of_hearts" texture="2_of_hearts"/>
+
+    <texture type="2d" file="2_of_spades.png"/>
+    <material name="2_of_spades" texture="2_of_spades"/>
+
+    <texture type="2d" file="3_of_clubs.png"/>
+    <material name="3_of_clubs" texture="3_of_clubs"/>
+
+    <texture type="2d" file="3_of_diamonds.png"/>
+    <material name="3_of_diamonds" texture="3_of_diamonds"/>
+
+    <texture type="2d" file="3_of_hearts.png"/>
+    <material name="3_of_hearts" texture="3_of_hearts"/>
+
+    <texture type="2d" file="3_of_spades.png"/>
+    <material name="3_of_spades" texture="3_of_spades"/>
+
+    <texture type="2d" file="4_of_clubs.png"/>
+    <material name="4_of_clubs" texture="4_of_clubs"/>
+
+    <texture type="2d" file="4_of_diamonds.png"/>
+    <material name="4_of_diamonds" texture="4_of_diamonds"/>
+
+    <texture type="2d" file="4_of_hearts.png"/>
+    <material name="4_of_hearts" texture="4_of_hearts"/>
+
+    <texture type="2d" file="4_of_spades.png"/>
+    <material name="4_of_spades" texture="4_of_spades"/>
+
+    <texture type="2d" file="5_of_clubs.png"/>
+    <material name="5_of_clubs" texture="5_of_clubs"/>
+
+    <texture type="2d" file="5_of_diamonds.png"/>
+    <material name="5_of_diamonds" texture="5_of_diamonds"/>
+
+    <texture type="2d" file="5_of_hearts.png"/>
+    <material name="5_of_hearts" texture="5_of_hearts"/>
+
+    <texture type="2d" file="5_of_spades.png"/>
+    <material name="5_of_spades" texture="5_of_spades"/>
+
+    <texture type="2d" file="6_of_clubs.png"/>
+    <material name="6_of_clubs" texture="6_of_clubs"/>
+
+    <texture type="2d" file="6_of_diamonds.png"/>
+    <material name="6_of_diamonds" texture="6_of_diamonds"/>
+
+    <texture type="2d" file="6_of_hearts.png"/>
+    <material name="6_of_hearts" texture="6_of_hearts"/>
+
+    <texture type="2d" file="6_of_spades.png"/>
+    <material name="6_of_spades" texture="6_of_spades"/>
+
+    <texture type="2d" file="7_of_clubs.png"/>
+    <material name="7_of_clubs" texture="7_of_clubs"/>
+
+    <texture type="2d" file="7_of_diamonds.png"/>
+    <material name="7_of_diamonds" texture="7_of_diamonds"/>
+
+    <texture type="2d" file="7_of_hearts.png"/>
+    <material name="7_of_hearts" texture="7_of_hearts"/>
+
+    <texture type="2d" file="7_of_spades.png"/>
+    <material name="7_of_spades" texture="7_of_spades"/>
+
+    <texture type="2d" file="8_of_clubs.png"/>
+    <material name="8_of_clubs" texture="8_of_clubs"/>
+
+    <texture type="2d" file="8_of_diamonds.png"/>
+    <material name="8_of_diamonds" texture="8_of_diamonds"/>
+
+    <texture type="2d" file="8_of_hearts.png"/>
+    <material name="8_of_hearts" texture="8_of_hearts"/>
+
+    <texture type="2d" file="8_of_spades.png"/>
+    <material name="8_of_spades" texture="8_of_spades"/>
+
+    <texture type="2d" file="9_of_clubs.png"/>
+    <material name="9_of_clubs" texture="9_of_clubs"/>
+
+    <texture type="2d" file="9_of_diamonds.png"/>
+    <material name="9_of_diamonds" texture="9_of_diamonds"/>
+
+    <texture type="2d" file="9_of_hearts.png"/>
+    <material name="9_of_hearts" texture="9_of_hearts"/>
+
+    <texture type="2d" file="9_of_spades.png"/>
+    <material name="9_of_spades" texture="9_of_spades"/>
+
+    <texture type="2d" file="10_of_clubs.png"/>
+    <material name="10_of_clubs" texture="10_of_clubs"/>
+
+    <texture type="2d" file="10_of_diamonds.png"/>
+    <material name="10_of_diamonds" texture="10_of_diamonds"/>
+
+    <texture type="2d" file="10_of_hearts.png"/>
+    <material name="10_of_hearts" texture="10_of_hearts"/>
+
+    <texture type="2d" file="10_of_spades.png"/>
+    <material name="10_of_spades" texture="10_of_spades"/>
+
+    <texture type="2d" file="ace_of_clubs.png"/>
+    <material name="ace_of_clubs" texture="ace_of_clubs"/>
+
+    <texture type="2d" file="ace_of_diamonds.png"/>
+    <material name="ace_of_diamonds" texture="ace_of_diamonds"/>
+
+    <texture type="2d" file="ace_of_hearts.png"/>
+    <material name="ace_of_hearts" texture="ace_of_hearts"/>
+
+    <texture type="2d" file="ace_of_spades.png"/>
+    <material name="ace_of_spades" texture="ace_of_spades"/>
+
+    <texture type="2d" file="black_joker.png"/>
+    <material name="black_joker" texture="black_joker"/>
+
+    <texture type="2d" file="jack_of_clubs.png"/>
+    <material name="jack_of_clubs" texture="jack_of_clubs"/>
+
+    <texture type="2d" file="jack_of_diamonds.png"/>
+    <material name="jack_of_diamonds" texture="jack_of_diamonds"/>
+
+    <texture type="2d" file="jack_of_hearts.png"/>
+    <material name="jack_of_hearts" texture="jack_of_hearts"/>
+
+    <texture type="2d" file="jack_of_spades.png"/>
+    <material name="jack_of_spades" texture="jack_of_spades"/>
+
+    <texture type="2d" file="king_of_clubs.png"/>
+    <material name="king_of_clubs" texture="king_of_clubs"/>
+
+    <texture type="2d" file="king_of_diamonds.png"/>
+    <material name="king_of_diamonds" texture="king_of_diamonds"/>
+
+    <texture type="2d" file="king_of_hearts.png"/>
+    <material name="king_of_hearts" texture="king_of_hearts"/>
+
+    <texture type="2d" file="king_of_spades.png"/>
+    <material name="king_of_spades" texture="king_of_spades"/>
+
+    <texture type="2d" file="queen_of_clubs.png"/>
+    <material name="queen_of_clubs" texture="queen_of_clubs"/>
+
+    <texture type="2d" file="queen_of_diamonds.png"/>
+    <material name="queen_of_diamonds" texture="queen_of_diamonds"/>
+
+    <texture type="2d" file="queen_of_hearts.png"/>
+    <material name="queen_of_hearts" texture="queen_of_hearts"/>
+
+    <texture type="2d" file="queen_of_spades.png"/>
+    <material name="queen_of_spades" texture="queen_of_spades"/>
+  </asset>
+
+  <default>
+    <geom solref=".5e-4" solimp="0.9 0.99 1e-4" fluidcoef="0.5 0.25 0.5 2.0 1.0"/>
+    <default class="card">
+      <geom type="mesh" mesh="card" mass="1.84e-4" fluidshape="ellipsoid" contype="0" conaffinity="0"/>
+    </default>
+    <default class="collision">
+      <geom type="box" mass="0" size="0.047 0.032 .00035" group="3" friction=".1"/>
+    </default>
+  </default>
+
+  <worldbody>
+    <light cutoff="30" pos="0 1 1" dir="0 -1 -2"/>
+    <light cutoff="30" pos="0 -1 1" dir="0 1 -2"/>
+    <camera name="cinematic" pos="0.119 -0.507 0.239" xyaxes="1 0 0 0 0.608 0.794"  mode="trackcom" fovy="40"/>
+
+    <geom type="plane" size="5 5 .01" pos="0 0 -1" material="grid"/>
+    <geom type="capsule" size="0.03" fromto=".1 -.1 -.3 .1 .1 -.3"/>
+
+    <body pos="0.000 -0.040 -0.000" euler="-100 180 0">
+      <freejoint/>
+      <geom class="card" material="2_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.005 -0.037 -0.005" euler="-103 180 0">
+      <freejoint/>
+      <geom class="card" material="2_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.010 -0.034 -0.010" euler="-106 180 0">
+      <freejoint/>
+      <geom class="card" material="2_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.015 -0.031 -0.015" euler="-109 180 0">
+      <freejoint/>
+      <geom class="card" material="2_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.020 -0.029 -0.020" euler="-112 180 0">
+      <freejoint/>
+      <geom class="card" material="3_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.025 -0.026 -0.025" euler="-115 180 0">
+      <freejoint/>
+      <geom class="card" material="3_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.030 -0.024 -0.030" euler="-118 180 0">
+      <freejoint/>
+      <geom class="card" material="3_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.035 -0.021 -0.035" euler="-121 180 0">
+      <freejoint/>
+      <geom class="card" material="3_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.040 -0.019 -0.040" euler="-124 180 0">
+      <freejoint/>
+      <geom class="card" material="4_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.045 -0.017 -0.045" euler="-127 180 0">
+      <freejoint/>
+      <geom class="card" material="4_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.050 -0.015 -0.050" euler="-130 180 0">
+      <freejoint/>
+      <geom class="card" material="4_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.055 -0.013 -0.055" euler="-133 180 0">
+      <freejoint/>
+      <geom class="card" material="4_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.060 -0.012 -0.060" euler="-136 180 0">
+      <freejoint/>
+      <geom class="card" material="5_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.065 -0.010 -0.065" euler="-139 180 0">
+      <freejoint/>
+      <geom class="card" material="5_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.070 -0.009 -0.070" euler="-142 180 0">
+      <freejoint/>
+      <geom class="card" material="5_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.075 -0.007 -0.075" euler="-145 180 0">
+      <freejoint/>
+      <geom class="card" material="5_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.080 -0.006 -0.080" euler="-148 180 0">
+      <freejoint/>
+      <geom class="card" material="6_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.085 -0.005 -0.085" euler="-151 180 0">
+      <freejoint/>
+      <geom class="card" material="6_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.090 -0.004 -0.090" euler="-154 180 0">
+      <freejoint/>
+      <geom class="card" material="6_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.095 -0.003 -0.095" euler="-157 180 0">
+      <freejoint/>
+      <geom class="card" material="6_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.100 -0.002 -0.100" euler="-160 180 0">
+      <freejoint/>
+      <geom class="card" material="7_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.105 -0.001 -0.105" euler="-163 180 0">
+      <freejoint/>
+      <geom class="card" material="7_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.110 -0.001 -0.110" euler="-166 180 0">
+      <freejoint/>
+      <geom class="card" material="7_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.115 -0.001 -0.115" euler="-169 180 0">
+      <freejoint/>
+      <geom class="card" material="7_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.120 -0.000 -0.120" euler="-172 180 0">
+      <freejoint/>
+      <geom class="card" material="8_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.125 -0.000 -0.125" euler="-175 180 0">
+      <freejoint/>
+      <geom class="card" material="8_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.130 -0.000 -0.130" euler="-178 180 0">
+      <freejoint/>
+      <geom class="card" material="8_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.135 -0.000 -0.135" euler="-181 180 0">
+      <freejoint/>
+      <geom class="card" material="8_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.140 -0.000 -0.140" euler="-184 180 0">
+      <freejoint/>
+      <geom class="card" material="9_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.145 -0.001 -0.145" euler="-187 180 0">
+      <freejoint/>
+      <geom class="card" material="9_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.150 -0.001 -0.150" euler="-190 180 0">
+      <freejoint/>
+      <geom class="card" material="9_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.155 -0.001 -0.155" euler="-193 180 0">
+      <freejoint/>
+      <geom class="card" material="9_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.160 -0.002 -0.160" euler="-196 180 0">
+      <freejoint/>
+      <geom class="card" material="10_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.165 -0.003 -0.165" euler="-199 180 0">
+      <freejoint/>
+      <geom class="card" material="10_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.170 -0.004 -0.170" euler="-202 180 0">
+      <freejoint/>
+      <geom class="card" material="10_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.175 -0.005 -0.175" euler="-205 180 0">
+      <freejoint/>
+      <geom class="card" material="10_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.180 -0.006 -0.180" euler="-208 180 0">
+      <freejoint/>
+      <geom class="card" material="ace_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.185 -0.007 -0.185" euler="-211 180 0">
+      <freejoint/>
+      <geom class="card" material="ace_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.190 -0.009 -0.190" euler="-214 180 0">
+      <freejoint/>
+      <geom class="card" material="ace_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.195 -0.010 -0.195" euler="-217 180 0">
+      <freejoint/>
+      <geom class="card" material="ace_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.200 -0.012 -0.200" euler="-220 180 0">
+      <freejoint/>
+      <geom class="card" material="black_joker"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.205 -0.013 -0.205" euler="-223 180 0">
+      <freejoint/>
+      <geom class="card" material="jack_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.210 -0.015 -0.210" euler="-226 180 0">
+      <freejoint/>
+      <geom class="card" material="jack_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.215 -0.017 -0.215" euler="-229 180 0">
+      <freejoint/>
+      <geom class="card" material="jack_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.220 -0.019 -0.220" euler="-232 180 0">
+      <freejoint/>
+      <geom class="card" material="jack_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.225 -0.021 -0.225" euler="-235 180 0">
+      <freejoint/>
+      <geom class="card" material="king_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.230 -0.024 -0.230" euler="-238 180 0">
+      <freejoint/>
+      <geom class="card" material="king_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.235 -0.026 -0.235" euler="-241 180 0">
+      <freejoint/>
+      <geom class="card" material="king_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.240 -0.029 -0.240" euler="-244 180 0">
+      <freejoint/>
+      <geom class="card" material="king_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.245 -0.031 -0.245" euler="-247 180 0">
+      <freejoint/>
+      <geom class="card" material="queen_of_clubs"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.250 -0.034 -0.250" euler="-250 180 0">
+      <freejoint/>
+      <geom class="card" material="queen_of_diamonds"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.255 -0.037 -0.255" euler="-253 180 0">
+      <freejoint/>
+      <geom class="card" material="queen_of_hearts"/>
+      <geom class="collision"/>
+    </body>
+
+    <body pos="0.260 -0.040 -0.260" euler="-256 180 0">
+      <freejoint/>
+      <geom class="card" material="queen_of_spades"/>
+      <geom class="collision"/>
+    </body>
+
+  </worldbody>
+</mujoco>

model/composite/cloth.xml

@@ -1,35 +0,0 @@
-<!-- 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.
-     You may obtain a copy of the License at
-
-         http://www.apache.org/licenses/LICENSE-2.0
-
-     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.
-     See the License for the specific language governing permissions and
-     limitations under the License.
--->
-
-<mujoco model="Cloth">
-  <include file="scene.xml"/>
-
-  <option timestep="0.002" solver="CG" tolerance="1e-6"/>
-
-  <size memory="10M"/>
-
-  <worldbody>
-
-    <body name="B3_5" pos="0 0 1">
-      <freejoint/>
-      <composite type="cloth" count="9 9 1" spacing="0.05" flatinertia="0.01">
-        <joint kind="main" damping="0.001"/>
-        <skin material="matcarpet" texcoord="true" inflate="0.005" subgrid="2"/>
-        <geom type="capsule" size="0.015 0.01" rgba=".8 .2 .1 1"/>
-      </composite>
-    </body>
-
-  </worldbody>
-</mujoco>

model/composite/loop.xml

@@ -1,32 +0,0 @@
-<!-- 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.
-     You may obtain a copy of the License at
-
-         http://www.apache.org/licenses/LICENSE-2.0
-
-     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.
-     See the License for the specific language governing permissions and
-     limitations under the License.
--->
-
-<mujoco model="Loop">
-  <include file="scene.xml"/>
-
-  <option timestep="0.002" jacobian="dense"/>
-
-  <size memory="2M"/>
-
-  <worldbody>
-    <body name="B0" pos="0 0 1">
-      <freejoint/>
-      <composite type="loop" count="20 1 1" spacing="0.04" offset="0 0 2">
-        <joint kind="main" damping="0.005"/>
-        <geom type="capsule" size=".01 .015" rgba=".8 .2 .1 1"/>
-      </composite>
-    </body>
-  </worldbody>
-</mujoco>

model/cube/cube_3x3x3.xml

@@ -1,5 +1,5 @@
 <mujoco model="Cube 3x3x3">
-  <compiler autolimits="true" angle="radian" texturedir="assets"/>
+  <compiler autolimits="true" texturedir="assets"/>
 
   <option timestep="0.01" integrator="implicitfast"/>
 
@@ -17,7 +17,7 @@
     <motor ctrlrange="-0.05 0.05"/>
     <default class="cubelet">
       <joint type="ball" armature="0.0001" damping="0.0005" frictionloss="0.001"/>
-      <geom type="mesh" condim="1" mesh="cubelet"/>
+      <geom type="mesh" condim="1" mesh="cubelet" euler="0 0 90"/>
     </default>
     <default class="core">
       <geom type="sphere" contype="0" conaffinity="0" group="4" size="0.01"/>
@@ -26,33 +26,33 @@
 
   <asset>
     <texture type="skybox" builtin="gradient" width="512" height="512"/>
-    <texture file="white.png" gridsize="3 4" gridlayout=".....F......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....F......" file="white.png"/>
-    <texture file="yellow.png" gridsize="3 4" gridlayout=".....B......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....B......" file="yellow.png"/>
-    <texture file="red.png" gridsize="3 4" gridlayout=".....D......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....D......" file="red.png"/>
-    <texture file="orange.png" gridsize="3 4" gridlayout=".....U......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....U......" file="orange.png"/>
-    <texture file="blue.png" gridsize="3 4" gridlayout=".....R......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....R......" file="blue.png"/>
-    <texture file="green.png" gridsize="3 4" gridlayout=".....L......" rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....L......" file="green.png"/>
-    <texture file="red_white.png" gridsize="3 4" gridlayout=".....DF....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....DF....." file="red_white.png"/>
-    <texture file="orange_white.png" gridsize="3 4" gridlayout=".....UF....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....UF....." file="orange_white.png"/>
-    <texture file="blue_white.png" gridsize="3 4" gridlayout=".....RF....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RF....." file="blue_white.png"/>
-    <texture file="green_white.png" gridsize="3 4" gridlayout=".....LF....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LF....." file="green_white.png"/>
-    <texture file="red_yellow.png" gridsize="3 4" gridlayout=".....DB....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....DB....." file="red_yellow.png"/>
-    <texture file="orange_yellow.png" gridsize="3 4" gridlayout=".....UB....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....UB....." file="orange_yellow.png"/>
-    <texture file="blue_yellow.png" gridsize="3 4" gridlayout=".....RB....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RB....." file="blue_yellow.png"/>
-    <texture file="green_yellow.png" gridsize="3 4" gridlayout=".....LB....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LB....." file="green_yellow.png"/>
-    <texture file="orange_red.png" gridsize="3 4" gridlayout=".....UD....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....UD....." file="orange_red.png"/>
-    <texture file="blue_red.png" gridsize="3 4" gridlayout=".....RD....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RD....." file="blue_red.png"/>
-    <texture file="green_red.png" gridsize="3 4" gridlayout=".....LD....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LD....." file="green_red.png"/>
-    <texture file="blue_orange.png" gridsize="3 4" gridlayout=".....RU....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RU....." file="blue_orange.png"/>
-    <texture file="green_orange.png" gridsize="3 4" gridlayout=".....LU....." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LU....." file="green_orange.png"/>
-    <texture file="blue_red_white.png" gridsize="3 4" gridlayout=".....RDF...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RDF...." file="blue_red_white.png"/>
-    <texture file="green_red_white.png" gridsize="3 4" gridlayout=".....LDF...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LDF...." file="green_red_white.png"/>
-    <texture file="blue_orange_white.png" gridsize="3 4" gridlayout=".....RUF...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RUF...." file="blue_orange_white.png"/>
-    <texture file="green_orange_white.png" gridsize="3 4" gridlayout=".....LUF...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LUF...." file="green_orange_white.png"/>
-    <texture file="blue_red_yellow.png" gridsize="3 4" gridlayout=".....RDB...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RDB...." file="blue_red_yellow.png"/>
-    <texture file="green_red_yellow.png" gridsize="3 4" gridlayout=".....LDB...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LDB...." file="green_red_yellow.png"/>
-    <texture file="blue_orange_yellow.png" gridsize="3 4" gridlayout=".....RUB...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....RUB...." file="blue_orange_yellow.png"/>
-    <texture file="green_orange_yellow.png" gridsize="3 4" gridlayout=".....LUB...." rgb1="0 0 0"/>
+    <texture rgb1="0 0 0" gridsize="3 4" gridlayout=".....LUB...." file="green_orange_yellow.png"/>
     <material name="white" texture="white"/>
     <material name="yellow" texture="yellow"/>
     <material name="red" texture="red"/>

model/plugin/elasticity/flag.xml

@@ -23,22 +23,33 @@
 -->
   <statistic center=".4 0 .8" extent="1.3"/>
 
-  <option wind="5 5 0" density="10">
+  <option wind="5 5 0" density="10" solver="CG" tolerance="1e-6">
-    <flag constraint="disable"/>
   </option>
 
+  <extension>
+    <plugin plugin="mujoco.elasticity.shell"/>
+  </extension>
+
   <worldbody>
     <geom name="floor" type="plane" size="0 0 .1"/>
     <light diffuse=".6 .6 .6" specular="0.2 0.2 0.2" pos="0 0 4" dir="0 0 -1"/>
-    <body name="B0_0" pos="0 0 1">
+    <body pos="0 0 1">
-      <composite type="cloth" count="9 19 1" spacing="0.05" flatinertia="0.01">
+      <composite type="particle" count="9 19 1" spacing="0.05" flatinertia="0.01">
-        <joint kind="main" damping="0.001" stiffness=".1"/>
         <skin texcoord="true" inflate="0.005" subgrid="4"/>
-        <geom type="ellipsoid" size="0.025 0.01 0.025" rgba=".8 .2 .1 1"/>
+        <geom type="ellipsoid" size="0.025 0.01 0.025" rgba=".8 .2 .1 1" group="4"/>
-        <tendon kind="main" stiffness="100" damping=".001"/>
+        <plugin plugin="mujoco.elasticity.shell">
-        <tendon kind="shear" stiffness="100" damping=".001"/>
+          <config key="poisson" value="0"/>
+          <config key="damping" value="0.001"/>
+          <config key="thickness" value="1e-2"/>
+          <!--Units are in Pa (SI)-->
+          <config key="young" value="3e6"/>
+        </plugin>
       </composite>
     </body>
   </worldbody>
+
+  <equality>
+    <connect body1="B0_0_0" anchor="0 0 0" solref="0.0002 1"/>
+  </equality>
 </mujoco>
 

model/plugin/elasticity/mannequin.xml

@@ -0,0 +1,171 @@
+<!-- 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.
+     You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+     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.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+-->
+
+<mujoco model="Mannequin">
+  <!-- Static humanoid model with all joints removed -->
+  <option timestep="0.005"/>
+
+  <visual>
+    <map force="0.1" zfar="30"/>
+    <rgba haze="0.15 0.25 0.35 1"/>
+    <global offwidth="2560" offheight="1440" elevation="-20" azimuth="120"/>
+  </visual>
+
+  <statistic center="0 0 0.7"/>
+
+  <asset>
+    <texture type="skybox" builtin="gradient" rgb1=".3 .5 .7" rgb2="0 0 0" width="32" height="512"/>
+    <texture name="body" type="cube" builtin="flat" mark="cross" width="128" height="128" rgb1="0.8 0.6 0.4" rgb2="0.8 0.6 0.4" markrgb="1 1 1" random="0.01"/>
+    <material name="body" texture="body" texuniform="true" rgba="0.8 0.6 .4 1"/>
+    <texture name="grid" type="2d" builtin="checker" width="512" height="512" rgb1=".1 .2 .3" rgb2=".2 .3 .4"/>
+    <material name="grid" texture="grid" texrepeat="1 1" texuniform="true" reflectance=".2"/>
+  </asset>
+
+  <default>
+    <motor ctrlrange="-1 1" ctrllimited="true"/>
+    <default class="body">
+
+      <!-- geoms -->
+      <geom type="capsule" condim="1" friction=".7" solimp=".9 .99 .003" solref=".015 1" material="body"/>
+      <default class="thigh">
+        <geom size=".06"/>
+      </default>
+      <default class="shin">
+        <geom fromto="0 0 0 0 0 -.3"  size=".049"/>
+      </default>
+      <default class="foot">
+        <geom size=".027"/>
+        <default class="foot1">
+          <geom fromto="-.07 -.01 0 .14 -.03 0"/>
+        </default>
+        <default class="foot2">
+          <geom fromto="-.07 .01 0 .14  .03 0"/>
+        </default>
+      </default>
+      <default class="arm_upper">
+        <geom size=".04"/>
+      </default>
+      <default class="arm_lower">
+        <geom size=".031"/>
+      </default>
+      <default class="hand">
+        <geom type="sphere" size=".04"/>
+      </default>
+
+      <!-- joints -->
+      <joint type="hinge" damping=".2" stiffness="1" armature=".01" limited="true" solimplimit="0 .99 .01"/>
+      <default class="joint_big">
+        <joint damping="5" stiffness="10"/>
+        <default class="hip_x">
+          <joint range="-30 10"/>
+        </default>
+        <default class="hip_z">
+          <joint range="-60 35"/>
+        </default>
+        <default class="hip_y">
+          <joint axis="0 1 0" range="-150 20"/>
+        </default>
+        <default class="joint_big_stiff">
+          <joint stiffness="20"/>
+        </default>
+      </default>
+      <default class="knee">
+        <joint pos="0 0 .02" axis="0 -1 0" range="-160 2"/>
+      </default>
+      <default class="ankle">
+        <joint range="-50 50"/>
+        <default class="ankle_y">
+          <joint pos="0 0 .08" axis="0 1 0" stiffness="6"/>
+        </default>
+        <default class="ankle_x">
+          <joint pos="0 0 .04" stiffness="3"/>
+        </default>
+      </default>
+      <default class="shoulder">
+        <joint range="-85 60"/>
+      </default>
+      <default class="elbow">
+        <joint range="-100 50" stiffness="0"/>
+      </default>
+    </default>
+  </default>
+
+  <worldbody>
+    <geom name="floor" size="0 0 .05" type="plane" material="grid" condim="3"/>
+    <light name="spotlight" mode="targetbodycom" target="torso" diffuse=".8 .8 .8" specular="0.3 0.3 0.3" pos="0 -6 4" cutoff="30"/>
+    <body name="torso" pos="0 0 1.282" childclass="body">
+      <light name="top" pos="0 0 2" mode="trackcom"/>
+      <camera name="back" pos="-3 0 1" xyaxes="0 -1 0 1 0 2" mode="trackcom"/>
+      <camera name="side" pos="0 -3 1" xyaxes="1 0 0 0 1 2" mode="trackcom"/>
+      <freejoint name="root"/>
+      <geom name="torso" fromto="0 -.07 0 0 .07 0" size=".07"/>
+      <geom name="waist_upper" fromto="-.01 -.06 -.12 -.01 .06 -.12" size=".06"/>
+      <body name="head" pos="0 0 .19">
+        <geom name="head" type="sphere" size=".09"/>
+        <camera name="egocentric" pos=".09 0 0" xyaxes="0 -1 0 .1 0 1" fovy="80"/>
+      </body>
+      <body name="waist_lower" pos="-.01 0 -.26">
+        <geom name="waist_lower" fromto="0 -.06 0 0 .06 0" size=".06"/>
+        <body name="pelvis" pos="0 0 -.165">
+          <geom name="butt" fromto="-.02 -.07 0 -.02 .07 0" size=".09"/>
+          <body name="thigh_right" pos="0 -.1 -.04">
+            <geom name="thigh_right" fromto="0 0 0 0 .01 -.34" class="thigh"/>
+            <body name="shin_right" pos="0 .01 -.4">
+              <geom name="shin_right" class="shin"/>
+              <body name="foot_right" pos="0 0 -.39">
+                <geom name="foot1_right" class="foot1"/>
+                <geom name="foot2_right" class="foot2"/>
+              </body>
+            </body>
+          </body>
+          <body name="thigh_left" pos="0 .1 -.04">
+            <geom name="thigh_left" fromto="0 0 0 0 -.01 -.34" class="thigh"/>
+            <body name="shin_left" pos="0 -.01 -.4">
+              <geom name="shin_left" fromto="0 0 0 0 0 -.3" class="shin"/>
+              <body name="foot_left" pos="0 0 -.39">
+                <geom name="foot1_left" class="foot1"/>
+                <geom name="foot2_left" class="foot2"/>
+              </body>
+            </body>
+          </body>
+        </body>
+      </body>
+      <body name="upper_arm_right" pos="0 -.17 .06">
+        <geom name="upper_arm_right" fromto="0 0 0 0 -.22 0" class="arm_upper"/>
+        <body name="lower_arm_right" pos="0 -.22 0">
+          <geom name="lower_arm_right" fromto=".01 .01 .01 0 -.21 -.05" class="arm_lower"/>
+          <body name="hand_right" pos="0 -.22 -.05">
+            <geom name="hand_right" zaxis="1 1 1" class="hand"/>
+          </body>
+        </body>
+      </body>
+      <body name="upper_arm_left" pos="0 .17 .06">
+        <geom name="upper_arm_left" fromto="0 0 0 0 .22 0" class="arm_upper"/>
+        <body name="lower_arm_left" pos="0 .22 0">
+          <geom name="lower_arm_left" fromto=".01 -.01 .01 0 .21 -.05" class="arm_lower"/>
+          <body name="hand_left" pos="0 .22 -.05">
+            <geom name="hand_left" zaxis="1 -1 1" class="hand"/>
+          </body>
+        </body>
+      </body>
+    </body>
+  </worldbody>
+
+  <contact>
+    <exclude body1="waist_lower" body2="thigh_right"/>
+    <exclude body1="waist_lower" body2="thigh_left"/>
+  </contact>
+
+</mujoco>

model/plugin/elasticity/plate.xml

@@ -0,0 +1,54 @@
+<!-- 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.
+     You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+     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.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+-->
+
+<mujoco model="Plate">
+  <include file="scene.xml"/>
+
+  <extension>
+    <plugin plugin="mujoco.elasticity.shell"/>
+  </extension>
+
+  <option solver="CG" tolerance="1e-6"/>
+
+  <size memory="10M"/>
+
+  <visual>
+    <map stiffness="100"/>
+  </visual>
+
+  <default>
+    <default class="wall">
+      <geom type="plane" size=".5 .5 .05"/>
+    </default>
+  </default>
+
+  <worldbody>
+    <body mocap="true" pos="-.1 .05 0" zaxis=".5 0 1">
+      <geom type="capsule" size=".1 .1" group="1"/>
+    </body>
+    <composite type="particle" count="16 16 1" spacing="0.05" offset="0 0 1">
+      <geom size=".02" rgba=".8 .2 .1 1" group="4" density="1000"
+            condim="3" solref="0.01 1" solimp=".95 .99 .0001"/>
+      <skin inflate="0.0001" rgba=".4 0 .3 1" subgrid="1"/>
+      <plugin plugin="mujoco.elasticity.shell">
+        <config key="poisson" value="0"/>
+        <config key="damping" value="0.001"/>
+        <config key="thickness" value="1e-2"/>
+        <!--Units are in Pa (SI)-->
+        <config key="young" value="3e7"/>
+      </plugin>
+    </composite>
+  </worldbody>
+</mujoco>