20 KiB
20 KiB
FemLite 0.5.3 TODO
Source plan: docs/v5.3_development_plan.md
Version goal:
FemLite 0.5.3 = 接触与非线性诊断加固版
Boundary:
- Do not add broad new feature families in 0.5.3.
- Do not claim complete industrial AL/mortar consistent tangent.
- Do not move deferred shell preload buckling, high-order solid
K_G, mixed-control Riks, cohesive contact mainline, nonzero harmonic cyclic, DEM subcycling or production roll forming into the 0.5.3 must-complete list. - Every new diagnostic field must be consumed by a test, checker or report audit.
Execution Order
- NL-1: failure reason taxonomy.
- LS-1: linear solver nonlinear-diagnostic bridge.
- CT-1: contact state count standardization.
- CT-2: contact residual diagnostics.
- CT-3: mortar/friction tangent audit enhancement.
- CT-4: OpenMP contact path consistency enhancement.
- NL-2: nonlinear residual breakdown output.
- DOC-1: documentation and benchmark matrix synchronization.
- REL-1: 0.5.3 build/regression/version close-out.
Detailed Execution Map
| TODO | Code targets | Output/API contract | Test/checker target | Not in scope |
|---|---|---|---|---|
| 0.5.3-1 | src/base/fem_control.f90, src/base/fem_api_diagnostics.f90, nonlinear solver failure markers |
Add stable NFAIL_* id/name while keeping existing CONV_FAIL_* status codes |
solver_implicit, implicit_inp |
Rewrite cutback/Newton algorithms |
| 0.5.3-2 | src/solver/fem_solver_implicit_support.f90, src/solver/fem_linear_solver_dispatch.f90 |
Map linear-solver failure diagnostics into nonlinear reason id/name | linear_solver_cg, solver_implicit |
Add new linear solver backends |
| 0.5.3-3 | src/boundary/fem_contact_history.f90, src/boundary/fem_contact_multiplier.f90, contact report writers |
Standard contact state counts: open/stick/slip/restick/separating/failed projection | restart, contact report module tests |
Full contact state-machine rewrite |
| 0.5.3-4 | Contact search/history diagnostics and contact CSV/report output | Add max penetration, mean gap, gap L2, failed projection and active-set flip fields | contact_mortar_report, compression checker |
Change contact enforcement method |
| 0.5.3-5 | Friction history diagnostics and sliding/contact report output | Add slip increment/residual and tangential residual fields | friction/contact module tests, sliding checker | Retune friction law |
| 0.5.3-6 | Multiplier and mortar AL diagnostics/report paths | Add multiplier residual and augmentation/update count fields | contact_multiplier_report, restart |
Industrial AL/mortar consistent tangent rewrite |
| 0.5.3-7 | Mortar tangent audit helpers/output | Split normal tangent finite-difference audit fields | contact_mortar_tangent |
Replace production normal-contact tangent |
| 0.5.3-8 | Friction tangent audit helpers/output | Split stick/slip tangent finite-difference audit fields | contact_mortar_tangent |
Replace production friction tangent |
| 0.5.3-9 | perf_contact_pair and tools/testing/check_perf_contact_pair_omp.py |
Compare deterministic force/tangent/cache/state/residual fields across threads | perf_contact_pair_omp_consistency |
Treat timing differences as failures |
| 0.5.3-10 | Nonlinear static/Newmark diagnostic storage | Store total/force/contact/constraint/arc/material residual breakdown | solver_implicit |
Add new nonlinear control family |
| 0.5.3-11 | Path CSV/contact summary writers and schema comments | Write residual breakdown columns without removing old columns | continuation/contact checkers | Break old CSV consumers |
| 0.5.3-12 | Restart writer/reader and restart contact audit test | Verify contact diagnostics before/after restart after an accepted increment | restart, compact INP restart if needed |
Redesign restart format |
| 0.5.3-13 | Contact example checkers and README field notes | Check explainable diagnostic fields in compression/sliding/shell contact examples | four contact benchmark CTest entries | Overfit exact nonlinear values |
| 0.5.3-14 | V5 docs, interface docs, manuals, example docs | Document new diagnostic boundary and deferred items | wording rg checks |
Claim full industrial AL/mortar tangent |
| 0.5.3-15 | V5 matrix/report/version files | Close 0.5.3 only after green targeted and V5 acceptance tests | build, targeted tests, V5 acceptance, git diff --check |
Release/version bump before tests pass |
Implementation Rules
- Work in the execution order above; do not mark a TODO done until its tests or checker target consumes the new field.
- Prefer additive fields and thin accessors over changing existing public signatures.
- If a task exposes multiple incompatible implementation routes, 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 rather than partially implementing both.
0.5.3 Task List
[x] TODO 0.5.3-1: Define nonlinear failure reason taxonomy
- Source:
docs/v5.3_development_plan.mdsection 4.1, NL-1.
- Implementation:
- Add stable reason ids and names for nonlinear/cutback failures.
- Cover at least these categories: linear solve failure, residual stagnation, correction norm too large, line-search failure, trust rejection, contact active-set oscillation, projection failure, excessive penetration, material return failure, Riks/arc constraint failure, constraint residual failure and minimum step exhaustion.
- Keep existing solver status codes compatible; add mapping rather than replacing public status values abruptly.
- Expose the last reason id/name through the existing nonlinear diagnostic path or a thin new accessor.
- Tests:
- Add
solver_implicitcoverage for at least three distinct failure reasons. - Add
implicit_inpcoverage that reason fields remain stable through INP-driven nonlinear failure.
- Add
- Acceptance:
- Failure summaries no longer report only a generic solver error when a known nonlinear/cutback cause is available.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp)$" --output-on-failurepassed.
[x] TODO 0.5.3-2: Map linear solver failures into nonlinear failure reasons
- Source:
docs/v5.3_development_plan.mdsections 4.7 and 5, LS-1 before CT tasks.
- Implementation:
- Extend linear-solver diagnostics with selected method, preconditioner, matrix class, initial/final/relative residual and failure class.
- Map linear solver nonconvergence, invalid matrix class and dense fallback failure into nonlinear failure reason ids.
- Preserve current CG/BiCGSTAB/GMRES/dense behavior; this task must not add a new solver backend.
- Add a selected-solver reason string for nonlinear contexts.
- Tests:
- Extend
linear_solver_cgfailure-state coverage. - Extend
solver_implicitto verify linear failure becomes a nonlinear failure reason.
- Extend
- Acceptance:
- A nonlinear solve that fails because the linear solve failed reports both linear residual diagnostics and the mapped nonlinear reason.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(linear_solver_cg|solver_implicit|implicit_inp)$" --output-on-failurepassed.
[x] TODO 0.5.3-3: Standardize contact state count fields
- Source:
docs/v5.3_development_plan.mdsection 4.3, CT-1.
- Implementation:
- Define stable contact state names or ids for the 0.5.3 subset:
open,closed-stick,closed-slip,closed-restick,separatingandfailed-projection. - Map existing contact history and active/released/open multiplier states onto the stable subset without rewriting the full contact solver.
- Add aggregate state counts to contact report/summary data.
- Ensure state counts are available after trial, commit and restart paths.
- Define stable contact state names or ids for the 0.5.3 subset:
- Tests:
- Extend
restartto check active/open and stick/slip state count preservation. - Extend a contact report/module test to validate state count totals.
- Extend
- Acceptance:
- Contact benchmark summaries expose stable state counts that survive restart round trips.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(restart|contact_multiplier_report)$" --output-on-failurepassed.
[x] TODO 0.5.3-4: Add contact gap and penetration residual diagnostics
- Source:
docs/v5.3_development_plan.mdsection 4.4, CT-2.
- Implementation:
- Add max penetration, mean gap and gap L2 norm to contact diagnostics.
- Track failed projection count where the current search/projection path can identify it.
- Add active-set flip count for multi-step contact paths where previous contact state is available.
- Write these fields to contact report/summary output.
- Tests:
- Extend
contact_mortar_reportor adjacent contact tests for gap fields. - Update
example_contact_two_blocks_compression_benchmarkchecker to consume at least max penetration and gap norm fields.
- Extend
- Acceptance:
- Compression contact failures can be distinguished as penetration/gap issues rather than opaque nonlinear failures.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(contact|example_contact_two_blocks_compression_benchmark)$" --output-on-failurepassed.
[x] TODO 0.5.3-5: Add contact slip and friction residual diagnostics
- Source:
docs/v5.3_development_plan.mdsection 4.4, CT-2.
- Implementation:
- Add slip increment norm and slip residual to contact/friction diagnostics.
- Add tangential/friction residual summary where friction history is active.
- Keep friction work and accumulated slip fields backward compatible.
- Write slip/friction diagnostic fields to sliding benchmark output or contact report output.
- Tests:
- Extend friction/contact module tests for slip residual fields.
- Update
example_contact_block_sliding_benchmarkchecker to consume at least one slip/friction diagnostic field.
- Acceptance:
- Sliding contact output can distinguish normal contact problems from tangential stick/slip residual problems.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(contact|example_contact_block_sliding_benchmark)$" --output-on-failurepassed.
[x] TODO 0.5.3-6: Add multiplier and AL augmentation diagnostics
- Source:
docs/v5.3_development_plan.mdsection 4.4, CT-2.
- Implementation:
- Add normal multiplier residual summary.
- Add AL augmentation count or equivalent update count where available.
- Preserve existing multiplier duplicate/invalid/max commit error audit fields.
- Include multiplier/AL fields in report summary output.
- Tests:
- Extend
contact_multiplier_reportcoverage for new fields. - Extend restart or contact report coverage to verify committed multiplier diagnostics are stable after restart.
- Extend
- Acceptance:
- Multiplier-related contact failures can be separated from geometry/gap and friction/slip failures.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(contact_multiplier_report|restart)$" --output-on-failurepassed.
[x] TODO 0.5.3-7: Enhance normal-contact tangent audit
- Source:
docs/v5.3_development_plan.mdsection 4.5, CT-3.
- Implementation:
- Split tangent audit output so normal-only tangent error is explicit.
- Keep rigid translation residual and row/column balance diagnostics.
- Add a relative finite-difference error summary for normal contact.
- Avoid replacing the production contact tangent with a broad new consistent tangent implementation in this task.
- Tests:
- Extend
contact_mortar_tangentto verify normal-only tangent audit fields.
- Extend
- Acceptance:
- Tangent audit output can identify normal-contact tangent error independently from friction tangent error.
- Evidence:
ctest --test-dir build-codex-gcc -R "^contact_mortar_tangent$" --output-on-failurepassed.
[x] TODO 0.5.3-8: Enhance friction stick/slip tangent audit
- Source:
docs/v5.3_development_plan.mdsection 4.5, CT-3.
- Implementation:
- Add separate stick tangent audit metrics.
- Add separate slip tangent audit metrics.
- Preserve energy probe and non-symmetry diagnostics.
- Report tangent error, rigid residual and energy residual as distinct quantities.
- Tests:
- Extend
contact_mortar_tangentto cover both stick and slip audit branches.
- Extend
- Acceptance:
- Friction tangent audit can say whether failure comes from stick branch, slip branch, rigid residual or energy probe.
- Evidence:
ctest --test-dir build-codex-gcc -R "^contact_mortar_tangent$" --output-on-failurepassed.
[x] TODO 0.5.3-9: Strengthen OpenMP contact path consistency
- Source:
docs/v5.3_development_plan.mdsection 4.6, CT-4.
- Implementation:
- Extend
perf_contact_pairor its checker to compare force path, tangent path, candidate cache path and multi-step active-set statistics. - Compare contact state counts and gap/slip diagnostics across thread counts.
- Prefer 1/2/4 thread coverage if practical; otherwise keep 1/4 coverage and add the new state/residual fields.
- Keep timing data non-blocking; compare deterministic/non-timing fields.
- Extend
- Tests:
- Update
perf_contact_pair_omp_consistencyandtools/testing/check_perf_contact_pair_omp.py.
- Update
- Acceptance:
- OpenMP contact checks verify state, force, active set, cache and residual diagnostics, not only basic force/tangent totals.
- Evidence:
ctest --test-dir build-codex-gcc -R "^perf_contact_pair_omp_consistency$" --output-on-failurepassed.
[x] TODO 0.5.3-10: Add nonlinear residual breakdown storage
- Source:
docs/v5.3_development_plan.mdsection 4.2, NL-2.
- Implementation:
- Add storage for total residual, force residual, contact residual, constraint residual, arc residual and material local failure count.
- Populate the fields in nonlinear static paths where data already exists.
- Populate the fields in nonlinear Newmark paths for the available subset.
- Preserve existing scalar residual fields for backward compatibility.
- Tests:
- Extend
solver_implicitto check residual breakdown values or presence in static and Newmark-Newton paths.
- Extend
- Acceptance:
- Nonlinear diagnostics can report at least total, contact and constraint residual categories without breaking existing residual queries.
- Evidence:
ctest --test-dir build-codex-gcc -R "^solver_implicit$" --output-on-failurepassed.
[x] TODO 0.5.3-11: Write residual breakdown to CSV/report outputs
- Source:
docs/v5.3_development_plan.mdsections 4.2 and 6.
- Implementation:
- Add residual breakdown columns to
continuation_path.csvor the appropriate nonlinear/contact summary output. - Ensure missing data is represented consistently for paths that do not have a category.
- Update output headers and schema comments in code/docs.
- Keep old output columns stable where existing checkers depend on them.
- Add residual breakdown columns to
- Tests:
- Update spherical-cap or continuation checker to verify residual breakdown columns exist.
- Update contact checker to verify contact residual columns exist.
- Acceptance:
- Checker failure occurs if required 0.5.3 residual columns are absent.
- Evidence:
ctest --test-dir build-codex-gcc -R "^solver_implicit$" --output-on-failurepassed;python -m py_compile examples\spherical_cap_with_central_point_load\check_spherical_cap_results.pypassed.
[x] TODO 0.5.3-12: Add restart-after-increment audit for contact diagnostics
- Source:
docs/v5.3_development_plan.mdsections 4.3 and 6.
- Implementation:
- Add a restart audit scenario that writes restart after an accepted contact increment and resumes from it.
- Compare contact state counts, friction history, multiplier diagnostics, gap/slip diagnostics and residual summaries before and after restart.
- Keep existing restart format compatibility checks intact.
- Tests:
- Extend
restartmodule test for the new audit. - Add or update a compact INP/CLI restart scenario if module coverage is insufficient.
- Extend
- Acceptance:
- Contact diagnostics are reproducible across restart, not only contact forces and displacement state.
- Evidence:
ctest --test-dir build-codex-gcc -R "^restart$" --output-on-failurepassed.
[x] TODO 0.5.3-13: Update contact benchmark checkers for explainable diagnostics
- Source:
docs/v5.3_development_plan.mdsections 4.4, 4.6 and 6.
- Implementation:
- Update
examples/contact_two_blocks_compressionchecker for gap, penetration, state count and multiplier diagnostics. - Update
examples/contact_block_slidingchecker for slip/friction diagnostics and state counts. - Update shell-shell and shell-solid checkers where shared contact summary fields are available.
- Keep numerical tolerances focused on existence, sign, nonnegativity, boundedness and consistency; avoid overfitting complex nonlinear values.
- Update
- Tests:
- Run the four contact benchmark CTest entries after checker updates.
- Acceptance:
- Contact benchmark failures point to a missing/invalid diagnostic field or a clear contact residual category.
- Evidence:
ctest --test-dir build-codex-gcc -R "^(example_contact_two_blocks_compression_benchmark|example_contact_block_sliding_benchmark|example_shell_shell_contact_benchmark|example_shell_solid_contact_benchmark)$" --output-on-failurepassed.
[x] TODO 0.5.3-14: Synchronize documentation and API descriptions
- Source:
docs/v5.3_development_plan.mdsection 4.8, DOC-1.
- Implementation:
- Update mathematical/algorithm documentation for failure reasons, residual breakdown and contact state/residual diagnostics.
- Update interface documentation for any new API/query/output fields.
- Update test plan with new 0.5.3 regression commands and acceptance criteria.
- Update user/developer manuals with the 0.5.3 diagnostic boundary.
- Update contact example README files with new output fields.
- Tests:
- Run
rgchecks to ensure old wording does not claim 0.5.3 delivers full industrial AL/mortar consistent tangent.
- Run
- Acceptance:
- Documentation states that 0.5.3 improves explainability and diagnostics while deferring complete AL/mortar tangent rewrite.
- Evidence: documentation addenda added to design, algorithm, interface,
test plan, user/developer manuals and four contact example READMEs; wording
rgcheck found only explicit non-delivery boundary statements.
[x] TODO 0.5.3-15: Update V5 matrix, acceptance report and version close-out
- Source:
docs/v5.3_development_plan.mdsections 6 and 8.
- Implementation:
- Update
docs/v5_benchmark_matrix.mdwith 0.5.3 tests and diagnostic evidence. - Update
docs/v5_acceptance_report.mdwith 0.5.3 scope, commands and limitations. - Update
docs/v5_development_plan.mdstatus lines if 0.5.3 changes V5.3 contact status or evidence. - Raise project version only when 0.5.3 implementation is ready to close.
- Update
- Tests:
- Run the planned 0.5.3 targeted regression command.
- Run
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure. - Run
git diff --check.
- Acceptance:
- 0.5.3 closes with green targeted tests, green V5 acceptance subset and documented deferred boundaries.
- Evidence:
cmake --build build-codex-gcc --parallelpassed; 0.5.3 targeted nonlinear/contact diagnostics passed 8/8; contact benchmark diagnostic checker subset passed 4/4; V5 acceptance passed 39/39;git diff --checkpassed with line-ending warnings only.
Suggested 0.5.3 Regression Commands
cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|linear_solver_cg|restart|contact_mortar_report|contact_mortar_tangent|contact_multiplier_report|perf_contact_pair_omp_consistency)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^(example_contact_two_blocks_compression_benchmark|example_contact_block_sliding_benchmark|example_shell_shell_contact_benchmark|example_shell_solid_contact_benchmark)$" --output-on-failure
ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure