# FemLite 0.6.0 Development Plan Document status: development plan draft Date: 2026-07-01 Scope: FemLite 0.6.0 development, review, testing and release planning. Source: `docs/suggests.md` ## 1. Positioning FemLite 0.6.0 is the algorithm-foundation release after the 0.5.x V5 close-out. ```text FemLite 0.6.0 = unified nonlinear state machine and lifecycle foundation ``` 0.5.3 completed nonlinear/contact explainability hardening: stable failure reasons, residual breakdown fields, contact diagnostics, restart diagnostic round trips, tangent audit split and OpenMP deterministic contact checks. 0.6.0 should build on that work by making the nonlinear increment lifecycle explicit and shared. The release should improve depth and reliability instead of adding broad new feature families. The first controlled loop is: ```text begin increment begin trial state assemble residual/tangent solve correction evaluate convergence and events accept or reject commit or rollback every owned state record diagnostics end increment ``` ## 2. Delivery Boundary ### 2.1 0.6.0 must deliver - A small, shared nonlinear lifecycle/state-machine module. - Stable event ids/names for increment begin, trial begin, iteration result, accept, reject, cutback, commit and rollback. - A rollback audit that can prove rejected increments do not contaminate material, contact, cohesive, particle, Newmark or continuation-owned state for the covered subset. - Unified per-increment diagnostics that connect reason id, residual breakdown, linear-solver diagnostics, contact/material counters and lifecycle event status. - Static nonlinear, Newmark nonlinear and Riks/arc-length paths using the same lifecycle recording points for the covered subset. - Restart-after-accepted-increment evidence that lifecycle diagnostics survive the round trip where the underlying state is already restart-supported. - Documentation and checkers that make the new lifecycle contract visible. ### 2.2 0.6.0 does not deliver The following remain follow-up work unless explicitly re-planned: - Complete industrial AL/mortar consistent tangent rewrite. - Full contact state-machine rewrite for all contact algorithms. - General mixed-control continuation and branch switching. - Complete shell preload `K_G` and high-order solid geometric stiffness. - Cohesive contact mainline integration. - Nonzero harmonic cyclic symmetry. - DEM/FEM subcycling and large-particle long runs. - Production roll-forming process chain. - New third-party solver backends. These topics may consume the lifecycle interface, but they are not 0.6.0 blocking scope. ## 3. Design Principles - Keep the first state machine additive and observable. It should not rewrite every solver loop at once. - Use thin lifecycle hooks around existing paths before moving ownership of algorithm decisions. - Make every new diagnostic field consumed by a test, checker or report audit. - Preserve existing public APIs and CSV columns unless a versioned change is documented. - Treat rollback correctness as a product behavior, not only an internal implementation detail. - Pause for review if a task requires choosing between incompatible solver-loop designs. ## 4. Proposed Architecture ### 4.1 Lifecycle levels ```text Analysis step Increment Iteration Trial state Residual assembly Tangent assembly Linear solve Line search / damping / trust region Accept / reject Commit / rollback ``` ### 4.2 Core module Recommended new module: ```text src/solver/fem_nonlinear_lifecycle.f90 ``` Responsibilities: - Define lifecycle event ids and names. - Store the current increment/iteration lifecycle snapshot. - Provide begin/end/update helpers for solver loops. - Store rollback/commit audit counters. - Provide a query API for tests and output modules. The module should not own Newton, Riks, contact or material algorithms in 0.6.0. It should first record and verify their lifecycle behavior. ### 4.3 Owner adapters The following owners should initially expose small audit hooks: | Owner | 0.6.0 expectation | |---|---| | Material state | Record local failure count and state checksum before/after rollback for covered elements. | | Contact state | Record active/state counters, gap/slip diagnostics and restart-owned contact fields. | | Cohesive state | Record damage/energy/status checks where existing cohesive state restart exists. | | Particle state | Record mass/momentum/energy counters for explicit particle step subset. | | Newmark state | Record displacement/velocity/acceleration trial and rollback checks for the covered nonlinear path. | | Continuation/Riks path | Record load factor, arc residual and accepted-path append decision. | ### 4.4 Diagnostics 0.6.0 should connect, not replace, existing diagnostics: - nonlinear reason id/name from 0.5.3; - residual breakdown from 0.5.3; - linear solver diagnostics from 0.5.x; - contact state/residual diagnostics from 0.5.3; - material local failure count; - lifecycle event id/name; - commit/rollback audit status; - accepted/rejected increment counters. ## 5. Execution Plan | Item | Theme | Output | Primary tests | |---|---|---|---| | 0.6.0-1 | Scope and API skeleton | lifecycle ids, names and empty snapshot query | new lifecycle unit test | | 0.6.0-2 | Static nonlinear hook | increment/iteration begin/end events | `solver_implicit` | | 0.6.0-3 | Newmark hook | dynamic nonlinear lifecycle events | `solver_implicit` | | 0.6.0-4 | Riks/arc hook | load-factor/arc event fields | `solver_implicit`, `implicit_inp` | | 0.6.0-5 | Rollback audit core | generic audit counters and status | lifecycle unit test | | 0.6.0-6 | Material rollback audit | material state checksum subset | `solver_implicit`, material tests | | 0.6.0-7 | Contact rollback audit | contact state/diagnostic subset | `restart`, contact report tests | | 0.6.0-8 | Cohesive/particle audit adapters | existing compact owner checks | `cohesive_contact`, `particle_acceptance` | | 0.6.0-9 | Lifecycle output | path/report columns or compact lifecycle CSV | `solver_implicit`, checker | | 0.6.0-10 | Restart audit | accepted-increment lifecycle round trip | `restart` | | 0.6.0-11 | Documentation | design/interface/manual/test plan sync | wording checks | | 0.6.0-12 | Release close-out | version, matrix and regression evidence | targeted + acceptance tests | ## 6. Acceptance Criteria 0.6.0 can close when: - all 0.6.0 TODO items are complete; - the lifecycle snapshot is queryable from tests; - static nonlinear, nonlinear Newmark and Riks/arc paths record lifecycle events consistently for covered paths; - rollback audit catches at least one intentionally rejected increment scenario; - accepted-increment restart preserves both state and lifecycle diagnostics for the covered subset; - existing V5 acceptance tests do not regress; - documentation states the boundary between lifecycle foundation and deferred larger algorithm rewrites. Suggested regression commands: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|restart|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance)$" --output-on-failure ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure git diff --check ``` ## 7. Follow-up Route After 0.6.0 After the lifecycle foundation is proven, the next releases can safely deepen larger algorithms: - 0.6.x: contact state-machine stabilization and AL/mortar tangent long-path work. - 0.7.x: shell/solid geometric stiffness and preload-to-buckling workflow. - 0.8.x: generalized continuation, cohesive mainline and harmonic cyclic expansion. - 0.9.x: DEM/FEM subcycling, solver scaling/block preconditioning and production process long runs. ## 8. Implementation Contract The implemented 0.6.0 lifecycle foundation is additive. It records the current nonlinear step, increment, iteration, event id/name, reason id/name, arc state and audit status without changing Newton, Newmark, Riks or contact algorithms. Stable event names are: - `none` - `increment-begin` - `trial-begin` - `iteration-begin` - `iteration-result` - `accept` - `reject` - `cutback` - `commit` - `rollback` Stable audit status names are: - `none` - `begin-trial` - `rollback-requested` - `rollback-ok` - `rollback-failed` - `commit-ok` The public diagnostic boundary is: - Fortran diagnostics query the latest lifecycle snapshot, arc/path state and audit counters. - `continuation_path.csv` keeps older columns in place and appends lifecycle event/status, lifecycle increment/iteration and accepted/rejected counters. - Restart version 5 appends an optional `LIFECYCLE_DIAGNOSTICS` block after contact diagnostics. Readers still accept files that end at `END` without this block. 0.6.0 does not implement a complete industrial AL/mortar consistent tangent, mixed-control continuation or cohesive contact mainline. Those items remain follow-up work that can consume the lifecycle interface.