# FemLite 0.6.0 TODO Source plan: `docs/v6.0_development_plan.md` Version goal: ```text FemLite 0.6.0 = unified nonlinear state machine and lifecycle foundation ``` Boundary: - The fifth-version closure boundary is lifted for future planning, but 0.6.0 should still remain a controlled loop. - Do not implement a complete industrial AL/mortar consistent tangent rewrite in this task list. - Do not move mixed-control continuation, shell preload `K_G`, high-order solid `K_G`, cohesive contact mainline, nonzero harmonic cyclic, DEM subcycling or production roll forming into the 0.6.0 must-complete list. - Every new lifecycle or audit field must be consumed by a test, checker or report audit. - Keep TODO item size uniform: each task should add one observable contract and one focused verification path. ## Execution Order 1. NLCS-1: lifecycle ids, names and snapshot skeleton. 2. NLCS-2: static nonlinear lifecycle hook. 3. NLCS-3: nonlinear Newmark lifecycle hook. 4. NLCS-4: Riks/arc lifecycle hook. 5. NLCS-5: rollback audit core. 6. NLCS-6: material rollback audit adapter. 7. NLCS-7: contact rollback audit adapter. 8. NLCS-8: cohesive and particle audit adapters. 9. NLCS-9: lifecycle output/report schema. 10. NLCS-10: restart lifecycle audit. 11. DOC-1: documentation and interface synchronization. 12. REL-1: 0.6.0 regression/version close-out. ## Detailed Execution Map | TODO | Code targets | Output/API contract | Test/checker target | Not in scope | |---|---|---|---|---| | 0.6.0-1 | `src/solver/fem_nonlinear_lifecycle.f90`, diagnostics API | Stable lifecycle event ids/names and queryable empty snapshot | new lifecycle unit/module test | Change Newton algorithms | | 0.6.0-2 | static nonlinear solver loop | Record increment/iteration begin/end and accept/reject events | `solver_implicit` | Change convergence rules | | 0.6.0-3 | nonlinear Newmark solver loop | Record dynamic nonlinear lifecycle events | `solver_implicit` | Rewrite Newmark integration | | 0.6.0-4 | Riks/arc static path | Record load factor, arc residual and path append lifecycle fields | `solver_implicit`, `implicit_inp` | Mixed-control continuation | | 0.6.0-5 | lifecycle audit module | Generic commit/rollback audit counters and status | lifecycle audit unit/module test | Owner-specific checksum details | | 0.6.0-6 | material/element state path | Material local state rollback audit for covered subset | `solver_implicit`, material tests | New material models | | 0.6.0-7 | contact state/history path | Contact state and diagnostic rollback audit for covered subset | `restart`, contact report tests | Full contact state-machine rewrite | | 0.6.0-8 | cohesive and particle compact paths | Cohesive/particle owner audit hooks using existing compact tests | `cohesive_contact`, `particle_acceptance` | Cohesive mainline or DEM subcycling | | 0.6.0-9 | output/report modules | Lifecycle event/report columns or compact lifecycle CSV | `solver_implicit`, output checker | Break existing CSV consumers | | 0.6.0-10 | restart writer/reader and restart tests | Accepted-increment lifecycle diagnostics round trip | `restart` | Redesign restart format | | 0.6.0-11 | docs and manuals | Document lifecycle API, output and deferred boundaries | wording `rg` checks | Expand feature scope | | 0.6.0-12 | version/matrix/report files | Close 0.6.0 after green targeted and V5 acceptance tests | build, targeted tests, acceptance, `git diff --check` | Version bump before tests pass | ## Implementation Rules - Work in the execution order above. - Do not mark a TODO done until its lifecycle field or audit status is consumed by a test, checker or report audit. - Prefer additive lifecycle hooks over solver-loop rewrites. - Keep existing public signatures stable unless a thin new accessor is clearly safer. - If a task exposes incompatible designs for lifecycle ownership, pause and ask for a decision before editing that route. - If a later task needs a field created by an earlier task, finish and test the earlier task first. ## 0.6.0 Task List ### [x] TODO 0.6.0-1: Add nonlinear lifecycle ids and snapshot skeleton - Source: - `docs/v6.0_development_plan.md` sections 4.1 and 5, NLCS-1. - Implementation: - [x] Add stable lifecycle event ids and names for increment begin, trial begin, iteration result, accept, reject, cutback, commit and rollback. - [x] Add a small lifecycle snapshot with step/increment/iteration/event fields and last reason id/name linkage. - [x] Add a reset/begin/query API that returns a valid empty snapshot before any nonlinear solve. - [x] Keep the module passive; it must not change solver behavior yet. - Tests: - [x] Add a lifecycle unit/module test for id/name stability and empty snapshot defaults. - Acceptance: - [x] Tests can query lifecycle state without running a solve, and all event names are stable. Verified: - `ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|linear_solver_cg|c_api)$" --output-on-failure` ### [x] TODO 0.6.0-2: Hook static nonlinear lifecycle events - Source: - `docs/v6.0_development_plan.md` sections 4.1 and 5, NLCS-2. - Implementation: - [x] Record increment begin and iteration begin in the nonlinear static path. - [x] Record iteration result with convergence status and current failure reason fields. - [x] Record accepted, rejected or cutback increment events without changing the existing cutback decision. - [x] Preserve existing convergence metrics and continuation path behavior. - Tests: - [x] Extend `solver_implicit` to verify lifecycle event sequence for a converged static nonlinear path and one rejected/cutback path. - Acceptance: - [x] Static nonlinear diagnostics expose lifecycle events that match the existing solver outcome. Verified: - `ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure` ### [x] TODO 0.6.0-3: Hook nonlinear Newmark lifecycle events - Source: - `docs/v6.0_development_plan.md` sections 4.1 and 5, NLCS-3. - Implementation: - [x] Record Newmark nonlinear increment and iteration lifecycle events. - [x] Link dynamic residual status to the shared lifecycle snapshot. - [x] Record accepted/rejected dynamic increments where the current path can identify them. - [x] Preserve current Newmark time integration and convergence behavior. - Tests: - [x] Extend `solver_implicit` to verify lifecycle fields after a nonlinear Newmark run. - Acceptance: - [x] Static and Newmark nonlinear paths expose the same lifecycle field contract for the covered subset. Verified: - `ctest --test-dir build-codex-gcc -R "^(solver_implicit|nonlinear_lifecycle|c_api)$" --output-on-failure` ### [x] TODO 0.6.0-4: Hook Riks/arc lifecycle events - Source: - `docs/v6.0_development_plan.md` sections 4.1 and 5, NLCS-4. - Implementation: - [x] Record Riks/arc lifecycle events in the load-type arc path. - [x] Store current load factor, arc residual and arc reason in the lifecycle snapshot. - [x] Record whether a path row is appended because the increment was accepted. - [x] Preserve current Riks/arc equations and direct displacement-control behavior. - Tests: - [x] Extend `solver_implicit` or `implicit_inp` to verify arc lifecycle fields on an accepted Riks path. - Acceptance: - [x] Riks/arc diagnostics can be interpreted through the same lifecycle event model as static nonlinear diagnostics. Verified: - `ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|c_api)$" --output-on-failure` ### [x] TODO 0.6.0-5: Add generic rollback audit core - Source: - `docs/v6.0_development_plan.md` sections 4.2 and 5, NLCS-5. - Implementation: - [x] Add generic audit counters for begin-trial, rollback-requested, rollback-ok, rollback-failed and commit-ok. - [x] Add an audit status/name field to the lifecycle snapshot. - [x] Add helpers that owner modules can call without depending on each other. - [x] Keep owner-specific checksum logic out of the generic core. - Tests: - [x] Add lifecycle audit coverage for counter transitions and failure naming. - Acceptance: - [x] A test can simulate owner audit success/failure and observe the shared audit status. Verified: - `ctest --test-dir build-codex-gcc -R "^nonlinear_lifecycle$" --output-on-failure` ### [x] TODO 0.6.0-6: Add material rollback audit adapter - Source: - `docs/v6.0_development_plan.md` sections 4.3 and 5, NLCS-6. - Implementation: - [x] Add a covered-subset material state checksum or equivalent audit value before trial updates. - [x] Compare material state after rollback for a rejected nonlinear increment. - [x] Feed material rollback status into the lifecycle audit core. - [x] Keep material constitutive algorithms unchanged. - Tests: - [x] Extend `solver_implicit` or material tests with one rejected/cutback material-state rollback audit. - Acceptance: - [x] Rejected material trial updates are proven not to contaminate committed state for the covered subset. Verified: - `ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure` ### [x] TODO 0.6.0-7: Add contact rollback audit adapter - Source: - `docs/v6.0_development_plan.md` sections 4.3 and 5, NLCS-7. - Implementation: - [x] Capture contact state counts and selected contact diagnostics before trial changes. - [x] Compare contact state after rollback for a rejected/cutback increment. - [x] Feed contact rollback status into the lifecycle audit core. - [x] Reuse existing 0.5.3 contact diagnostics rather than adding broad new contact fields. - Tests: - [x] Extend `restart` or contact report tests with a contact rollback audit scenario. - Acceptance: - [x] Contact diagnostics and state counts remain consistent after rollback for the covered subset. Verified: - `ctest --test-dir build-codex-gcc -R "^(contact|contact_multiplier_diag)$" --output-on-failure` ### [x] TODO 0.6.0-8: Add cohesive and particle audit adapters - Source: - `docs/v6.0_development_plan.md` sections 4.3 and 5, NLCS-8. - Implementation: - [x] Add cohesive compact-path audit hooks for damage/status/energy rollback where existing state support allows it. - [x] Add particle compact-path audit hooks for mass/momentum/energy counters. - [x] Feed both owner statuses into the lifecycle audit core. - [x] Keep cohesive mainline contact and DEM subcycling out of this task. - Tests: - [x] Extend `cohesive_contact` and `particle_acceptance` to consume the new audit statuses. - Acceptance: - [x] Existing compact cohesive and particle tests can report lifecycle audit status without changing their physics paths. Verified: - `ctest --test-dir build-codex-gcc -R "^(cohesive_contact|particle_step|nonlinear_lifecycle)$" --output-on-failure` ### [x] TODO 0.6.0-9: Write lifecycle diagnostics to output/report path - Source: - `docs/v6.0_development_plan.md` sections 4.4 and 5, NLCS-9. - Implementation: - [x] Add lifecycle event/status fields to an existing nonlinear report path or a compact `nonlinear_lifecycle.csv`. - [x] Include event id/name, audit status/name, increment, iteration, reason id/name and accepted/rejected counters. - [x] Keep old continuation/contact CSV columns stable. - [x] Represent missing lifecycle data consistently for unsupported paths. - Tests: - [x] Extend `solver_implicit` or an output checker to verify lifecycle output headers and at least one accepted row. - Acceptance: - [x] Checker failure occurs if required 0.6.0 lifecycle output fields are missing. Verified: - `ctest --test-dir build-codex-gcc -R "^(solver_implicit|nonlinear_lifecycle)$" --output-on-failure` ### [x] TODO 0.6.0-10: Add restart lifecycle audit - Source: - `docs/v6.0_development_plan.md` sections 4.4 and 6, NLCS-10. - Implementation: - [x] Persist accepted-increment lifecycle diagnostics needed for restart audit where restart format already supports the owned state. - [x] Read old restart files without requiring lifecycle fields. - [x] Compare lifecycle event/status and owner audit summaries before and after restart. - [x] Avoid redesigning the restart format beyond an optional lifecycle block. - Tests: - [x] Extend `restart` to verify lifecycle diagnostics survive an accepted increment restart round trip. - Acceptance: - [x] Restart proves both owned state and lifecycle diagnostics for the covered subset. Verified: - `ctest --test-dir build-codex-gcc -R "^(restart|nonlinear_lifecycle)$" --output-on-failure` ### [x] TODO 0.6.0-11: Synchronize documentation and API descriptions - Source: - `docs/v6.0_development_plan.md` sections 2, 4 and 6, DOC-1. - Implementation: - [x] Update design and algorithm docs with lifecycle levels and event names. - [x] Update interface docs with new lifecycle query/output fields. - [x] Update test plan with 0.6.0 regression commands and acceptance criteria. - [x] Update user/developer manuals with lifecycle boundary and deferred algorithm rewrites. - Tests: - [x] Run wording `rg` checks so docs do not claim 0.6.0 delivers complete AL/mortar tangent, mixed-control continuation or cohesive mainline. - Acceptance: - [x] Documentation states that 0.6.0 delivers lifecycle foundation and rollback audit, while larger solver rewrites remain follow-up work. Verified: - `rg -n "0\\.6\\.0.*(complete industrial AL/mortar|mixed-control continuation|cohesive contact mainline|cohesive mainline|complete AL/mortar|generalized mixed-control)" docs README.md todo.md` - `rg -n "LIFECYCLE_DIAGNOSTICS|lifecycle_event_id|fem_get_nl_lifecycle|0\\.6\\.0 Lifecycle" docs` ### [x] TODO 0.6.0-12: Update version, matrix, report and release evidence - Source: - `docs/v6.0_development_plan.md` section 6, REL-1. - Implementation: - [x] Update benchmark/acceptance matrix with 0.6.0 lifecycle tests and diagnostic evidence. - [x] Update acceptance report with 0.6.0 scope, commands and limitations. - [x] Raise project version only when 0.6.0 implementation is ready to close. - [x] Keep deferred boundaries explicit in release documentation. - Tests: - [x] Run the planned 0.6.0 targeted regression command. - [x] Run `ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure`. - [x] Run `git diff --check`. - Acceptance: - [x] 0.6.0 closes with green targeted tests, green acceptance subset and documented deferred boundaries. Verified: - `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` ## Suggested 0.6.0 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 ```