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

tests/oracle/nl-cylinder-inflation/README.md

@@ -0,0 +1,7 @@
+# Inflation of a thick neo-Hookean cylinder (follower pressure)
+
+A quarter of a tube A = 10, B = 20, one unit long, in plane strain (symmetry planes x = 0,
+y = 0 and both ends), 6 × 16 hybrid hex20 elements, neo-Hookean with E = 3, ν = 0.4995
+(μ = 1.00033, κ = 1000). The bore pressure p = 0.428371199 follows the deforming bore; the incompressible
+closed form puts the bore at a = 15 and the outer wall at b = 22.912878475. This is the follower-pressure
+case: the pressure turns with the bore and grows with its area.

tests/oracle/nl-cylinder-inflation/expected.json

@@ -0,0 +1,53 @@
+{
+ "title": "Inflation of a thick neo-Hookean cylinder by a follower pressure (plane strain)",
+ "kind": "theory",
+ "source": "Finite inflation of an incompressible neo-Hookean thick-walled tube in plane strain: r² = R² + a² − A², σ_θ − σ_r = μ (λ² − λ⁻²) with λ = r/R, integrated through the wall: p = (μ/2)[(ln λ_a² − λ_a⁻²) − (ln λ_b² − λ_b⁻²)] (R. S. Rivlin, Large elastic deformations of isotropic materials VI, Phil. Trans. R. Soc. A 242:173–195, 1949; R. W. Ogden, Non-Linear Elastic Deformations, Dover 1997, §5.3.2)",
+ "quantities": [
+  {
+   "id": "ua",
+   "quantity": "radial displacement of the bore (10, 0, 0) at the pressure that inflates it to a = 15",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Inflate",
+     "at": [
+      [
+       10.0,
+       0,
+       0
+      ]
+     ]
+    },
+    "pointer": "/nodes/0/displacement/0"
+   },
+   "value": 5.0,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "the closed form is incompressible and our material nearly so (κ/μ = 1000, a volume change of order p/κ ≈ 4·10⁻⁴); hybrid hex20, 6 × 16, follow the wall's strain gradient well inside"
+  },
+  {
+   "id": "ub",
+   "quantity": "radial displacement of the outer wall (20, 0, 0)",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Inflate",
+     "at": [
+      [
+       20.0,
+       0,
+       0
+      ]
+     ]
+    },
+    "pointer": "/nodes/0/displacement/0"
+   },
+   "value": 2.9128784747791983,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "as at the bore"
+  }
+ ]
+}

tests/oracle/nl-cylinder-inflation/fixture.json

@@ -0,0 +1,13 @@
+{
+  "note": "FieldCraft's accepted results for this case, written by `cargo xtask oracle --bless`. A result outside its band fails CI.",
+  "values": {
+    "ua": {
+      "band": 5.003966508393597e-9,
+      "value": 5.003966508393597
+    },
+    "ub": {
+      "band": 2.917320022569369e-9,
+      "value": 2.9173200225693687
+    }
+  }
+}

tests/oracle/nl-cylinder-inflation/recipe.json

@@ -0,0 +1,18 @@
+[
+ {"command": "mesh.block", "params": {"body": "Pipe", "kind": "hex20", "corners": [[10.0, 0, 0], [20.0, 0, 0], [0, 20.0, 0], [0, 10.0, 0], [10.0, 0, 1], [20.0, 0, 1], [0, 20.0, 1], [0, 10.0, 1]], "divisions": [6, 16, 1], "edges": [{"corners": [2, 3], "arc": {"center": [0, 0, 0]}}, {"corners": [1, 4], "arc": {"center": [0, 0, 0]}}, {"corners": [6, 7], "arc": {"center": [0, 0, 1]}}, {"corners": [5, 8], "arc": {"center": [0, 0, 1]}}], "faces": {"6": "bore", "3": "y0", "5": "x0", "1": "z0", "2": "z1"}}},
+ {"command": "model.set.create", "params": {"name": "all", "geometry": [{"body": "Pipe"}]}},
+ {"command": "model.set.create", "params": {"name": "bore", "geometry": [{"body": "Pipe", "face": "bore"}]}},
+ {"command": "model.set.create", "params": {"name": "x0", "geometry": [{"body": "Pipe", "face": "x0"}]}},
+ {"command": "model.set.create", "params": {"name": "y0", "geometry": [{"body": "Pipe", "face": "y0"}]}},
+ {"command": "model.set.create", "params": {"name": "z0", "geometry": [{"body": "Pipe", "face": "z0"}]}},
+ {"command": "model.set.create", "params": {"name": "z1", "geometry": [{"body": "Pipe", "face": "z1"}]}},
+ {"command": "model.material.create", "params": {"name": "Rubber", "elastic": {"type": "isotropic", "young": 3.0, "poisson": 0.4995}, "hyperelastic": {"type": "neo_hookean"}}},
+ {"command": "model.section.create", "params": {"name": "pipe", "set": "all", "material": "Rubber", "kind": {"type": "solid"}, "formulation": {"hybrid": true}}},
+ {"command": "model.boundary_condition.create", "params": {"name": "sx", "type": "symmetry", "target": {"set": "x0"}, "plane": "x"}},
+ {"command": "model.boundary_condition.create", "params": {"name": "sy", "type": "symmetry", "target": {"set": "y0"}, "plane": "y"}},
+ {"command": "model.boundary_condition.create", "params": {"name": "sz0", "type": "symmetry", "target": {"set": "z0"}, "plane": "z"}},
+ {"command": "model.boundary_condition.create", "params": {"name": "sz1", "type": "symmetry", "target": {"set": "z1"}, "plane": "z"}},
+ {"command": "model.load.create", "params": {"name": "p", "type": "pressure", "set": "bore", "magnitude": 0.42837119949633445}},
+ {"command": "model.step.create", "params": {"name": "Inflate", "procedure": {"type": "nonlinear_static"}, "boundary_conditions": ["sx", "sy", "sz0", "sz1"], "loads": ["p"]}},
+ {"command": "solve.nonlinear", "params": {"step": "Inflate"}, "id": "solve"}
+]