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

15 KiB

FemLite 0.6.0 TODO

Source plan: docs/v6.0_development_plan.md

Version goal:

FemLite 0.6.0 = unified nonlinear state machine and lifecycle foundation

Boundary:

  • The fifth-version closure boundary is lifted for future planning, but 0.6.0 should still remain a controlled loop.
  • Do not implement a complete industrial AL/mortar consistent tangent rewrite in this task list.
  • Do not move mixed-control continuation, shell preload K_G, high-order solid K_G, cohesive contact mainline, nonzero harmonic cyclic, DEM subcycling or production roll forming into the 0.6.0 must-complete list.
  • Every new lifecycle or audit field must be consumed by a test, checker or report audit.
  • Keep TODO item size uniform: each task should add one observable contract and one focused verification path.

Execution Order

  1. NLCS-1: lifecycle ids, names and snapshot skeleton.
  2. NLCS-2: static nonlinear lifecycle hook.
  3. NLCS-3: nonlinear Newmark lifecycle hook.
  4. NLCS-4: Riks/arc lifecycle hook.
  5. NLCS-5: rollback audit core.
  6. NLCS-6: material rollback audit adapter.
  7. NLCS-7: contact rollback audit adapter.
  8. NLCS-8: cohesive and particle audit adapters.
  9. NLCS-9: lifecycle output/report schema.
  10. NLCS-10: restart lifecycle audit.
  11. DOC-1: documentation and interface synchronization.
  12. REL-1: 0.6.0 regression/version close-out.

Detailed Execution Map

TODO Code targets Output/API contract Test/checker target Not in scope
0.6.0-1 src/solver/fem_nonlinear_lifecycle.f90, diagnostics API Stable lifecycle event ids/names and queryable empty snapshot new lifecycle unit/module test Change Newton algorithms
0.6.0-2 static nonlinear solver loop Record increment/iteration begin/end and accept/reject events solver_implicit Change convergence rules
0.6.0-3 nonlinear Newmark solver loop Record dynamic nonlinear lifecycle events solver_implicit Rewrite Newmark integration
0.6.0-4 Riks/arc static path Record load factor, arc residual and path append lifecycle fields solver_implicit, implicit_inp Mixed-control continuation
0.6.0-5 lifecycle audit module Generic commit/rollback audit counters and status lifecycle audit unit/module test Owner-specific checksum details
0.6.0-6 material/element state path Material local state rollback audit for covered subset solver_implicit, material tests New material models
0.6.0-7 contact state/history path Contact state and diagnostic rollback audit for covered subset restart, contact report tests Full contact state-machine rewrite
0.6.0-8 cohesive and particle compact paths Cohesive/particle owner audit hooks using existing compact tests cohesive_contact, particle_acceptance Cohesive mainline or DEM subcycling
0.6.0-9 output/report modules Lifecycle event/report columns or compact lifecycle CSV solver_implicit, output checker Break existing CSV consumers
0.6.0-10 restart writer/reader and restart tests Accepted-increment lifecycle diagnostics round trip restart Redesign restart format
0.6.0-11 docs and manuals Document lifecycle API, output and deferred boundaries wording rg checks Expand feature scope
0.6.0-12 version/matrix/report files Close 0.6.0 after green targeted and V5 acceptance tests build, targeted tests, acceptance, git diff --check Version bump before tests pass

Implementation Rules

  • Work in the execution order above.
  • Do not mark a TODO done until its lifecycle field or audit status is consumed by a test, checker or report audit.
  • Prefer additive lifecycle hooks over solver-loop rewrites.
  • Keep existing public signatures stable unless a thin new accessor is clearly safer.
  • If a task exposes incompatible designs for lifecycle ownership, pause and ask for a decision before editing that route.
  • If a later task needs a field created by an earlier task, finish and test the earlier task first.

0.6.0 Task List

[x] TODO 0.6.0-1: Add nonlinear lifecycle ids and snapshot skeleton

  • Source:
    • docs/v6.0_development_plan.md sections 4.1 and 5, NLCS-1.
  • Implementation:
    • Add stable lifecycle event ids and names for increment begin, trial begin, iteration result, accept, reject, cutback, commit and rollback.
    • Add a small lifecycle snapshot with step/increment/iteration/event fields and last reason id/name linkage.
    • Add a reset/begin/query API that returns a valid empty snapshot before any nonlinear solve.
    • Keep the module passive; it must not change solver behavior yet.
  • Tests:
    • Add a lifecycle unit/module test for id/name stability and empty snapshot defaults.
  • Acceptance:
    • Tests can query lifecycle state without running a solve, and all event names are stable.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|linear_solver_cg|c_api)$" --output-on-failure

