Default flex internal contacts to "false".

This function is unusual in the context of soft body simulations and has been a common gotcha for users, see e.g. #2500, #2079, #1900, and #1433. It should be used only if element inversion cannot be prevented otherwise.

PiperOrigin-RevId: 736822983
Change-Id: I76b0965c91c94dd88123826d218d7544ec37a88c

doc/XMLreference.rst

@@ -4041,7 +4041,7 @@ extensions specific to flexes.
 
 .. _flex-contact-internal:
 
-:at:`internal`: :at-val:`[true, false], "true"`
+:at:`internal`: :at-val:`[true, false], "false"`
    Enables or disables internal collisions which prevent flex self-penetration and element inversion. Note that flex
    elements that have shared vertices cannot collide (or else there will be permanent contacts). In 1D and 2D, internal
    collision checks rely on predefined vertex-element pairs, where the vertex is treated as a sphere with the same
@@ -4049,7 +4049,9 @@ extensions specific to flexes.
    flex. The pre-defined vertex-element pairs are generated by the model compiler automatically. In 3D, internal
    collision checks are performed within each tetraheron: each vertex is collided with the plane corresponding to the
    opposing triangle face (again using the flex radius). The resulting contacts are always created with condim 1, gap 0,
-   margin 0.
+   margin 0. Note that internal contacts modify the behavior implied by the :ref:`elasticity
+   parameters<flex-elasticity>` and is recommended only for flexes where element inversion cannot be prevented. The
+   default value of this attribute was changed from "true" to "false" in version 3.3.1.
 
 .. _flex-contact-selfcollide:
 

doc/changelog.rst

@@ -5,6 +5,12 @@ Changelog
 Upcoming version (not yet released)
 -----------------------------------
 
+.. admonition:: Breaking API changes
+   :class: attention
+
+   - The default value of the flag for toggling :ref:`internal flex contacts<flex-contact-internal>` was changed from
+     "true" to "false". This feature has proven to be counterintuitive for users.
+
 Bug fixes
 ^^^^^^^^^
 - :ref:`mj_jacDot` was missing a term that accounts for the motion of the point with respect to

src/user/user_init.c

@@ -229,7 +229,7 @@ void mjs_defaultFlex(mjsFlex* flex) {
   // set other defaults
   flex->dim = 2;
   flex->radius = 0.005;
-  flex->internal = 1;
+  flex->internal = 0;
   flex->selfcollide = mjFLEXSELF_AUTO;
   flex->activelayers = 1;
   flex->rgba[0] = flex->rgba[1] = flex->rgba[2] = 0.5f;

test/testdata/flex.xml

@@ -31,24 +31,27 @@
       <flexcomp name="f1" type="ellipsoid" rgba=".8 .2 .2 1" radius="0.001" count="4 4 4"
                 spacing=".025 .025 .025" dim="3" mass="1" dof="radial">
         <edge equality="true" solref="0.15 0.2" stiffness="0" damping="0"/>
+        <contact internal="true"/>
       </flexcomp>
     </body>
 
     <flexcomp name="f2" type="grid" rgba="1 1 0 1" radius="0.003" dim="2" pos="0 0 .1"
               zaxis="0 0 1" count="6 6 1" mass="1" spacing="0.02 0.03 0.04" material="grid">
       <edge equality="true" solref="0.15 0.2" stiffness="0" damping="0"/>
+      <contact internal="true"/>
       <pin id="0"/>
     </flexcomp>
 
     <flexcomp name="f3" type="grid" rgba=".6 .5 .1 1" radius="0.003" dim="3" pos="0 0 .3"
               zaxis="1 1 1" count="3 3 3" mass="1" spacing="0.02 0.03 0.04">
       <edge equality="true" solref="0.15 0.2" stiffness="0" damping="0"/>
+      <contact internal="true"/>
     </flexcomp>
 
     <flexcomp type="grid" count="8 8 8" spacing=".007 .007 .007" pos="0 0 1.5" dim="3"
               radius=".0001" rgba="0 .7 .7 1" mass=".25" name="softbody" dof="trilinear">
       <elasticity young="1e4" poisson="0.1" damping="0.01"/>
-      <contact selfcollide="none" internal="false"/>
+      <contact selfcollide="none"/>
     </flexcomp>
   </worldbody>