FEM foundation B: heat transfer and thermal stress (solids, 2D, explicit), coupled temperature–displacement, solve.heat (#45)

* Heat transfer and thermal stress: thermal materials, temperature BCs, heat loads, heat transfer and coupled temperature–displacement steps, solve.heat

Model: Material.thermal (conductivity, specific heat, expansion, isotropic or
per axis; reference temperature), BoundaryCondition::Temperature (dof 11),
loads SurfaceFlux, Convection, HeatSource and Temperature (a field in static
steps), procedures HeatTransfer { transient (θ-method) } and
CoupledTemperatureDisplacement; checks for missing conductivity/specific
heat/expansion. fem: heat conduction kernels (conductivity, capacity,
source, face flux/film, heat flux) on the DofLayout (one T per node), thermal
strain load and stress D(ε − ε_th) for every solid formulation incl.
incompatible modes. Solver: steady and transient heat transfer, thermal loads
in static steps, coupled steps (exact one-way coupling). Engine: solve.heat,
temperature/heat-flux result fields, probes. Decks refuse heat transfer by
name. Analytic verification: slab, source+convection/flux, thick cylinder,
erfc semi-infinite solid, free/constrained expansion, bimetal strip, coupled
step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* thermal: strains in 2D elements and explicit dynamics

Plane::thermal_load and stresses_with for plane stress (εzz free), plane
strain (σzz = −D₃·ε_th) and axisymmetric elements, incompatible modes
included; the solver's 2D kernels take them. Explicit dynamics turns a
step's temperature loads into a per-element thermal strain rate (reached
linearly over the step) subtracted from each strain increment, so it feeds
J2 and Johnson–Cook updates. Verified: free expansion in every 2D theory
and element, a biaxially held plate, an explicit free bar (ΔL = αΔT L,
stress-free) and a clamped bar at −EαΔT, capped at the yield stress with
perfect plasticity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* clippy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* thermal: trusses take the axial thermal strain; keep the roadmap's M7 line

Truss::thermal_load and stresses_with project the thermal strain on the
member's tangent (Σ αₖ tₖ² ΔT); the static solver applies them to rod2/rod3
(#38). Explicit trusses take none yet and a warning says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

---------

Co-authored-by: jyviko <2501648+jyviko@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

docs/elements.md

@@ -83,6 +83,6 @@ hex8/20/27 with first and second derivatives).
 | Cohesive (2D, 3D) | Adhesive layers, delamination | planned |
 | Gasket | Through-thickness gasket behaviour | planned |
 | Infinite elements | Unbounded domains | planned |
-| Heat transfer (all shapes), coupled temperature–displacement | Thermal and thermal-stress analyses | in progress (FEM foundation, phase B); temperature DOF kind done |
+| Heat transfer (all shapes), coupled temperature–displacement | Thermal and thermal-stress analyses | done for solids (tet4/10, wedge6, hex8/20: steady and transient conduction, flux, convection, sources; coupled temperature–displacement); thermal strain in solids, trusses, 2D elements (plane stress, plane strain, axisymmetric) and explicit dynamics (one-point hex8, nodal-pressure tet4, with plasticity); 2D/shell/beam conduction and shell/beam thermal strain planned |
 | Acoustic | Fluid acoustics, structural–acoustic coupling | planned |
 | Rigid elements | Rigid bodies from meshes | planned (M7) |

docs/features.md

@@ -121,7 +121,7 @@ shown greyed with the roadmap milestone that brings them (ROADMAP.md).
 | Decks | Nastran Deck — Write Nastran bulk data (SOL 101, 103) | ready | `deck.write {"format":"nastran"}` |
 | Decks | LS-DYNA Deck — Write an LS-DYNA keyword file | ready | `deck.write {"format":"lsdyna"}` |
 | 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 | Static — Linear static (or coupled temperature–displacement) solve of a step with ModelCraft's own solver; heat transfer in the drop-down | ready | `solve.static`, `solve.heat` |
 | Implicit | Frequency — Natural frequencies and mode shapes of a frequency step | ready | `solve.frequency` |
 | 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) |  |

docs/fem.md

@@ -101,3 +101,35 @@ of the family's degree; on a curved map, linear fields exact with zero Hessian,
 physical Hessian of a quadratic interpolant consistent with finite differences of its physical
 gradient. The solver and explicit migration to `DofLayout` was checked bit for bit: every
 result of the solver, explicit, engine and io test suites hashes identically before and after.
