Epic: NumSim constitutive-model compiler — Phase 0-6 roadmap

Vision

A "Define Once, Generate Everywhere" constitutive-model compiler that takes a symbolic physics description and emits verified C++ for MOOSE / Abaqus / ANSYS / standalone backends. Users write physics; NumSim generates validated implementations.

The user writes physics. NumSim generates validated implementations.

Spec: NumSim Architecture & Design Specification (Draft 0.1).

Current state

numsim-codegen + numsim-cas implement ~20% of Phase 1 + ~5% of Phase 5 of the vision. About 80% of the work in this epic is greenfield. Realistic total: 15-20 months to Phase 6.

Key architectural decisions (locked in during planning)

Phased structure

Cross-cutting subissues

Dependency graph (key edges)

   #29 (Phase 0.2)
      ↓
   #30 (Phase 1.1)    #31 (Phase 1.2)
                          ↓
                      #32 (Phase 1.3 spike)
                          ↓
                      #33 (Phase 2 — Material IR)
                          ↓
                      #34 (Phase 3a — LNS)
                          ↓
                      #35 (Phase 3b — tangent + KT)
                       ↓        ↓
                   #36 (Phase 4) #37 (Phase 5)
                                    ↓
                              #2, #3, #4 (Phase 6)

Cross-cutting #38 + #39 span all phases.

Related existing issues

• Add AbaqusVUMATTarget backend (vectorized UMAT) #2 / Add AnsysUSERMATTarget backend #3 / Add LSDynaUMATTarget backend #4 — Abaqus VUMAT / Ansys USERMAT / LS-DYNA UMAT backends. Phase 6 of this roadmap.
• Negative-path test coverage: validate(), History throw, all tensor stubs, duplicate-add #11 — Negative-path test coverage. Partially covered by the Phase 1 work (stub-throw tests come naturally with Phase 1.1 — Implement currently-stubbed emit cases #30).
• CI hygiene: pin numsim-cas, enable -Werror on tests, add UBSan/ASan job #13 — CI hygiene. Extend with macOS + HPC compiler matrix as part of this epic's cross-cutting CI work.
• Code review follow-up: Med & Low findings (umbrella) #14 — Med/Low review umbrella. Several stub items get closed by Phase 1.1 — Implement currently-stubbed emit cases #30 (Phase 1.1).
• MOOSE Phase A guard accepts stateful outputs silently (only inputs checked) #15 — Stateful-output guard. Folded into Phase 2 — Material IR extensions (StateVariable, Equation, Constraint, LocalNewtonSystem) #33 (Phase 2 — StateVariable becomes first-class).
• MOOSE backend: add runtime parity test against mock RankTwoTensor #12 — MOOSE backend runtime parity test. Closed by Phase 5 — MOOSE + Standalone state-variable + algorithmic-tangent wiring #37 (Phase 5).
• Open-set extensibility: user-registered emitters for custom cas nodes #17 — Operation registry. Independent flexibility win; not on critical path of this epic.
• Split Layer 2 into language-agnostic compile() + C++ render step (unlocks non-C++ backends) #18 — CompiledModel split (language-agnostic Layer 2). Orthogonal to this roadmap; enables future non-C++ backends.
• Extract reusable C++ FEM-framework scaffolding (CxxFrameworkTarget + TypeMap + TmechBoundaryAdaptor) #19 — CxxFrameworkTarget extraction. Relevant to Phase 6 backend authoring; could land in parallel.
• CI: add CPM source cache to avoid re-cloning numsim-cas every build #27 — CI cache for CPM. Adjacent infrastructure.

Acceptance for the epic

Closed when:

• Phase 6 has at least one functioning backend beyond MOOSE+Standalone (Abaqus UMAT, per Add AbaqusVUMATTarget backend (vectorized UMAT) #2)
• The golden recipe suite (J2, NeoHookean, Drucker-Prager, simple damage, viscoplastic) passes its tangent-check and runtime-parity acceptance in CI
• A user can write a constitutive recipe and get a verified MOOSE Material + Abaqus UMAT from a single source, with a generated report documenting both

Cross-checks

• Estimated total: 15-20 months to Phase 6. Re-baselined after Phase 1.3 — 1D scalar plasticity de-risk spike (Phase 3 risk reduction) #32 (Phase 1.3 spike).
• Highest single risk: Phase 3b — Algorithmic tangent + Kuhn-Tucker lowering #35 (Phase 3b algorithmic tangent). De-risked by Phase 1.3 — 1D scalar plasticity de-risk spike (Phase 3 risk reduction) #32.
• Critical path: 0.2 → 1.2 → 1.3 → 2 → 3a → 3b → 4 + 5 → 6.

Subissues — full list

• Phase 0.2 — Codegen catch-up to local numsim-cas HEAD #29 — Phase 0.2: codegen catch-up to local numsim-cas HEAD
• Phase 1.1 — Implement currently-stubbed emit cases #30 — Phase 1.1: implement currently-stubbed emit cases
• Phase 1.2 — Lightweight compiler pass framework #31 — Phase 1.2: lightweight compiler pass framework
• Phase 1.3 — 1D scalar plasticity de-risk spike (Phase 3 risk reduction) #32 — Phase 1.3: 1D scalar plasticity de-risk spike
• Phase 2 — Material IR extensions (StateVariable, Equation, Constraint, LocalNewtonSystem) #33 — Phase 2: Material IR extensions
• Phase 3a — Time integration + LocalNewton lowering #34 — Phase 3a: time integration + LocalNewton lowering
• Phase 3b — Algorithmic tangent + Kuhn-Tucker lowering #35 — Phase 3b: algorithmic tangent + Kuhn-Tucker
• Phase 4 — Verification framework + material drivers + report generation #36 — Phase 4: verification framework + drivers + reports
• Phase 5 — MOOSE + Standalone state-variable + algorithmic-tangent wiring #37 — Phase 5: MOOSE + Standalone state + tangent wiring
• Cross-cutting — Generated-code performance story (CSE, inline hints, benchmark suite) #38 — Cross-cutting: generated-code performance story
• Cross-cutting — Debugging story for generated code (--emit-debug-comments, source maps, recipe REPL) #39 — Cross-cutting: debugging story