Files
FemLite/docs/v6.1_development_plan.md
T
shenw 5e081806fb
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.6.1
2026-07-01 22:41:16 +08:00

12 KiB

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.

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:

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:

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:

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:

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.