explicit: deformable contact and friction, verified by bars, sliding blocks, the patch test and Hertz

Segment-to-segment penalty contact between element faces: each secondary
face and each main face facing it are projected onto the secondary face's
plane, split into triangles, clipped (Sutherland–Hodgman) and integrated
with a three-point rule per sub-triangle (Puso–Laursen segmentation, the
penalty at the integration points as Fischer–Wriggers), so a uniform
pressure gives the consistent nodal forces on both meshes and the contact
patch test passes on non-matching meshes. Every contact runs both ways at
half the penalty: pairs with each surface as the secondary, general and
self contact face against face. A bucket grid of face boxes every
increment, faces integrated in parallel and their forces added in face
order: the same numbers on any thread count.

The penalty per area ε = s γ min(m/A)/Δt² comes from the lumped masses,
each node's directional area and the stable increment, bounded by
Gershgorin's row sums so contact never shortens the increment. Coulomb
friction with exponential decay by a regularised return map at the
secondary nodes; rigid walls take Coulomb impulses. Contact work and
friction dissipation join the energy balance; each contact reports its
peak force, first and last contact, deepest penetration, friction and the
nodes adjusted at the start (initial penetrations adjusted strain-free or
refused with the node, face and depth); a cap on contact faces.

Verified (crates/explicit/tests/contact.rs, tests/oracle/explicit-*):
colliding bars (2L/c +1.2%, ρcAv₀/2, KE kept to 0.005%, contact energy
back to 8e-5 of it), blocks sliding to a stop on a rigid wall and on a
plate under constant and decaying friction (0.005–0.2%), the patch test
(σ_zz uniform to 0.06%), two spheres colliding against Hertz (peak +2.3%,
duration −0.4%; the oracle case waits for a graded sphere mesher), a free
body untouched by general contact, determinism across threads. Oracle
measures gain `over` (ratios). Existing fixtures do not move.

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

tests/oracle/explicit-contact-patch/README.md

@@ -0,0 +1,9 @@
+# Contact patch test (explicit contact, non-matching meshes)
+
+Two unit cubes stacked along z, meshed independently: 3 × 3 × 2 hex8 below, 2 × 2 × 2 above, so
+the nodes of the interface at z = 1 do not match. A frictionless contact pair joins the lower
+block's top and the upper block's bottom. The faces x = 0 and y = 0 of both blocks are symmetry
+planes (normal displacement held), the base z = 0 is held in z, and the top z = 2 is pushed down by
+0.01 at constant speed over a hundred wave transits (E = 1000, ν = 0.3, ρ = 1). The exact state
+is uniaxial stress, uniform in both blocks; the stresses are compared as ratios, since the penalty
+takes a small, uniform share of the squeeze.

tests/oracle/explicit-contact-patch/expected.json

@@ -0,0 +1,176 @@
+{
+ "title": "Contact patch test: two blocks with non-matching meshes in uniaxial compression (explicit contact)",
+ "kind": "theory",
+ "source": "The contact patch test: a contact discretisation must transmit a uniform pressure across a non-matching interface exactly; Taylor & Papadopoulos, On a patch test for contact problems in two dimensions, Nonlinear Computational Mechanics, Springer 1991, 690–702; Crisfield, Re-visiting the contact patch test, IJNME 48:435–449, 2000. Uniaxial stress between frictionless symmetry planes is uniform in both blocks",
+ "quantities": [
+  {
+   "id": "lower_corner",
+   "quantity": "σ_zz of the lower block's corner element under the interface (element 10) over that of the upper block's corner element over it (element 19)",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Squeeze",
+     "elements": [
+      10
+     ]
+    },
+    "pointer": "/elements/0/stress/2",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       19
+      ]
+     },
+     "pointer": "/elements/0/stress/2"
+    }
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "a uniform stress is an equilibrium of the discrete system (the integrated contact forces are the consistent nodal forces of a uniform pressure on both meshes); what is left is the ringing of the loading, a hundred wave transits slow"
+  },
+  {
+   "id": "lower_centre",
+   "quantity": "σ_zz of the lower block's centre element under the interface (element 14) over that of element 19",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Squeeze",
+     "elements": [
+      14
+     ]
+    },
+    "pointer": "/elements/0/stress/2",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       19
+      ]
+     },
+     "pointer": "/elements/0/stress/2"
+    }
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "as for the corner element"
+  },
+  {
+   "id": "lower_base",
+   "quantity": "σ_zz of the lower block's bottom corner element (element 1) over that of element 19",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Squeeze",
+     "elements": [
+      1
+     ]
+    },
+    "pointer": "/elements/0/stress/2",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       19
+      ]
+     },
+     "pointer": "/elements/0/stress/2"
+    }
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "as for the corner element"
+  },
+  {
+   "id": "upper_top",
+   "quantity": "σ_zz of the upper block's top far corner element (element 26) over that of element 19",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Squeeze",
+     "elements": [
+      26
+     ]
+    },
+    "pointer": "/elements/0/stress/2",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       19
+      ]
+     },
+     "pointer": "/elements/0/stress/2"
+    }
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.005
+   },
+   "reason": "as for the corner element"
+  },
+  {
+   "id": "force",
+   "quantity": "the force across the interface over −σ_zz A (A = 1)",
+   "measure": {
+    "from": "solve",
+    "pointer": "/contacts/0/peak_force",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       19
+      ]
+     },
+     "pointer": "/elements/0/stress/2",
+     "scale": -1.0
+    }
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.01
+   },
+   "reason": "the integrated contact pressure carries the whole load; the largest force of the run is the final one in a slow squeeze, up to the ringing"
+  },
+  {
+   "id": "lateral",
+   "quantity": "σ_xx of element 14 over its σ_zz (uniaxial stress: 0)",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Squeeze",
+     "elements": [
+      14
+     ]
+    },
+    "pointer": "/elements/0/stress/0",
+    "over": {
+     "command": "solve.probe",
+     "params": {
+      "step": "Squeeze",
+      "elements": [
+       14
+      ]
+     },
+     "pointer": "/elements/0/stress/2"
+    }
+   },
+   "value": 0.0,
+   "tolerance": {
+    "absolute": 0.005
+   },
+   "reason": "frictionless symmetry planes and a frictionless interface leave the blocks free to expand sideways; the non-matching interface must not hold them"
+  }
+ ]
+}

