Merge pull request #3466 from smallquail:flex-implicit-contact

PiperOrigin-RevId: 960804180
Change-Id: Ic3eb203ca0d9cf19c9043b46127db342678d94f9

doc/XMLreference.rst

@@ -4543,9 +4543,24 @@ extensions specific to flexes.
 .. _flex-contact-passive:
 
 :at:`passive`: :at-val:`[true, false], "false"`
-   When enabled, the contact is not added to the contact solver but it is instead used to compute passive
-   (spring-damper) contact forces. All contacts, regardless of the specified condim, are frictionless (condim 1). This
-   is an experimental feature.
+   When enabled, contact of this flex with another flex, with itself, or with static geometry is not added to the
+   contact solver and is instead applied as a passive normal force. Contact with a body that can move is left on the
+   constraint solver.
+
+   Friction is not modelled on this path: every passive contact is frictionless (condim 1) regardless of the
+   specified condim, and the force is purely normal. A flex therefore slides freely over static geometry, so a cloth
+   will not stay draped over a fixed shape and will not come to rest on a slope. Where friction matters more than
+   non-penetration, leave this option off.
+
+   The force is a penalty on penetration depth whose stiffness is chosen as a natural frequency scaled by the
+   participating vertex mass, so a single value is appropriate across model scales; it is not user-specified. That
+   stiffness is integrated implicitly, its curvature being carried by the effective metric, and is therefore far
+   stiffer than an explicit force at the same timestep could be. It follows that the feature requires an integrator
+   whose constraint solve runs in that metric: :at:`implicit` or :at:`implicitfast` with the CG solver, pyramidal
+   friction cones and sleep disabled. A model requesting passive flex collisions otherwise is rejected with an error.
+
+   Being a penalty force, it does not guarantee non-penetration: a thin flex moving fast enough to cross another
+   within one step will pass through it. This is an experimental feature.
 
 
 .. _deformable-skin:

doc/changelog.rst

@@ -53,6 +53,14 @@ Engine
 .. admonition:: Breaking API changes
    :class: attention
 
+   - Contacts of a flex with :ref:`passive<flexcomp-contact-passive>` collisions are now integrated implicitly:
+     their stiffness is carried by the effective metric rather than applied as an explicit spring, and can be far
+     stiffer than the timestep would otherwise permit. Models using passive collisions should be re-checked: the
+     feature now requires :at:`implicit` or :at:`implicitfast` with the CG solver, pyramidal cones and sleep
+     disabled; passive handling covers flex-flex, self-, and static-geometry contact, while contact with a moving
+     body stays on the constraint solver; and the stiffness is now a mass-scaled natural frequency rather than a
+     fixed 1e4.
+
    - Removed ``mjData.efm_L_rownnz``, ``mjData.efm_L_rowadr`` and ``mjData.efm_L_colind``. They described the sparsity
      of the effective-metric Cholesky factor, which no longer exists; ``mjData.efm_L`` now holds dense 3x3 blocks,
      9 numbers per covered vertex. ``mjData.efm_active`` no longer takes the value 2: nothing selects a solve path on
@@ -70,6 +78,10 @@ Engine
 Models
 ^^^^^^
 
+- Added `drape <https://github.com/google-deepmind/mujoco/blob/main/model/flex/drape.xml>`__ example model: three
+  cloths draped over a sphere, demonstrating :ref:`passive<flex-contact-passive>` collisions. It replaces the
+  ``sphere_passive`` model, which has been removed.
+
 - Added `bag <https://github.com/google-deepmind/mujoco/blob/main/model/flex/bag.xml>`__ example model: a cloth bag,
   held open by pinning the ring of vertices around its mouth, catching the standard humanoid dropped in from above.
   Unlike the poncho models, which are bending-only, this model exercises the 2D