Files
FemLite/todo.md
T
shenw ee18a9b757
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.6.2 stability hardening
2026-07-02 08:26:46 +08:00

17 KiB

FemLite 0.6.2 TODO

Version goal:

FemLite 0.6.2 = release hardening and stability reinforcement

Boundary:

  • 0.6.2 does not add new user-facing algorithms or broaden the feature scope.
  • 0.6.2 must stabilize the 0.6.1 lifecycle/contact/Riks/solver diagnostic work and tighten release gates.
  • Do not implement complete industrial AL/mortar consistent tangents, mixed-control continuation, cohesive contact mainline, DEM/FEM subcycling, shell preload K_G, high-order solid K_G, nonzero harmonic cyclic symmetry or production roll-forming workflow in this task list.
  • Each TODO should add one observable stability contract and one focused verification path.
  • Prefer small refactors, schema guards, deterministic tests and error-path checks over solver-loop rewrites.

Execution Order

  1. RH-1: source-size hard failure cleanup.
  2. RH-2: release quality gate definition.
  3. RH-3: continuation_path.csv writer/schema hardening.
  4. RH-4: nonlinear_lifecycle.csv writer/schema hardening.
  5. RH-5: nonlinear path storage/reset hardening.
  6. RH-6: restart compatibility and test decomposition.
  7. RH-7: contact benchmark checker schema consolidation.
  8. RH-8: OpenMP contact determinism checks.
  9. RH-9: contact state edge/default checks.
  10. RH-10: linear-solver fallback state stability.
  11. RH-11: INP/CLI error-boundary stability.
  12. RH-12: documentation/version close-out.

Detailed Execution Map

TODO Code targets Stability contract Test/checker target Not in scope
0.6.2-1 fem_control, fem_output_csv, test_restart source_size hard limit passes without changing solver behavior source_size, affected module tests Add blanket exceptions
0.6.2-2 docs, release command notes 0.6.2 release gate always includes build, source_size, targeted regression, V5 acceptance and git diff --check documented command replay New CI service
0.6.2-3 fem_output_csv path writer continuation_path.csv keeps old column order and writes a validated row schema solver_implicit, implicit_inp New path-following algorithm
0.6.2-4 fem_output_csv lifecycle writer nonlinear_lifecycle.csv writes stable columns for empty, accepted, rejected and solver-failure states nonlinear_lifecycle, solver_implicit New lifecycle fields
0.6.2-5 fem_control path storage path append/reset/release/capacity growth does not leave stale rows or corrupted diagnostics nonlinear_lifecycle, solver_implicit Change continuation math
0.6.2-6 fem_restart, test_restart restart tests are decomposed and cover optional/missing/truncated diagnostic blocks cleanly restart New restart format
0.6.2-7 contact example checkers compact contact benchmark schema checks share one required-field contract contact benchmark CTests New benchmark physics
0.6.2-8 contact OpenMP path 1-thread and 4-thread compact contact paths remain deterministic for accepted diagnostics contact_omp1, contact_omp4, perf_contact_pair_omp_consistency Parallel algorithm rewrite
0.6.2-9 contact state/report modules no-pair, release/recontact and failed-projection states report stable defaults/counters contact, contact report tests Full contact state-machine rewrite
0.6.2-10 linear solver dispatch/fallback solver fallback restores user configuration and reports failure class without stale status linear_solver_cg, solver_implicit, c_api New solver backend
0.6.2-11 INP parser, CLI boundary invalid controls, unsupported shell geometry and output-dir edge cases fail deterministically implicit_inp, CLI CTests, output tests New keywords
0.6.2-12 README, manuals, reports, version files 0.6.2 docs/version match stability scope and do not claim deferred features wording checks, full release gate Feature expansion

Implementation Rules

  • Work in the execution order above.
  • Do not mark a TODO done until its test/checker target passes.
  • If a refactor changes numerical output outside formatting/schema-only differences, stop and inspect before continuing.
  • Keep old CSV columns stable; append-only changes are allowed only when a specific stability check needs them.
  • Keep restart readers backward compatible; optional diagnostic blocks should remain optional.
  • Prefer extracting helper routines over adding source_size exceptions.
  • If a hard limit cannot be cleared without risky behavior changes, document the exact reason in tests/source_size_exceptions.txt and ask before accepting the exception.
  • Generated CSV/VTK/restart/result files must not be committed.