[x] TODO 0.6.0-2: Hook static nonlinear lifecycle events

  • Source:
    • docs/v6.0_development_plan.md sections 4.1 and 5, NLCS-2.
  • Implementation:
    • Record increment begin and iteration begin in the nonlinear static path.
    • Record iteration result with convergence status and current failure reason fields.
    • Record accepted, rejected or cutback increment events without changing the existing cutback decision.
    • Preserve existing convergence metrics and continuation path behavior.
  • Tests:
    • Extend solver_implicit to verify lifecycle event sequence for a converged static nonlinear path and one rejected/cutback path.
  • Acceptance:
    • Static nonlinear diagnostics expose lifecycle events that match the existing solver outcome.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure

[x] TODO 0.6.0-3: Hook nonlinear Newmark lifecycle events

  • Source:
    • docs/v6.0_development_plan.md sections 4.1 and 5, NLCS-3.
  • Implementation:
    • Record Newmark nonlinear increment and iteration lifecycle events.
    • Link dynamic residual status to the shared lifecycle snapshot.
    • Record accepted/rejected dynamic increments where the current path can identify them.
    • Preserve current Newmark time integration and convergence behavior.
  • Tests:
    • Extend solver_implicit to verify lifecycle fields after a nonlinear Newmark run.
  • Acceptance:
    • Static and Newmark nonlinear paths expose the same lifecycle field contract for the covered subset.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(solver_implicit|nonlinear_lifecycle|c_api)$" --output-on-failure

[x] TODO 0.6.0-4: Hook Riks/arc lifecycle events

  • Source:
    • docs/v6.0_development_plan.md sections 4.1 and 5, NLCS-4.
  • Implementation:
    • Record Riks/arc lifecycle events in the load-type arc path.
    • Store current load factor, arc residual and arc reason in the lifecycle snapshot.
    • Record whether a path row is appended because the increment was accepted.
    • Preserve current Riks/arc equations and direct displacement-control behavior.
  • Tests:
    • Extend solver_implicit or implicit_inp to verify arc lifecycle fields on an accepted Riks path.
  • Acceptance:
    • Riks/arc diagnostics can be interpreted through the same lifecycle event model as static nonlinear diagnostics.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|c_api)$" --output-on-failure

[x] TODO 0.6.0-5: Add generic rollback audit core

  • Source:
    • docs/v6.0_development_plan.md sections 4.2 and 5, NLCS-5.
  • Implementation:
    • Add generic audit counters for begin-trial, rollback-requested, rollback-ok, rollback-failed and commit-ok.
    • Add an audit status/name field to the lifecycle snapshot.
    • Add helpers that owner modules can call without depending on each other.
    • Keep owner-specific checksum logic out of the generic core.
  • Tests:
    • Add lifecycle audit coverage for counter transitions and failure naming.
  • Acceptance:
    • A test can simulate owner audit success/failure and observe the shared audit status.

Verified:

  • ctest --test-dir build-codex-gcc -R "^nonlinear_lifecycle$" --output-on-failure

[x] TODO 0.6.0-6: Add material rollback audit adapter

  • Source:
    • docs/v6.0_development_plan.md sections 4.3 and 5, NLCS-6.
  • Implementation:
    • Add a covered-subset material state checksum or equivalent audit value before trial updates.
    • Compare material state after rollback for a rejected nonlinear increment.
    • Feed material rollback status into the lifecycle audit core.
    • Keep material constitutive algorithms unchanged.
  • Tests:
    • Extend solver_implicit or material tests with one rejected/cutback material-state rollback audit.
  • Acceptance:
    • Rejected material trial updates are proven not to contaminate committed state for the covered subset.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure

[x] TODO 0.6.0-7: Add contact rollback audit adapter

  • Source:
    • docs/v6.0_development_plan.md sections 4.3 and 5, NLCS-7.
  • Implementation:
    • Capture contact state counts and selected contact diagnostics before trial changes.
    • Compare contact state after rollback for a rejected/cutback increment.
    • Feed contact rollback status into the lifecycle audit core.
    • Reuse existing 0.5.3 contact diagnostics rather than adding broad new contact fields.
  • Tests:
    • Extend restart or contact report tests with a contact rollback audit scenario.
  • Acceptance:
    • Contact diagnostics and state counts remain consistent after rollback for the covered subset.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(contact|contact_multiplier_diag)$" --output-on-failure

