[lmoresi]

Viscoelastic constituents in MultiMaterialConstitutiveModel, so a fault material (TI-VEP, or a weak VEP) can sit beside an isotropic VEP bulk under a level set or an index variable. This is item A of the VE/plastic gap closure. Stacked on #851; review and merge #851 first, then this PR retargets to development.

What was broken

A composite with any viscoelastic constituent ran without error and gave wrong results:

• No stress history. The composite did not forward requires_stress_history, order, the history kwargs, dt_elastic, the pre- and post-solve hooks or history_flux. The run was silently viscous or produced NaN.
• One ETD α for every material. α and φ lived on the shared stress history, so the last constituent to update them set them for all.
• TI-VEP given its parameters before a solver. The tensor was built and cached at dt = ∞ and gave NaN, even for a single material.
• VEP BDF at dt = ∞. The effective viscosity was 0·∞.

What changed

• ETD coefficients belong to the model (_ExponentialCoefficients mixin). Each constituent relaxes on its own Maxwell time. The history's own coefficients are removed; nothing reads them, and snapshots never carried them.
• An infinite elastic timestep is the viscous limit in the VEP and TI-VEP effective viscosity and tensor. The TI dt setter resets the cached tensor.
• The composite forwards the stress-history interface:
  • order is the highest order of any constituent. Each constituent keeps its own order, and a history of lower order than a constituent needs is refused.
  • The solver now checks the order before assigning the model, so a refused composite is never left on the solver.
  • It also forwards effective_order, the history kwargs (contradictory requests raise), dt_elastic, the hooks, and history_flux.
• Docs: a section in constitutive-models.md; EXPONENTIAL_VE_INTEGRATOR.md.

A single-material run is bit-identical to the base.

Tests

tests/test_1054_multimaterial_viscoelastic.py (23 tests) uses pure shear with prescribed walls, against closed forms for each material:

• Identical constituents equal the single material to 5.6e-12.
• 4:1 Maxwell times; BDF-1 beside ETD-1; BDF-2 beside BDF-1; yield in one constituent; isotropic beside TI.
• A constituent change reaches the solver.
• Reassignment keeps each constituent's order.
• A refused composite is not assigned.
• Dimensional constituents take their scaled Maxwell times.
• Viscous beside VEP (characterisation, tier_b).
• The two single-material regressions above.

The errors elsewhere are the projected history smearing the stress jump at the interface, 2e-4 to 8e-3. The tolerances are about three times those values, and the measurements are in the module docstring. On the base, 15 of the first 18 tests fail.

Run: test_1054 serial and np2 (23/23); the VE and constitutive tier a/b subset (test_005*, 0017, 0019, 0070, 0610, 0857, test_10*): 874 passed. Two failures, both on the base too: test_1079 (#848), and test_0017 after test_1057 (its plugin TensorTransport stays in the family registry, the same order dependence as test_0016).

Review

Two internal adversarial review rounds, both posted below. The second found a units bug in the base PR (#851's ETD read parameter magnitudes, not scaled values), which is now fixed there (189aa88) and merged here.

Checklist (UW3 Style Charter)

• I have read the Style Charter and followed it over the surrounding code (S2)
• No drive-by refactors, renames, or "while I was here" cleanups (S9)
• Bug fixes ship the regression test, written first, with level_* and tier_* markers (S8)
• No hedging names and no commented-out code (S3, S4)
• Every exception swallow states its sanctioned failure mode in a comment (S4)
• New data access uses .array / mesh.X.coords (S7)
• Parallel safety considered: test_1054 on 2 ranks (S11)
• No dependency changes
• AI-assisted work carries the attribution line below

Underworld development team with AI support from Claude Code

[lmoresi]

Internal adversarial review: two rounds

Each round had independent reviewers working against a build of the base (#851). Probes are kept in the session scratchpad.

Round 1 (at 45b6d58)

#	Finding	Severity	Done
1	The composite's order setter forwarded the solver's order to every constituent, so a BDF-1 constituent beside a BDF-2 one became BDF-2 on reassignment (error 9.2e-2 against the closed form)	should-fix	The setter keeps each constituent's order and refuses a history of lower order than a constituent needs (83e8b76); reassignment test
2	The constituent-change test could not fail: the change it made did not alter the compiled flux	should-fix	Rewritten as a structural change. B is [0.4996, 0.5067] against τ_y = 0.5 with forwarding, and [0.976, 1.18] without, under a tolerance of 0.05 τ_y
3	The stress history's own ETD coefficients were dead once each model owned its α and φ	should-fix	Removed (a8dd765). No reader is left in src, tests, examples or notebooks, and snapshots never carried them

Round 2 (at 83e8b76)

#	Finding	Severity	Done
1	ETD in a units model: α = 1 − 3e-12 where e^-0.1 was expected (the parameter magnitudes were read in their own units). It is in the base #851 and predates both PRs	should-fix (base)	Fixed on #851 (189aa88) and merged here. Tests in test_1053 (single model, VEP and TI) and test_1054 (each constituent's own scaled τ)
2	A refused composite stayed assigned: VE_Stokes(order=1) given a BDF-2 constituent raised, but solver._constitutive_model was already the composite	should-fix	The solver sets an explicit history order on a model before assigning it (petsc_generic_snes_solvers.pyx); test_a_refused_composite_is_not_assigned
3	Stale comments in systems/solvers.py about the history's exponential coefficients	should-fix	Fixed. inventory.json is generated and is left to regenerate
4	A single model and a composite take the solver's order differently (a single model is raised to the history's order; a composite keeps each constituent's own)	nit	One line in constitutive-models.md

Attacks that failed (round 2)

• Order paths: Stokes(order=2) with two BDF-1 constituents; reassignment keeps (2,1); a lower-order history is refused with a clear message.
• BDF-2 step-ratio guard tripped inside a mix: the BDF-2 material tracks a single-material BDF-2 run within 7.6e-4 relative at every step.
• NavierStokes with a composite (ETD-1 beside BDF-2): eulerian and semi-Lagrangian agree to 3 figures at the sample points.
• describe() on an ETD composite names each model's own α.
• Every new test can fail: checked against the pre-fix code, or by the separation shown above.

Interactions

• ETD Maxwell integrator: a viscosity that varies in space keeps its elastic response #851: the base of this PR. This PR retargets to development once ETD Maxwell integrator: a viscosity that varies in space keeps its elastic response #851 merges.
• Forward-from-nodes history; semi-Lagrangian schemes named by trace and launch; every history equals serial in parallel #800: both PRs edit the constitutive and ddt code. Expect hand resolutions in the history-coefficient hooks, whichever lands second.
• New, found by the defaults study: the default nodal stress history never moves its stored stress with the flow (it refreshed its snapshot before the trace-back). A separate fix and PR is coming from development. The tests here use pure shear with walls that do not move, so they are unaffected.

---

Generated by Claude Code