Explicit dynamics core: central differences, one-point hex8 with hourglass control, nodal-pressure tet4, solve.explicit (M10 X1) (#27)

* Model: explicit dynamic steps (end time, increment scale and cap, output intervals, initial velocities, rigid walls, hourglass and bulk viscosity controls); deck writers refuse them

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* fem: uniform-strain hex8 and tet4 kinematics, Flanagan–Belytschko hourglass shape vectors, element frequency bound

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Explicit solver crate (L2): central differences with lumped mass, one-point hex8 with Flanagan–Belytschko hourglass control, Bonet–Burton tet4, bulk viscosity, rigid walls, energy account; wave and impact verification

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Engine: solve.explicit and solve.history commands, explicit results in the session and solve.probe; cantilever period against the modal solver

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Docs: explicit solver in the architecture, roadmap (M10 started), parity and literature (Part H)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Simplify: Model::select_step shared by both solvers, Procedure::sets/is_dynamic, fused per-increment passes without allocation, shared element tail, generic command caps

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Catalogue: solve.explicit is ready; solve.history beside solve.probe

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Rebase onto the implicit couplings work: Procedure is no longer Copy

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

---------

Co-authored-by: jyviko <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

docs/architecture.md

@@ -21,10 +21,11 @@ crates in strictly lower layers.
 | L0 | `modelcraft-model` | Solver-neutral FE model: nodes and elements by label, their geometry tags, sets, materials, sections, couplings, BCs, loads and steps, the model check and the resolved view the writers read. Knows no file format and no geometry type. | started |
 | L1 | `modelcraft-geometry` | The only door to SolidCraft: opens `.solidcraft` designs (rebuilt from their timeline, bodies with persistent face names), B-rep bodies, measures, tessellation into a face-tagged `SurfaceMesh`; face-tagged 3MF files read into the same type without the kernel (docs/formats/tagged-mesh.md). No SolidCraft type in its API. | started |
 | L1 | `modelcraft-mesh` | Surface preparation (weld, watertightness, feature edges), robust predicates, Delaunay tetrahedralization and refinement, Voronoi-based optimization, hex meshing, quality metrics. | started |
-| L1 | `modelcraft-fem` | Element kernels shared by every structural solver: the element table (tet4, tet10, wedge6, hex8 full and incompatible modes, hex20 full and reduced), shape functions, quadrature, element stiffness, consistent and lumped mass, body and pressure loads, stresses and their extrapolation, isotropic and orthotropic elasticity. Pure functions, no solver loop. | started |
+| L1 | `modelcraft-fem` | Element kernels shared by every structural solver: the element table (tet4, tet10, wedge6, hex8 full and incompatible modes, hex20 full and reduced), shape functions, quadrature, element stiffness, consistent and lumped mass, body and pressure loads, stresses and their extrapolation, isotropic and orthotropic elasticity, and the uniform-strain (one-point) hex8 and tet4 kinematics, hourglass shape vectors and element frequency bounds of the explicit solver. Pure functions, no solver loop. | started |
 | L1 | `modelcraft-decks` | Abaqus input, Nastran bulk data and LS-DYNA keyword readers and writers, to and from `model`. Text out, no file system; `deck.write` saves it. | started |
 | L1 | `modelcraft-render` | Display data without a GPU dependency: the visible faces, element edges and nodes of a model, the orbit camera, a CPU rasterizer for headless snapshots; contour maps later. | started |
-| L2 | `modelcraft-solver` | Implicit solver: assembly from the resolved model, boundary conditions, sparse direct solution, linear static and modal analysis, stresses and reactions. The explicit (`modelcraft-explicit`) and lattice Boltzmann (`modelcraft-lbm`) solvers join this layer. | started |
+| L2 | `modelcraft-solver` | Implicit solver: assembly from the resolved model, boundary conditions, sparse direct solution, linear static and modal analysis, stresses and reactions. The lattice Boltzmann solver (`modelcraft-lbm`) joins this layer. | started |
+| L2 | `modelcraft-explicit` | Explicit dynamics: central-difference time integration with lumped mass, one-point hex8 with hourglass control, nodal-pressure tet4, bulk viscosity, rigid walls, energy account, histories and field frames. | started |
 | L3 | `modelcraft-fsi` | Fluid–structure coupling between the L2 solvers (later). | planned |
 | L4 | `modelcraft-doc` | The document: geometry, mesh, model, results, history. | planned |
 | L5 | `modelcraft-io` | `.modelcraft` files (docs/formats/modelcraft.md): text model definition, binary mesh, geometry references with content hashes, the journal; atomic saves; autosave storage for crash recovery. Bytes in, bytes out; the file system only in `fs` and `recovery`. Result files later. | started |
@@ -170,6 +171,39 @@ modes), tension through a distributing coupling against the equivalent pressure
 end, pure bending by a moment through a distributing coupling, torsion of a tube by a moment on
 a kinematically coupled point (twist and shear stress).
 
