Master plan: phases, stages and status #22

Master plan of HyperFEMKernels.jl: phases, stages and status. Updated when a stage closes. Detailed plans live in the project design documents (design/weak-form-frontend.md, design/internal-variables.md, design/solvers.md); the solver block has its own tracking issue, #21.

Legend: ✅ done · 🔄 in progress · ⬜ pending

Phase 0 — Profiling ✅

Goal: continue only if assembly is > 50 % of the runtime of HyperFEM's reference problems.

• ✅ EM 3D plate (README case, Gmsh mesh) and box Q2: assembly 59–65 % of runtime (30 % on the 90k-DOF box, where LU dominates).
• ✅ hMRE 2D (Adv_Mater): assembly 72–76 %.
• ✅ Refinable meshes for larger models (benchmark/meshes).

Result: go.

Phase 1 — Engine ✅ (v0.1.0)

Goal: minimal engine verified against Gridap, with the HyperFEM adapter; criterion measured on assembly (decision: the iterative solver becomes a separate block).

• ✅ Weak-form front end: Gridap's lazy tree read at run time with probes; no per-physics descriptor (design/weak-form-frontend.md).
• ✅ Code generation (RuntimeGeneratedFunctions), slot layout, CSE.
• ✅ Linear-map shortcut: residual coefficients and tangents without dual numbers when the form is linear in its state inputs.
• ✅ Tables (geometry, nodal shape functions), fused element kernels, Jacobian as register-tiled matrix products.
• ✅ Threaded assembly: sparsity equal to Gridap's, precomputed nonzero positions, greedy colouring, work-based chunks; update reuses tables, pattern and colouring.
• ✅ Subdomain integration (glue), Dirichlet masks, multi-field.
• ✅ Sum factorisation on n-cubes and matrix-free Jacobian (MatrixFreeJacobian, prepare!, mul!).
• ✅ GridapDistributed capture per part verified (4 parts, with_debug).
• ✅ Verification: check vs Gridap (1e-15 on EM, hMRE, visco), allocations (0 B in all kernels; HyperFEM's ViscousPolyconvex law allocates — report delivered).
• ✅ Test suite (22 k+ tests) and CI on Ubuntu/macOS; HyperFEM weak-form tests in CI.
• ✅ Performance: assembly ×5–7 (1 thread), ×20–36 (18 threads) vs Gridap; gemm_add! at 65–85 % of OpenBLAS; absolute-efficiency study (benchmark/roofline.jl).
• ✅ HyperFEM adapter (backend=:kernel|:gridap, extension in HyperFEM branch kernel-backend).
• ✅ Protected main (PR + 5 checks); Julia ≥ 1.12 (Require Julia 1.12 #17).

Not reached, by decision: full solve! ×5 with LU (×1.5–1.7, LU dominates) → solver block.

Phase 2 — Coverage of the weak forms 🔄

• ✅ Hybrid fallback: contributions the engine cannot translate are assembled by Gridap and added, with a warning (Phase 2: hybrid fallback (untranslatable contributions assembled by Gridap) #1).
• ✅ Boundary integrals (Neumann, Robin, surface and follower loads with the normal) (Phase 2: boundary integrals in the engine #2).
• ✅ Numbers of the weak form as runtime parameters: update without recompiling (Numbers of the weak form as runtime parameters: update without recompiling #4, Numbers of the weak form as runtime parameters (#4) into main #5).
• ✅ update reuses cell maps and colourings (update: reuse the cell maps and colourings of the previous operator #11).
• ✅ Internal variables: update_state! executed by the engine (Phase 2: internal variables (update_state!) executed by the engine #12, design/internal-variables.md).
• ✅ Skeleton integrals: plus/minus, jump, mean, facet kernels seeing both cells; matrix-free with skeleton groups (Skeleton integrals in the engine (plus/minus, jump, mean) #16). Left for later: states on facets, memory of facet positions (Skeleton integrals: features left for later (states on facets, memory of facet positions) #20).
• ✅ HyperFEM integration tests with backend=:kernel: Dirichlet projection (test/hyperfem: Dirichlet projection of HyperFEM's drivers with backend=:kernel #10), StaticLinearModel (test/hyperfem: StaticLinearModel with backend=:kernel #13), BoundaryConditions and Coupling (Example hMRE + vacuum 2D (Adv_Mater hMRE_Vacuum_2D.jl) with both backends; subdomain/interface tests #7, hmre_vacuum_2d: interface coupling as Coupling (HyperFEM coupling-prescription) #8), the seven simulation tests with both backends (HyperFEM's simulation tests with both backends (included from HyperFEM kernel-backend) #14, Simulation tests live in HyperFEM (kernel-backend) and are included here #15), third-medium contact.
• ✅ Examples: patient aorta CFD (Example: patient aorta CFD, Gridap vs HyperFEMKernels #3), hMRE + vacuum 2D (Example hMRE + vacuum 2D (Adv_Mater hMRE_Vacuum_2D.jl) with both backends; subdomain/interface tests #7); meshes local to the repository (Meshes local to the repository; drop Adv_Mater_Ultra_Soft_Magnet #6); benchmarks in benchmark/ (Move benchmarks out of dev/ and stop versioning dev/ #9).
• ⬜ Mixed meshes (several cell types in one triangulation): today the whole form goes to Gridap through the fallback.
• ⬜ Differential operators on products with the unknown (∇(u*w)): whole form to Gridap; only if a case needs it.

Solver block ✅ (tracking issue #21, design/solvers.md)

Goal: solve! ≥ ×5 vs Gridap+LU from ~200k DOFs; Krylov iterations nearly mesh-independent.

• ✅ D1 Libraries: PETSc via GridapPETSc (GAMG, BoomerAMG, fieldsplit, MUMPS); AlgebraicMultigrid.jl for CI.
• ✅ D2 Code location: S0′, S1, S2 in HyperFEM (extension on GridapPETSc); S3–S5 in HyperFEMKernels.
• ✅ D3 Hardware: laptop (M5 Max, 128 GB, 18 threads) for the criteria; cluster for MPI/GPU.
• ✅ D4 Problem priority; ⬜ D5 curvature-criterion default.
• ✅ S0 Baseline, PETSc check (½ session)
• ✅ S0′ Newton fixes in HyperFEM (½)
• ✅ S1 Krylov + AMG + rigid modes, HyperFEM (2)
• ✅ S2 fieldsplit blocks u–φ, HyperFEM (1½)
• ✅ S3 Matrix-free inside Newton, HyperFEMKernels (1)
• ✅ S4-A Matrix-free p-multigrid (Q2→Q1, Q3→Q1, Q3→Q2→Q1), HyperFEMKernels p-multigrid preconditioner for MatrixFreeSolver (S4-A) #49 (0.2.2) + HyperFEM #281: ×8.3 per Newton iteration at 957k Q2 and ×19 at 227k Q3 vs CG + GAMG on the assembled tangent, ~4× less memory
• ✅ S4-B h-multigrid for Q1/P1 models on a refined mesh hierarchy (MeshHierarchy, HMultigridSolver, FieldSplitSolver), HyperFEM #282 + HyperFEMKernels benchmark: S4-B hierarchy cases and h-multigrid configurations #51: ×5.0 per Newton iteration at 799k Q1 hexahedra and ×5.7 at 893k P1 tetrahedra vs CG + GAMG, ×3.0 on the EM plate (u, φ) at 555k vs the PETSc fieldsplit
• ✅ S5 Performance levers + robustness near instabilities, HyperFEM #283 + HyperFEMKernels MatrixFreeSolver: linear_indefinite; S5 benchmark cases #52: linear_indefinite hook on every solver, HybridTangent switches to the projected tangent (stay_projected = 2), HessianRegularization of coupled electro-mechanical models (in E); EM plate past the pull-in to Λ = 1 at 71k in 22 s (LU 331–683 s, same equilibrium) and at 555k in 182 s (LU does not fit); forcing term ×1.7–2.4 on the h-multigrid cases
• ⬜ Pending (administrative): HyperFEM release with S4-B/S5; README recipe of the hybrid Newton for electro-mechanics. Backlog in design/future-improvements.md; MPI in R5 (Driver refactor in HyperFEM (tracking, companion of #21) #23)

Driver refactor in HyperFEM ⬜ (tracking issue #23)

Companion of the solver block: typed caches, backend as a type, one incremental loop, Dirichlet projection on the Newton cache, single Newton designed with S1/S3. User interface unchanged.

• ✅ R0 Driver baseline (inside S0)
• ✅ R1 Typed caches, backend as a type
• ✅ R2 Single incremental loop
• ✅ R3 Dirichlet projection and StaticLinearModel
• ✅ R4a Newton ↔ linear-solver interface (after S1) · ⬜ R4 Single Newton (before S3)
• R5 MPI: postponed

GPU block ⬜

• ⬜ KernelAbstractions port of the element kernels (residual, Jacobian, states); same generated code per cell.
• ⬜ Needs an NVIDIA machine (Apple GPUs have no Float64 in Metal).
• Design rules already enforced: dense isbits data, no allocations in cell/point loops, local numbering, element compute separated from scatter.

Phase 3 — Distributed and other spaces ⬜

• ⬜ Distributed KernelOperator on GridapDistributed (capture per part already verified).
• ⬜ Domain decomposition (BDDC/FETI-DP via PETSc).
• ⬜ DG (skeleton kernels done; DG spaces and fluxes).
• ⬜ Piola-mapped spaces (H(div), H(curl)).

Maintenance

• ⬜ CI time has grown to 15–20 min per PR: split the examples into a job that runs only when examples/ changes.
• ⬜ Enable "Automatically delete head branches" and remove the 12 merged remote branches.
• ✅ Release v0.1.0 tag on the phase-1 commit (d779f34).

Generated by Claude Code