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-bars-collision/README.md

@@ -0,0 +1,9 @@
+# Two identical elastic bars colliding (explicit contact)
+
+Two bars 10 × 0.1 × 0.1 of 200 one-point hex8 elements each (E = 10⁴, ρ = 1, ν = 0, c = 100),
+end to end and touching at x = 10 with separate nodes; the first moves at v₀ = 0.1 into the
+second, at rest. A frictionless contact pair joins the two end faces (each face's nodes kept out
+of the other, segment to segment). One-dimensional theory: the bars stay in contact for 2L/c =
+0.2 with a force ρcAv₀/2 across the interface, then the striker stops and the struck bar leaves at
+v₀ with all the kinetic energy. Linear bulk viscosity is off (it dissipates at the wave fronts).
+Solved to t = 0.3.

tests/oracle/explicit-bars-collision/expected.json

@@ -0,0 +1,107 @@
+{
+ "title": "Two identical elastic bars colliding (explicit contact)",
+ "kind": "theory",
+ "source": "One-dimensional elastic impact of equal bars: contact for 2L/c, interface force ρcAv₀/2, exchange of velocities, no loss of energy; Graff, Wave Motion in Elastic Solids, Dover 1991, §2.1–2.3; Johnson, Impact Strength of Materials, Arnold 1972, §1.6",
+ "quantities": [
+  {
+   "id": "duration",
+   "quantity": "time of the last contact (the bars touch from t = 0) against 2L/c = 0.2",
+   "measure": {
+    "from": "solve",
+    "pointer": "/contacts/0/last_contact"
+   },
+   "value": 0.2,
+   "tolerance": {
+    "relative": 0.02
+   },
+   "reason": "the penalty springs at the interface delay the release by a few element transit times (about 1% of 2L/c with 200 elements per bar)"
+  },
+  {
+   "id": "force",
+   "quantity": "the largest force across the interface against ρcAv₀/2 = 0.05",
+   "measure": {
+    "from": "solve",
+    "pointer": "/contacts/0/peak_force"
+   },
+   "value": 0.05,
+   "tolerance": {
+    "relative": 0.04
+   },
+   "reason": "the plateau is ρcAv₀/2 to 0.01%; the peak is the plateau plus the ringing behind the discrete wave front, a few percent"
+  },
+  {
+   "id": "v_a",
+   "quantity": "velocity of the struck bar's far end after the impact (0: the striker stops)",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Impact",
+     "at": [
+      [
+       0,
+       0,
+       0
+      ]
+     ]
+    },
+    "pointer": "/nodes/0/velocity/0"
+   },
+   "value": 0.0,
+   "tolerance": {
+    "absolute": 0.005
+   },
+   "reason": "the striker stops on average (its kinetic energy is under 0.01% of the start's, see ke); its far end node keeps the ringing of the discrete release front, a few percent of v₀"
+  },
+  {
+   "id": "v_b",
+   "quantity": "velocity of the struck bar's far end after the impact (v₀ = 0.1)",
+   "measure": {
+    "command": "solve.probe",
+    "params": {
+     "step": "Impact",
+     "at": [
+      [
+       20.0,
+       0,
+       0
+      ]
+     ]
+    },
+    "pointer": "/nodes/0/velocity/0"
+   },
+   "value": 0.1,
+   "tolerance": {
+    "relative": 0.05
+   },
+   "reason": "the struck bar leaves at v₀ on average; its far end node keeps the ringing of the discrete wave fronts, a few percent"
+  },
+  {
+   "id": "ke",
+   "quantity": "kinetic energy after the impact over ½mv₀² (frictionless elastic impact)",
+   "measure": {
+    "from": "solve",
+    "pointer": "/energy/kinetic",
+    "scale": 2000.0
+   },
+   "value": 1.0,
+   "tolerance": {
+    "relative": 0.01
+   },
+   "reason": "an elastic impact keeps the kinetic energy; the quadratic bulk viscosity at the compression fronts and the vibration left in the bars take a fraction of a percent"
+  },
+  {
+   "id": "contact_energy",
+   "quantity": "energy left in the contact after the separation, over ½mv₀² (its drift)",
+   "measure": {
+    "from": "solve",
+    "pointer": "/energy/contact",
+    "scale": 2000.0
+   },
+   "value": 0.0,
+   "tolerance": {
+    "absolute": 0.001
+   },
+   "reason": "the penalty springs give back what they took; the trapezoidal work of a spring that engages between increments drifts by far less than 0.1%"
+  }
+ ]
+}