+## Explicit solver
+
+`modelcraft-explicit` integrates a model's `explicit_dynamic` steps in time (`solve.explicit`;
+`solve.history` and `solve.probe` read the stored histories and frames). Methods and papers are
+cited in the module docs and in docs/solvers/literature.md (Part H).
+
+1. **System.** `Model::resolve()`; hex8 sections with reduced integration become one-point
+   uniform-strain hexahedra with Flanagan–Belytschko hourglass control, tet4 sections Bonet–Burton
+   average nodal pressure tetrahedra (`modelcraft_fem::uniform` holds their kinematics). Other
+   element kinds and formulations, couplings, reference points and moments return "not supported
+   yet". Masses are row-sum lumped. A zero-valued boundary condition holds a degree of freedom; a
+   displacement value is reached at constant velocity over the step. Loads act in full from the
+   start. The step lists initial velocities and fixed frictionless rigid planes by set.
+2. **Time step.** Each element's highest frequency is bounded in closed form (exact for a cube);
+   the increment is the step's scale (0.9 by default) times the smallest element increment with
+   Wilkins' bulk-viscosity correction, recomputed every increment. The ten controlling elements
+   are reported; a step that would need more increments than its cap is refused before it runs.
+3. **Integration.** Central differences in the half-step form, elements in label order, no
+   parallel reductions (bit-for-bit repeatable). Rigid walls and prescribed degrees of freedom are
+   kinematic velocity constraints whose impulses are the reactions.
+4. **Energy account.** Kinetic, internal (stress work), hourglass, bulk viscosity, external and
+   constraint work, and their balance; a run warns when the balance is off by more than 1% of the
+   largest energy or the hourglass energy exceeds 10% of the internal energy.
+5. **Results.** Histories (energies, momentum, constraint force, chosen nodes) at the history
+   interval and field frames (displacement, velocity, element stress and strain) at the output
+   interval, capped in size; kept in the session like the implicit results.
+
+The first version is geometrically linear with linear elastic materials. Verification
+(`crates/explicit/tests/verification.rs`, analytic only): stress waves in hex8 and tet4 bars
+(front at c·t, σ = ρ c v, work input), a bar striking a rigid wall (contact time 2L/c, rebound
+speed, plateau force ρ c v₀ A), the energy balance, bit-for-bit repeatability; in the engine
+(`solve.rs`), a cantilever's free-vibration period against `solve.frequency`.
+
 ## Commands
 
 Every user-visible action is a `CommandSpec` in `crates/engine/src/cmd/<area>.rs` with a JSON

docs/features.md

@@ -5,7 +5,7 @@ Generated from the capability catalogue (`crates/engine/src/catalogue.rs`) by
 Every entry is a toolbar button. **Ready** entries run their command; **coming soon** entries are
 shown greyed with the roadmap milestone that brings them (ROADMAP.md).
 
-35 ready, 65 coming soon.
+36 ready, 64 coming soon.
 
 ## Geometry
 
@@ -121,7 +121,7 @@ shown greyed with the roadmap milestone that brings them (ROADMAP.md).
 | Decks | Read Deck — Read a deck, keeping keywords ModelCraft does not know | coming soon (M9) |  |
 | Implicit | Static — Linear static solve of a step with ModelCraft's own solver | ready | `solve.static` |
 | Implicit | Frequency — Natural frequencies and mode shapes of a frequency step | ready | `solve.frequency` |
-| Explicit | Explicit — Explicit dynamics: central differences, contact, erosion | coming soon (M10) |  |
+| Explicit | Explicit — Transient dynamics of an explicit step by central differences (contact and erosion coming in M10) | ready | `solve.explicit` |
 | Explicit | Blast & Impact — EOS-driven fluids with fluid–structure contact (ALE or SPH) | coming soon (M14) |  |
 | Fluids | Lattice Boltzmann — Lattice Boltzmann flow on the CPU or the GPU | coming soon (M12) |  |
 | Fluids | Fluid–Structure — Coupled fluid and structure solve | coming soon (M13) |  |
@@ -134,7 +134,7 @@ shown greyed with the roadmap milestone that brings them (ROADMAP.md).
 | Display | Contours — Contour plots of stress, strain and displacement | coming soon (M4) |  |
 | Display | Mode Shapes — Mode shapes of a frequency step | coming soon (M4) |  |
 | Display | Animate — Animate modes and time histories | coming soon (M9) |  |
