Hybrid (mixed u–p) solids: hex8 and tet10 with a constant pressure, hex20 with a linear one (#49)

The isotropic elasticity splits into D_dev + K m mᵀ; an element-wise
discontinuous pressure is condensed out (p̂ = K M⁻¹ Gᵀ u), leaving
K_dev + K G M⁻¹ Gᵀ (Hughes §4.3–4.5). Q2–P1disc and P2–P0 are inf-sup
stable; Q1–P0 does not lock; tet4 and wedge6 still lock and are refused, as
are orthotropic materials (named at the section). ElementDofs counts the
condensed pressures. Verified: element patch, rigid modes and totals for
every hybrid kind, a block in uniaxial strain at ν = 0.4999 (exact), Lamé's
cylinder in plane strain at ν = 0.4999 (hex20 1e-5, tet10 1.3e-3, hex8
2.5e-3 vs the locking displacement hex8 at −80 %). Every non-hybrid result
of the test suites hashes identically before and after.


Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

Co-authored-by: jyviko <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

docs/elements.md

@@ -73,7 +73,7 @@ hex8/20/27 with first and second derivatives).
 | wedge6 | Swept meshes from triangles, transitions | done |
 | hex8 one-point with hourglass control, nodal-pressure tet4 (explicit) | Explicit dynamics | done |
 | wedge15, pyramid5/13 | Quadratic transitions, tet–hex transition | planned (M5); wedge15 and pyramid5 shape functions done |
-| Hybrid (mixed u–p) solids | Nearly incompressible materials (rubber) | in progress (FEM foundation, phase C); pressure DOF kind done |
+| Hybrid (mixed u–p) solids | Nearly incompressible materials (rubber) | done for hex8 (constant pressure), hex20 (linear pressure) and tet10 (constant pressure), discontinuous pressure condensed, isotropic materials; tet4/wedge6 refused (they lock); continuous-pressure (Taylor–Hood) elements planned with an indefinite factorization |
 | Modified quadratic tet (tet10 for contact/plasticity) | Robust quadratic tets | planned |
 
 ## Special-purpose and multiphysics

docs/fem.md

@@ -133,3 +133,19 @@ or per axis, and `reference_temperature`), `BoundaryCondition::Temperature`, loa
 in a static step), procedures `HeatTransfer { transient }` and `CoupledTemperatureDisplacement`.
 Commands: `solve.heat`, and `solve.static` for coupled steps. The deck writers refuse heat
 transfer by name for now.
+## Hybrid (mixed u–p) solids
+
+A section with `"formulation": {"hybrid": true}` gives `Formulation::Hybrid { pressures }`
+(`crate::hybrid`): the isotropic elasticity splits as D = D_dev + K m mᵀ, the mean stress is an
+independent field discontinuous between elements (hex20: 1, x, y, z; hex8 and tet10: constant),
+and it is condensed out element by element, p̂ = K M⁻¹ Gᵀ u, leaving the stiffness
+K_dev + K G M⁻¹ Gᵀ. `ElementDofs.internal.pressure` counts the condensed unknowns; nothing
+global changes, and Cholesky still applies. Stresses are D_dev ε + p m with the element's
+pressure field. The choice of pressure space follows the inf-sup analysis (docs in
+`crates/fem/src/hybrid.rs`): Q2–P1disc and P2–P0 are stable; Q1–P0 does not lock but may show
+checkerboard pressures; linear tetrahedra and wedges lock even so and are refused. A thermal
+strain splits the same way: ∫ Bᵀ D_dev ε_th on the nodes and, through the pressure,
+K G M⁻¹ ∫ N_p tr ε_th, so a heated nearly incompressible solid takes its bulk stress −3KαΔT
+when confined. A continuous
+nodal pressure (`DofKind::P`, Taylor–Hood) needs a symmetric indefinite factorization and is
+planned.

docs/solvers/literature.md

@@ -1141,3 +1141,17 @@ update are written from (cited again in the module docs):
   constrained thermal expansion (σ = −EαΔT), the bimetal strip (S. Timoshenko, *Analysis of
   bi-metal thermostats*, J. Opt. Soc. Am. 11(3):233–255, 1925), and the coupled step against
   the heat step followed by the static step.
+
+## Part L: Hybrid (mixed u–p) solids, as implemented
+
+- Perturbed-Lagrangian u–p formulation with element-wise condensed discontinuous pressure:
+  T. J. R. Hughes, *The Finite Element Method*, Dover 2000, §4.3–4.5 (B-bar and mean
+  dilatation as the constant-pressure case); J. C. Nagtegaal, D. M. Parks, J. R. Rice, CMAME
+  4(2):153–177, 1974 (locking of displacement elements near incompressibility).
+- Pressure spaces and the inf-sup condition: F. Brezzi, M. Fortin, *Mixed and Hybrid Finite
+  Element Methods*, Springer 1991, ch. VI; K.-J. Bathe, *Finite Element Procedures*, 2nd ed.,
+  2014, §4.5 (Q2–P1disc and P2–P0 stable, Q1–P0 checkerboard-prone, P1–P0 locks).
+- Verification (`crates/solver/tests/hybrid.rs`, analytic): a block in uniaxial strain at
+  ν = 0.4999 (exact), Lamé's thick cylinder in plane strain at ν = 0.4999 (hex20 1e-5,
+  tet10 1e-3, hex8 3e-3 relative error in the bore displacement, where the displacement hex8
+  is 80 % too stiff). Cook's membrane is a published benchmark, not part of the analytic gate.