Files
FemLite/todo.md
T
shenw 5e081806fb
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.6.1
2026-07-01 22:41:16 +08:00

17 KiB

FemLite 0.6.1 TODO

Source plan: docs/v6.1_development_plan.md

Version goal:

FemLite 0.6.1 = nonlinear/contact lifecycle diagnostics hardening

Boundary:

  • 0.6.1 deepens the 0.6.0 lifecycle foundation; it is not a broad algorithm rewrite release.
  • 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.1 must-complete list.
  • Every new reason, status, counter or output field must be consumed by a regression 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. NLHD-1: lifecycle increment summary.
  2. NLHD-2: cutback reason taxonomy.
  3. NLHD-3: lifecycle report output.
  4. NLHD-4: contact state diagnostics.
  5. NLHD-5: contact long-path diagnostic smoke.
  6. NLHD-6: AL/friction diagnostics.
  7. NLHD-7: tangent-audit report shell.
  8. NLHD-8: Riks/arc diagnostics.
  9. NLHD-9: restart-after-each-accepted audit.
  10. NLHD-10: solver diagnostics coupling.
  11. DOC-1: documentation and matrix synchronization.
  12. REL-1: 0.6.1 regression/version close-out.

Detailed Execution Map

TODO Code targets Output/API contract Test/checker target Not in scope
0.6.1-1 lifecycle module and diagnostics API Increment summary fields for lifecycle, convergence, residual, solver and audit state nonlinear_lifecycle, solver_implicit Change Newton algorithms
0.6.1-2 control/reason taxonomy Stable cutback reason ids/names and last cutback reason query solver_implicit, lifecycle test New nonlinear strategy
0.6.1-3 output/report module Compact lifecycle report or appended nonlinear report fields output checker Break old CSV columns
0.6.1-4 contact state/report modules Stable contact state counters and gap/slip/friction fields contact, contact reports Full contact state-machine rewrite
0.6.1-5 contact benchmark checkers Long-path diagnostic smoke for existing compact contact examples contact benchmark checkers New contact benchmark physics
0.6.1-6 multiplier/friction diagnostics AL multiplier, augmentation and friction trend summaries contact_multiplier_report, restart Complete AL tangent
0.6.1-7 tangent audit reporting Shared audit schema and coverage counters tangent audit tests Claim production consistent tangents
0.6.1-8 Riks/arc path diagnostics Arc residual history, predictor and reversal indicators solver_implicit, implicit_inp Mixed-control continuation
0.6.1-9 restart writer/reader tests Multi-increment restart lifecycle audit restart Large restart benchmark
0.6.1-10 linear solver diagnostics Solver status fields linked into lifecycle/nonlinear rows linear_solver_cg, solver_implicit New solver backend
0.6.1-11 docs and matrices Updated interface/user/developer docs and benchmark matrix wording rg checks Expand feature scope
0.6.1-12 version/report files Close 0.6.1 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 new field, reason or status is consumed by a test, checker or report audit.
  • Prefer additive diagnostics over solver-loop rewrites.
  • Keep old CSV columns stable; append new fields.
  • Keep restart readers backward compatible; optional diagnostic blocks are preferred over format breaks.
  • If a task exposes incompatible designs for contact, Riks, material or restart 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.1 Task List

[x] TODO 0.6.1-1: Add lifecycle increment summary

  • Source:
    • docs/v6.1_development_plan.md sections 4.1 and 5, NLHD-1.
  • Implementation:
    • Add a compact lifecycle increment summary structure or query path.
    • Include step, increment, final event id/name and reason id/name.
    • Include convergence status, residual breakdown, linear solver status and audit status fields already available in 0.6.0.
    • Keep existing lifecycle snapshot APIs compatible.
  • Tests:
    • Extend nonlinear_lifecycle to verify empty and populated summary fields.
    • Extend solver_implicit to consume the summary after one accepted and one rejected/cutback path.
  • Acceptance:
    • A test can explain the latest nonlinear increment from one summary query without reading console output.

Verified:

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

[x] TODO 0.6.1-2: Add cutback reason taxonomy

  • Source:
    • docs/v6.1_development_plan.md sections 4.2 and 5, NLHD-2.
  • Implementation:
    • Add stable cutback reason ids/names for common nonlinear failure modes.
    • Track the last cutback reason separately from the final convergence failure reason.
    • Map existing min-step, nonconvergence and linear-solver failure paths into the new taxonomy.
    • Leave unavailable reasons as reserved/documented ids until a real path consumes them.
  • Tests:
    • Extend nonlinear_lifecycle to verify reason-name stability.
    • Extend solver_implicit to verify at least min-step and nonconvergence cutback reasons.
  • Acceptance:
    • Every implemented 0.6.1 cutback reason is consumed by a regression assertion.

