# FemLite 0.6.1 Development Plan Document status: development plan draft Date: 2026-07-01 Scope: FemLite 0.6.1 development, review, testing and release planning. Source: `docs/suggests.md`, `docs/v6.0_development_plan.md`, `docs/v6_acceptance_report.md` ## 1. Positioning FemLite 0.6.1 is a diagnostic and stability hardening release after the 0.6.0 nonlinear lifecycle foundation. ```text FemLite 0.6.1 = nonlinear/contact lifecycle diagnostics hardening ``` 0.6.0 made nonlinear lifecycle events, rollback audit, lifecycle CSV fields and restart lifecycle diagnostics visible. 0.6.1 should use that foundation to make cutback reasons, contact state, restart-after-increment behavior and Riks/arc diagnostics more explainable and more reproducible. The release should still avoid broad algorithm rewrites. The goal is to deepen the controlled loop: ```text begin increment begin trial state assemble residual/tangent solve correction evaluate convergence, residual categories and cutback reason accept or reject commit or rollback every owned state record lifecycle/contact/restart diagnostics end increment ``` ## 2. Delivery Boundary ### 2.1 0.6.1 should deliver - A compact lifecycle increment summary that ties together event state, convergence status, residual breakdown, linear solver status and cutback reason. - A more explicit cutback reason taxonomy for common nonlinear failure modes. - A standalone or compact lifecycle output path that covers no-solve, accepted and rejected increment cases without relying only on `continuation_path.csv`. - Contact state diagnostics hardened around stable state names and counters: `open`, `closed-stick`, `closed-slip`, `closed-restick`, `separating` and `failed-projection`. - Contact long-path diagnostic smoke checks for existing compact benchmarks. - AL multiplier and friction diagnostic summaries for multiplier residual, augmentation update count and gap/slip trends. - A shared tangent-audit report shell that can summarize existing material, contact, Riks and shell tangent audits without claiming complete tangents. - Riks/arc diagnostics for arc residual history, predictor consistency and simple turning/load-factor reversal indicators. - Restart-after-each-accepted-increment audit for a small covered model. - Solver diagnostics linked to nonlinear lifecycle rows: matrix class, solver method, preconditioner, iteration count and status. - Documentation and benchmark matrix updates that keep the 0.6.1 boundary visible. ### 2.2 0.6.1 should 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 every contact algorithm. - Complete shell preload `K_G` and high-order solid geometric stiffness. - Generalized mixed-control continuation and branch switching. - 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 0.6.1 diagnostics later, but they are not 0.6.1 blocking scope. ## 3. Design Principles - Keep every 0.6.1 item observable through an API, CSV/report row, restart check or regression test. - 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. - Do not call tangent-audit report fields "consistent tangent support" unless the production tangent path is actually implemented and tested. - Stop for review if an item requires choosing between incompatible contact, Riks or material ownership designs. ## 4. Planned Work ### 4.1 Lifecycle Increment Summary Add a compact summary that can describe the latest increment or a small fixed history of recent increments: - step and increment; - final lifecycle event id/name; - convergence status and failure reason id/name; - cutback count and cutback reason id/name; - accepted/rejected counters; - residual total, force, contact, constraint, arc and material failure count; - linear solver method, preconditioner, iterations and status; - audit status and owner rollback/commit counters. Primary tests: - `nonlinear_lifecycle` - `solver_implicit` ### 4.2 Cutback Reason Taxonomy Extend existing nonlinear failure reasons with a 0.6.1 cutback layer: - linear solver failed; - Newton nonconvergence; - minimum step reached; - material local update failed; - contact projection failed; - contact active-set oscillation; - contact penetration/gap limit exceeded; - friction slip residual limit exceeded; - arc constraint failed; - Riks predictor or direction update failed; - displacement correction too large; - tangent audit failed or matrix classification unsafe. Each reason added in 0.6.1 must be consumed by a test, checker or report schema. Primary tests: - `solver_implicit` - contact report tests - lifecycle unit test ### 4.3 Lifecycle Output File Add a compact lifecycle report path, either: - `nonlinear_lifecycle.csv`, or - an existing nonlinear report with lifecycle summary fields appended. The output should cover: - no-solve / initialized state; - accepted increment; - rejected or cutback increment; - restart-restored lifecycle state. Primary tests: - `nonlinear_lifecycle` - `solver_implicit` - output checker ### 4.4 Contact State Diagnostics Stabilize contact diagnostic state names and counters: ```text open closed-stick closed-slip closed-restick separating failed-projection ``` For each state, record: - trial count; - active count; - released count; - failed projection count; - gap maximum, mean and L2; - slip increment and slip residual; - friction residual; - active-set flip count. This task is diagnostic hardening only. It is not a full contact solver state-machine rewrite. Primary tests: - `contact` - `contact_mortar_report` - `contact_multiplier_report` - compact contact benchmarks ### 4.5 Contact Long-Path Diagnostic Smoke Add small long-path diagnostic checks around existing examples: - two-block compression; - block sliding friction; - shell-shell contact; - shell-solid contact. Acceptance should focus on explainability: - required diagnostic columns exist; - state counts remain finite and consistent; - gap/slip/friction/multiplier residuals are reported each path step; - restart does not change accepted contact diagnostic summaries. Primary tests: - existing contact benchmark checkers - `restart` ### 4.6 AL Multiplier And Friction Diagnostic Summary Add compact diagnostic fields for: - multiplier residual trend; - augmentation update count; - maximum augmented multiplier; - penalty/augmentation factor used in the accepted step; - gap/slip residual relationship; - restart before/after multiplier residual consistency. Primary tests: - `contact_multiplier_report` - `restart` - `contact` ### 4.7 Shared Tangent-Audit Report Shell Create a shared report schema for existing tangent audits: - material tangent audit; - contact normal tangent audit; - contact stick tangent audit; - contact slip tangent audit; - Riks augmented tangent audit; - shell finite-strain tangent audit. 0.6.1 should only unify the audit report vocabulary and coverage counters. It should not claim complete industrial AL/mortar consistent tangent support. Primary tests: - existing tangent audit tests - source/report schema checker ### 4.8 Riks/Arc Diagnostic Hardening Extend current Riks/arc diagnostics with: - arc residual history; - predictor direction consistency; - load-factor reversal indicator; - simple turning-point indicator; - cutback reason when Riks path control fails; - path row fields that distinguish load-control Riks from direct displacement control. This task does not implement generalized mixed-control continuation or branch switching. Primary tests: - `solver_implicit` - `implicit_inp` - spherical-cap bounded checker if a small deterministic path is available ### 4.9 Restart After Each Accepted Increment Audit Extend restart coverage from one accepted-increment round trip to a compact multi-increment audit: ```text run accepted increment write restart read restart into fresh model compare lifecycle/contact/material/path diagnostics continue one increment repeat for a small fixed count ``` The model should be small and deterministic. This is a reliability check, not a large benchmark. Primary tests: - `restart` - `solver_implicit` or a compact restart-lifecycle test ### 4.10 Solver Diagnostics Coupled To Nonlinear Rows Record linear solver diagnostics in lifecycle or nonlinear report rows: - matrix class; - method; - preconditioner; - iteration count; - status; - initial/final/relative residual; - fallback marker if dense pivoting or method fallback is used. The goal is to make nonlinear failures distinguishable from contact/material or path-control failures. Primary tests: - `linear_solver_cg` - `solver_implicit` - `implicit_inp` ### 4.11 Documentation And Matrix Updates Update: - `docs/v6_benchmark_matrix.md`; - `docs/v6_acceptance_report.md` or a new 0.6.1 report; - interface/control documentation; - user and developer manuals; - `todo.md` with uniform 0.6.1 task granularity. Documentation must keep the boundary clear: - 0.6.1 deepens lifecycle/contact diagnostics. - 0.6.1 does not deliver the deferred large algorithm rewrites. ## 5. Execution Plan | Item | Theme | Output | Primary tests | |---|---|---|---| | 0.6.1-1 | Lifecycle increment summary | summary fields and API/query hook | `nonlinear_lifecycle`, `solver_implicit` | | 0.6.1-2 | Cutback reason taxonomy | stable reason ids/names and tests | `solver_implicit` | | 0.6.1-3 | Lifecycle report output | compact CSV or appended nonlinear report | output checker | | 0.6.1-4 | Contact state diagnostics | stable state counters and report fields | `contact`, contact reports | | 0.6.1-5 | Contact long-path smoke | compact benchmark diagnostic checks | contact benchmark checkers | | 0.6.1-6 | AL/friction diagnostics | multiplier/friction trend fields | `contact_multiplier_report`, `restart` | | 0.6.1-7 | Tangent-audit report shell | unified audit schema | tangent audit tests | | 0.6.1-8 | Riks/arc diagnostics | predictor, reversal and arc residual fields | `solver_implicit`, `implicit_inp` | | 0.6.1-9 | Restart-after-each-accepted audit | multi-increment restart lifecycle proof | `restart` | | 0.6.1-10 | Solver diagnostics coupling | lifecycle rows include linear solver status | `linear_solver_cg`, `solver_implicit` | | 0.6.1-11 | Documentation and matrix | docs, matrix, acceptance boundaries | wording checks | | 0.6.1-12 | Release close-out | version, report and regression evidence | targeted + V5 acceptance tests | ## 6. Acceptance Criteria 0.6.1 can close when: - all 0.6.1 TODO items are complete; - every new reason/status/output field is consumed by a regression test or checker; - lifecycle summary rows can explain at least one accepted increment and one rejected/cutback increment; - contact state diagnostics are stable enough for compact long-path checks; - restart-after-accepted-increment audit covers more than one increment in a small deterministic model; - Riks/arc diagnostics expose arc residual and predictor/path direction state; - existing 0.6.0 and V5 acceptance subsets do not regress; - documentation clearly separates 0.6.1 diagnostic hardening from deferred algorithm rewrites. Suggested 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 ``` ## 7. Deferred Route After 0.6.1 After 0.6.1 hardens lifecycle and contact diagnostics, larger algorithm work can be planned with better evidence: - 0.7.x: contact consistent tangent long-path work and shell/solid geometric stiffness. - 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.