This commit is contained in:
@@ -0,0 +1,387 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user