Verified:

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

[x] TODO 0.6.1-3: Write lifecycle report output

  • Source:
    • docs/v6.1_development_plan.md sections 4.3 and 5, NLHD-3.
  • Implementation:
    • Add nonlinear_lifecycle.csv or append equivalent lifecycle summary fields to an existing nonlinear report.
    • Cover initialized/no-solve, accepted increment and rejected/cutback increment rows.
    • Include lifecycle summary, cutback reason, residual breakdown, solver status and audit status columns.
    • Preserve old continuation_path.csv column order if that file is extended again.
  • Tests:
    • Add or extend an output checker to validate required lifecycle report headers.
    • Verify at least one accepted row and one rejected/cutback row.
  • Acceptance:
    • Missing lifecycle report fields cause a regression failure.

Verified:

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

[x] TODO 0.6.1-4: Stabilize contact state diagnostics

  • Source:
    • docs/v6.1_development_plan.md sections 4.4 and 5, NLHD-4.
  • Implementation:
    • Define stable contact state names: open, closed-stick, closed-slip, closed-restick, separating and failed-projection.
    • Report state counters through existing contact diagnostics or a compact helper.
    • Include gap maximum/mean/L2, slip increment/residual, friction residual and active-set flip count where available.
    • Keep this diagnostic-only; do not rewrite contact solve state ownership.
  • Tests:
    • Extend contact or contact report tests to verify state names and counters.
    • Verify unsupported/unavailable state fields default consistently.
  • Acceptance:
    • Contact diagnostics can distinguish open, stick/slip and failed projection states without parsing logs.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^contact$" --output-on-failure

[x] TODO 0.6.1-5: Add compact contact long-path diagnostic smoke

  • Source:
    • docs/v6.1_development_plan.md sections 4.5 and 5, NLHD-5.
  • Implementation:
    • Select existing compact examples for two-block compression, block sliding, shell-shell contact and shell-solid contact.
    • Add checker expectations for required diagnostic columns and finite state counters.
    • Check gap/slip/friction/multiplier diagnostics across path steps.
    • Keep benchmark physics and tolerances bounded to existing examples.
  • Tests:
    • Extend existing contact benchmark checkers or their CTest assertions.
    • Verify at least two path steps for one compact long-path case.
  • Acceptance:
    • A compact contact path can fail diagnostics loudly if state or residual fields disappear.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^contact$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^example_(contact_two_blocks_compression|contact_block_sliding|shell_shell_contact|shell_solid_contact)_benchmark$" --output-on-failure

[x] TODO 0.6.1-6: Add AL multiplier and friction diagnostic summaries

  • Source:
    • docs/v6.1_development_plan.md sections 4.6 and 5, NLHD-6.
  • Implementation:
    • Add multiplier residual trend and maximum augmented multiplier summary fields.
    • Add augmentation update count and accepted-step penalty/augmentation factor fields.
    • Add slip/friction residual summary fields where existing friction state supports them.
    • Include restart before/after consistency checks for supported fields.
  • Tests:
    • Extend contact_multiplier_report to consume new summary fields.
    • Extend restart or contact to compare supported multiplier/friction summaries before and after restart.
  • Acceptance:
    • AL/friction diagnostic summaries are visible in tests and survive the covered restart path.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(contact_multiplier_report|restart)$" --output-on-failure

[x] TODO 0.6.1-7: Add shared tangent-audit report shell

  • Source:
    • docs/v6.1_development_plan.md sections 4.7 and 5, NLHD-7.
  • Implementation:
    • Define a shared tangent-audit report schema with audit name, branch, sample count, relative error and status fields.
    • Route existing material/contact/shell/Riks audit summaries into the shared vocabulary where already available.
    • Add coverage counters for missing or not-applicable audit branches.
    • Document that this is an audit report shell, not production consistent tangent delivery.
  • Tests:
    • Extend existing tangent audit tests or add a schema checker.
    • Verify at least normal contact and one non-contact audit category in the shared report vocabulary.
  • Acceptance:
    • Tangent audit output has a uniform schema without changing production tangent behavior.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^contact_mortar_tangent$" --output-on-failure

