Explicit X2: large deformation, J2 and Johnson-Cook plasticity, damage and erosion (M10)

- model: materials gain solver-neutral plastic (bilinear isotropic/kinematic,
  hardening table, Johnson-Cook with adiabatic heating), damage (Johnson-Cook
  D1-D5) and erosion (plastic strain); explicit steps gain nonlinear_geometry
  (default on) and stress_rate (jaumann | green_naghdi).
- fem: rotation (Hughes-Winget, Flanagan-Taylor), plasticity (radial return,
  capped bracketed Newton for Johnson-Cook, damage; the update takes the
  mechanical strain increment so thermal strains can be subtracted), closed-form
  hex8 gradients for deformed configurations.
- explicit: updated Lagrangian hex8/tet4, per-element material state, erosion
  with reported energy, plastic work in the energy account.
- solver: warns that the linear solver uses the elastic constants of plastic
  materials (results hash-identical).
- decks: Abaqus *PLASTIC (+ Johnson-Cook keywords), Nastran MATS1/TABLES1,
  LS-DYNA *MAT_PLASTIC_KINEMATIC / *MAT_PIECEWISE_LINEAR_PLASTICITY; what a
  format cannot express is reported as Unsupported.
- engine: model.material.plasticity, model.material.damage (catalogue ready),
  explicit element probe, eroded elements in the solve summary.

Step commits before the rebase onto the DOF framework: branch explicit-x2-steps.

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

docs/architecture.md

@@ -21,11 +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, 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-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, the uniform-strain (one-point) hex8 and tet4 kinematics, hourglass shape vectors and element frequency bounds of the explicit solver, objective stress rates and J2/Johnson–Cook return mapping. 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, geometry surfaces with their face boundaries, deformed shapes and banded contour plots of nodal results, picking. | started |
 | L2 | `modelcraft-solver` | Implicit solver: assembly from the resolved model, boundary conditions, sparse direct solution, linear static and modal analysis, stresses and reactions. | 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 |
+| 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, large deformation with objective rates, plasticity, damage and erosion, energy account, histories and field frames. | started |
 | L2 | `modelcraft-lbm` | Lattice Boltzmann flow solver on the CPU: D3Q19 two-relaxation-time scheme, bounce-back and slip walls, Zou–He inlets and outlets, obstacles voxelised from the face-tagged surface with exact predicates, momentum-exchange forces per face. Uses `mesh` for the predicates and the boundary surface. | started |
 | L3 | `modelcraft-fsi` | Fluid–structure coupling between the L2 solvers (later). | planned |
 | L4 | `modelcraft-doc` | The document: geometry, mesh, model, results, history. | planned |
@@ -187,7 +187,8 @@ a kinematically coupled point (twist and shear stress).
 
 `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).
+cited in the module docs and in docs/solvers/literature.md (Parts H and J). Both structural solvers
+number their degrees of freedom with `modelcraft_fem::DofLayout` (docs/fem.md).
 
 1. **System.** `Model::resolve()`; hex8 sections with reduced integration become one-point
    uniform-strain hexahedra with Flanagan–Belytschko hourglass control, tet4 sections Bonet–Burton
@@ -210,11 +211,24 @@ cited in the module docs and in docs/solvers/literature.md (Part H).
    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`.
