25 KiB
25 KiB
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_solverecords CSR matrix class, initial residual, final residual, relative residual, method, preconditioner, iteration and status.linear_solver_cg,solver_implicit,implicit_inpandc_apicover 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_compressionuses 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.csvis written in the result directory for benchmark inspection.
- Tests:
check_contact_results.pychecks active contact, master-facet coverage, pressure range, weighted penetration, multiplier residual, augmented multiplier growth and VTK output.- CTest
example_contact_two_blocks_compression_benchmarkruns the example and calls the check script throughtools/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-failurepassed on 2026-06-26.
[x] DONE V5.3-2: Promote sliding contact to large-sliding mortar-friction benchmark
- Implementation:
examples/contact_block_slidingnow 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
restartCTest; the example benchmark focuses on the large-sliding friction trajectory.
- Tests:
check_contact_results.pywritessliding_profile.csvand 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_benchmarkruns the full example and checker throughtools/testing/run_example_smoke.py. - Existing
contact_omp1,contact_omp4andperf_contact_pair_omp_consistencycontinue 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-failurepassed on 2026-06-26.
[x] DONE V5.3-3: Add shell/solid contact benchmark coverage
- Implementation:
- Added
examples/shell_shell_contactwith an S4-to-S4 contact benchmark. - Added
examples/shell_solid_contactwith 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.
- 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_benchmarkandexample_shell_solid_contact_benchmarkrun 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-failurepassed 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_coulombnow covers triaxial compression, triaxial extension, pure shear, tensile cutoff, mixed return, branch id, post-return yield tolerance and plastic increment checks.test_material_mc_driverandtest_material_mc_envelopecover 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/strengthReductionto use real Mohr-Coulomb material input. - Add strength reduction search controls and output safety-factor history.
- Output plastic zone and displacement control probe.
- Update
- 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.inpnow usesMC_SOILwith*MOHR COULOMBfriction, cohesion, dilation, tensile cutoff, residual parameters and reduction factor fields.tools/benchmarks/strength_reduction_benchmark.f90links 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.pyrejects 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_benchmarkpassed on 2026-06-26 withFS=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_bucklingwith README, benchmark input, double-clickrun_case.batandcheck_buckling_results.py. - Added
tools/benchmarks/euler_column_buckling_benchmark.f90outsidesrc; it assembles beam bending stiffness, uses productiongeom_beam2d_column_stiffness, callsbuckling_dense_solve, compares againstbuckling_euler_column_loadand writes summary/mode CSV files. - Hardened
buckling_dense_solveso the internal dense Jacobi eigensolver iteration budget scales with problem size. - CTest
example_euler_column_buckling_benchmarkpassed on 2026-06-26 with relative error3.27660856E-05, residual1.50014805E-11andphi^T K_G phi = 1.0.
- Added
[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.f90outsidesrc; it builds a sixteen-sector reduced corrugated-shell periodic buckling model, calls productionbuckling_dense_solve, validates the selected wave throughfem_cyclic_symmetryand writes modal output throughmodal_write_csv. - Added
corrugated_shell_buckling_benchmark.inp,check_buckling_results.py, updatedrun_case.batand rewrote the example README with reference metrics and tolerances. - Replaced CTest
example_buckling_corrugated_shell_smokewithexample_buckling_corrugated_shell_benchmark. - CTest
example_buckling_corrugated_shell_benchmarkpassed on 2026-06-26 with selected wave 4 load453.031407, critical wave 8 load393.369677, cyclic/full relative error1.25473461E-16and modal residual1.31855319E-12. source_sizeCTest passed after the new benchmark tool was added.
- 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_tractiontofem_rigid_roller; it uses the same roller tangential velocity path and a smoothtanh(slip/reference_speed)friction factor so spin changes traction magnitude, not only slip speed. - Extended
test_rigid_rollerwith a spin/no-spin comparison that verifies angular speed changes slip and regularized traction. - Added
tools/benchmarks/roll_forming_kinematics_benchmark.f90outsidesrc; 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.pyand updatedrun_case.bat/README. - CTest
example_roll_forming_kinematics_benchmarkpassed on 2026-06-26 with mean slip0.4with spin vs0.2without spin, mean traction289.208274with spin vs228.478247without spin, max traction delta60.7300272and positive roller torque14.4604137.
- Added production
[x] DONE V5.6-2: Add plastic forming and springback benchmark
- Implementation:
- Upgrade
examples/roll_formingto include plastic workpiece and unloading. - Output residual displacement, plastic zone and springback metric.
- Upgrade
- 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_rollercoverage. - Added
tools/benchmarks/roll_forming_springback_benchmark.f90outsidesrc; 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.inpandcheck_springback_results.py;run_case.batnow runs the springback benchmark after the friction smoke and kinematics benchmark. - Targeted checker passed on 2026-06-26 with springback ratio
0.473154068, residual displacement0.0316107559, plastic work1.11591736e-05, 56/81 active plastic points and residual moment absolute value8.92778801e-11.
- Added production roll metrics helpers for residual displacement and
springback ratio, with
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_contactnow 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_stateandfem_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.
- Use cohesive law/state in
- 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.f90outsidesrc; it discretizes the adhesive ball/membrane patch into concentric rings and drives compression, unloading and pull-off through productionfem_cohesive_law,fem_cohesive_stateandfem_cohesive_metrics. - Added
ball_adhesion_cohesive_benchmark.inpandcheck_cohesive_results.pyunderexamples/ball_adhesion_decohesion;run_case.batnow runs the original contact smoke and the cohesive benchmark. - The benchmark writes
adhesion_history.csv,adhesion_summary.csvanddecohesion_profile.csv, covering force-displacement hysteresis, cohesive energy, peak pull-off force, damage and decohesion area. - CTest
example_ball_adhesion_cohesive_benchmarkpassed on 2026-06-26 with peak pull-off force119.246023, min compression force-362.051100, dissipated energy0.451891017, hysteresis area0.898170568and final failed fraction1.0.
- Added
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_valuesto exposeparticle_step_diagmass, 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-failurepassed on 2026-06-26.
- Added
[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.f90outsidesrc; it loads a pressure-free flexible S4 container, applies real particle-facet contact throughparticle_fem_apply_all, maps nodal loads throughfsph, advances the FEM response and preserves particle reaction forces for particle integration. - Added
dynamic_grain_container_benchmark.inp,flexible_container_grain_benchmark.inpandcheck_grain_container_results.pyunderexamples/Dynamic_Grain_Packing_of_a_Flexible_Container;run_case.batnow 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_benchmarkpassed on 2026-06-26 with 4 particles, 4 facet contacts,mapped_steps=40, max mapped vertical load3.68E+01, minimum center displacement-7.29240354E-06and max overlap3.00615680E-03. - Full Release command
ctest --test-dir build-win-gcc-16 -C Release --output-on-failurepassed on 2026-06-26 with 106/106 tests.
- Added
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.mdwith V5.2-V5.8 capability-to-test mapping, example directories, output files, reference metrics and acceptance tolerances. - Added CTest label
v5_acceptanceto 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.
- Added
[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.
- Status-table wording remains confined to
- 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.mdanddocs/v5_benchmark_matrix.mdfor 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.
- Updated README,
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.
- Add
- Acceptance:
- Report identifies every remaining deferred item, reason, risk and effect on users.
- Completion evidence:
- Added
docs/v5_acceptance_report.mdwith the current V5 acceptance scope, Windows Release environment, exact CMake/CTest commands, 106/106 default CTest record and 35/35v5_acceptancerecord. - 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.
- Added
[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-failurepassed on 2026-06-26 with 35/35 tests.ctest --test-dir build-win-gcc-16 -C Release --output-on-failurepassed 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.
- Root-level generated result files (