Integrate passive flex contact implicitly

Contact of a flex with `passive` collisions enabled was applied as an
explicit spring of fixed stiffness 1e4, which the timestep bounds: any
stiffness worth having oscillates faster than the step can resolve, so
the force was too soft to keep sheets apart and interpenetration was
routine.

Carry its curvature in the effective metric M + K instead, alongside the
flex's own stretch and bending stiffness. The contact block k*J^T*J is
appended to the per-vertex candidate list already assembled for the flex
stencils, so it costs additional entries in an existing matrix rather
than a new one, and the accompanying shift -h*K*v is what damps the
stiff modes. At a 2 ms timestep this holds roughly 50x the stiffness an
explicit force of the same step could.

With the timestep no longer setting the bound, the stiffness is chosen
as a natural frequency scaled by the participating vertex mass rather
than left at a fixed 1e4, so one value suits models of any scale.

Passive handling is scoped to contacts whose every dof is a flex vertex
carried by the metric: flex against flex, flex against itself, and flex
against static geometry, which contributes no dofs of its own. For those
the Hessian is assembled in full. Contact with a body that can move
would have that body's dofs dropped from it, and is left on the
constraint solver.

The feature now requires an integrator whose constraint solve runs in
that metric, and is rejected with an error otherwise.

Add model/flex/drape.xml as the example model, replacing sphere_passive,
whose contacts no longer demonstrated the feature.

Author: smallquail

doc/XMLreference.rst

@@ -4550,9 +4550,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

@@ -46,6 +46,17 @@ 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 M + K rather than applied as an explicit spring, and so can
+     be far stiffer than the timestep would otherwise permit -- at a 2 ms timestep, roughly 50x what an explicit
+     force of the same step could hold. Being a penalty force it still does not guarantee non-penetration. A model
+     using passive collisions changes in three ways and should be re-checked: the feature now requires an integrator
+     whose constraint solve runs in that metric (:at:`implicit` or :at:`implicitfast` with the CG solver, pyramidal
+     cones and sleep disabled) and is rejected with an error otherwise; passive handling now covers contact of such a
+     flex with another flex, with itself, and with static geometry, while contact with a moving body returns to the
+     constraint solver and gains friction; and the stiffness is no longer a fixed 1e4 but a natural frequency scaled
+     by the participating vertex mass, which is considerably stiffer for typical models.
+
    - 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
@@ -57,6 +68,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

model/flex/drape.xml

@@ -0,0 +1,52 @@
+<!-- Copyright 2026 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="Drape">
+  <include file="scene.xml"/>
+
+  <!-- Three cloths dropped over a sphere. Every contact here is handled by the passive path: cloth
+       against cloth, each cloth against itself, and cloth against the sphere, which is static and
+       so contributes no dofs of its own. Their stiffness is carried implicitly by the effective
+       metric, which is why the sheets rest on each other without interpenetrating. -->
+
+  <!-- The metric solve for qacc_smooth is iterative and its blocks do not see the vertex-to-vertex
+       coupling that contact introduces, so a contact-rich scene like this one needs a larger
+       iteration budget than the default to converge it. -->
+  <option timestep="0.002" solver="CG" tolerance="1e-6" iterations="400" integrator="implicitfast"/>
+
+  <size memory="50M"/>
+
+  <worldbody>
+    <geom name="ball" type="sphere" size=".3" pos="0 0 .3" rgba=".45 .45 .5 1"/>
+
+    <flexcomp type="grid" count="13 13 1" spacing=".055 .055 .055" pos="0 0 .68"
+              radius=".004" mass=".25" name="cloth1" dim="2" rgba=".85 .35 .25 1">
+      <contact selfcollide="auto" passive="true" solref="0.01 1" solimp=".95 .99 .0001"/>
+      <elasticity young="2e4" poisson=".2" thickness="1e-3" elastic2d="both" damping="1e-4"/>
+    </flexcomp>
+
+    <flexcomp type="grid" count="13 13 1" spacing=".055 .055 .055" pos=".06 -.04 .78"
+              radius=".004" mass=".25" name="cloth2" dim="2" rgba=".25 .55 .8 1">
+      <contact selfcollide="auto" passive="true" solref="0.01 1" solimp=".95 .99 .0001"/>
+      <elasticity young="2e4" poisson=".2" thickness="1e-3" elastic2d="both" damping="1e-4"/>
+    </flexcomp>
+
+    <flexcomp type="grid" count="13 13 1" spacing=".055 .055 .055" pos="-.05 .05 .88"
+              radius=".004" mass=".25" name="cloth3" dim="2" rgba=".95 .8 .3 1">
+      <contact selfcollide="auto" passive="true" solref="0.01 1" solimp=".95 .99 .0001"/>
+      <elasticity young="2e4" poisson=".2" thickness="1e-3" elastic2d="both" damping="1e-4"/>
+    </flexcomp>
+  </worldbody>
+</mujoco>

model/flex/sphere_passive.xml

@@ -2549,11 +2549,26 @@ static int mj_nc(const mjModel* m, mjData* d, int* nnz) {
   for (int i=0; i < ncon; i++) {
     mjContact* con = d->contact + i;
 
-    // skip if passive
-    if ((con->flex[0] > -1 && m->flex_passive[con->flex[0]]) ||
-        (con->flex[1] > -1 && m->flex_passive[con->flex[1]])) {
-      con->efc_address = -1;
-      con->exclude = 4;
+    // Passive handling covers flex-flex contact, self-collision included, and contact between a
+    // flex and STATIC geometry. What those have in common is that every dof the contact touches is
+    // a flex vertex carried by the effective metric -- a static geom has none -- so the Hessian
+    // k*J^T*J is assembled in full rather than truncated. A flex against a MOVING body keeps the
+    // constraint path: its dofs would be dropped from the Hessian, and the passive force is a
+    // normal penalty with no friction cone, which is the wrong trade where a gripper closes on
+    // cloth. A contact is passive if either flex asks for it.
+    {
+      int f0 = con->flex[0], f1 = con->flex[1];
+      int wants = (f0 > -1 && m->flex_passive[f0]) || (f1 > -1 && m->flex_passive[f1]);
+      int ok = (f0 > -1 && f1 > -1);   // flex-flex, or a flex with itself
+      for (int s = 0; s < 2 && !ok; s++) {
+        if (con->flex[s] < 0 && con->geom[s] > -1) {
+          ok = (m->body_weldid[m->geom_bodyid[con->geom[s]]] == 0);   // welded to the world
+        }
+      }
+      if (wants && ok) {
+        con->efc_address = -1;
+        con->exclude = 4;
+      }
     }
 
     // skip if excluded