Add discrete elastic rod bending elasticity to 1D flexes.

1D flexes had no elasticity besides edge springs, so cables needed the cable plugin, whose chain of ball joints gives a dense mass matrix along the cable. With this change, a positive `young` on a 1D flex adds bending forces on the existing translational vertex dofs.

The model is a twist-free isotropic discrete elastic rod (Bergou et al. 2008). Every vertex with exactly two edges stores `k |κb|^2`, where κb is the discrete curvature binormal and `k = EI / (l0 + l1)` with I the second moment of area of the cross-section. The reference configuration (qpos0) must be straight: the compiler rejects any hinge bent by more than 1e-4 rad. Without material frames, an isotropic rod with a curved reference would only resist the curvature magnitude, so a planar arc could coil into a helix at no cost, and the force would not vanish through straight. Curved initial poses (coiled, draped) are set through qpos or keyframes and start with stored bending energy. Rods with a curved rest shape, such as coil springs, still need the cable plugin; curved rest shapes without material frames are left for a follow-up. Twist is assumed to relax instantly, which is exact unless both rod ends have constrained orientations. Damping acts on the rate of |κb| only, so rigid rotations are not damped.

Forces go through the generic flex scatter, so pinned and articulated attachments work, and 1D bending is compatible with edge equality constraints, and with mocap attachments when its damping is zero (mocap vertices have no velocity). Interpolated and rigid 1D flexes get no rod bending. Under the discrete integrator the bending is integrated implicitly with a PSD Gauss-Newton Hessian that is exact at rest; it is state dependent, so it rides the per-step stiffness path, not the constant 2D bending factor. Other integrators integrate it explicitly. The matrix-free operator applies J'(W(Jv)) per hinge; only the CSR assembly forms the 9x9 hinge stiffness.

The cross-section is selected by new `elasticity` attributes `section="circle|box"` and `sectionsize` (box half-sizes, stored as `mjsFlex.section`, of the new enum type `mjtFlexSection`, and `mjsFlex.sectionsize`). A circle uses the flex radius. A box uses the weak-axis `I = min(w h^3, h w^3) / 12`, because the bending model is isotropic. Both half-sizes are kept so that a later anisotropic model with material frames can use them without an API change. Decoupling the section from the radius also lets the collision/visual radius stay small, since flexcomp requires the spacing to be larger than the radius. The schema-generated files, references.h, the introspection enums and structs, and the wasm bindings are regenerated; APItypes.rst documents mjtFlexSection.

The connecting rod of `model/flex/mechanisms/slidercrank.xml` and the arm of `dipper.xml` are now rods (21 vertices each) instead of 12-cell trilinear 3D flexes, with the same mass and (weak-axis) cross-section and a flex radius of half the section height, so they look as thick; two point equalities per attachment replace the four-node clamps. The trilinear cells shear-locked, so `young` is raised 1.8x and 2.25x to keep the original deflections, and the Rayleigh damping coefficients are divided by the same factors to keep the physical damping. `cantilever.xml` keeps the 3D comparison and gets a fourth beam: a 1D rod with the same box cross-section and material as the soft 3D beam. Its edge equalities set their own solref/solimp, since the scene's `equality` default does not apply to flex edges. It settles at a tip deflection of 0.0746 m, versus 0.0752 m from Euler-Bernoulli and 0.069 m for the 3D quadratic beams.

Tests cover compiled data (circle and box), zero force at rest, force vs energy gradient, damping, the Hessian against finite differences, CSR assembly vs operator, a cantilever that matches Euler-Bernoulli tip deflection within 0.5% for both sections, XML save/reload of the section attributes, interpolated 1D flexes (no rod bending), the mocap/damping rule, the curved-reference compile error, a straight reference posed curved through qpos (the bending force straightens it), rigid 1D flexes (no rod bending, no straightness check), and loading and simulating the three mechanism models.

