# FemLite V5 Remaining TODO Status date: 2026-06-26 This file is the executable TODO list for the current 0.5.x development cycle. The phase status table is maintained only in `docs/v5_development_plan.md`. Rules for closing an item: - Completed task headings use `[x]`; open task headings use `[ ]`. - Code must be implemented in production modules, not benchmark-only helpers in `src`. - Tests must be automated through CTest or a documented extended test command. - Examples must live under `examples/`, one folder per case, with README, input, double-click run script and a check script when the case is used for acceptance. - Documentation must describe the algorithm, interface, user behavior and developer maintenance path. - Large generated result files must not be committed. ## V5.2 Dependency-Free Sparse Solver Hardening Boundary for this module: - Do not add third-party solver libraries. - Do not introduce an external solver process as a required or accepted production backend. - Do not expose third-party or external solver method/backend interfaces through the Fortran API, C ABI, CMake options or helper tools. - Legacy external solver numeric values must be rejected as invalid configuration and must leave the active internal solver settings unchanged. ### [x] DONE V5.2-1: Harden internal sparse solver workflows - Implementation: - Keep CG, BiCGSTAB and GMRES as the production solver family. - Reject legacy external solver method/backend ids at the configuration boundary with no fallback solve and no state mutation. - Record method, preconditioner, iteration count, residual, matrix class and failure status for every static and implicit solve. - Reuse the existing CSR diagnostics to classify SPD, structurally symmetric and nonsymmetric systems before dispatch. - Tests: - Add or extend CTest coverage for SPD CG, nonsymmetric BiCGSTAB and nonsymmetric GMRES matrices. - Add structural workflow checks for linear static, implicit Newmark and one nonlinear/contact correction path using internal solvers. - Add a C ABI check that the legacy external solver method value is rejected and does not change solver settings. - Acceptance: - Default builds have no third-party solver dependency. - No external solver constants, C ABI prototypes, CMake targets or helper tools remain in the module. - Static, implicit and nonlinear/contact paths solve through internal dispatch and report diagnostics. - Legacy external solver selection never silently falls back to an internal solve. - Completion evidence: - `linear_solver_solve` records CSR matrix class, initial residual, final residual, relative residual, method, preconditioner, iteration and status. - `linear_solver_cg`, `solver_implicit`, `implicit_inp` and `c_api` cover the internal diagnostic path and legacy external method rejection. ### [x] DONE V5.2-2: Document no-external-solver policy - Implementation: - Update user, algorithm and developer documentation to state that the core module is dependency-free with respect to sparse solvers. - Document the supported internal solver methods, preconditioners and diagnostics. - Document that external solver interfaces have been removed and legacy external method values are invalid. - Tests: - Keep default CTest working without any optional solver package. - Add source/documentation checks when practical to prevent reintroducing third-party solver build options. - Acceptance: - V5 planning and release documentation no longer list external solver enablement or adapter interfaces as current-version acceptance items. - Completion evidence: - User, algorithm, interface, test and developer documentation now describe the no-external-solver policy and the internal solver diagnostic fields. ## V5.3 Mortar / Augmented Lagrangian Contact ### [x] DONE V5.3-1: Promote two-block contact to nonmatching mortar benchmark - Implementation: - `examples/contact_two_blocks_compression` uses a nonmatching 4-facet lower master face against a 1-facet upper slave face. - The checker derives pressure profile, max gap, weighted gap, multiplier residual and augmented multiplier metrics from contact CSV output. - `pressure_profile.csv` is written in the result directory for benchmark inspection. - Tests: - `check_contact_results.py` checks active contact, master-facet coverage, pressure range, weighted penetration, multiplier residual, augmented multiplier growth and VTK output. - CTest `example_contact_two_blocks_compression_benchmark` runs the example and calls the check script through `tools/testing/run_example_smoke.py`. - Acceptance: - The nonmatching pressure benchmark passes in the default Release CTest path. - Example README documents the nonmatching mesh, reference metrics and limitations. - Completion evidence: - `ctest --test-dir build-win-gcc-16 -C Release -R example_contact_two_blocks_compression_benchmark --output-on-failure` passed on 2026-06-26. ### [x] DONE V5.3-2: Promote sliding contact to large-sliding mortar-friction benchmark - Implementation: - `examples/contact_block_sliding` now uses a nonmatching 4-facet lower master surface and a 1-facet upper slave surface. - The upper block is force-driven over the master surface while normal augmented multiplier history and tangential stick/slip/friction-work output remain coupled through the production contact path. - Restart continuity for contact friction and multiplier state is covered by the module-level `restart` CTest; the example benchmark focuses on the large-sliding friction trajectory. - Tests: - `check_contact_results.py` writes `sliding_profile.csv` and checks multiple master facets, multiple active candidates, accumulated slip, stick/slip counters, tangential force, positive friction work and VTK output. - CTest `example_contact_block_sliding_benchmark` runs the full example and checker through `tools/testing/run_example_smoke.py`. - Existing `contact_omp1`, `contact_omp4` and `perf_contact_pair_omp_consistency` continue to cover OpenMP contact consistency at module/performance-smoke level. - Acceptance: - Stick/slip transitions are reported. - Frictional work is nonnegative within tolerance. - Restart continues multiplier and friction history without jumps in the module restart regression. - Completion evidence: - `ctest --test-dir build-win-gcc-16 -C Release -R example_contact_block_sliding_benchmark --output-on-failure` passed on 2026-06-26. ### [x] DONE V5.3-3: Add shell/solid contact benchmark coverage - Implementation: - Added `examples/shell_shell_contact` with an S4-to-S4 contact benchmark. - Added `examples/shell_solid_contact` with an S4 slave surface contacting a C3D8 solid master face. - Both examples use the existing contact pair, mortar force/output and augmented multiplier paths; no special-case production path was added. - Tests: - Each example has a local checker that writes a compact profile CSV and checks active contact, force norm, gap residual, augmented multiplier, master search and VTK output. - CTest entries `example_shell_shell_contact_benchmark` and `example_shell_solid_contact_benchmark` run the examples and checkers. - Acceptance: - At least one shell-solid and one shell-shell contact case pass automated checks. - Completion evidence: - `ctest --test-dir build-win-gcc-16 -C Release -R "example_shell_(shell|solid)_contact_benchmark" --output-on-failure` passed on 2026-06-26. ## V5.4 Mohr-Coulomb And Strength Reduction ### [x] DONE V5.4-1: Finish material-point acceptance tests - Implementation: - Cover triaxial compression, triaxial extension, pure shear and tensile cutoff. - Record active branch or return-map mode for each test. - Tests: - Add explicit tolerance checks for stress, plastic multiplier and branch id. - Acceptance: - All material-point tests pass without substep explosion. - Tangent or algorithmic stiffness limitations are documented. - Completion evidence: - `test_material_mohr_coulomb` now covers triaxial compression, triaxial extension, pure shear, tensile cutoff, mixed return, branch id, post-return yield tolerance and plastic increment checks. - `test_material_mc_driver` and `test_material_mc_envelope` cover path driver diagnostics, branch counts, limited status, tangent diagnostics, envelope margins, safety ratios and reduced material parameters. - Algorithm, detailed design, interface, test, user and developer documentation now describe the Mohr-Coulomb equations, input format, state variables, driver diagnostics and engineering tangent limitations. - Targeted CTest command: `ctest --test-dir build-win-gcc-16 -C Release -R "material_mohr_coulomb|material_mc_driver|material_mc_envelope" --output-on-failure`. ### [x] DONE V5.4-2: Replace strengthReduction placeholder with MC benchmark - Implementation: - Update `examples/strengthReduction` to use real Mohr-Coulomb material input. - Add strength reduction search controls and output safety-factor history. - Output plastic zone and displacement control probe. - Tests: - Add check script for final safety factor range, bracket convergence and plastic-zone extent. - Acceptance: - Safety factor lies inside documented tolerance. - Check script fails if the solve only runs linear elastic behavior. - Completion evidence: - `strength_reduction_slope_static.inp` now uses `MC_SOIL` with `*MOHR COULOMB` friction, cohesion, dilation, tensile cutoff, residual parameters and reduction factor fields. - `tools/benchmarks/strength_reduction_benchmark.f90` links the production core and calls the Mohr-Coulomb yield path plus strength-reduction driver/report modules to generate safety-factor history, summary, plastic-zone and displacement-probe files. - `check_strength_reduction_results.py` rejects the old elastic placeholder and checks converged safety factor, real stable/unstable bracket, plastic zone activation, displacement probe signs, VTK and node output. - CTest `example_strength_reduction_benchmark` passed on 2026-06-26 with `FS=1.21125`, 8 trials, 3 stable trials, 5 unstable trials and 2 active plastic probes. ## V5.5 Linear Buckling And Cyclic Symmetry ### [x] DONE V5.5-1: Add analytic buckling verification - Implementation: - Add a small column or beam benchmark with known Euler critical load. - Assemble prestress/geometric stiffness through the production path. - Tests: - Check first eigenvalue relative error. - Acceptance: - Relative error and mode normalization are documented. - Completion evidence: - Added `examples/euler_column_buckling` with README, benchmark input, double-click `run_case.bat` and `check_buckling_results.py`. - Added `tools/benchmarks/euler_column_buckling_benchmark.f90` outside `src`; it assembles beam bending stiffness, uses production `geom_beam2d_column_stiffness`, calls `buckling_dense_solve`, compares against `buckling_euler_column_load` and writes summary/mode CSV files. - Hardened `buckling_dense_solve` so the internal dense Jacobi eigensolver iteration budget scales with problem size. - CTest `example_euler_column_buckling_benchmark` passed on 2026-06-26 with relative error `3.27660856E-05`, residual `1.50014805E-11` and `phi^T K_G phi = 1.0`. ### [x] DONE V5.5-2: Upgrade corrugated shell benchmark - Implementation: - Replace static-only smoke with buckling eigenvalue analysis. - Add cyclic sector model and full-model comparison when feasible. - Write mode shape output through modal output path. - Tests: - Check critical load range and cyclic/full consistency. - Acceptance: - README documents eigenvalue, mode count, cyclic wave number and tolerance. - Completion evidence: - Added `tools/benchmarks/corrugated_shell_buckling_benchmark.f90` outside `src`; it builds a sixteen-sector reduced corrugated-shell periodic buckling model, calls production `buckling_dense_solve`, validates the selected wave through `fem_cyclic_symmetry` and writes modal output through `modal_write_csv`. - Added `corrugated_shell_buckling_benchmark.inp`, `check_buckling_results.py`, updated `run_case.bat` and rewrote the example README with reference metrics and tolerances. - Replaced CTest `example_buckling_corrugated_shell_smoke` with `example_buckling_corrugated_shell_benchmark`. - CTest `example_buckling_corrugated_shell_benchmark` passed on 2026-06-26 with selected wave 4 load `453.031407`, critical wave 8 load `393.369677`, cyclic/full relative error `1.25473461E-16` and modal residual `1.31855319E-12`. - `source_size` CTest passed after the new benchmark tool was added. ## V5.6 High-Fidelity Roll Forming ### [x] DONE V5.6-1: Add real roller kinematics to contact workflow - Implementation: - Ensure rigid roller rotation contributes to relative tangential velocity. - Couple roller translation, down-feed and angular velocity in input/control. - Output roller force, torque, contact pressure band and friction work. - Tests: - Unit test roller kinematics and relative velocity sign. - Example check for nonzero rolling traction and stable energy trend. - Acceptance: - Removing angular velocity changes tangential traction in the check case. - Completion evidence: - Added production `roller_regularized_traction` to `fem_rigid_roller`; it uses the same roller tangential velocity path and a smooth `tanh(slip/reference_speed)` friction factor so spin changes traction magnitude, not only slip speed. - Extended `test_rigid_roller` with a spin/no-spin comparison that verifies angular speed changes slip and regularized traction. - Added `tools/benchmarks/roll_forming_kinematics_benchmark.f90` outside `src`; it drives production roller pose, schedule, contact kinematics, regularized traction and roll metrics to output roller history and summary. - Added `examples/roll_forming/roll_forming_kinematics_benchmark.inp`, `check_roller_kinematics.py` and updated `run_case.bat`/README. - CTest `example_roll_forming_kinematics_benchmark` passed on 2026-06-26 with mean slip `0.4` with spin vs `0.2` without spin, mean traction `289.208274` with spin vs `228.478247` without spin, max traction delta `60.7300272` and positive roller torque `14.4604137`. ### [x] DONE V5.6-2: Add plastic forming and springback benchmark - Implementation: - Upgrade `examples/roll_forming` to include plastic workpiece and unloading. - Output residual displacement, plastic zone and springback metric. - Tests: - Check forming force range, positive plastic work and springback sign/range. - Acceptance: - Example is no longer only an elastic contact surrogate. - Completion evidence: - Added production roll metrics helpers for residual displacement and springback ratio, with `test_rigid_roller` coverage. - Added `tools/benchmarks/roll_forming_springback_benchmark.f90` outside `src`; it drives production roller kinematics, regularized traction, roll metrics and J2 small-strain material updates on a compact multilayer workpiece section, then solves unloading release curvature by bending moment balance. - Added `examples/roll_forming/roll_forming_springback_benchmark.inp` and `check_springback_results.py`; `run_case.bat` now runs the springback benchmark after the friction smoke and kinematics benchmark. - Targeted checker passed on 2026-06-26 with springback ratio `0.473154068`, residual displacement `0.0316107559`, plastic work `1.11591736e-05`, 56/81 active plastic points and residual moment absolute value `8.92778801e-11`. ## V5.7 Cohesive Adhesion / Decohesion ### [x] DONE V5.7-1: Add cohesive single-point acceptance tests - Implementation: - Cover loading, unloading, mixed-mode damage and complete decohesion. - Track damage, maximum opening, energy and status. - Tests: - Verify nonnegative dissipated energy and irreversible damage. - Acceptance: - Restarted state preserves damage and maximum opening. - Completion evidence: - `test_cohesive_contact` now drives one cohesive integration point through bonded loading, mixed-mode damage, unloading, reload and complete decohesion. - The path records damage, maximum opening, effective separation, dissipated energy and status through `fem_cohesive_state` and `fem_cohesive_metrics`. - The test verifies nonnegative energy increments, irreversible damage, failed-state zero traction, failed-area metrics and restart preservation of damage, maximum opening, maximum effective separation, energy and status. - Targeted command passed on 2026-06-26: `ctest --test-dir build-win-gcc-16 -C Release -R "cohesive_contact|source_size" --output-on-failure`. ### [x] DONE V5.7-2: Upgrade ball adhesion/decohesion example - Implementation: - Use cohesive law/state in `examples/ball_adhesion_decohesion`. - Output force-displacement curve, cohesive energy and decohesion area. - Tests: - Add check script for hysteresis, peak pull-off force and dissipated energy. - Acceptance: - Example fails if cohesive damage is not activated. - Completion evidence: - Added `tools/benchmarks/ball_adhesion_cohesive_benchmark.f90` outside `src`; it discretizes the adhesive ball/membrane patch into concentric rings and drives compression, unloading and pull-off through production `fem_cohesive_law`, `fem_cohesive_state` and `fem_cohesive_metrics`. - Added `ball_adhesion_cohesive_benchmark.inp` and `check_cohesive_results.py` under `examples/ball_adhesion_decohesion`; `run_case.bat` now runs the original contact smoke and the cohesive benchmark. - The benchmark writes `adhesion_history.csv`, `adhesion_summary.csv` and `decohesion_profile.csv`, covering force-displacement hysteresis, cohesive energy, peak pull-off force, damage and decohesion area. - CTest `example_ball_adhesion_cohesive_benchmark` passed on 2026-06-26 with peak pull-off force `119.246023`, min compression force `-362.051100`, dissipated energy `0.451891017`, hysteresis area `0.898170568` and final failed fraction `1.0`. ## V5.8 Particle / Flexible Container Coupling ### [x] DONE V5.8-1: Complete particle acceptance primitives - Implementation: - Cover particle free fall, wall collision, particle-particle pile and particle-facet coupling with production modules. - Output mass, momentum, kinetic energy, dissipated energy and max overlap. - Tests: - Add checks for mass conservation, bounded overlap and nonnegative dissipation. - Acceptance: - Diagnostics are available through Fortran and documented output paths. - Completion evidence: - Added `pstep_diag_values` to expose `particle_step_diag` mass, momentum, kinetic energy, step dissipated energy and max-overlap values through the Fortran module API. - Added CTest `particle_acceptance`, covering free fall, damped wall rebound, three-particle pile contact and particle-facet load transfer with the production particle state/contact/step/facet modules. - The test checks mass conservation, bounded overlap, nonnegative dissipation, kinetic/momentum diagnostics and particle-facet nodal force balance. - `ctest --test-dir build-win-gcc-16 -C Release -R "particle_acceptance|source_size" --output-on-failure` passed on 2026-06-26. ### [x] DONE V5.8-2: Upgrade dynamic grain container example - Implementation: - Replace pressure surrogate with real particles and flexible container two-way force mapping. - Record particle count, contact count, container displacement and energy. - Tests: - Add example check script for particle statistics and container response. - Acceptance: - Example fails if particle forces are not mapped back to the FEM model. - Completion evidence: - Added `tools/benchmarks/dynamic_grain_container_benchmark.f90` outside `src`; it loads a pressure-free flexible S4 container, applies real particle-facet contact through `particle_fem_apply_all`, maps nodal loads through `fsph`, advances the FEM response and preserves particle reaction forces for particle integration. - Added `dynamic_grain_container_benchmark.inp`, `flexible_container_grain_benchmark.inp` and `check_grain_container_results.py` under `examples/Dynamic_Grain_Packing_of_a_Flexible_Container`; `run_case.bat` now runs the old smoke and the V5.8 benchmark checker. - The checker rejects pressure surrogate input and verifies particle count, contact count, mapped nodal force, downward container response, mass conservation, bounded overlap and nonnegative energy. - CTest `example_dynamic_grain_container_benchmark` passed on 2026-06-26 with 4 particles, 4 facet contacts, `mapped_steps=40`, max mapped vertical load `3.68E+01`, minimum center displacement `-7.29240354E-06` and max overlap `3.00615680E-03`. - Full Release command `ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` passed on 2026-06-26 with 106/106 tests. ## V5.9 Benchmark, Performance And Documentation ### [x] DONE V5.9-1: Build V5 benchmark matrix - Implementation: - Add a table mapping every V5 completed capability to an example directory, test name, reference metric and tolerance. - Keep smoke and benchmark tiers separate. - Tests: - Default CTest remains fast. - Extended benchmark command runs the V5 acceptance checks. - Acceptance: - No completed V5 capability relies only on a smoke test. - Completion evidence: - Added `docs/v5_benchmark_matrix.md` with V5.2-V5.8 capability-to-test mapping, example directories, output files, reference metrics and acceptance tolerances. - Added CTest label `v5_acceptance` to current V5 acceptance tests and benchmark examples while preserving existing default CTest behavior. - Documented the extended command `ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure`. - The extended command passed on 2026-06-26 with 35/35 tests. ### [x] DONE V5.9-2: Refresh documentation after each capability closes - Implementation: - Update requirements, architecture, detailed design, algorithms, interface, test plan, user manual and developer manual only with factual implementation details. - Keep status markers only in `docs/v5_development_plan.md`. - Acceptance: - Status-table wording remains confined to `docs/v5_development_plan.md`. - Completion evidence: - Updated README, `docs/01_requirements_specification.md`, `docs/02_software_architecture_design.md`, `docs/03_detailed_design.md`, `docs/04_mathematical_model_and_algorithms.md`, `docs/05_interface_control_document.md`, `docs/06_test_and_verification_plan.md`, `docs/07_user_manual.md`, `docs/08_developer_manual.md`, `docs/v5_development_plan.md` and `docs/v5_benchmark_matrix.md` for V5.8 and V5.9-1 changes. - Core docs describe the implemented particle algorithm, staggered particle-container coupling, benchmark CLI, output files and verification commands without adding phase status markers outside `docs/v5_development_plan.md`. - Documentation checks verified no phase-status markers in the core docs listed above. ## V5.10 Acceptance And Release ### [x] DONE V5.10-1: Create V5 acceptance report - Implementation: - Add `docs/v5_acceptance_report.md`. - Summarize completed, incomplete and postponed items from `docs/v5_development_plan.md`. - Include exact test commands, environment and results. - Acceptance: - Report identifies every remaining deferred item, reason, risk and effect on users. - Completion evidence: - Added `docs/v5_acceptance_report.md` with the current V5 acceptance scope, Windows Release environment, exact CMake/CTest commands, 106/106 default CTest record and 35/35 `v5_acceptance` record. - The report summarizes completed V5.2-V5.8 capabilities, remaining engineering gaps, and postponed or out-of-current-module items with reason, risk and user effect. - README now links to the V5 acceptance report. ### [x] DONE V5.10-2: Final release hygiene - Implementation: - Ensure worktree is clean except intended release files. - Clean generated root result files. - Run default CTest and any enabled extended benchmark tests. - Acceptance: - Release branch or main merge has reproducible test output. - README and version metadata match the release state. - Completion evidence: - Root-level generated result files (`history.csv`, `nodes_*.csv`, `elements_*.csv`, `reactions_*.csv`, `contact_*.csv`, `result_*.vtk`, `femlite.log`) were removed after the final full CTest run. - `ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure` passed on 2026-06-26 with 35/35 tests. - `ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` passed on 2026-06-26 with 106/106 tests. - README and version metadata are aligned on `0.5.0`. - V5 release changes are prepared as the intended release-file set on `main`; committing these changes makes the worktree clean for the current release checkpoint.