[x] TODO 0.6.0-8: Add cohesive and particle audit adapters

  • Source:
    • docs/v6.0_development_plan.md sections 4.3 and 5, NLCS-8.
  • Implementation:
    • Add cohesive compact-path audit hooks for damage/status/energy rollback where existing state support allows it.
    • Add particle compact-path audit hooks for mass/momentum/energy counters.
    • Feed both owner statuses into the lifecycle audit core.
    • Keep cohesive mainline contact and DEM subcycling out of this task.
  • Tests:
    • Extend cohesive_contact and particle_acceptance to consume the new audit statuses.
  • Acceptance:
    • Existing compact cohesive and particle tests can report lifecycle audit status without changing their physics paths.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(cohesive_contact|particle_step|nonlinear_lifecycle)$" --output-on-failure

[x] TODO 0.6.0-9: Write lifecycle diagnostics to output/report path

  • Source:
    • docs/v6.0_development_plan.md sections 4.4 and 5, NLCS-9.
  • Implementation:
    • Add lifecycle event/status fields to an existing nonlinear report path or a compact nonlinear_lifecycle.csv.
    • Include event id/name, audit status/name, increment, iteration, reason id/name and accepted/rejected counters.
    • Keep old continuation/contact CSV columns stable.
    • Represent missing lifecycle data consistently for unsupported paths.
  • Tests:
    • Extend solver_implicit or an output checker to verify lifecycle output headers and at least one accepted row.
  • Acceptance:
    • Checker failure occurs if required 0.6.0 lifecycle output fields are missing.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(solver_implicit|nonlinear_lifecycle)$" --output-on-failure

[x] TODO 0.6.0-10: Add restart lifecycle audit

  • Source:
    • docs/v6.0_development_plan.md sections 4.4 and 6, NLCS-10.
  • Implementation:
    • Persist accepted-increment lifecycle diagnostics needed for restart audit where restart format already supports the owned state.
    • Read old restart files without requiring lifecycle fields.
    • Compare lifecycle event/status and owner audit summaries before and after restart.
    • Avoid redesigning the restart format beyond an optional lifecycle block.
  • Tests:
    • Extend restart to verify lifecycle diagnostics survive an accepted increment restart round trip.
  • Acceptance:
    • Restart proves both owned state and lifecycle diagnostics for the covered subset.

Verified:

  • ctest --test-dir build-codex-gcc -R "^(restart|nonlinear_lifecycle)$" --output-on-failure

[x] TODO 0.6.0-11: Synchronize documentation and API descriptions

  • Source:
    • docs/v6.0_development_plan.md sections 2, 4 and 6, DOC-1.
  • Implementation:
    • Update design and algorithm docs with lifecycle levels and event names.
    • Update interface docs with new lifecycle query/output fields.
    • Update test plan with 0.6.0 regression commands and acceptance criteria.
    • Update user/developer manuals with lifecycle boundary and deferred algorithm rewrites.
  • Tests:
    • Run wording rg checks so docs do not claim 0.6.0 delivers complete AL/mortar tangent, mixed-control continuation or cohesive mainline.
  • Acceptance:
    • Documentation states that 0.6.0 delivers lifecycle foundation and rollback audit, while larger solver rewrites remain follow-up work.

Verified:

  • rg -n "0\\.6\\.0.*(complete industrial AL/mortar|mixed-control continuation|cohesive contact mainline|cohesive mainline|complete AL/mortar|generalized mixed-control)" docs README.md todo.md
  • rg -n "LIFECYCLE_DIAGNOSTICS|lifecycle_event_id|fem_get_nl_lifecycle|0\\.6\\.0 Lifecycle" docs

[x] TODO 0.6.0-12: Update version, matrix, report and release evidence

  • Source:
    • docs/v6.0_development_plan.md section 6, REL-1.
  • Implementation:
    • Update benchmark/acceptance matrix with 0.6.0 lifecycle tests and diagnostic evidence.
    • Update acceptance report with 0.6.0 scope, commands and limitations.
    • Raise project version only when 0.6.0 implementation is ready to close.
    • Keep deferred boundaries explicit in release documentation.
  • Tests:
    • Run the planned 0.6.0 targeted regression command.
    • Run ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure.
    • Run git diff --check.
  • Acceptance:
    • 0.6.0 closes with green targeted tests, green acceptance subset and documented deferred boundaries.

Verified:

  • 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

Suggested 0.6.0 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