MJWarp implements 1D rod bending with the same model: passive forces and damping (`passive.py`), the hinge stiffness assembled into the effective-metric CSR and its matrix-free operator for non-simple attachments and the velocity shift (`derivative.py`, `passive.flex_rod_mul`), a per-hinge map built in `put_model` (new Model fields `nflexrodhinge`, `flex_rodhinge_map`, `has_flex_stiff_dim23`, with the MJX warp shims regenerated), and the C rule that rods do not require the discrete integrator (`forward.check_discrete`). `flex_test.py` compares forces, damping, disable flags, `efm_K_val`, `efm_c`, the `qacc_smooth` residual and 10-step trajectories (including slider-crank- and dipper-like rods and an articulated attachment) with MuJoCo C, for one and two worlds.

Under IPC, an elastic 1D flex is now a covered non-2D flex, so the sparse 2D metric factor falls back to blocks, like a 3D solid. `IpcTest.SparseFactorCoverage` keeps its inelastic cable case and adds an elastic rod case for this.

PiperOrigin-RevId: 1003076441
Change-Id: I689ad4cdcd8ad952e693027aeb0af2263183dba9

Author: quagla

doc/APIreference/APItypes.rst

@@ -973,6 +973,15 @@ Type of built-in procedural mesh.
 
 .. mujoco-include:: mjtMeshBuiltin
 
+.. _mjtFlexSection:
+
+mjtFlexSection
+~~~~~~~~~~~~~~
+
+Cross-section of 1D flex :ref:`elasticity<flex-elasticity>`, see :ref:`section<flex-elasticity-section>`.
+
+.. mujoco-include:: mjtFlexSection
+
 .. _mjtConflict:
 
 mjtConflict

doc/XMLreference.rst

@@ -4202,9 +4202,11 @@ element is used to adjust the properties of all edges in the flex.
 .. _flexcomp-elasticity-damping:
 .. _flexcomp-elasticity-thickness:
 .. _flexcomp-elasticity-elastic2d:
+.. _flexcomp-elasticity-section:
+.. _flexcomp-elasticity-sectionsize:
 
 .. |body/flexcomp/elasticity attrib list| replace::
-   :at:`young`, :at:`poisson`, :at:`damping`, :at:`thickness`, :at:`elastic2d`
+   :at:`young`, :at:`poisson`, :at:`damping`, :at:`thickness`, :at:`elastic2d`, :at:`section`, :at:`sectionsize`
 
 |body/flexcomp/elasticity attrib list|
    Same as in :ref:`flex/elasticity<flex-elasticity>`.
@@ -4743,6 +4745,22 @@ to large displacements (finite rotations) and small strains, since it uses a non
 stress-strain relationship. See also :ref:`deformable <CDeformable>` objects and `this model
 <https://github.com/google-deepmind/mujoco/blob/main/model/flex/floppy.xml>`__.
 
+For 1D flexes, elasticity is a twist-free, isotropic `discrete elastic rod
+<https://www.cs.columbia.edu/cg/pdfs/143-rods.pdf>`__ bending model with the cross-section given by
+:ref:`section<flex-elasticity-section>`. Every vertex shared by exactly two edges stores the energy
+:math:`k |\kappa b|^2`, where :math:`\kappa b` is the discrete curvature binormal and
+:math:`k = E I / (\ell_0 + \ell_1)`, with :math:`I` the second moment of area of the cross-section and
+:math:`\ell_{0,1}` the reference lengths of the two edges. The reference configuration ``qpos0`` must be straight: a
+compiler error is raised if any such vertex is bent by more than :math:`10^{-4}` rad, since without material frames an
+isotropic rod with a curved reference would only resist the magnitude of its curvature, not its direction. A curved
+initial pose, e.g. coiled or draped, can be set with ``qpos`` or a :ref:`keyframe<keyframe>`; the rod then starts with
+stored bending energy and is pushed toward straightening. Rods with a curved rest shape, such as coil springs, can use
+the :ref:`cable<CComposite>` composite instead. Twist is assumed to relax instantly, which is exact unless the
+orientation of both ends of the rod is constrained. Stretching is not included; use :ref:`edge<flex-edge>` constraints
+or stiffness instead. Rod bending is integrated implicitly by the :ref:`discrete<option-integrator>` integrator, using a
+positive semi-definite approximation of its Hessian, and explicitly by all other integrators. It is not supported by
+:ref:`dof<body-flexcomp-dof>` **trilinear** and **quadratic**.
+
 .. _flex-elasticity-young:
 
 :at:`young`: :at-val:`real(1), "0"`
