verification: nonlinear oracle cases and the nonlinear solver's documentation

Theory cases for the nonlinear solver, each frozen as a fixture: uniaxial
stretch of a neo-Hookean block to twice its length (closed form), the
nonlinear patch test on a distorted hex8 mesh, a quarter turn of the same
mesh (objectivity: zero stress), the elastica of a hex20 cantilever at
P L²/(E I) = 1, 2, 5, 10 against Bisshopp–Drucker (0.2–0.5 %), and the
inflation of a thick neo-Hookean tube by a follower pressure against
Rivlin's closed form (0.08 % at the bore). A finite-strain Cook's membrane
is pending its transcribed reference. docs/fem.md describes the
formulation, the material point interface, the follower-pressure choice and
what nonlinear steps refuse; the literature, parity and roadmap pages
follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

docs/fem.md

@@ -149,3 +149,97 @@ K G M⁻¹ ∫ N_p tr ε_th, so a heated nearly incompressible solid takes its b
 when confined. A continuous
 nodal pressure (`DofKind::P`, Taylor–Hood) needs a symmetric indefinite factorization and is
 planned.
+
+## Nonlinear static analysis (finite strain)
+
+A step `{"type": "nonlinear_static", …}` (`Procedure::NonlinearStatic`, solved by
+`solve.nonlinear`, `fieldcraft_solver::nonlinear`) follows equilibrium in load increments with
+Newton–Raphson iterations. The step's load factor λ runs from 0 to 1: dead loads are λ times
+their values, a pressure follows the deformed faces with λ times its magnitude, and prescribed
+displacements are λ times theirs (a linear ramp).
+
+**Material point** (`fieldcraft_fem::constitutive`). Given the deformation gradient F and the
+history committed at the end of the last converged increment, a material returns the
+**Kirchhoff stress** τ = J σ and the **spatial tangent** c of its Lie derivative (L_v τ = c : d),
+in Voigt order with engineering-shear columns, so c = D at F = I. This is the push-forward of
+the second Piola–Kirchhoff stress and its tangent: τ = F S Fᵀ, c_ijkl = F_iI F_jJ F_kK F_lL
+C_IJKL. History variables (`MaterialModel::history_len` per integration point) are read from the
+committed slice and written to a separate one, which the solver commits when the increment
+converges, so a cut-back increment leaves no trace. The materials:
+
+| Material in a nonlinear step | Model |
+|---|---|
+| Elastic (isotropic or orthotropic), no option | St Venant–Kirchhoff: S = D E, E = ½(FᵀF − I). Right for large rotations with small strains; it softens without bound in large compression. |
+| Isotropic elastic with `"hyperelastic": {"type": "neo_hookean"}` | Compressible neo-Hookean with the isochoric–volumetric split, W = μ/2 (Ī₁ − 3) + κ/2 (J − 1)², μ and κ from E and ν (C₁₀ = μ/2, D₁ = 2/κ). Its small-strain limit is the linear material, which linear steps use. |
+
+"Isotropic elastic" keeps meaning the same thing everywhere: the neo-Hookean model is chosen
+only by the explicit option, and explicit dynamics refuses a hyperelastic material by name.
+
+**Elements** (`fieldcraft_fem::finite`), total Lagrangian over the reference element with its
+own quadrature: f_a = ∫ Bₓ,aᵀ τ dV₀ and K_ab = ∫ (Bₓ,aᵀ c Bₓ,b + ∇ₓN_a·τ∇ₓN_b I) dV₀ with the
+current gradients ∇ₓN = F⁻ᵀ∇₀N (material plus geometric stiffness), identical term by term to
+∫ B₀ᵀ S dV₀ and its linearisation. Every element's tangent is checked against central
+differences of its forces.
+
+| Element | Nonlinear steps |
+|---|---|
+| tet4, tet10, wedge6, hex8, hex20 (full), hex20 (reduced) | total Lagrangian |
+| hybrid hex8, hex20, tet10 | Simo–Taylor–Pister three-field form on the linear hybrid elements' pressure fields (θ the projection of J, p the projection of U′(θ)); needs the neo-Hookean option (St Venant–Kirchhoff has no volumetric split) |
+| hex8 and quad4 incompatible modes | refused: their finite-strain form (enhanced assumed strain, Simo–Armero 1992) needs the modes as unknowns carried between iterations and hourglasses in large compression; use full integration, hybrid or quadratic elements |
+| plane strain, axisymmetric (tri3, tri6, quad4, quad8) | total Lagrangian with F₃₃ = 1 or r/R (hoop column N/r, geometric term τ_θθ N_a N_b/r²) |
+| plane stress | refused (σ_zz = 0 needs a local iteration for the thickness) |
+| trusses, shells, beams | refused (large rotations of structural elements come later in M15) |
+
+Without nonlinear geometry (`"nonlinear_geometry": false`) the elements are the linear ones:
+every material is elastic today, so such a step is the linear solution reached by Newton (the
+path the next materials, plasticity first, take with small strains).
+
+**Follower pressure** (`fieldcraft_fem::face::follower_pressure`, `follower_edge_pressure`):
+fᵢ = −p ∫ Nᵢ (x,ξ × x,η) dξ dη on the current face, with its load stiffness
+K = p ∫ N_a (N_b,η [x,ξ]× − N_b,ξ [x,η]×). The load stiffness is not symmetric. The solver keeps
+its symmetric part and leaves the skew part out, so the tangent stays symmetric for the
+supernodal Cholesky factorization: the residual is exact (the converged answer does not
+change), and over a closed surface or one whose boundary is held the skew parts of neighbouring
+faces cancel (Schweizerhof & Ramm 1984), so nothing is lost there; elsewhere Newton may converge
+linearly instead of quadratically, and the result says how large the left-out part is. An LU
+factorization would double the factor's memory and lose the symmetric solver for a gain only in
+the rate of convergence of open loaded surfaces; it is revisited with the symmetric indefinite
+(LDLᵀ) factorization that arc-length and Taylor–Hood need. Without nonlinear geometry a pressure
+is a dead load.
+
+**Newton–Raphson** with the consistent tangent refactored every iteration, an optional line
+search (off by default: on large elastic rotations the full step converges in fewer
+iterations), and convergence when the force residual (∞-norm over the largest force seen), the
+displacement correction (over the increment's largest displacement) and the energy (over the
+first iteration's) are all below their tolerances, or the residual is round-off. Each increment
+starts from the linear extrapolation of the last one. Automatic incrementation grows an
+increment by half after two fast ones (≤ 4 iterations), shrinks it after a slow one (> 8), and
+cuts it to a quarter when an element inverts, the residual is not finite or grows twice, the
+tangent is not positive definite, or the iterations run out; the step stops with the load factor
+and the reason at the minimum increment, the increment cap, or `Limits::max_newton_iterations`.
+
+**Results**: the final displacements and reactions, the **Cauchy stress** and the
+**logarithmic strain** (ln V, engineering shears) at the integration points and averaged at the
+nodes, every increment's load factor, iterations and residuals, and a displacement frame per
+converged increment (`results.frame`, the slider in the results panel).
+
+**Couplings** stay the linear constraints of the linear solver (small rotations of the
+reference points), with a warning; springs act along their fixed directions. Temperature and
+centrifugal loads are refused by name in nonlinear steps.
+
+**Decks**: Abaqus `*STEP, NLGEOM=YES|NO, INC=` with `*STATIC` (initial, period 1, minimum,
+maximum) and `*CONTROLS, PARAMETERS=LINE SEARCH`; the neo-Hookean option as `*HYPERELASTIC, NEO
+HOOKE`. LS-DYNA: the ramped implicit run with full Newton (`ilimit` 1, `maxref`) and
+`*CONTROL_IMPLICIT_AUTO`; hyperelastic materials in nonlinear steps and steps without nonlinear
+geometry are refused. Nastran refuses nonlinear steps (SOL 400) by name. Iteration caps and
+tolerances are left to each solver's own controls, whose norms differ from ours.
+
+**Verification** (`crates/solver/tests/nonlinear.rs`, `crates/fem/src/{constitutive,finite,face}.rs`,
+and `tests/oracle/nl-*`): consistent tangents of both materials and of every element (central
+differences); uniaxial stretch to λ = 2 of a neo-Hookean block in every element kind, plane
+strain and axisymmetric (closed form); St Venant–Kirchhoff uniaxial stretch; the nonlinear patch
+test on a distorted mesh (all solids, hybrid ones included); a 90° rigid rotation (zero stress);
+the elastica (Bisshopp–Drucker) at P L²/(E I) = 1, 2, 5, 10 with hex20 (0.2–0.5 %); the inflation of a thick neo-Hookean tube by a follower pressure (Rivlin's closed form);
+Newton's quadratic convergence; the linear limit; a finite-strain Cook's membrane is pending
+its transcribed reference; and the failures (an element inverted by
+crushing stops at the minimum increment, naming it; the caps; what is refused).