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

crates/explicit/src/result.rs

@@ -22,21 +22,34 @@ pub struct Energies {
     pub external: f64,
     /// Work of the boundary conditions and rigid walls on the model.
     pub constraint: f64,
+    /// Energy taken by contact: the work the model does against the contact forces (the penalty
+    /// energy stored in the contact springs, plus what friction dissipates there).
+    pub contact: f64,
+    /// Friction dissipation, in contact and on rigid walls (part of `contact` and of
+    /// `constraint`).
+    pub friction: f64,
     /// Plastic work: the part of `internal` dissipated by plastic flow.
     pub plastic: f64,
     /// Internal energy of the eroded elements when they eroded (part of `internal`).
     pub eroded: f64,
-    /// kinetic + internal + hourglass + viscous − external − constraint − the initial kinetic
-    /// energy: zero when energy is conserved.
+    /// kinetic + internal + hourglass + viscous + contact − external − constraint − the initial
+    /// kinetic energy: zero when energy is conserved.
     pub balance: f64,
 }
 
 impl Energies {
     /// The balance relative to the largest energy in the account.
     pub fn relative_error(&self, initial_kinetic: f64) -> f64 {
-        let scale = [initial_kinetic, self.kinetic, self.internal + self.hourglass + self.viscous, self.external.abs(), self.constraint.abs()]
-            .into_iter()
-            .fold(0.0, f64::max);
+        let scale = [
+            initial_kinetic,
+            self.kinetic,
+            self.internal + self.hourglass + self.viscous,
+            self.external.abs(),
+            self.constraint.abs(),
+            self.contact.abs(),
+        ]
+        .into_iter()
+        .fold(0.0, f64::max);
         if scale > 0.0 { self.balance.abs() / scale } else { 0.0 }
     }
 }
@@ -84,12 +97,33 @@ pub struct History {
     pub momentum: Vec<[f64; 3]>,
     /// Sum of the forces the boundary conditions and rigid walls exert on the model.
     pub constraint_force: Vec<[f64; 3]>,
+    /// Per contact (in [`ExplicitResult::contacts`] order): the normal force across it (the sum
+    /// of its constraints' normal forces).
+    pub contact_force: Vec<Vec<f64>>,
     /// The nodes with histories, and per sample their displacement and velocity (in this order).
     pub nodes: Vec<u32>,
     pub displacement: Vec<Vec<[f64; 3]>>,
     pub velocity: Vec<Vec<[f64; 3]>>,
 }
 
+/// What a contact did over the run.
+#[derive(Debug, Clone, Default, PartialEq, Serialize)]
+pub struct ContactSummary {
+    pub name: String,
+    /// Nodes moved onto the other surface before the analysis.
+    pub adjusted: Vec<crate::contact::Adjustment>,
+    /// The largest normal force across it, and when.
+    pub peak_force: f64,
+    pub peak_time: f64,
+    /// The first and the last time it carried a force (none when it never did).
+    pub first_contact: Option<f64>,
+    pub last_contact: Option<f64>,
+    /// The deepest penetration of a node into a face.
+    pub max_penetration: f64,
+    /// Friction dissipated in it.
+    pub friction: f64,
+}
+
 /// An element that limits the stable time increment.
 #[derive(Debug, Clone, Copy, PartialEq, Serialize)]
 pub struct ControllingElement {
@@ -122,5 +156,7 @@ pub struct ExplicitResult {
     pub initial_kinetic: f64,
     /// Elements eroded during the run, in the order they eroded.
     pub eroded: Vec<ErodedElement>,
+    /// Per contact of the model, in name order.
+    pub contacts: Vec<ContactSummary>,
     pub warnings: Vec<String>,
 }