Flex Feature Parity Tracker: MuJoCo → MuJoCo Warp

This issue tracks the implementation status of MuJoCo's [flexible object (flex)](https://mujoco.readthedocs.io/en/latest/XMLreference.html#body-flexcomp) features in MuJoCo Warp. Flex enables simulation of deformable objects — ropes (`dim=1`), cloth/shells (`dim=2`), and volumetric soft bodies (`dim=3`).

All `` 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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/jelly.xml), [floppy.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/floppy.xml), [sphere_full.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/sphere_full.xml) |
| `dof="radial"` | ✅ | 1 radial DOF per vertex | [sphere_radial.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/sphere_radial.xml) |
| `dof="trilinear"` | 🔲 | 24 DOFs (8 bounding-box corners × 3). Requires `flex_interp` kernel dispatch. | [trilinear.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/trilinear.xml), [gripper_trilinear.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/gripper_trilinear.xml), [sphere_trilinear.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/sphere_trilinear.xml) |
| `dof="quadratic"` | 🔲 | 81 DOFs (quadratic interpolation). Requires `flex_interp` kernel dispatch. | [quadratic.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/quadratic.xml), [bunny_quadratic.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/jelly.xml), [press.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/hollow_vs_solid.xml) |
| **Edge stiffness** (`edge/@stiffness`) | ✅ | 1D edge springs | [plate.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/plate.xml) |
| **Edge damping** (`edge/@damping`) | ✅ | Edge velocity damping | — |
| **Bending forces** (dim=2) | ✅ | Linear + nonlinear (cross-product). `passive._flex_bending` | [flag.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/flag.xml), [plate.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/plate.xml) |
| **Trilinear/quadratic implicit stiffness** | 🔲 | `flex_interp` integration + implicit solver terms | [trilinear.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/pinch.xml), [gripper_2d.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/gripper_2d.xml) |
| **Geom-flex (dim=3)**: Sphere, Capsule, Box, Cylinder vs shell faces | ✅ | `collision_flex._flex_narrowphase_dim3` | [floppy.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/floppy.xml), [gripper.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/gripper.xml) |
| **Flex-flex collision** | 🔲 | Flex element vs flex element | — |
| **Self-collision** (`selfcollide`: `none`/`narrow`/`bvh`/`sap`/`auto`) | 🚧 | WIP | [poncho.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/poncho.xml) |
| **Internal collision** (`internal="true"`) | ❌ | Won't implement. Prevents self-penetration/inversion. | [bunny.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/bunny.xml) |
| **Passive contacts** (`contact/@passive="true"`) | ❌ | Won't implement. Experimental spring-damper contacts. | [sphere_passive.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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](https://github.com/google-deepmind/mujoco/blob/main/model/flex/plate.xml), [flag.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/flag.xml), [basket.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/basket.xml), [pulley.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/pulley.xml), [softbox.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/softbox.xml) |
| **`mjEQ_FLEXVERT`** (vertex-averaged strain) | ❌ | Won't implement. Locking-free vertex-averaged constraints (dim=2). | [poncho.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/poncho.xml) |
| **`mjEQ_FLEXSTRAIN`** (strain-tensor) | 🔲 | Planned. Strain-tensor constraints for trilinear/quadratic. Requires trilinear support. | [strain.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/strain.xml), [hollow_vs_solid.xml](https://github.com/google-deepmind/mujoco/blob/main/model/flex/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/`](https://github.com/google-deepmind/mujoco/tree/main/model/flex). Here is a mapping of models to the key features they exercise:

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