@@ -4781,7 +4799,22 @@ stress-strain relationship. See also :ref:`deformable <CDeformable>` objects and
    With the :ref:`discrete<option-integrator>` integrator, use :ref:`solver<option-solver>` **CG** for general attachments.
    Newton supports fixed attachments and independent slide bodies with local positive X, Y and Z joints in that order
    and fixed ancestors. Mocap attachments are not supported for non-rigid flexes with elasticity because mocap poses do
-   not provide velocities for elastic damping.
+   not provide velocities for elastic damping, except for 1D flexes with zero :ref:`damping<flex-elasticity-damping>`.
+
+.. _flex-elasticity-section:
+
+:at:`section`: :at-val:`[circle, box], "circle"`
+   Cross-section of 1D flexes, used to compute the second moment of area :math:`I` of the bending stiffness. "circle":
+   :math:`I = \pi r^4 / 4`, where :math:`r` is the flex :ref:`radius <deformable-flex-radius>`. "box": rectangle with
+   half-sizes given by :ref:`sectionsize<flex-elasticity-sectionsize>`. Since the bending model is isotropic, a box uses
+   the second moment of area of its weak axis, :math:`I = \min(w h^3, h w^3) / 12`, where :math:`w, h` are the full
+   sizes. Collisions and rendering always use the flex radius.
+
+.. _flex-elasticity-sectionsize:
+
+:at:`sectionsize`: :at-val:`real(2), "0 0"`
+   Half-sizes of the "box" cross-section of 1D flexes, units of length. Both values must be positive when
+   :ref:`section<flex-elasticity-section>` is "box"; ignored otherwise.
 
 .. _flex-contact:
 

doc/XMLschema.rst

@@ -1580,6 +1580,12 @@
                .. grid-item::
                   :ref:`elastic2d<flexcomp-elasticity-elastic2d>`
 
+               .. grid-item::
+                  :ref:`section<flexcomp-elasticity-section>`
+
+               .. grid-item::
+                  :ref:`sectionsize<flexcomp-elasticity-sectionsize>`
+
 
          .. dropdown:: :ref:`contact<flexcomp-contact>` :octicon:`dot`
 
@@ -1802,6 +1808,12 @@
                .. grid-item::
                   :ref:`elastic2d<flex-elasticity-elastic2d>`
 
+               .. grid-item::
+                  :ref:`section<flex-elasticity-section>`
+
+               .. grid-item::
+                  :ref:`sectionsize<flex-elasticity-sectionsize>`
+
 
       .. dropdown:: :ref:`skin<deformable-skin>` |*|
 

doc/XMLunits.rst

@@ -574,6 +574,8 @@
      - :math:`T`
    * - :ref:`flexcomp/elasticity/thickness<flexcomp-elasticity-thickness>`
      - :math:`L`
+   * - :ref:`flexcomp/elasticity/sectionsize<flexcomp-elasticity-sectionsize>`
+     - :math:`L`
    * - :ref:`flexcomp/contact/friction<flexcomp-contact-friction>`
      - :math:`1,\ L,\ L`
    * - :ref:`flexcomp/contact/solmix<flexcomp-contact-solmix>`

doc/changelog.rst

@@ -7,6 +7,15 @@ Upcoming Version (not yet released)
 
 Engine
 ^^^^^^
+- Added bending :ref:`elasticity<flex-elasticity>` for 1D flexes, using a twist-free isotropic discrete elastic rod
+  model. The cross-section is selected with the new :ref:`section<flex-elasticity-section>` attribute: a circle of the
+  flex radius, or a box with half-sizes :ref:`sectionsize<flex-elasticity-sectionsize>` that uses the stiffness of its
+  weak axis. It is enabled by a positive :ref:`young<flex-elasticity-young>` modulus, requires a straight reference
+  configuration (curved initial poses can be set with ``qpos`` or keyframes), is compatible with edge equality
+  constraints, and is integrated implicitly by the :ref:`discrete<option-integrator>` integrator. Previously ``young``
+  was ignored for 1D flexes: existing models that set it now bend, and fail to compile if the cross-section is
+  degenerate (zero radius with the default circle section), if a vertex joins a zero-length edge, or if the rod is not
+  straight.
 - Trees marked :ref:`sleep="init"<body-sleep>` which cannot be put to sleep now cause a warning rather than an error,
   and start awake. See :ref:`Sleeping<siSleepSleeping>` for details.
 - Added single-shot :ref:`multicontact<coMultiCCD>` for geoms with positive contact :ref:`margins<body-geom-margin>`.