0.6.2 Task List

[x] TODO 0.6.2-1: Clear current source_size hard failures

  • Source:
    • 0.6.2 stability review P0.
  • Implementation:
    • Split nlc_path_append in src/base/fem_control.f90 into focused helper routines for arc indicators, row initialization and diagnostics copy.
    • Split output_csv_write_path in src/output/fem_output_csv.f90 into header, row-prefix, residual and lifecycle/arc tail helpers.
    • Split check_contact_history_restart in tests/module/test_restart.f90 into smaller contact history, contact state and friction/multiplier comparison helpers.
    • Avoid broad source_size exceptions unless a split would alter runtime behavior.
  • Tests:
    • Run ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure.
    • Run affected tests: nonlinear_lifecycle, solver_implicit, restart.
  • Acceptance:
    • source_size has no hard failures.
    • Refactors are behavior-preserving.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit|restart)$" --output-on-failure

[x] TODO 0.6.2-2: Define the 0.6.2 release quality gate

  • Source:
    • 0.6.2 stability review P0.
  • Implementation:
    • Add/update release notes so 0.6.2 requires build, source_size, targeted stability regression, V5 acceptance and git diff --check.
    • Add a compact 0.6.2 stability matrix section listing required commands.
    • Keep the quality gate focused on stability checks already present in the repository.
  • Tests:
    • Replay the documented command list locally once it is written.
  • Acceptance:
    • The documented gate would have caught the current source_size failure before release.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^source_size$" --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|c_api)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
    • git diff --check

[x] TODO 0.6.2-3: Harden continuation_path.csv schema and writer

  • Source:
    • 0.6.2 stability review P1.
  • Implementation:
    • Keep existing continuation_path.csv column order stable.
    • Add a single schema/header helper for path output.
    • Add a row check that verifies required lifecycle, linear solver and arc diagnostic fields are present after writing.
    • Preserve existing accepted-path numerical values.
  • Tests:
    • Extend solver_implicit or implicit_inp to validate header fields and a representative row.
  • Acceptance:
    • Missing or reordered path diagnostic columns fail a regression test.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-4: Harden nonlinear_lifecycle.csv schema and writer

  • Source:
    • 0.6.2 stability review P1.
  • Implementation:
    • Factor lifecycle CSV header and row writing into small helpers.
    • Verify empty lifecycle, accepted increment, rejected/cutback increment and linear-solver failure rows use the same column contract.
    • Keep field names stable for lifecycle, cutback, residual, linear solver and audit status.
  • Tests:
    • Extend nonlinear_lifecycle and solver_implicit CSV checks.
  • Acceptance:
    • All covered lifecycle rows have the documented schema and parse without ad hoc column handling.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-5: Harden nonlinear path storage reset and capacity growth

  • Source:
    • 0.6.2 stability review P1.
  • Implementation:
    • Add focused checks for repeated nlc_path_reset and nlc_path_release.
    • Add a capacity-growth test that appends more rows than the initial allocation.
    • Verify arc reversal/turning-point diagnostics do not read stale prior row data after reset.
  • Tests:
    • Extend nonlinear_lifecycle or solver_implicit.
  • Acceptance:
    • Repeated path append/reset/release cycles remain deterministic and do not corrupt existing diagnostics.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-6: Decompose restart tests and add compatibility error paths

  • Source:
    • 0.6.2 stability review P1.
  • Implementation:
    • Split contact restart comparisons into contact history, state summary, friction summary and multiplier summary helpers.
    • Add a missing optional lifecycle block read-back check.
    • Add a truncated/corrupt diagnostic block check that returns a clear error instead of partial silent state.
    • Keep current restart version and old-file compatibility behavior.
  • Tests:
    • Run ctest --test-dir build-codex-gcc -R "^restart$" --output-on-failure.
  • Acceptance:
    • Restart coverage is easier to review and preserves backward-compatible optional diagnostics.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^restart$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-7: Consolidate compact contact benchmark schema checks

  • Source:
    • 0.6.2 stability review P2.
  • Implementation:
    • Extract shared required-column checks for compact contact benchmark Python checkers.
    • Apply the shared schema to two-block compression, block sliding, shell-shell contact and shell-solid contact checkers.
    • Keep each benchmark's existing physics assertions local to that checker.
  • Tests:
    • Run contact compact benchmark CTests for the four affected examples.
  • Acceptance:
    • A missing contact diagnostic column fails consistently in every compact contact checker.
  • Verified:
    • 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.2-8: Strengthen OpenMP contact determinism checks

  • Source:
    • 0.6.2 stability review P2.
  • Implementation:
    • Compare 1-thread and 4-thread compact contact diagnostics for active count, force norm, gap summary, friction work and cache statistics.
    • Add repeat-run tolerance checks where existing outputs are deterministic.
    • Keep OpenMP implementation unchanged unless a race is exposed.
  • Tests:
    • Run contact_omp1, contact_omp4 and perf_contact_pair_omp_consistency.
  • Acceptance:
    • OpenMP contact diagnostics are stable across the covered compact path.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(contact_omp1|contact_omp4|perf_contact_pair_omp_consistency)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-9: Add contact state edge/default stability checks

  • Source:
    • 0.6.2 stability review P2.
  • Implementation:
    • Verify no-contact-pair diagnostics return stable zero/default state.
    • Verify release/recontact transitions preserve expected counters in a compact path.
    • Verify failed projection counters are exposed consistently when the existing code reports projection failure.
  • Tests:
    • Extend contact or a contact report test.
  • Acceptance:
    • Contact state diagnostics do not require special-case parsing for unsupported or inactive paths.
  • 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 "^source_size$" --output-on-failure

