@@ -0,0 +1,247 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user