Files
FemLite/todo.md
T
shenw 2b7962eb96
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.5.3
2026-07-01 18:39:18 +08:00

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

  1. NL-1: failure reason taxonomy.
  2. LS-1: linear solver nonlinear-diagnostic bridge.
  3. CT-1: contact state count standardization.
  4. CT-2: contact residual diagnostics.
  5. CT-3: mortar/friction tangent audit enhancement.
  6. CT-4: OpenMP contact path consistency enhancement.
  7. NL-2: nonlinear residual breakdown output.
  8. DOC-1: documentation and benchmark matrix synchronization.
  9. 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.md section 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_implicit coverage for at least three distinct failure reasons.
    • Add implicit_inp coverage that reason fields remain stable through INP-driven nonlinear failure.
  • 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-failure passed.

[x] TODO 0.5.3-2: Map linear solver failures into nonlinear failure reasons

  • Source:
    • docs/v5.3_development_plan.md sections 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_cg failure-state coverage.
    • Extend solver_implicit to verify linear failure becomes a nonlinear failure reason.
  • 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-failure passed.

[x] TODO 0.5.3-3: Standardize contact state count fields

  • Source:
    • docs/v5.3_development_plan.md section 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, separating and failed-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.
  • Tests:
    • Extend restart to check active/open and stick/slip state count preservation.
    • Extend a contact report/module test to validate state count totals.
  • 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-failure passed.

[x] TODO 0.5.3-4: Add contact gap and penetration residual diagnostics

  • Source:
    • docs/v5.3_development_plan.md section 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_report or adjacent contact tests for gap fields.
    • Update example_contact_two_blocks_compression_benchmark checker to consume at least max penetration and gap norm fields.
  • 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-failure passed.

[x] TODO 0.5.3-5: Add contact slip and friction residual diagnostics

  • Source:
    • docs/v5.3_development_plan.md section 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_benchmark checker 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-failure passed.

[x] TODO 0.5.3-6: Add multiplier and AL augmentation diagnostics

  • Source:
    • docs/v5.3_development_plan.md section 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_report coverage for new fields.
    • Extend restart or contact report coverage to verify committed multiplier diagnostics are stable after restart.
  • 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-failure passed.

[x] TODO 0.5.3-7: Enhance normal-contact tangent audit

  • Source:
    • docs/v5.3_development_plan.md section 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_tangent to verify normal-only tangent audit fields.
  • 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-failure passed.

[x] TODO 0.5.3-8: Enhance friction stick/slip tangent audit

  • Source:
    • docs/v5.3_development_plan.md section 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_tangent to cover both stick and slip audit branches.
  • 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-failure passed.

[x] TODO 0.5.3-9: Strengthen OpenMP contact path consistency

  • Source:
    • docs/v5.3_development_plan.md section 4.6, CT-4.
  • Implementation:
    • Extend perf_contact_pair or 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.
  • Tests:
    • Update perf_contact_pair_omp_consistency and tools/testing/check_perf_contact_pair_omp.py.
  • 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-failure passed.

[x] TODO 0.5.3-10: Add nonlinear residual breakdown storage

  • Source:
    • docs/v5.3_development_plan.md section 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_implicit to check residual breakdown values or presence in static and Newmark-Newton paths.
  • 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-failure passed.

[x] TODO 0.5.3-11: Write residual breakdown to CSV/report outputs

  • Source:
    • docs/v5.3_development_plan.md sections 4.2 and 6.
  • Implementation:
    • Add residual breakdown columns to continuation_path.csv or 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.
  • 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-failure passed; python -m py_compile examples\spherical_cap_with_central_point_load\check_spherical_cap_results.py passed.

[x] TODO 0.5.3-12: Add restart-after-increment audit for contact diagnostics

  • Source:
    • docs/v5.3_development_plan.md sections 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 restart module test for the new audit.
    • Add or update a compact INP/CLI restart scenario if module coverage is insufficient.
  • 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-failure passed.

[x] TODO 0.5.3-13: Update contact benchmark checkers for explainable diagnostics

  • Source:
    • docs/v5.3_development_plan.md sections 4.4, 4.6 and 6.
  • Implementation:
    • Update examples/contact_two_blocks_compression checker for gap, penetration, state count and multiplier diagnostics.
    • Update examples/contact_block_sliding checker 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.
  • 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-failure passed.

[x] TODO 0.5.3-14: Synchronize documentation and API descriptions

  • Source:
    • docs/v5.3_development_plan.md section 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 rg checks to ensure old wording does not claim 0.5.3 delivers full industrial AL/mortar consistent tangent.
  • 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 rg check 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.md sections 6 and 8.
  • Implementation:
    • Update docs/v5_benchmark_matrix.md with 0.5.3 tests and diagnostic evidence.
    • Update docs/v5_acceptance_report.md with 0.5.3 scope, commands and limitations.
    • Update docs/v5_development_plan.md status 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.
  • 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 --parallel passed; 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 --check passed 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