-| Query | Probe — Displacement, reaction and stress at nodes, or a mode shape | ready | `solve.probe` |
+| Query | Probe — Displacement, reaction and stress at nodes, a mode shape, or an explicit field frame | ready | `solve.probe`, `solve.history` |
 | Query | Reactions — Reaction force and moment sums | coming soon (M4) |  |
 | Query | Free Body — Free-body forces across a cut | coming soon (M9) |  |
 | Plots | XY Plot — Plot a quantity against time or another | coming soon (M9) |  |

docs/parity.md

@@ -61,6 +61,7 @@ products are run, no documentation text is copied). Status: **done**, **started*
 | Decks | LS-DYNA keyword writer (implicit; explicit in M8) | M3 | | done (implicit static and eigenvalue; beam sections planned) |
 | Decks | Readers keeping unknown keywords | M9 | | planned |
 | Solve | Own linear static and modal solver, verified against analytic solutions | M4 | yes | started (solid elements: tet4, tet10, wedge6, hex8, hex20; reference points, kinematic and distributing couplings, moments) |
+| Solve | Own explicit dynamics solver (central differences, one-point hex8 with hourglass control, nodal-pressure tet4, bulk viscosity, energy balance), verified against analytic wave and impact solutions | M10 | yes | started (X1 core: small-strain elastic, rigid walls; large deformation, plasticity and contact planned) |
 | Results | Deformed shape, contours, mode shapes, probes, reaction sums | M4 | | started (results in the session, `solve.probe`, reaction sums; display planned) |
 | Results | XY and path plots, cuts, display groups, free-body forces, animation | M9 | | planned |
 | Results | Readers for public result formats (Nastran OP2, LS-DYNA d3plot, Abaqus `.fil`) | M9 | | planned |

docs/solvers/literature.md

@@ -991,3 +991,34 @@ the module docs):
   element accuracy*, Finite Elem. Anal. Des. 1(1):3–20, 1985 (patch tests); Lamé, Kirsch,
   Timoshenko and Euler–Bernoulli closed forms; Saint-Venant's principle (tension through a
   coupling), pure bending σ = M z / I, torsion of a circular tube φ = T L / (G J), τ = T r / J.
+
+## Part H: Explicit solver core (X1), as implemented
+
+The papers and books `modelcraft-explicit` and `modelcraft_fem::uniform` are written from (cited
+again in the module docs):
+
+- Time integration, energy balance, element eigenvalue inequality: T. Belytschko, W. K. Liu,
+  B. Moran, K. Elkhodary, *Nonlinear Finite Elements for Continua and Structures*, 2nd ed., Wiley
+  2014 (ch. 6: central differences in the half-step form with variable increments, the energy
+  balance check, the critical time step).
+- One-point hexahedron and hourglass control: D. P. Flanagan, T. Belytschko, IJNME
+  17(5):679–706, 1981 (integrated gradients b, mean strain, the γ hourglass shape vectors
+  orthogonal to linear fields, viscous and stiffness resisting forces). Our scaling of the
+  coefficient with ρ, c and the element size is our own: κ is the fraction of critical damping
+  (viscous) or the squared frequency ratio (stiffness) of a cube's hourglass modes at 2c/h.
+- Element frequency bound: in the spirit of D. P. Flanagan, T. Belytschko, J. Appl. Mech.
+  51(1):35–40, 1984; we bound uᵀKu ≤ (k/V) λ_max(Σ b bᵀ) ‖u‖² with k = max(3λ + 2μ, 2μ)
+  (isotropic) or 2 λ_max(D), which is exact for a cube; the 3 × 3 eigenvalue in closed form after
+  O. K. Smith, Commun. ACM 4(4):168, 1961.
+- Average nodal pressure tetrahedron: J. Bonet, A. J. Burton, Commun. Numer. Methods Eng.
+  14(5):437–449, 1998.
+- Bulk viscosity and its time-step correction: J. von Neumann, R. D. Richtmyer, J. Appl. Phys.
+  21(3):232–237, 1950; M. L. Wilkins, J. Comput. Phys. 36(3):281–303, 1980.
+- Rigid walls as kinematic velocity constraints: T. J. R. Hughes, R. L. Taylor, J. L. Sackman,
+  A. Curnier, W. Kanoknukulchai, CMAME 8(3):249–276, 1976.
+- Verification: d'Alembert's solution of the 1D wave equation (front at c t, σ = ρ c v), the
+  elastic bar impact on a rigid wall (contact 2L/c, rebound at the impact speed; Hughes et al.
+  1976), Euler–Bernoulli and the implicit modal solver for the cantilever period. The one-point
+  element keeps 1 − 1/n² of the bending energy with n elements through the depth, which predicts
+  its period with viscous hourglass control to 0.03%.
+