From 147efb5192ce9e3a9e4ca5c6e87a57ef3eb2121b Mon Sep 17 00:00:00 2001
From: Saran Tunyasuvunakool <stunya@google.com>
Date: Tue, 15 Mar 2022 15:45:08 +0000
Subject: [PATCH] Add 2.1.2 release date and document experimental fluid
 interaction model in the changelog.

PiperOrigin-RevId: 434760829
Change-Id: I71d3ca9864890927d2945c73767511e5e973be73
---
 doc/APIreference.rst |  3 +++
 doc/XMLreference.rst | 28 +++++++++++++++++++++++++++-
 doc/changelog.rst    | 14 ++++++++++----
 3 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/doc/APIreference.rst b/doc/APIreference.rst
index f5711c6f..f8d9fe5c 100644
--- a/doc/APIreference.rst
+++ b/doc/APIreference.rst
@@ -1505,6 +1505,7 @@ mjModel
        mjtNum*   geom_friction;        // friction for (slide, spin, roll)         (ngeom x 3)
        mjtNum*   geom_margin;          // detect contact if dist<margin            (ngeom x 1)
        mjtNum*   geom_gap;             // include in solver if dist<margin-gap     (ngeom x 1)
+       mjtNum*   geom_fluid;           // fluid interaction parameters             (ngeom x mjNFLUID)
        mjtNum*   geom_user;            // user data                                (ngeom x nuser_geom)
        float*    geom_rgba;            // rgba when material is omitted            (ngeom x 4)
 
@@ -3170,6 +3171,8 @@ Numeric constants
 | mjNBIAS          | 10     | The maximal number of real-valued parameters used to define the bias of each actuator. |
 |                  |        | Determines the size of mjModel.actuator_biasprm.                                       |
 +------------------+--------+----------------------------------------------------------------------------------------+
+| mjNFLUID         | 12     | The number of per-geom fluid interaction parameters required by the ellipsoidal model. |
++------------------+--------+----------------------------------------------------------------------------------------+
 | mjNREF           | 2      | The maximal number of real-valued parameters used to define the reference acceleration |
 |                  |        | of each scalar constraint. Determines the size of all mjModel.XXX_solref fields.       |
 +------------------+--------+----------------------------------------------------------------------------------------+
diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst
index 3af496b6..34d4b600 100644
--- a/doc/XMLreference.rst
+++ b/doc/XMLreference.rst
@@ -274,7 +274,7 @@ XML schema
 |                          |    |    +-------------------------+-------------------------+-------------------------+ |
 |                          |    |    | :at:`mesh`              | :at:`fitscale`          | :at:`rgba`              | |
 |                          |    |    +-------------------------+-------------------------+-------------------------+ |
-|                          |    |    | :at:`user`              |                         |                         | |
+|                          |    |    | :at:`user`              | :at:`fluidshape`        | :at:`fluidcoef`         | |
 |                          |    |    +-------------------------+-------------------------+-------------------------+ |
 +--------------------------+----+------------------------------------------------------------------------------------+
 | |_2|:el:`site`           | ?  | .. table::                                                                         |
@@ -609,6 +609,8 @@ XML schema
 |                          |    |    +-------------------------+-------------------------+-------------------------+ |
 |                          |    |    | :at:`fitscale`          | :at:`rgba`              | :at:`user`              | |
 |                          |    |    +-------------------------+-------------------------+-------------------------+ |
+|                          |    |    | :at:`fluidshape`        | :at:`fluidcoef`         |                         | |
+|                          |    |    +-------------------------+-------------------------+-------------------------+ |
 +--------------------------+----+------------------------------------------------------------------------------------+
 | |_2|:el:`site`           | \* | .. table::                                                                         |
 |                          |    |    :class: mjcf-attributes                                                         |
@@ -3327,6 +3329,30 @@ mjModel. If the XML model is saved, it will appear as a regular joint of type "f
    This attribute is used only when a primitive geometric type is being fitted to a mesh asset. The scale specified here
    is relative to the output of the automated fitting procedure. The default value of 1 leaves the result unchanged, a
    value of 2 makes all sizes of the fitted geom two times larger.
+:at:`fluidshape`: :at-val:`[none, ellipsoid], "none"`
+   "ellipsoid" Activates geom-level stateless 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.
+:at:`fluidcoef`: :at-val:`real(5), "0.5 0.25 1.5 1.0 1.0"`
+   Dimensionless coefficients of fluid interaction model, as follows.
+
+
+.. table::
+   :align: left
+
+   +--------+-----------------------------+----------+
+   | 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      |
+   +--------+-----------------------------+----------+
+
 :at:`user`: :at-val:`real(nuser_geom), "0 0 ..."`
    See :ref:`CUser`.
 
diff --git a/doc/changelog.rst b/doc/changelog.rst
index bbf55035..d8e9e766 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -2,8 +2,8 @@
 Changelog
 =========
 
-Version 2.1.2 (Date TBD, 2022)
-------------------------------
+Version 2.1.2 (Mar. 15, 2022)
+-----------------------------
 
 New modules
 ^^^^^^^^^^^
@@ -64,10 +64,16 @@ General
    perspective of C and C++, this is a non-change since array types in function signatures decay to pointer types.
    However, it allows autogenerated code to be aware of expected input shapes.
 
+#. Experimental stateless fluid interaction model. As described :ref:`here <gePassive>`, fluid forces use sizes computed
+   from body inertia. While sometimes convenient, this is very rarely a good approximation. In the new model forces act
+   on geoms, rather than bodies, and have a several user-settable parameters. The model is activated by setting a new
+   attribute: ``<geom fluidshape="ellipsoid"/>``. The parameters are described succinctly :ref:`here<geom>`, but we
+   leave a full description or the model and its parameters to when this feature leaves experimental status.
+
 Bug Fixes
 ^^^^^^^^^
 
-15. ``mj_loadXML`` and ``mj_saveLastXML`` are now locale-independent. The Unity plugin should now work correctly for
+16. ``mj_loadXML`` and ``mj_saveLastXML`` are now locale-independent. The Unity plugin should now work correctly for
     users whose system locales use commas as decimal separators.
 #.  XML assets in VFS no longer need to end in a null character. Instead, the file size is determined by the size
     parameter of the corresponding VFS entry.
@@ -77,7 +83,7 @@ Bug Fixes
 Binary build
 ^^^^^^^^^^^^
 
-18. Windows binaries are now built with Clang.
+20. Windows binaries are now built with Clang.
 
 Version 2.1.1 (Dec. 16, 2021)
 -----------------------------