tests/oracle/explicit-contact-patch/fixture.json

@@ -0,0 +1,29 @@
+{
+  "note": "FieldCraft's accepted results for this case, written by `cargo xtask oracle --bless`. A result outside its band fails CI.",
+  "values": {
+    "force": {
+      "band": 1.0025883998151134e-9,
+      "value": 1.0025883998151133
+    },
+    "lateral": {
+      "band": 0.005,
+      "value": -0.00036052361311792505
+    },
+    "lower_base": {
+      "band": 1.00013429984765e-9,
+      "value": 1.00013429984765
+    },
+    "lower_centre": {
+      "band": 1.0002867148178652e-9,
+      "value": 1.0002867148178651
+    },
+    "lower_corner": {
+      "band": 1.0001179568787019e-9,
+      "value": 1.0001179568787018
+    },
+    "upper_top": {
+      "band": 1e-9,
+      "value": 0.9994358602920412
+    }
+  }
+}

tests/oracle/explicit-contact-patch/recipe.json

@@ -0,0 +1,22 @@
+[
+ {"command": "mesh.block", "params": {"body": "Lower", "kind": "hex8", "corners": [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]], "divisions": [3, 3, 2], "faces": {"1": "bottom", "2": "top", "3": "y0", "6": "x0"}}},
+ {"command": "mesh.block", "params": {"body": "Upper", "kind": "hex8", "corners": [[0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1], [0, 0, 2], [1, 0, 2], [1, 1, 2], [0, 1, 2]], "divisions": [2, 2, 2], "faces": {"1": "bottom", "2": "top", "3": "y0", "6": "x0"}, "merge": 0}},
+ {"command": "model.set.create", "params": {"name": "lower", "geometry": [{"body": "Lower"}]}},
+ {"command": "model.set.create", "params": {"name": "upper", "geometry": [{"body": "Upper"}]}},
+ {"command": "model.set.create", "params": {"name": "lower_top", "geometry": [{"body": "Lower", "face": "top"}]}},
+ {"command": "model.set.create", "params": {"name": "upper_bottom", "geometry": [{"body": "Upper", "face": "bottom"}]}},
+ {"command": "model.set.create", "params": {"name": "x0", "geometry": [{"body": "Lower", "face": "x0"}, {"body": "Upper", "face": "x0"}]}},
+ {"command": "model.set.create", "params": {"name": "y0", "geometry": [{"body": "Lower", "face": "y0"}, {"body": "Upper", "face": "y0"}]}},
+ {"command": "model.set.create", "params": {"name": "z0", "geometry": [{"body": "Lower", "face": "bottom"}]}},
+ {"command": "model.set.create", "params": {"name": "top", "geometry": [{"body": "Upper", "face": "top"}]}},
+ {"command": "model.material.create", "params": {"name": "Mat", "elastic": {"type": "isotropic", "young": 1000.0, "poisson": 0.3}, "density": 1.0}},
+ {"command": "model.section.create", "params": {"name": "lower", "set": "lower", "material": "Mat", "kind": {"type": "solid"}, "formulation": {"integration": "reduced"}}},
+ {"command": "model.section.create", "params": {"name": "upper", "set": "upper", "material": "Mat", "kind": {"type": "solid"}, "formulation": {"integration": "reduced"}}},
+ {"command": "interaction.contact.pair", "params": {"name": "interface", "main": "lower_top", "secondary": "upper_bottom"}},
+ {"command": "model.boundary_condition.create", "params": {"name": "x0", "type": "displacement", "target": {"set": "x0"}, "values": [0, null, null, null, null, null]}},
+ {"command": "model.boundary_condition.create", "params": {"name": "y0", "type": "displacement", "target": {"set": "y0"}, "values": [null, 0, null, null, null, null]}},
+ {"command": "model.boundary_condition.create", "params": {"name": "z0", "type": "displacement", "target": {"set": "z0"}, "values": [null, null, 0, null, null, null]}},
+ {"command": "model.boundary_condition.create", "params": {"name": "push", "type": "displacement", "target": {"set": "top"}, "values": [null, null, -0.01, null, null, null]}},
+ {"command": "model.step.create", "params": {"name": "Squeeze", "procedure": {"type": "explicit_dynamic", "end_time": 5.451}, "boundary_conditions": ["x0", "y0", "z0", "push"], "loads": []}},
+ {"command": "solve.explicit", "params": {"step": "Squeeze"}, "id": "solve"}
+]