tests/oracle/explicit-bars-collision/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": {
+    "contact_energy": {
+      "band": 0.001,
+      "value": -0.00007743495029686868
+    },
+    "duration": {
+      "band": 2.0242265804764194e-10,
+      "value": 0.20242265804764192
+    },
+    "force": {
+      "band": 5.1469625943477736e-11,
+      "value": 0.05146962594347773
+    },
+    "ke": {
+      "band": 1e-9,
+      "value": 0.9999532471694228
+    },
+    "v_a": {
+      "band": 0.005,
+      "value": -0.0033987044489733886
+    },
+    "v_b": {
+      "band": 1.0339870444897614e-10,
+      "value": 0.10339870444897613
+    }
+  }
+}

tests/oracle/explicit-bars-collision/recipe.json

@@ -0,0 +1,14 @@
+[
+ {"command": "mesh.block", "params": {"body": "BarA", "kind": "hex8", "corners": [[0, 0, 0], [10.0, 0, 0], [10.0, 0.1, 0], [0, 0.1, 0], [0, 0, 0.1], [10.0, 0, 0.1], [10.0, 0.1, 0.1], [0, 0.1, 0.1]], "divisions": [200, 1, 1], "faces": {"4": "end"}}},
+ {"command": "mesh.block", "params": {"body": "BarB", "kind": "hex8", "corners": [[10.0, 0, 0], [20.0, 0, 0], [20.0, 0.1, 0], [10.0, 0.1, 0], [10.0, 0, 0.1], [20.0, 0, 0.1], [20.0, 0.1, 0.1], [10.0, 0.1, 0.1]], "divisions": [200, 1, 1], "faces": {"6": "start"}, "merge": 0}},
+ {"command": "model.set.create", "params": {"name": "A", "geometry": [{"body": "BarA"}]}},
+ {"command": "model.set.create", "params": {"name": "B", "geometry": [{"body": "BarB"}]}},
+ {"command": "model.set.create", "params": {"name": "a_end", "geometry": [{"body": "BarA", "face": "end"}]}},
+ {"command": "model.set.create", "params": {"name": "b_start", "geometry": [{"body": "BarB", "face": "start"}]}},
+ {"command": "model.material.create", "params": {"name": "Mat", "elastic": {"type": "isotropic", "young": 10000.0, "poisson": 0.0}, "density": 1.0}},
+ {"command": "model.section.create", "params": {"name": "A", "set": "A", "material": "Mat", "kind": {"type": "solid"}, "formulation": {"integration": "reduced"}}},
+ {"command": "model.section.create", "params": {"name": "B", "set": "B", "material": "Mat", "kind": {"type": "solid"}, "formulation": {"integration": "reduced"}}},
+ {"command": "interaction.contact.pair", "params": {"name": "impact", "main": "b_start", "secondary": "a_end"}},
+ {"command": "model.step.create", "params": {"name": "Impact", "procedure": {"type": "explicit_dynamic", "end_time": 0.3, "initial_velocities": [{"set": "A", "velocity": [0.1, 0, 0]}], "bulk_viscosity": {"linear": 0.0, "quadratic": 1.5}}, "boundary_conditions": [], "loads": []}},
+ {"command": "solve.explicit", "params": {"step": "Impact"}, "id": "solve"}
+]