Flex Feature Parity Tracker: MuJoCo → MuJoCo Warp

[quagla]

This issue tracks the implementation status of MuJoCo's flexible object (flex) features in MuJoCo Warp. Flex enables simulation of deformable objects — ropes (dim=1), cloth/shells (dim=2), and volumetric soft bodies (dim=3).

All <flexcomp> types (grid, box, mesh, gmsh, direct, ellipsoid, disc, circle, cylinder, square) are processed by MuJoCo's C compiler before the model is transferred to Warp, so model generation works for all types.

Status Legend

Icon	Meaning
✅	Implemented — working in MuJoCo Warp
🔲	Planned — will be implemented
🚧	WIP — work in progress
❌	Won't implement — out of scope for MuJoCo Warp

---

1. DOF Parametrization

Feature	Status	Notes	Example Models
dof="full"	✅	3 translational DOFs per vertex	jelly.xml, floppy.xml, sphere_full.xml
dof="radial"	✅	1 radial DOF per vertex	sphere_radial.xml
dof="trilinear"	🔲	24 DOFs (8 bounding-box corners × 3). Requires flex_interp kernel dispatch.	trilinear.xml, gripper_trilinear.xml, sphere_trilinear.xml
dof="quadratic"	🔲	81 DOFs (quadratic interpolation). Requires flex_interp kernel dispatch.	quadratic.xml, bunny_quadratic.xml
dof="2d"	✅	2 DOFs per vertex (X-Y plane)	—

---

2. Kinematics

Feature	Status	Notes
Vertex world positions (flexvert_xpos)	✅	smooth._flex_vertices kernel
Edge lengths (flexedge_length)	✅	smooth._flex_edges kernel
Edge velocities (flexedge_velocity)	✅	Via Jacobian products
Sparse edge Jacobian (flexedge_J)	✅	—
Trilinear/quadratic vertex interpolation	🔲	Requires flex_interp support in smooth.py

---

3. Passive Forces

Feature	Status	Notes	Example Models
Elasticity (elasticity/@young, @poisson)	✅	Green-Lagrange strain, all dims. passive._flex_elasticity kernel	jelly.xml, press.xml
Rayleigh damping (elasticity/@damping)	✅	Implicit via flex_damping / timestep	—
Shell thickness (elasticity/@thickness)	✅	Baked into stiffness at compile time (dim=2)	—
2D elastic modes (elasticity/@elastic2d)	🔲	none/bend/stretch/both. Requires trilinear support.	hollow_vs_solid.xml
Edge stiffness (edge/@stiffness)	✅	1D edge springs	plate.xml
Edge damping (edge/@damping)	✅	Edge velocity damping	—
Bending forces (dim=2)	✅	Linear + nonlinear (cross-product). passive._flex_bending	flag.xml, plate.xml
Trilinear/quadratic implicit stiffness	🔲	flex_interp integration + implicit solver terms	trilinear.xml

---

4. Collision Detection

Feature	Status	Notes	Example Models
Geom-flex (dim=2): Sphere, Capsule, Box, Cylinder vs triangles	✅	collision_flex._flex_narrowphase_dim2	pinch.xml, gripper_2d.xml
Geom-flex (dim=3): Sphere, Capsule, Box, Cylinder vs shell faces	✅	collision_flex._flex_narrowphase_dim3	floppy.xml, gripper.xml
Plane-flex collision	✅	Per-vertex collision against plane geoms	All flex models with ground planes
Contact parameter mixing (priority, solmix, solref, solimp, friction, gap)	✅	_mix_flex_contact_params	—
contype/conaffinity filtering	✅	Standard bitmask filtering	gripper.xml
Flex-flex collision	🔲	Flex element vs flex element	—
Self-collision (selfcollide: none/narrow/bvh/sap/auto)	🚧	WIP	poncho.xml
Internal collision (internal="true")	❌	Won't implement. Prevents self-penetration/inversion.	bunny.xml
Passive contacts (contact/@passive="true")	❌	Won't implement. Experimental spring-damper contacts.	sphere_passive.xml
Mesh-flex collision	🔲	Mesh geom vs flex not supported	—
Ellipsoid-flex collision	🔲	Ellipsoid geom vs flex not supported	—
Flex collision broadphase	🔲	Currently iterates all geoms per element (no broadphase)	—

---

5. Equality Constraints