+
+## Heat transfer and thermal strain
+
+A heat conduction element carries one temperature per node (`heat::HEAT_DOFS`, kind `T`);
+`heat::Conduction` gives the conductivity ∫ ∇Nᵀ k ∇N dV (full rule), the capacity ∫ ρc N Nᵀ dV
+and a source ∫ N Q dV (mass rule), and the heat flux −k∇T at the integration points;
+`heat::face_weights` and `face_film` integrate surface flux and convection on tri3/tri6/quad4/quad8
+faces. The solver (`modelcraft_solver::heat`) numbers the temperatures with
+`DofLayout::uniform(…, DofSet::TEMPERATURE)` and assembles with the same `sparse::add_block`.
+
+Thermal strain ε_th = α (T − T_ref) along the material axes enters a solid as the load
+`Solid::thermal_load(d, &ThermalStrain { alpha, delta })` = ∫ Bᵀ D ε_th dV and its stress as
+`Solid::stresses_with(d, u, Some(&thermal))` = D (ε − ε_th); `delta` is the nodal T − T_ref.
+2D elements have the same pair (`Plane::thermal_load`, `Plane::stresses_with`): plane stress
+leaves εzz free (σzz = 0), plane strain holds it (σzz = −D₃·ε_th), axisymmetric elements strain
+the hoop direction too. Trusses (rod2, rod3) take the axial part Σ αₖ tₖ² ΔT along their tangent (`Truss::thermal_load`,
+`Truss::stresses_with`). Shells and beams will provide the same two functions for their strains;
+springs, dashpots and point masses have no thermal strain.
+
+Explicit dynamics takes a step's temperature loads as a thermal strain rate per element,
+α ΔT / end time (the change reached linearly over the step, like a prescribed displacement, so
+there is no thermal shock), subtracted from each increment's strain increment before the
+constitutive update, so it feeds J2 and Johnson–Cook plasticity alike; isotropic expansion only
+(the rate is the same in any frame). Explicit trusses take no thermal strain yet (a warning
+says so).
+
+Model side: `Material::thermal` (`conductivity`, `specific_heat`, `expansion`, each isotropic
+or per axis, and `reference_temperature`), `BoundaryCondition::Temperature`, loads
+`SurfaceFlux`, `Convection`, `HeatSource` (heat transfer) and `Temperature` (a temperature field
+in a static step), procedures `HeatTransfer { transient }` and `CoupledTemperatureDisplacement`.
+Commands: `solve.heat`, and `solve.static` for coupled steps. The deck writers refuse heat
+transfer by name for now.

docs/solvers/literature.md

@@ -1119,3 +1119,25 @@ update are written from (cited again in the module docs):
   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.
+
+## Part K: Heat transfer and thermal stress, as implemented
+
+- **Conduction.** Galerkin form of ρc Ṫ = ∇·(k∇T) + Q with surface flux and convection:
+  O. C. Zienkiewicz, R. L. Taylor, J. Z. Zhu, *The Finite Element Method: Its Basis and
+  Fundamentals*, 7th ed., Butterworth-Heinemann 2013, §3.2; T. J. R. Hughes, *The Finite Element
+  Method*, Dover 2000, ch. 1. Kernels in `modelcraft_fem::heat`, solver in `modelcraft_solver::heat`.
+- **Time integration.** The generalized trapezoidal (θ) family, unconditionally stable for
+  θ ≥ ½ (Hughes 2000, §8.2): backward Euler (θ = 1, the default) and Crank–Nicolson (θ = ½).
+- **Thermal strain.** Initial-strain load ∫ Bᵀ D ε_th dV and stress D(ε − ε_th)
+  (Zienkiewicz, Taylor & Zhu 2013, §6.2.3); incompatible modes condensed with the same load.
+- **Coupled temperature–displacement.** One-way coupling (temperature strains the solid) solved
+  in turn, which is the exact monolithic solution of linear quasi-static thermoelasticity
+  without thermoelastic dissipation (B. A. Boley, J. H. Weiner, *Theory of Thermal Stresses*,
+  Wiley 1960, ch. 1).
+- **Verification** (`crates/solver/tests/thermal.rs`, analytic): steady slab conduction, a slab
+  with a heat source and convection or flux (quadratic profile), radial conduction through a
+  thick cylinder (T ∝ ln r), the semi-infinite solid T = erfc(x / 2√(κt)) (H. S. Carslaw,
+  J. C. Jaeger, *Conduction of Heat in Solids*, 2nd ed., Oxford 1959, §2.4), free and
+  constrained thermal expansion (σ = −EαΔT), the bimetal strip (S. Timoshenko, *Analysis of
+  bi-metal thermostats*, J. Opt. Soc. Am. 11(3):233–255, 1925), and the coupled step against
+  the heat step followed by the static step.