# FemLite 0.6.1 TODO Source plan: `docs/v6.1_development_plan.md` Version goal: ```text FemLite 0.6.1 = nonlinear/contact lifecycle diagnostics hardening ``` Boundary: - 0.6.1 deepens the 0.6.0 lifecycle foundation; it is not a broad algorithm rewrite release. - 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.1 must-complete list. - Every new reason, status, counter or output field must be consumed by a regression 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. NLHD-1: lifecycle increment summary. 2. NLHD-2: cutback reason taxonomy. 3. NLHD-3: lifecycle report output. 4. NLHD-4: contact state diagnostics. 5. NLHD-5: contact long-path diagnostic smoke. 6. NLHD-6: AL/friction diagnostics. 7. NLHD-7: tangent-audit report shell. 8. NLHD-8: Riks/arc diagnostics. 9. NLHD-9: restart-after-each-accepted audit. 10. NLHD-10: solver diagnostics coupling. 11. DOC-1: documentation and matrix synchronization. 12. REL-1: 0.6.1 regression/version close-out. ## Detailed Execution Map | TODO | Code targets | Output/API contract | Test/checker target | Not in scope | |---|---|---|---|---| | 0.6.1-1 | lifecycle module and diagnostics API | Increment summary fields for lifecycle, convergence, residual, solver and audit state | `nonlinear_lifecycle`, `solver_implicit` | Change Newton algorithms | | 0.6.1-2 | control/reason taxonomy | Stable cutback reason ids/names and last cutback reason query | `solver_implicit`, lifecycle test | New nonlinear strategy | | 0.6.1-3 | output/report module | Compact lifecycle report or appended nonlinear report fields | output checker | Break old CSV columns | | 0.6.1-4 | contact state/report modules | Stable contact state counters and gap/slip/friction fields | `contact`, contact reports | Full contact state-machine rewrite | | 0.6.1-5 | contact benchmark checkers | Long-path diagnostic smoke for existing compact contact examples | contact benchmark checkers | New contact benchmark physics | | 0.6.1-6 | multiplier/friction diagnostics | AL multiplier, augmentation and friction trend summaries | `contact_multiplier_report`, `restart` | Complete AL tangent | | 0.6.1-7 | tangent audit reporting | Shared audit schema and coverage counters | tangent audit tests | Claim production consistent tangents | | 0.6.1-8 | Riks/arc path diagnostics | Arc residual history, predictor and reversal indicators | `solver_implicit`, `implicit_inp` | Mixed-control continuation | | 0.6.1-9 | restart writer/reader tests | Multi-increment restart lifecycle audit | `restart` | Large restart benchmark | | 0.6.1-10 | linear solver diagnostics | Solver status fields linked into lifecycle/nonlinear rows | `linear_solver_cg`, `solver_implicit` | New solver backend | | 0.6.1-11 | docs and matrices | Updated interface/user/developer docs and benchmark matrix | wording `rg` checks | Expand feature scope | | 0.6.1-12 | version/report files | Close 0.6.1 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 new field, reason or status is consumed by a test, checker or report audit. - Prefer additive diagnostics over solver-loop rewrites. - Keep old CSV columns stable; append new fields. - Keep restart readers backward compatible; optional diagnostic blocks are preferred over format breaks. - If a task exposes incompatible designs for contact, Riks, material or restart 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.1 Task List ### [x] TODO 0.6.1-1: Add lifecycle increment summary - Source: - `docs/v6.1_development_plan.md` sections 4.1 and 5, NLHD-1. - Implementation: - [x] Add a compact lifecycle increment summary structure or query path. - [x] Include step, increment, final event id/name and reason id/name. - [x] Include convergence status, residual breakdown, linear solver status and audit status fields already available in 0.6.0. - [x] Keep existing lifecycle snapshot APIs compatible. - Tests: - [x] Extend `nonlinear_lifecycle` to verify empty and populated summary fields. - [x] Extend `solver_implicit` to consume the summary after one accepted and one rejected/cutback path. - Acceptance: - [x] A test can explain the latest nonlinear increment from one summary query without reading console output. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure ``` ### [x] TODO 0.6.1-2: Add cutback reason taxonomy - Source: - `docs/v6.1_development_plan.md` sections 4.2 and 5, NLHD-2. - Implementation: - [x] Add stable cutback reason ids/names for common nonlinear failure modes. - [x] Track the last cutback reason separately from the final convergence failure reason. - [x] Map existing min-step, nonconvergence and linear-solver failure paths into the new taxonomy. - [x] Leave unavailable reasons as reserved/documented ids until a real path consumes them. - Tests: - [x] Extend `nonlinear_lifecycle` to verify reason-name stability. - [x] Extend `solver_implicit` to verify at least min-step and nonconvergence cutback reasons. - Acceptance: - [x] Every implemented 0.6.1 cutback reason is consumed by a regression assertion. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure ``` ### [x] TODO 0.6.1-3: Write lifecycle report output - Source: - `docs/v6.1_development_plan.md` sections 4.3 and 5, NLHD-3. - Implementation: - [x] Add `nonlinear_lifecycle.csv` or append equivalent lifecycle summary fields to an existing nonlinear report. - [x] Cover initialized/no-solve, accepted increment and rejected/cutback increment rows. - [x] Include lifecycle summary, cutback reason, residual breakdown, solver status and audit status columns. - [x] Preserve old `continuation_path.csv` column order if that file is extended again. - Tests: - [x] Add or extend an output checker to validate required lifecycle report headers. - [x] Verify at least one accepted row and one rejected/cutback row. - Acceptance: - [x] Missing lifecycle report fields cause a regression failure. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure ``` ### [x] TODO 0.6.1-4: Stabilize contact state diagnostics - Source: - `docs/v6.1_development_plan.md` sections 4.4 and 5, NLHD-4. - Implementation: - [x] Define stable contact state names: `open`, `closed-stick`, `closed-slip`, `closed-restick`, `separating` and `failed-projection`. - [x] Report state counters through existing contact diagnostics or a compact helper. - [x] Include gap maximum/mean/L2, slip increment/residual, friction residual and active-set flip count where available. - [x] Keep this diagnostic-only; do not rewrite contact solve state ownership. - Tests: - [x] Extend `contact` or contact report tests to verify state names and counters. - [x] Verify unsupported/unavailable state fields default consistently. - Acceptance: - [x] Contact diagnostics can distinguish open, stick/slip and failed projection states without parsing logs. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^contact$" --output-on-failure ``` ### [x] TODO 0.6.1-5: Add compact contact long-path diagnostic smoke - Source: - `docs/v6.1_development_plan.md` sections 4.5 and 5, NLHD-5. - Implementation: - [x] Select existing compact examples for two-block compression, block sliding, shell-shell contact and shell-solid contact. - [x] Add checker expectations for required diagnostic columns and finite state counters. - [x] Check gap/slip/friction/multiplier diagnostics across path steps. - [x] Keep benchmark physics and tolerances bounded to existing examples. - Tests: - [x] Extend existing contact benchmark checkers or their CTest assertions. - [x] Verify at least two path steps for one compact long-path case. - Acceptance: - [x] A compact contact path can fail diagnostics loudly if state or residual fields disappear. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^contact$" --output-on-failure ctest --test-dir build-codex-gcc -R "^example_(contact_two_blocks_compression|contact_block_sliding|shell_shell_contact|shell_solid_contact)_benchmark$" --output-on-failure ``` ### [x] TODO 0.6.1-6: Add AL multiplier and friction diagnostic summaries - Source: - `docs/v6.1_development_plan.md` sections 4.6 and 5, NLHD-6. - Implementation: - [x] Add multiplier residual trend and maximum augmented multiplier summary fields. - [x] Add augmentation update count and accepted-step penalty/augmentation factor fields. - [x] Add slip/friction residual summary fields where existing friction state supports them. - [x] Include restart before/after consistency checks for supported fields. - Tests: - [x] Extend `contact_multiplier_report` to consume new summary fields. - [x] Extend `restart` or `contact` to compare supported multiplier/friction summaries before and after restart. - Acceptance: - [x] AL/friction diagnostic summaries are visible in tests and survive the covered restart path. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(contact_multiplier_report|restart)$" --output-on-failure ``` ### [x] TODO 0.6.1-7: Add shared tangent-audit report shell - Source: - `docs/v6.1_development_plan.md` sections 4.7 and 5, NLHD-7. - Implementation: - [x] Define a shared tangent-audit report schema with audit name, branch, sample count, relative error and status fields. - [x] Route existing material/contact/shell/Riks audit summaries into the shared vocabulary where already available. - [x] Add coverage counters for missing or not-applicable audit branches. - [x] Document that this is an audit report shell, not production consistent tangent delivery. - Tests: - [x] Extend existing tangent audit tests or add a schema checker. - [x] Verify at least normal contact and one non-contact audit category in the shared report vocabulary. - Acceptance: - [x] Tangent audit output has a uniform schema without changing production tangent behavior. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^contact_mortar_tangent$" --output-on-failure ``` ### [x] TODO 0.6.1-8: Harden Riks and arc diagnostics - Source: - `docs/v6.1_development_plan.md` sections 4.8 and 5, NLHD-8. - Implementation: - [x] Record arc residual history for accepted Riks/arc increments. - [x] Add predictor direction consistency and load-factor reversal indicators. - [x] Add a simple turning-point indicator where current path data supports it. - [x] Add path/report fields that distinguish load-control Riks from direct displacement control. - Tests: - [x] Extend `solver_implicit` to verify Riks/arc diagnostic fields. - [x] Extend `implicit_inp` only if an existing deterministic input path can consume the fields cheaply. - Acceptance: - [x] Riks/arc diagnostics expose residual and predictor/path direction state without implementing mixed-control continuation. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp)$" --output-on-failure ``` ### [x] TODO 0.6.1-9: Add restart-after-each-accepted audit - Source: - `docs/v6.1_development_plan.md` sections 4.9 and 5, NLHD-9. - Implementation: - [x] Add a compact multi-increment restart audit flow. - [x] After each accepted increment, write restart, read into a fresh model and compare lifecycle diagnostics. - [x] Compare supported contact/material/path diagnostic summaries before and after restart. - [x] Continue one increment after restart to prove the restored state is usable. - Tests: - [x] Extend `restart` or add a compact restart-lifecycle test. - [x] Keep the model small and deterministic. - Acceptance: - [x] Restart audit covers more than one accepted increment without relying on a large benchmark. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^restart$" --output-on-failure ``` ### [x] TODO 0.6.1-10: Couple solver diagnostics to nonlinear rows - Source: - `docs/v6.1_development_plan.md` sections 4.10 and 5, NLHD-10. - Implementation: - [x] Link matrix class, solver method, preconditioner, iteration count and solver status into lifecycle or nonlinear report rows. - [x] Include initial/final/relative residual where current solver diagnostics already provide them. - [x] Add a fallback marker for dense pivoting or method fallback paths if available. - [x] Keep solver selection behavior unchanged. - Tests: - [x] Extend `linear_solver_cg` for field availability and naming where needed. - [x] Extend `solver_implicit` to verify nonlinear rows include solver diagnostics. - Acceptance: - [x] A nonlinear failure can be distinguished from a linear solver failure through report/API fields. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(solver_implicit|linear_solver_cg)$" --output-on-failure ``` ### [x] TODO 0.6.1-11: Synchronize documentation and benchmark matrix - Source: - `docs/v6.1_development_plan.md` sections 4.11 and 5, DOC-1. - Implementation: - [x] Update `docs/v6_benchmark_matrix.md` with 0.6.1 diagnostic tests and evidence placeholders. - [x] Update interface docs with new lifecycle, cutback, contact and solver diagnostic fields. - [x] Update user/developer manuals with the 0.6.1 boundary and deferred algorithm rewrites. - [x] Add or update a 0.6.1 acceptance report section. - Tests: - [x] Run wording `rg` checks so docs do not claim 0.6.1 delivers complete AL/mortar tangent, mixed-control continuation or cohesive mainline. - Acceptance: - [x] Documentation states that 0.6.1 delivers diagnostic hardening, while larger solver rewrites remain follow-up work. Verified: ```powershell rg -n "0\.6\.1.*(complete|完整|industrial|生产一致切线|mixed-control continuation|AL/mortar consistent tangent).*交付|0\.6\.1.*delivers complete|0\.6\.1.*完整 AL|0\.6\.1.*mixed-control" docs rg -n "0\.6\.1|nonlinear_lifecycle.csv|arc_mode|fem_tangent_audit_report|closed-stick|linear_fail_class" docs/v6_benchmark_matrix.md docs/v6_acceptance_report.md docs/07_user_manual.md docs/08_developer_manual.md ``` ### [x] TODO 0.6.1-12: Update version, report and release evidence - Source: - `docs/v6.1_development_plan.md` section 6, REL-1. - Implementation: - [x] Update benchmark/acceptance matrix with final 0.6.1 test evidence. - [x] Update acceptance report with 0.6.1 scope, commands and limitations. - [x] Raise project version only when 0.6.1 implementation is ready to close. - [x] Keep deferred boundaries explicit in release documentation. - Tests: - [x] Run the planned 0.6.1 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.1 closes with green targeted tests, green acceptance subset and documented deferred boundaries. Verified: ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(smoke|perf_contact_pair_p1)$" --output-on-failure ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|implicit_inp|restart|contact|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance|linear_solver_cg)$" --output-on-failure ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure git diff --check ``` ## Suggested 0.6.1 Regression Commands ```powershell cmake --build build-codex-gcc --parallel ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|implicit_inp|restart|contact|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance|linear_solver_cg)$" --output-on-failure ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure git diff --check ```