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/lib.rs

@@ -14,8 +14,12 @@
 //!   hourglass control (viscous or stiffness), the Bonet–Burton average nodal pressure
 //!   tetrahedron, von Neumann–Richtmyer/Wilkins bulk viscosity, and the element critical time
 //!   increments.
-//! - **Integration** ([`integrate`]): the time loop, kinematic constraints, energy accounting
-//!   with a balance check, history samples and field frames ([`result`]).
+//! - **Contact** ([`contact`]): penalty contact between element faces (pairs both ways, single
+//!   surface and general contact) with Coulomb friction by a regularised return map, a bucket
+//!   grid search, and the stiffness from the masses and the stable increment.
+//! - **Integration** ([`integrate`]): the time loop, kinematic constraints (rigid walls with
+//!   friction), energy accounting with a balance check, history samples and field frames
+//!   ([`result`]).
 //!
 //! With nonlinear geometry (the default) the elements are updated Lagrangian and the material
 //! state is integrated in rate form with an objective stress rate (Jaumann by Hughes–Winget,
@@ -33,6 +37,7 @@
 // Small fixed-size vector kernels read as the textbook formulas with index loops.
 #![allow(clippy::needless_range_loop)]
 
+pub mod contact;
 pub mod discrete;
 pub mod elements;
 pub mod integrate;
@@ -41,7 +46,7 @@ pub mod system;
 
 pub use elements::Failure;
 pub use integrate::solve_explicit;
-pub use result::{ControllingElement, Energies, ErodedElement, ExplicitResult, Frame, History};
+pub use result::{ContactSummary, ControllingElement, Energies, ErodedElement, ExplicitResult, Frame, History};
 
 #[derive(Debug, Clone, PartialEq, thiserror::Error)]
 pub enum Error {
@@ -82,16 +87,24 @@ pub struct Limits {
     pub max_increments: u64,
     /// Numbers kept in field frames and histories together (8 bytes each).
     pub max_output_values: usize,
+    /// Element faces of every contact surface together.
+    pub max_contact_faces: usize,
 }
 
 impl Limits {
     pub const MAX_DOFS: usize = 6_000_000;
     pub const MAX_INCREMENTS: u64 = fieldcraft_model::steps::MAX_INCREMENTS;
     pub const MAX_OUTPUT_VALUES: usize = 50_000_000;
+    pub const MAX_CONTACT_FACES: usize = 10_000_000;
 }
 
 impl Default for Limits {
     fn default() -> Limits {
-        Limits { max_dofs: Limits::MAX_DOFS, max_increments: Limits::MAX_INCREMENTS, max_output_values: Limits::MAX_OUTPUT_VALUES }
+        Limits {
+            max_dofs: Limits::MAX_DOFS,
+            max_increments: Limits::MAX_INCREMENTS,
+            max_output_values: Limits::MAX_OUTPUT_VALUES,
+            max_contact_faces: Limits::MAX_CONTACT_FACES,
+        }
     }
 }