[x] TODO 0.6.2-10: Harden linear-solver fallback state reporting

  • Source:
    • 0.6.2 stability review P3.
  • Implementation:
    • Verify CG failure fallback restores the user's configured method and preconditioner.
    • Verify dense fallback failure reports the expected fail class without stale success status.
    • Verify invalid solver/preconditioner configuration does not mutate the previous valid setting.
    • Keep solver algorithms unchanged.
  • Tests:
    • Extend linear_solver_cg, solver_implicit or c_api.
  • Acceptance:
    • Solver diagnostics distinguish fallback, configuration error and normal convergence in a repeatable way.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(linear_solver_cg|solver_implicit|c_api)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-11: Harden INP and CLI error boundaries

  • Source:
    • 0.6.2 stability review P3.
  • Implementation:
    • Verify invalid nonlinear continuation parameters fail before mutating existing control state.
    • Verify unsupported shell finite-strain requests fail clearly and do not fall back to linear shell behavior.
    • Verify CLI output-directory edge cases create directories when allowed and report clear errors when not allowed.
    • Do not add new INP keywords.
  • Tests:
    • Extend implicit_inp, CLI CTests or output tests.
  • Acceptance:
    • Invalid input and CLI boundaries fail deterministically with stable error messages/status.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^(implicit_inp|cli_output_dir_boundary|vtk_output)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure

[x] TODO 0.6.2-12: Close 0.6.2 docs, version and release evidence

  • Source:
    • 0.6.2 stability review close-out.
  • Implementation:
    • Update version files from 0.6.1 to 0.6.2 only after implementation and regression checks are ready.
    • Update README, user manual, developer manual, acceptance report and benchmark matrix to state that 0.6.2 is a stability release.
    • Correct stale document titles that still describe 0.5.x or 0.6.0 when referring to the current line.
    • Keep deferred feature boundaries explicit.
  • Tests:
    • Run the 0.6.2 release quality gate from TODO 0.6.2-2.
    • Run wording checks so docs do not claim new algorithms in 0.6.2.
  • Acceptance:
    • 0.6.2 closes with green release gate, clean version assertions and documentation matching the stability-only scope.
  • Verified:
    • cmake --build build-codex-gcc --parallel
    • ctest --test-dir build-codex-gcc -R "^source_size$" --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|c_api|cli_output_dir_boundary|vtk_output)$" --output-on-failure
    • ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
    • ctest --test-dir build-codex-gcc -R "^(smoke|c_api)$" --output-on-failure
    • git diff --check

Suggested 0.6.2 Regression Commands

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^source_size$" --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|c_api|cli_output_dir_boundary|vtk_output)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^(contact_omp1|contact_omp4|perf_contact_pair_omp_consistency)$" --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
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure
git diff --check