@@ -92,6 +101,12 @@ Bug fixes
 - Fixed a bug in the Filament renderer where textures did not allocate mipmap levels, preventing mipmap generation and
   causing minification aliasing, and where sRGB textures were unconditionally excluded from mipmapping.
 
+Models
+^^^^^^
+- The `elastic mechanism <https://github.com/google-deepmind/mujoco/tree/main/model/flex/mechanisms/>`__ example models
+  now use 1D flex rods: the cantilever comparison of quadratic flexes adds a rod, and the elastic slider-crank and the
+  tendon-loaded dipper arm are built from rods.
+
 Version 3.16.0 (October 14, 2026)
 ---------------------------------
 

doc/includes/references.h

@@ -1712,6 +1712,10 @@ typedef enum mjtMeshBuiltin {      // type of built-in procedural mesh
   mjMESH_BUILTIN_SQUARE,           // square
   mjMESH_BUILTIN_DISC              // disc
 } mjtMeshBuiltin;
+typedef enum mjtFlexSection {      // cross-section of 1D flex elasticity
+  mjFLEXSECTION_CIRCLE = 0,        // circle of the flex radius
+  mjFLEXSECTION_BOX                // box with half-sizes sectionsize
+} mjtFlexSection;
 typedef enum mjtBuiltin {          // type of built-in procedural texture
   mjBUILTIN_NONE = 0,              // no built-in texture
   mjBUILTIN_GRADIENT,              // gradient: rgb1->rgb2
@@ -2113,6 +2117,8 @@ typedef struct mjsFlex_ {          // flex specification
   int elastic2d;                   // 2D passive forces; 0: none, 1: bending, 2: stretching, 3: both
   int elastic3d;  // experimental 3D material (mjSpec only); 0: Saint
                   // Venant-Kirchhoff, 1: Stable Neo-Hookean
+  mjtFlexSection section;          // 1D cross-section (mjtFlexSection)
+  double sectionsize[2];           // 1D box cross-section half-sizes
   int cellcount[3];                // grid cell count for finite cell method
   int order;                       // interpolation order (1: trilinear, 2: quadratic)
 

include/mujoco/mjspec.h

@@ -89,6 +89,12 @@ typedef enum mjtMeshBuiltin {      // type of built-in procedural mesh
 } mjtMeshBuiltin;
 
 
+typedef enum mjtFlexSection {      // cross-section of 1D flex elasticity
+  mjFLEXSECTION_CIRCLE = 0,        // circle of the flex radius
+  mjFLEXSECTION_BOX                // box with half-sizes sectionsize
+} mjtFlexSection;
+
+
 typedef enum mjtBuiltin {          // type of built-in procedural texture
   mjBUILTIN_NONE = 0,              // no built-in texture
   mjBUILTIN_GRADIENT,              // gradient: rgb1->rgb2
@@ -534,6 +540,8 @@ typedef struct mjsFlex_ {          // flex specification
   int elastic2d;                   // 2D passive forces; 0: none, 1: bending, 2: stretching, 3: both
   int elastic3d;  // experimental 3D material (mjSpec only); 0: Saint
                   // Venant-Kirchhoff, 1: Stable Neo-Hookean
+  mjtFlexSection section;          // 1D cross-section (mjtFlexSection)
+  double sectionsize[2];           // 1D box cross-section half-sizes
   int cellcount[3];                // grid cell count for finite cell method
   int order;                       // interpolation order (1: trilinear, 2: quadratic)
 

include/mujoco/mjspecmacro.h

@@ -277,44 +277,46 @@
 
 #define MJSFLEX_FIELDS                           \
     X   ( mjsElement*,   element,       1      ) \
-    X   ( int,           contype,       1      ) \
-    X   ( int,           conaffinity,   1      ) \
-    X   ( int,           condim,        1      ) \
-    X   ( int,           priority,      1      ) \
-    XVEC( double,        friction,      3      ) \
-    X   ( double,        solmix,        1      ) \
-    XVEC( mjtNum,        solref,        mjNREF ) \
-    XVEC( mjtNum,        solimp,        mjNIMP ) \
-    X   ( double,        margin,        1      ) \
-    X   ( double,        gap,           1      ) \
-    X   ( int,           dim,           1      ) \
-    X   ( double,        radius,        1      ) \
-    XVEC( double,        size,          3      ) \
-    X   ( mjtBool,       flatskin,      1      ) \
-    X   ( mjtFlexSelf,   selfcollide,   1      ) \
-    X   ( int,           passive,       1      ) \
-    X   ( int,           activelayers,  1      ) \
-    X   ( int,           group,         1      ) \
-    X   ( double,        edgestiffness, 1      ) \
-    X   ( double,        edgedamping,   1      ) \
-    XVEC( float,         rgba,          4      ) \
-    X   ( mjString*,     material,      1      ) \
-    X   ( double,        young,         1      ) \
-    X   ( double,        poisson,       1      ) \
-    X   ( double,        damping,       1      ) \
-    X   ( double,        thickness,     1      ) \
-    X   ( int,           elastic2d,     1      ) \
-    X   ( int,           elastic3d,     1      ) \
-    XVEC( int,           cellcount,     3      ) \
-    X   ( int,           order,         1      ) \
-    X   ( mjStringVec*,  nodebody,      1      ) \
-    X   ( mjStringVec*,  vertbody,      1      ) \
-    X   ( mjDoubleVec*,  node,          1      ) \
-    X   ( mjDoubleVec*,  vert,          1      ) \
-    X   ( mjIntVec*,     elem,          1      ) \
-    X   ( mjFloatVec*,   texcoord,      1      ) \
-    X   ( mjIntVec*,     elemtexcoord,  1      ) \
-    X   ( mjString*,     info,          1      )
+    X   ( int,            contype,       1      ) \
+    X   ( int,            conaffinity,   1      ) \
+    X   ( int,            condim,        1      ) \
+    X   ( int,            priority,      1      ) \
+    XVEC( double,         friction,      3      ) \
+    X   ( double,         solmix,        1      ) \
+    XVEC( mjtNum,         solref,        mjNREF ) \
+    XVEC( mjtNum,         solimp,        mjNIMP ) \
+    X   ( double,         margin,        1      ) \
+    X   ( double,         gap,           1      ) \
+    X   ( int,            dim,           1      ) \
+    X   ( double,         radius,        1      ) \
+    XVEC( double,         size,          3      ) \
+    X   ( mjtBool,        flatskin,      1      ) \
+    X   ( mjtFlexSelf,    selfcollide,   1      ) \
+    X   ( int,            passive,       1      ) \
+    X   ( int,            activelayers,  1      ) \
+    X   ( int,            group,         1      ) \
+    X   ( double,         edgestiffness, 1      ) \
+    X   ( double,         edgedamping,   1      ) \
+    XVEC( float,          rgba,          4      ) \
+    X   ( mjString*,      material,      1      ) \
+    X   ( double,         young,         1      ) \
+    X   ( double,         poisson,       1      ) \
+    X   ( double,         damping,       1      ) \
+    X   ( double,         thickness,     1      ) \
+    X   ( int,            elastic2d,     1      ) \
+    X   ( int,            elastic3d,     1      ) \
+    X   ( mjtFlexSection, section,       1      ) \
+    XVEC( double,         sectionsize,   2      ) \
+    XVEC( int,            cellcount,     3      ) \
+    X   ( int,            order,         1      ) \
+    X   ( mjStringVec*,   nodebody,      1      ) \
+    X   ( mjStringVec*,   vertbody,      1      ) \
+    X   ( mjDoubleVec*,   node,          1      ) \
+    X   ( mjDoubleVec*,   vert,          1      ) \
+    X   ( mjIntVec*,      elem,          1      ) \
+    X   ( mjFloatVec*,    texcoord,      1      ) \
+    X   ( mjIntVec*,      elemtexcoord,  1      ) \
+    X   ( mjString*,      info,          1      )
 
 
 //-------------------------------- mjsMesh ---------------------------------------------------------