248 lines
8.9 KiB
Markdown
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.
|