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

8.9 KiB

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.

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:

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

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:

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:

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.