+6. **Large deformation and materials (X2).** With `nonlinear_geometry` (the default) the
+   elements are updated Lagrangian: strain and spin increments on the midpoint configuration,
+   forces on the current one (hex8 gradients in closed form, `UniformStrain::hex8_deformed`). The
+   material state (stress, back stress, strain, stiffness hourglass forces) is rotated with the
+   Jaumann rate (Hughes–Winget) or the Green–Naghdi rate (Flanagan–Taylor), `fem::rotation`;
+   materials are hypoelastic or J2 plastic (bilinear isotropic/kinematic, hardening table,
+   Johnson–Cook with adiabatic heating) by radial return with Johnson–Cook damage,
+   `fem::plasticity`. Elements whose damage reaches 1 or whose plastic strain reaches the
+   material's erosion strain are eroded (reported with their energy; their nodes keep mass and
+   momentum). The energy account adds the plastic work and the eroded energy.
+
+Verification (`crates/explicit/tests/verification.rs` and `large_deformation.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; Dienes' simple shear for both rates, a stressed element turned rigidly
+by 90°, the J2 uniaxial curve and unloading at large strain, damage failure at the fracture
+strain, and the Taylor bar against Taylor's 1948 estimate; in the engine (`solve.rs`), a
+cantilever's free-vibration period against `solve.frequency`.
 
 ## Lattice Boltzmann solver
 

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).
 
-46 ready, 55 coming soon.
+48 ready, 53 coming soon.
 
 ## Geometry
 
@@ -56,9 +56,9 @@ shown greyed with the roadmap milestone that brings them (ROADMAP.md).
 | Panel | Capability | Status | Command |
 |---|---|---|---|
 | Materials | Material — Elastic (isotropic, orthotropic) material with density | ready | `model.material.create`, `model.material.edit`, `model.material.delete` |
-| Materials | Plasticity — Plastic hardening data | coming soon (M8) |  |
+| Materials | Plasticity — Von Mises plasticity: bilinear, hardening table or Johnson–Cook | ready | `model.material.plasticity` |
 | Materials | Hyperelastic — Hyperelastic material models | coming soon (M8) |  |
-| Materials | Damage — Damage initiation and evolution | coming soon (M8) |  |
+| Materials | Damage — Johnson–Cook damage and element erosion | ready | `model.material.damage` |
 | Materials | Thermal — Conductivity, specific heat and expansion | coming soon (M8) |  |
 | Materials | Equation of State — Polynomial, ideal gas, Mie–Grüneisen, JWL and tabulated equations of state | coming soon (M11) |  |
 | Sections | Section — Solid, shell, beam, rod or 2D (plane stress, plane strain, axisymmetric) section assigned to a set, with its element formulation | ready | `model.section.create`, `model.section.edit`, `model.section.delete` |

docs/parity.md

@@ -44,7 +44,7 @@ products are run, no documentation text is copied). Status: **done**, **started*
 | Mesh | Mesh editing (move, merge, split, collapse, remesh region), imported orphan meshes | M6 | yes | started (node/element add/remove) |
 | Model | Sets and surfaces bound to geometry names | M3 | yes | done |
 | Model | Materials: elastic (isotropic, orthotropic), density, unit-system check | M3 | | done |
-| Model | Materials: plasticity, hyperelasticity, damage, thermal | M8 | | planned |
+| Model | Materials: plasticity, hyperelasticity, damage, thermal | M8 | | started (von Mises plasticity: bilinear, table, Johnson–Cook; Johnson–Cook damage, erosion; written to Abaqus `*PLASTIC`, Nastran `MATS1`, LS-DYNA plastic materials where expressible) |
 | Model | Sections: solid, shell, beam profiles; assignment by set | M3 | | done |
 | Model | 2D sections: plane stress, plane strain, axisymmetric (XY plane, Y the axis); element edges in sets; centrifugal load | M4 | | done |
 | Model | Composite layups, material orientations, continuum shells | M8 | yes | planned |
@@ -62,7 +62,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; 2D plane stress, plane strain and axisymmetric tri3, tri6, quad4 (full, incompatible modes), quad8 (full, reduced); reference points, kinematic and distributing couplings, moments; centrifugal loads) |
-| 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) |
+| 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 and X2: large deformation, objective rates, J2 and Johnson–Cook plasticity, damage, erosion; 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

@@ -1061,3 +1061,33 @@ lattice Boltzmann package's code was opened.
   5(2):317–328, 1959, with the higher terms of A. S. Sangani, A. Acrivos, Int. J. Multiphase Flow
   8(4):343–360, 1982 (DOIs not checked). Benchmark (published numerical reference values, tagged,
   not part of the analytic gate): Schäfer & Turek 1996, 2D-1 (C8).
+
+## Part J: Large deformation and inelastic materials (X2), as implemented
+
+The papers and books `modelcraft_fem::{rotation, plasticity}` and `modelcraft-explicit`'s X2
+update are written from (cited again in the module docs):
+
+- Updated Lagrangian one-point elements, strain increments on the midpoint configuration:
+  T. Belytschko, W. K. Liu, B. Moran, K. Elkhodary, *Nonlinear Finite Elements for Continua and
+  Structures*, 2nd ed., Wiley 2014 (ch. 4–6); the closed-form integrated gradients b = ∂V/∂x of
+  the hexahedron, D. P. Flanagan, T. Belytschko, IJNME 17(5):679–706, 1981 (we tabulate the 24
+  coefficients of the volume form and check them against their exact integration).
+- Jaumann rate, incrementally objective: T. J. R. Hughes, J. Winget, IJNME 15(12):1862–1867,
+  1980 (Cayley rotation of the midpoint spin increment; a rigid rotation of any size is exact).
+- Green–Naghdi rate: D. P. Flanagan, L. M. Taylor, CMAME 62(3):305–320, 1987 (incremental polar
+  rotation from V̇ = L V − V Ω; we solve [(tr V) I − V] x = axial(D V − V D) and integrate V with
+  the midpoint rule).
+- Radial return for J2 with isotropic and linear kinematic (Prager) hardening: J. C. Simo, T. J.
+  R. Hughes, *Computational Inelasticity*, Springer 1998, §3.3; R. D. Krieg, D. B. Krieg, J.
+  Press. Vessel Technol. 99(4):510–515, 1977.
+- Johnson–Cook flow stress (rate clamped at ε̇* ≥ 1, T* in [0, 1], adiabatic heating with a
+  Taylor–Quinney fraction) and fracture strain D1–D5 with D = Σ Δε_p/ε_f: G. R. Johnson, W. H.
+  Cook 1983 (7th Int. Symp. Ballistics) and Eng. Fract. Mech. 21(1):31–48, 1985. The fracture
+  strain is floored at 10⁻⁶ (our choice).
+- Erosion: G. R. Johnson, R. A. Stryk, Int. J. Impact Eng. 5:411–421, 1987; T. Belytschko, J. I.
+  Lin, ibid. 5:111–127, 1987 (delete, keep nodal mass and momentum, report the energy).
+- Verification: J. K. Dienes, Acta Mech. 32:217–232, 1979 (simple shear, closed forms for both
+  rates); G. I. Taylor, Proc. R. Soc. A 194:289–299, 1948 (the yield stress from the final length
+  and undeformed length of a flat-ended projectile). Published experimental Taylor-bar lengths
+  (Wilkins & Guinan 1973) are not used: that needs the owner's sign-off for a tagged benchmark
+  suite.