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

388 lines
12 KiB
Markdown

# 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.