[x] TODO 0.6.1-8: Harden Riks and arc diagnostics

  • Source:
    • docs/v6.1_development_plan.md sections 4.8 and 5, NLHD-8.
  • Implementation:
    • Record arc residual history for accepted Riks/arc increments.
    • Add predictor direction consistency and load-factor reversal indicators.
    • Add a simple turning-point indicator where current path data supports it.
    • Add path/report fields that distinguish load-control Riks from direct displacement control.
  • Tests:
    • Extend solver_implicit to verify Riks/arc diagnostic fields.
    • Extend implicit_inp only if an existing deterministic input path can consume the fields cheaply.
  • Acceptance:
    • Riks/arc diagnostics expose residual and predictor/path direction state without implementing mixed-control continuation.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp)$" --output-on-failure

[x] TODO 0.6.1-9: Add restart-after-each-accepted audit

  • Source:
    • docs/v6.1_development_plan.md sections 4.9 and 5, NLHD-9.
  • Implementation:
    • Add a compact multi-increment restart audit flow.
    • After each accepted increment, write restart, read into a fresh model and compare lifecycle diagnostics.
    • Compare supported contact/material/path diagnostic summaries before and after restart.
    • Continue one increment after restart to prove the restored state is usable.
  • Tests:
    • Extend restart or add a compact restart-lifecycle test.
    • Keep the model small and deterministic.
  • Acceptance:
    • Restart audit covers more than one accepted increment without relying on a large benchmark.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^restart$" --output-on-failure

[x] TODO 0.6.1-10: Couple solver diagnostics to nonlinear rows

  • Source:
    • docs/v6.1_development_plan.md sections 4.10 and 5, NLHD-10.
  • Implementation:
    • Link matrix class, solver method, preconditioner, iteration count and solver status into lifecycle or nonlinear report rows.
    • Include initial/final/relative residual where current solver diagnostics already provide them.
    • Add a fallback marker for dense pivoting or method fallback paths if available.
    • Keep solver selection behavior unchanged.
  • Tests:
    • Extend linear_solver_cg for field availability and naming where needed.
    • Extend solver_implicit to verify nonlinear rows include solver diagnostics.
  • Acceptance:
    • A nonlinear failure can be distinguished from a linear solver failure through report/API fields.

Verified:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(solver_implicit|linear_solver_cg)$" --output-on-failure

[x] TODO 0.6.1-11: Synchronize documentation and benchmark matrix

  • Source:
    • docs/v6.1_development_plan.md sections 4.11 and 5, DOC-1.
  • Implementation:
    • Update docs/v6_benchmark_matrix.md with 0.6.1 diagnostic tests and evidence placeholders.
    • Update interface docs with new lifecycle, cutback, contact and solver diagnostic fields.
    • Update user/developer manuals with the 0.6.1 boundary and deferred algorithm rewrites.
    • Add or update a 0.6.1 acceptance report section.
  • Tests:
    • Run wording rg checks so docs do not claim 0.6.1 delivers complete AL/mortar tangent, mixed-control continuation or cohesive mainline.
  • Acceptance:
    • Documentation states that 0.6.1 delivers diagnostic hardening, while larger solver rewrites remain follow-up work.

Verified:

rg -n "0\.6\.1.*(complete|完整|industrial|生产一致切线|mixed-control continuation|AL/mortar consistent tangent).*交付|0\.6\.1.*delivers complete|0\.6\.1.*完整 AL|0\.6\.1.*mixed-control" docs
rg -n "0\.6\.1|nonlinear_lifecycle.csv|arc_mode|fem_tangent_audit_report|closed-stick|linear_fail_class" docs/v6_benchmark_matrix.md docs/v6_acceptance_report.md docs/07_user_manual.md docs/08_developer_manual.md

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

  • Source:
    • docs/v6.1_development_plan.md section 6, REL-1.
  • Implementation:
    • Update benchmark/acceptance matrix with final 0.6.1 test evidence.
    • Update acceptance report with 0.6.1 scope, commands and limitations.
    • Raise project version only when 0.6.1 implementation is ready to close.
    • Keep deferred boundaries explicit in release documentation.
  • Tests:
    • Run the planned 0.6.1 targeted regression command.
    • Run ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure.
    • Run git diff --check.
  • Acceptance:
    • 0.6.1 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 "^(smoke|perf_contact_pair_p1)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|implicit_inp|restart|contact|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance|linear_solver_cg)$" --output-on-failure
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
git diff --check

Suggested 0.6.1 Regression Commands

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|implicit_inp|restart|contact|contact_mortar_report|contact_multiplier_report|cohesive_contact|particle_acceptance|linear_solver_cg)$" --output-on-failure
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
git diff --check