17 KiB
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 solidK_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
- RH-1: source-size hard failure cleanup.
- RH-2: release quality gate definition.
- RH-3:
continuation_path.csvwriter/schema hardening. - RH-4:
nonlinear_lifecycle.csvwriter/schema hardening. - RH-5: nonlinear path storage/reset hardening.
- RH-6: restart compatibility and test decomposition.
- RH-7: contact benchmark checker schema consolidation.
- RH-8: OpenMP contact determinism checks.
- RH-9: contact state edge/default checks.
- RH-10: linear-solver fallback state stability.
- RH-11: INP/CLI error-boundary stability.
- 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_sizeexceptions. - If a hard limit cannot be cleared without risky behavior changes, document
the exact reason in
tests/source_size_exceptions.txtand 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_appendinsrc/base/fem_control.f90into focused helper routines for arc indicators, row initialization and diagnostics copy. - Split
output_csv_write_pathinsrc/output/fem_output_csv.f90into header, row-prefix, residual and lifecycle/arc tail helpers. - Split
check_contact_history_restartintests/module/test_restart.f90into smaller contact history, contact state and friction/multiplier comparison helpers. - Avoid broad
source_sizeexceptions unless a split would alter runtime behavior.
- Split
- Tests:
- Run
ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure. - Run affected tests:
nonlinear_lifecycle,solver_implicit,restart.
- Run
- Acceptance:
source_sizehas no hard failures.- Refactors are behavior-preserving.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failurectest --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 andgit 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.
- Add/update release notes so 0.6.2 requires build,
- Tests:
- Replay the documented command list locally once it is written.
- Acceptance:
- The documented gate would have caught the current
source_sizefailure before release.
- The documented gate would have caught the current
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failurectest --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-failurectest --test-dir build-codex-gcc -L v5_acceptance --output-on-failuregit 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.csvcolumn 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.
- Keep existing
- Tests:
- Extend
solver_implicitorimplicit_inpto validate header fields and a representative row.
- Extend
- Acceptance:
- Missing or reordered path diagnostic columns fail a regression test.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp)$" --output-on-failurectest --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_lifecycleandsolver_implicitCSV checks.
- Extend
- Acceptance:
- All covered lifecycle rows have the documented schema and parse without ad hoc column handling.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failurectest --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_resetandnlc_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.
- Add focused checks for repeated
- Tests:
- Extend
nonlinear_lifecycleorsolver_implicit.
- Extend
- Acceptance:
- Repeated path append/reset/release cycles remain deterministic and do not corrupt existing diagnostics.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(nonlinear_lifecycle|solver_implicit)$" --output-on-failurectest --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.
- Run
- Acceptance:
- Restart coverage is easier to review and preserves backward-compatible optional diagnostics.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^restart$" --output-on-failurectest --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_omp4andperf_contact_pair_omp_consistency.
- Run
- Acceptance:
- OpenMP contact diagnostics are stable across the covered compact path.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(contact_omp1|contact_omp4|perf_contact_pair_omp_consistency)$" --output-on-failurectest --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
contactor a contact report test.
- Extend
- Acceptance:
- Contact state diagnostics do not require special-case parsing for unsupported or inactive paths.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^contact$" --output-on-failurectest --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_implicitorc_api.
- Extend
- Acceptance:
- Solver diagnostics distinguish fallback, configuration error and normal convergence in a repeatable way.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(linear_solver_cg|solver_implicit|c_api)$" --output-on-failurectest --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.
- Extend
- Acceptance:
- Invalid input and CLI boundaries fail deterministically with stable error messages/status.
- Verified:
cmake --build build-codex-gcc --parallelctest --test-dir build-codex-gcc -R "^(implicit_inp|cli_output_dir_boundary|vtk_output)$" --output-on-failurectest --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 --parallelctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failurectest --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-failurectest --test-dir build-codex-gcc -L v5_acceptance --output-on-failurectest --test-dir build-codex-gcc -R "^(smoke|c_api)$" --output-on-failuregit 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