Files
FemLite/docs/v6.0_development_plan.md
T
shenw 175531e24d
FemLite CI / build-test (push) Has been cancelled
Release 0.6.0
2026-07-01 20:44:15 +08:00

248 lines
8.9 KiB
Markdown

# FemLite 0.6.0 Development Plan
Document status: development plan draft
Date: 2026-07-01
Scope: FemLite 0.6.0 development, review, testing and release planning.
Source: `docs/suggests.md`
## 1. Positioning
FemLite 0.6.0 is the algorithm-foundation release after the 0.5.x V5
close-out.
```text
FemLite 0.6.0 = unified nonlinear state machine and lifecycle foundation
```
0.5.3 completed nonlinear/contact explainability hardening: stable failure
reasons, residual breakdown fields, contact diagnostics, restart diagnostic
round trips, tangent audit split and OpenMP deterministic contact checks.
0.6.0 should build on that work by making the nonlinear increment lifecycle
explicit and shared.
The release should improve depth and reliability instead of adding broad new
feature families. The first controlled loop is:
```text
begin increment
begin trial state
assemble residual/tangent
solve correction
evaluate convergence and events
accept or reject
commit or rollback every owned state
record diagnostics
end increment
```
## 2. Delivery Boundary
### 2.1 0.6.0 must deliver
- A small, shared nonlinear lifecycle/state-machine module.
- Stable event ids/names for increment begin, trial begin, iteration result,
accept, reject, cutback, commit and rollback.
- A rollback audit that can prove rejected increments do not contaminate
material, contact, cohesive, particle, Newmark or continuation-owned state
for the covered subset.
- Unified per-increment diagnostics that connect reason id, residual
breakdown, linear-solver diagnostics, contact/material counters and lifecycle
event status.
- Static nonlinear, Newmark nonlinear and Riks/arc-length paths using the same
lifecycle recording points for the covered subset.
- Restart-after-accepted-increment evidence that lifecycle diagnostics survive
the round trip where the underlying state is already restart-supported.
- Documentation and checkers that make the new lifecycle contract visible.
### 2.2 0.6.0 does 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 all contact algorithms.
- General mixed-control continuation and branch switching.
- Complete shell preload `K_G` and high-order solid geometric stiffness.
- 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 the lifecycle interface, but they are not 0.6.0
blocking scope.
## 3. Design Principles
- Keep the first state machine additive and observable. It should not rewrite
every solver loop at once.
- Use thin lifecycle hooks around existing paths before moving ownership of
algorithm decisions.
- Make every new diagnostic field consumed by a test, checker or report audit.
- Preserve existing public APIs and CSV columns unless a versioned change is
documented.
- Treat rollback correctness as a product behavior, not only an internal
implementation detail.
- Pause for review if a task requires choosing between incompatible solver-loop
designs.
## 4. Proposed Architecture
### 4.1 Lifecycle levels
```text
Analysis step
Increment
Iteration
Trial state
Residual assembly
Tangent assembly
Linear solve
Line search / damping / trust region
Accept / reject
Commit / rollback
```
### 4.2 Core module
Recommended new module:
```text
src/solver/fem_nonlinear_lifecycle.f90
```
Responsibilities:
- Define lifecycle event ids and names.
- Store the current increment/iteration lifecycle snapshot.
- Provide begin/end/update helpers for solver loops.
- Store rollback/commit audit counters.
- Provide a query API for tests and output modules.
The module should not own Newton, Riks, contact or material algorithms in
0.6.0. It should first record and verify their lifecycle behavior.
### 4.3 Owner adapters
The following owners should initially expose small audit hooks:
| Owner | 0.6.0 expectation |
|---|---|
| Material state | Record local failure count and state checksum before/after rollback for covered elements. |
| Contact state | Record active/state counters, gap/slip diagnostics and restart-owned contact fields. |
| Cohesive state | Record damage/energy/status checks where existing cohesive state restart exists. |
| Particle state | Record mass/momentum/energy counters for explicit particle step subset. |
| Newmark state | Record displacement/velocity/acceleration trial and rollback checks for the covered nonlinear path. |
| Continuation/Riks path | Record load factor, arc residual and accepted-path append decision. |
### 4.4 Diagnostics
0.6.0 should connect, not replace, existing diagnostics:
- nonlinear reason id/name from 0.5.3;
- residual breakdown from 0.5.3;
- linear solver diagnostics from 0.5.x;
- contact state/residual diagnostics from 0.5.3;
- material local failure count;
- lifecycle event id/name;
- commit/rollback audit status;
- accepted/rejected increment counters.
## 5. Execution Plan
| Item | Theme | Output | Primary tests |
|---|---|---|---|
| 0.6.0-1 | Scope and API skeleton | lifecycle ids, names and empty snapshot query | new lifecycle unit test |
| 0.6.0-2 | Static nonlinear hook | increment/iteration begin/end events | `solver_implicit` |
| 0.6.0-3 | Newmark hook | dynamic nonlinear lifecycle events | `solver_implicit` |
| 0.6.0-4 | Riks/arc hook | load-factor/arc event fields | `solver_implicit`, `implicit_inp` |
| 0.6.0-5 | Rollback audit core | generic audit counters and status | lifecycle unit test |
| 0.6.0-6 | Material rollback audit | material state checksum subset | `solver_implicit`, material tests |
| 0.6.0-7 | Contact rollback audit | contact state/diagnostic subset | `restart`, contact report tests |
| 0.6.0-8 | Cohesive/particle audit adapters | existing compact owner checks | `cohesive_contact`, `particle_acceptance` |
| 0.6.0-9 | Lifecycle output | path/report columns or compact lifecycle CSV | `solver_implicit`, checker |
| 0.6.0-10 | Restart audit | accepted-increment lifecycle round trip | `restart` |
| 0.6.0-11 | Documentation | design/interface/manual/test plan sync | wording checks |
| 0.6.0-12 | Release close-out | version, matrix and regression evidence | targeted + acceptance tests |
## 6. Acceptance Criteria
0.6.0 can close when:
- all 0.6.0 TODO items are complete;
- the lifecycle snapshot is queryable from tests;
- static nonlinear, nonlinear Newmark and Riks/arc paths record lifecycle
events consistently for covered paths;
- rollback audit catches at least one intentionally rejected increment scenario;
- accepted-increment restart preserves both state and lifecycle diagnostics for
the covered subset;
- existing V5 acceptance tests do not regress;
- documentation states the boundary between lifecycle foundation and deferred
larger algorithm rewrites.
Suggested regression commands:
```powershell
cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|restart|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance)$" --output-on-failure
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
git diff --check
```
## 7. Follow-up Route After 0.6.0
After the lifecycle foundation is proven, the next releases can safely deepen
larger algorithms:
- 0.6.x: contact state-machine stabilization and AL/mortar tangent long-path
work.
- 0.7.x: shell/solid geometric stiffness and preload-to-buckling workflow.
- 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.
## 8. Implementation Contract
The implemented 0.6.0 lifecycle foundation is additive. It records the current
nonlinear step, increment, iteration, event id/name, reason id/name, arc state
and audit status without changing Newton, Newmark, Riks or contact algorithms.
Stable event names are:
- `none`
- `increment-begin`
- `trial-begin`
- `iteration-begin`
- `iteration-result`
- `accept`
- `reject`
- `cutback`
- `commit`
- `rollback`
Stable audit status names are:
- `none`
- `begin-trial`
- `rollback-requested`
- `rollback-ok`
- `rollback-failed`
- `commit-ok`
The public diagnostic boundary is:
- Fortran diagnostics query the latest lifecycle snapshot, arc/path state and
audit counters.
- `continuation_path.csv` keeps older columns in place and appends lifecycle
event/status, lifecycle increment/iteration and accepted/rejected counters.
- Restart version 5 appends an optional `LIFECYCLE_DIAGNOSTICS` block after
contact diagnostics. Readers still accept files that end at `END` without
this block.
0.6.0 does not implement a complete industrial AL/mortar consistent tangent,
mixed-control continuation or cohesive contact mainline. Those items remain
follow-up work that can consume the lifecycle interface.