Epic: property engine 2 — hardening (finite-strain partials, engine split, hot path, one way to do it) #237

Why

Epic #221 puts the concepts in place: a typed, inspectable graph, iteration groups, residual systems with the implicit-function-theorem tangent, declared partials with a finite-difference check, history kinds, checkpoints, and one error contract (#231). A review of #222–#231 found no design flaw, but three things keep the engine from being future-proof:

1. Finite strain cannot be differentiated. core/derivatives.h packs every rank-2 value into 6 Mandel components and keeps only its symmetric part. As a result:
   • dP/dF of neo_hooke and hencky_elasticity would be silently symmetrised, so both stay unmigrated in Declared partials for the elastic producers and the damage chain (#219, part 1) #230;
   • the deformation-gradient source sets inverse and determinant in bind() (driver/external_state_source.h:113-119), so neither carries a derivative from F;
   • any finite-strain inelastic model hits the same wall.
2. core/property_engine.h has become one class doing six jobs. It grows from 609 lines on main to 1359 lines with Property engine: residual systems set up at run time (#218) #229: graph building, scheduling and constant folding, iteration groups, derivative plans, residual-system solving, and history state. Every new feature touches the same file, and the units cannot be tested on their own.
3. The hot path is unmeasured. The FFT host evaluates millions of points per iteration. The review found allocations on hot paths:
   • fold() allocates J, B and dx/dp on every differentiate();
   • derivative() builds a string on every call (being fixed in Partial derivatives: per-callback declarations and forward accumulation (#217) #227);
   • checkpoints serialise through std::ostringstream.
     Nobody has benchmarked the engine against main since Epic: property engine with per-callback declared reads as the foundation #173.

Two more things block usefulness rather than correctness:

• there are two ways to do most things (old derivative outputs next to partials, vector_newton / backward_euler next to system, the deprecated declaration API);
• docs/writing_a_material.md predates partials, systems and the error contract.

Target

• Every value the graph carries can be differentiated: symmetric tensors as Mandel-6, general tensors as full-9, with the layout chosen from the declared kind.
• The engine is a thin facade over separately tested units, with no file over about 400 lines.
• update() and differentiate() allocate nothing after the first call. A benchmark in the repo shows the cost per point against main for elasticity, J2 on system, the damage chain with derivatives, and a composite group.
• There is one way to declare a callback, get a tangent and solve a local system. The old paths are removed after a deprecation release.
• A material author can write a new model from the guide alone. The guide's example compiles as part of the tests.

Phases (merge order)

• Split property_engine.h into separately tested units (no behaviour change) #232 Split property_engine.h into units (no behaviour change). First, because everything else touches the engine.
• Engine benchmark and an allocation-free update()/differentiate() #233 Benchmark and an allocation-free hot path. Needs H2.
• Partials for non-symmetric tensors: full-9 layout, derivatives of F-derived values (finite strain) #234 Non-symmetric partials for finite strain (full-9 layout, F-derived values with derivatives, neo_hooke and hencky migrated). Needs H2 and History codecs: storage and rotation of a history, type-erased at declaration (#216) #224.
• One way to do it: remove the old derivative outputs, local solvers and deprecated declarations #235 Remove the old paths. Needs the rest of Migrate materials to declared partials and residual systems #219, and numsim_material target: emit add_callback(...).reads(...) instead of the deprecated add_output callback numsim-codegen#161 for the Remove the deprecated declaration API #190 part.
• Rewrite docs/writing_a_material.md for the engine-2 API, with a compiled example #236 Rewrite docs/writing_a_material.md for the new API, with a compiled example. Can start any time and is finished after H4.

Already open and in scope

• Property engine: check reads of a material's own outputs #185 check reads of a material's own outputs
• Property engine: invalidate on the write, not on get_mutable() #186 invalidate on the write, not on get_mutable()
• Property engine: small API issues from the review of #174-#183 #189 small API issues from the phase: one callback per relay (#167) #174–One declaration style: deprecate the old callback declarations, author guide (#172) #183 review
• Remove the deprecated declaration API #190 remove the deprecated declaration API (becomes part of H4)
• Move the host-neutral headers errors.h and external_state_source.h out of umat/ #212 remaining step: move statev_map out of umat/

Decisions

• Deferred, each with its trigger:
  • nested iteration groups, when the first model needs a loop inside a loop;
  • second derivatives, when a tangent must pass through a derivative output (today isotropic_damage splits its callback instead);
  • Property engine: change propagation (deferred) #220 change propagation.
• Not a goal: automatic differentiation; the reasons are the same as in Epic: property engine 2 — inspectable graph, in-engine iteration, residual systems and derivative edges #221.
• Deprecation policy: a removed API is first [[deprecated]] for one tagged release, with the replacement named in the message.

Done when

• Every phase is merged.
• The benchmark table is in the H3 PR and there is no regression against main.
• check_partials passes for every material, including neo_hooke and hencky_elasticity.
• grep -r deprecated include/ is empty after H4.