Feature	Status	Notes	Example Models
mjEQ_FLEX (edge-length equality)	✅	Constrains all edges to initial rest lengths	plate.xml, flag.xml, basket.xml, pulley.xml, softbox.xml
mjEQ_FLEXVERT (vertex-averaged strain)	❌	Won't implement. Locking-free vertex-averaged constraints (dim=2).	poncho.xml
mjEQ_FLEXSTRAIN (strain-tensor)	🔲	Planned. Strain-tensor constraints for trilinear/quadratic. Requires trilinear support.	strain.xml, hollow_vs_solid.xml

---

6. Rendering & Visualization

Feature	Status
Deformable mesh rendering	✅
Flex BVH construction/refit	✅
Ray-flex intersection	✅
Vertex normals	✅
Texture coordinates (texcoord)	✅
Material application	✅
Flat/smooth shading (flatskin)	✅

---

7. Sensors & Energy

Feature	Status	Notes
Flex potential energy	🔲	TODO(team): flex in energy_pos()
Flex-specific sensors	❌	No flex-specific sensor types in MuJoCo itself

---

8. Solver & Integration

Feature	Status	Notes
CG solver with flex	✅
Newton solver with flex	✅
Implicit integrator (implicitfast)	✅	General velocity derivatives only
Implicit bending stiffness (dim=2)	🔲	Missing flexInterp_cgsolve outer CG loop that integrates K_bend implicitly. Bending is computed explicitly.
Implicit trilinear/quadratic stiffness	🔲	Missing K_interp implicit terms. Depends on trilinear support.
Island discovery with flex contacts	✅
Dense Jacobian for flex constraints	❌

---

9. Summary by Dimensionality

Feature	dim=1 (rope)	dim=2 (cloth)	dim=3 (volume)
Vertex kinematics	✅	✅	✅
Edge length/velocity/Jacobian	✅	✅	✅
Elasticity (SVK passive)	✅	✅	✅
Damping	✅	✅	✅
Bending forces	—	✅	—
Geom-flex collision	—	✅	✅
Plane-flex collision	✅	✅	✅
mjEQ_FLEX (edge equality)	✅	✅	✅
Trilinear/quadratic DOF	🔲	🔲	🔲
mjEQ_FLEXSTRAIN	—	—	🔲
Flex-flex collision	🔲	🔲	🔲
Self-collision	🚧	🚧	🚧
Rendering	✅	✅	✅

---

10. MuJoCo Model Files Reference

All flex model files are in model/flex/. Here is a mapping of models to the key features they exercise:

Model	dim	dof	Key Features
jelly.xml	3	full	Elasticity (Young's modulus), edge damping
floppy.xml	3	full	Basic 3D soft body, geom-flex collision
flag.xml	2	full	Edge equality, pin, bending
plate.xml	2	full	Edge equality, edge stiffness, bending
trampoline.xml	2	full	2D cloth, pin
press.xml	3	full	Two interacting flexcomps, elasticity
trilinear.xml	3	trilinear	🔲 Trilinear interpolation
quadratic.xml	3	quadratic	🔲 Quadratic interpolation
basket.xml	3	full	Box type, edge equality
softbox.xml	3	full	Box type, edge equality
strain.xml	3	trilinear	🔲 mjEQ_FLEXSTRAIN
hollow_vs_solid.xml	3	trilinear	🔲 mjEQ_FLEXSTRAIN + elastic2d
sphere_full.xml	3	full	Ellipsoid type
sphere_radial.xml	3	radial	Radial DOF
sphere_trilinear.xml	3	trilinear	🔲 Trilinear DOF
sphere_passive.xml	3	full	❌ Passive contacts
pancake.xml	2	full	Disc type
pulley.xml	1	full	1D circle, edge equality
bunny.xml	2	trilinear	🔲 Mesh type, trilinear, ❌ internal collision
bunny_multicell.xml	2	trilinear	🔲 Mesh with cellcount, trilinear
bunny_with_uv.xml	2	trilinear	🔲 Mesh with UV texcoords, trilinear
bunny_quadratic.xml	2	quadratic	🔲 Quadratic DOF
gripper.xml	3	full	Deformable gripper pads
gripper_trilinear.xml	3	trilinear	🔲 Trilinear gripper
gripper_2d.xml	2	full	Direct type, 2D fins
poncho.xml	2	full	❌ mjEQ_FLEXVERT, 🚧 self-collision
poncho_edgeequality.xml	2	full	Edge equality variant
pinch.xml	2	full	Cloth pinching
cloth_sdf.xml	2	full	Flex + SDF plugin
hammock.xml	2	full	Grid cloth, material