Files
FemLite/todo.md
T
2026-06-28 11:34:52 +08:00

82 KiB

FemLite V5 Remaining TODO

Status date: 2026-06-27

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, GMRES and the internal dense pivoting fallback 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, nonsymmetric GMRES and dense pivoting 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.
    • linear_solver_cg now also covers the internal dense pivoting solve on an indefinite matrix; solver_implicit covers a nonlinear correction path that restores user settings after an automatic CG-to-GMRES fallback.

[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 production src/solver/fem_buckling_column.f90; it reads the Euler *BUCKLING COLUMN block, assembles beam bending stiffness through geom_beam2d_column_stiffness, calls buckling_dense_solve, compares against buckling_euler_column_load and writes summary/mode CSV files.
    • Kept tools/benchmarks/euler_column_buckling_benchmark.f90 outside src as a thin wrapper around buckling_column_run_file; the old duplicate helper-side assembly/solve algorithm has been deleted.
    • Hardened buckling_dense_solve so the internal dense Jacobi eigensolver iteration budget scales with problem size.
    • examples/euler_column_buckling/run_case.bat and check_buckling_results.py now run the main femlite --buckling workflow.
    • CTest example_euler_column_buckling_benchmark passed on 2026-06-27 with relative error 3.27661E-05, residual 1.50015E-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.

V5.11 Finite-Membrane-Strain Shell And Spherical Cap Postbuckling

Boundary for this module:

  • A complete case must reproduce the geometric nonlinear postbuckling path from models.sme.spherical_cap_with_central_point_load.pdf; do not mark it complete while it only runs a linear, small-strain, monotone, or corotational diagnostic sample.
  • The production route is Abaqus-style finite-membrane-strain S4: finite rotation director update, finite membrane strain, Koiter-Sanders type curvature increment, MITC/ANS assumed strain, and analytic consistent tangent.
  • The existing S4 corotational route is temporary technical debt. It may explain current failures, but it is not a stable interface and not acceptance evidence. Once finite-strain S4 takes over, delete its production dispatch, input aliases, tests, documentation entry points, and any unused helper code. Do not leave fallback interfaces.
  • Reusable foundations are limited to fem_shell_section, shell layer/resultant state, shell pressure follower tangent, internal nonsymmetric solver support, and continuation path output.

Current facts:

  • examples/spherical_cap_with_central_point_load checks reference geometry, material scale, Shell-16 small-strain samples, and an optional S4 nonlinear diagnostic deck.
  • The optional nonlinear diagnostic can reach final displacement in some runs, but the reaction path remains monotone and therefore does not match the PDF postbuckling signature.
  • continuation_path.csv already records accepted displacement/reaction rows, and the checker can reject monotone nonlinear curves.
  • SHELL_GEOMETRIC=YES, GEOMETRIC_SHELL, COROTATIONAL_SHELL, and S4_COROTATIONAL are migration-era interfaces; the target user-facing syntax is SHELL_GEOMETRIC=FINITE_STRAIN or SHELL_GEOMETRIC=LINEAR.

[x] TODO V5.11-0: Redesign docs around finite-strain S4

  • Implementation:
    • Update docs/03_detailed_design.md with finite-strain S4 modules: rotation state, finite kinematics, assumed strain, nonlinear driver, tangent, drilling, and section coupling.
    • Update docs/04_mathematical_model_and_algorithms.md with finite membrane strain, finite rotation director update, Koiter-Sanders type curvature, MITC/ANS, and analytic tangent requirements.
    • Update docs/05_interface_control_document.md, docs/06_test_and_verification_plan.md, docs/07_user_manual.md, docs/08_developer_manual.md, and docs/v5_development_plan.md so they no longer describe corotational S4 as the V5.11 completion route.
    • Record the deletion rule: old exploratory code and aliases must be removed after the complete implementation replaces them.
  • Acceptance:
    • Documentation separates reusable foundations from temporary corotational code and explicitly forbids keeping unused interfaces.

[ ] TODO V5.11-1: Delete obsolete corotational interfaces and dead code

  • Implementation:
    • Inventory every production call site, input alias, public API, test, and documentation reference containing corotational, COROTATIONAL_SHELL, S4_COROTATIONAL, or old boolean-only SHELL_GEOMETRIC semantics.
    • Keep only foundations required by finite-strain S4: fem_shell_section, shell layer state, shell_resultant, pressure follower tangent, nonsymmetric solver support, and continuation path output.
    • Delete production dispatch paths, parser aliases, helper routines, and tests that only serve the old corotational route and are not needed by the finite-strain implementation.
    • Add input validation so SHELL_GEOMETRIC=FINITE_STRAIN and SHELL_GEOMETRIC=LINEAR are the stable forms; old aliases fail with a clear input error after migration.
  • Tests:
    • Add parser tests proving old aliases are rejected after migration.
    • Run shell, implicit input, spherical cap, and source-size regressions.
  • Acceptance:
    • No stable user-visible or internal production interface remains for the old corotational route.
    • rg -n "COROTATIONAL_SHELL|S4_COROTATIONAL|corotational" returns only historical notes or intentionally named removed-history comments, not live production dispatch.

[ ] TODO V5.11-2: Implement finite rotation shell state

  • Implementation:
    • Add node or shell-node rotation trial/committed state using exponential map or quaternion update.
    • Integrate rotation state with reset, backup, rollback, commit, cutback, line-search rejection, Newmark rollback, and restart.
    • Keep global node DOF 4:6 as Newton increments while committed director state carries finite rotation history.
  • Tests:
    • Rigid-body large rotation produces zero or near-zero shell internal force.
    • Failed increments restore rotation state exactly.
  • Acceptance:
    • Rotation state is not recomputed from small-angle accumulated DOF in a way that loses finite rotation objectivity.

[ ] TODO V5.11-3: Implement S4 finite kinematics and MITC/ANS

  • Implementation:
    • Compute reference/current covariant bases, director fields, surface metrics, finite membrane strain, Koiter-Sanders type curvature increment, and transverse shear strain for S4.
    • Handle initially curved or warped shell reference geometry without flattening the element into a small-strain local plane.
    • Implement S4 MITC/ANS transverse shear sampling and keep extension points for membrane/bending assumed strain if needed.
  • Tests:
    • Small-rotation finite-strain S4 matches existing linear S4 patch results.
    • Thin shell shear patch does not lock.
    • Warped/curved reference patch has no spurious initial stress.
  • Acceptance:
    • The formulation works for the spherical-cap mesh geometry, not only flat plates.

[ ] TODO V5.11-4: Implement analytic consistent shell tangent

  • Implementation:
    • Assemble material tangent B^T D_alg B.
    • Assemble geometric tangent from membrane force, bending moment, and transverse shear resultants.
    • Assemble rotation tangent from director and curvature linearization.
    • Assemble drilling stabilization tangent as a separate energy-consistent contribution.
    • Keep finite-difference tangent only as an audit tool, never as the final production Newton tangent.
  • Tests:
    • Finite-difference column audit passes for elastic S4.
    • J2/J2_JC/composite section tangent audit passes under large rotation.
    • Newton/cutback count improves over the old corotational diagnostic route on the spherical-cap mesh.
  • Acceptance:
    • The tangent is analytic, documented, and does not rely on hidden benchmark-only code.

[ ] TODO V5.11-5: Couple finite-strain S4 to shell sections and materials

  • Implementation:
    • Route ELASTIC, J2, J2_JC, and composite shell sections through fem_shell_section with trial/rollback semantics.
    • Complete multilayer plastic through-thickness state where composite layers use plastic materials.
    • Preserve membrane-bending coupling for unsymmetric laminates.
  • Tests:
    • ELASTIC/J2/J2_JC/composite large-rotation shell material tests pass.
    • Plastic layer state rolls back after failed increment.
  • Acceptance:
    • Unsupported shell material models fail explicitly, with no fallback to an elastic engineering tangent.

[ ] TODO V5.11-6: Complete spherical cap PDF postbuckling benchmark

  • Implementation:
    • Generate and run Shell-4, Shell-8, and Shell-16 PDF meshes with a = 10 m, th = 0.203840 m, E = 210 GPa, nu = 0.3, cap angle pi/4, fixed rim, and crown displacement to -6.2 m.
    • Output nondimensional curve data: wn = -w/th, Fn = -F*a/(E*th^3*2*pi).
    • Use production continuation and finite-strain shell code only.
  • Tests:
    • Checker compares Shell-4/8/16 curves to PDF tables or digitized reference values.
    • Checker requires post-peak load drop and later restiffening.
    • Checker fails monotone curves, small-strain samples, and old corotational diagnostic decks.
  • Acceptance:
    • example_spherical_cap_point_load_benchmark validates the full postbuckling path, not only geometry or displacement-control samples.

[ ] TODO V5.11-7: Final documentation, benchmark matrix, and evidence

  • Implementation:
    • Update benchmark matrix only after Shell-4/8/16 checker passes.
    • Update acceptance report with exact commands, dates, curve metrics, Newton/cutback counts, and known limits.
    • Remove obsolete corotational documentation references after code removal.
  • Tests:
    • Run targeted shell/implicit/spherical-cap/source-size regressions.
    • Run the relevant V5 acceptance subset if benchmark status changes.
  • Acceptance:
    • V5.11 can be marked PASS only when implementation, tests, docs, and benchmark evidence all align.

V5.12 V5 Development Plan Open Backlog

Boundary for this module:

  • This section mirrors the still-open PARTIAL and DEFERRED items in docs/v5_development_plan.md, especially the 0.5.2 two_arches reference route and the engineering close-out priorities listed in section 20.3.
  • Do not duplicate release hygiene items already closed in V5.10 unless the development plan still describes a concrete remaining engineering action.
  • A compact benchmark can be kept as regression coverage, but it cannot close a task that explicitly calls for a production workflow, full continuation path or high-fidelity reference case.

[ ] TODO V5.12-1: Finish examples/two_arches PDF reference route

  • Source:
    • docs/v5_development_plan.md marks examples/two_arches as PARTIAL / 0.5.2 TARGET.
    • Current coverage is PDF geometry, 30/75 shell mesh, contact activation, 1.2 mm upper-arch midpoint displacement and explicit micro-step stability.
  • Implementation:
    • Replace the literature-route acceptance path with static continuation or an equivalent global-equation workflow; keep the dynamic micro-step only as geometry/contact binding regression.
    • Implement or emulate the global equation disp_upper - max_disp*para = 0.
    • Use disp_upper as the upper-arch midpoint vertical displacement, max_disp = 60 mm, and advance para from 0 to 1, initially with range(0,0.02,1) or an equivalent continuation step sequence.
    • Keep the PDF geometry and mesh values explicit in the generator/input: Ri_upper = 80 mm, Ri_lower = 100 mm, shell width/thickness d = 3 mm, upper arc 80 deg, lower arc 100 deg, upper 30 mapped shell elements and lower 75 mapped shell elements.
    • Keep material values explicit: lower arch E = 40 GPa, nu = 0.2, rho = 1; upper arch E = 20 GPa, nu = 0.3, rho = 1.
    • Apply the reference in-plane constraints, lower-end fixed constraints, out-of-plane y constraints and upper-arch vertical edge-load control.
    • Use frictionless shell-shell contact with upper arch as source/slave and lower arch as destination/master.
    • Output two_arches_path.csv with at least para, disp_upper, edge-load factor, active contact count, max gap/penetration, residual and iteration status.
  • Tests:
    • Upgrade examples/two_arches/check_two_arches_results.py to reject the dynamic micro-step path as literature-route PASS evidence.
    • Verify geometry coordinates, 30/75 mesh counts, material values, disp_upper=max_disp*para residual, contact active set, bounded gap, nonnegative/bounded contact work and load-displacement path shape.
    • Add a CTest entry or update the existing benchmark entry so example_two_arches_contact_benchmark validates the static continuation route.
  • Acceptance:
    • examples/two_arches passes a reference-route checker without relying on explicit dynamic micro-steps.
    • The checker compares load-displacement/path metrics against documented reference indicators from models.sme.two_arches.pdf.

[ ] TODO V5.12-2: Close industrial mortar / AL contact gaps

  • Source:
    • V5.3 remains PARTIAL in docs/v5_development_plan.md.
  • Implementation:
    • Complete industrial-grade AL/mortar consistent tangent behavior for nonlinear contact paths.
    • Expand restart coverage beyond current active/released/open multiplier audits where the development plan still calls for more scenarios.
    • Add larger OpenMP contact benchmarks that exercise nonlinear long paths, not only compact or performance-smoke paths.
    • Clarify node-based surface to general element master support: direct support, conversion to facet constraints or explicitly deferred path.
  • Tests:
    • Add nonlinear long-path contact benchmarks with force, tangent, restart and OpenMP consistency checks.
    • Ensure internal BiCGSTAB/GMRES paths expose true status for nonsymmetric or difficult tangent systems instead of hiding failures.
  • Acceptance:
    • Contact mainline is closer to a production constraint solve, with documented convergence behavior and restart continuity on long paths.

[ ] TODO V5.12-3: Close Mohr-Coulomb structural workflow gaps

  • Source:
    • V5.4 and examples/strengthReduction remain PARTIAL / FOS PASS.
  • Planned INP selector:
    • Add a production INP-level nonlinear continuation selector: *NONLINEAR CONTINUATION, METHOD=value.
    • Accept numeric method ids 1 through 5 and stable symbolic names so old benchmark decks can stay compact while user-facing decks remain readable.
    • If the keyword is omitted, use method 1 as the default production algorithm.
    • Reject unknown method ids/names at input validation time; do not silently fall back to a different nonlinear path.
    • Record the selected method in nonlinear diagnostics, path CSV files and VTK/run summaries where applicable.
    • Completion evidence:
      • Added NLC_* continuation method enums and nonlinear_continuation_method default control state.
      • Added INP reader support for *NONLINEAR CONTINUATION, METHOD=value.
      • Added tests/data/c3d4_static_nonlinear_continuation.inp and implicit_inp coverage for default method 1, ids 1..5, symbolic names, invalid values and state preservation on parse failure.
      • Added continuation method diagnostics to strengthReduction nonlinear chain/cloud/progress CSV output and checker validation.
      • Targeted CTest command passed: ctest --test-dir build-win-gcc-16 -C Release -R "implicit_inp|example_strength_reduction_benchmark" --output-on-failure.
  • Implementation:
    • Add structure-level automatic trial re-solve for strength reduction.
    • Define and implement nonlinear instability criteria suitable for structural strength-reduction workflows.
    • Audit and document the Mohr-Coulomb engineering tangent in structural solves, including convergence status and substep counts.
    • Extend examples/strengthReduction beyond the current FOS curve so it can reproduce the PDF material case 2, alpha = 45 deg, FOS = 1.525 result with about 0.3 m displacement-cloud scale.
    • Implement method 1 / TWO_STAGE_LOAD_STRENGTH as the default route: first converge the real gravity/load state at strength factor F=1.0, then keep the external load fixed and continue the material strength reduction factor from 1.0 to the target factor.
      • Add production nonlinear static control static_ramp_load so the implicit static solver can either ramp external loads by pseudo-time or hold the assembled external load factor fixed.
      • Route strength_reduction_benchmark --nonlinear-chain through the method-1 two-stage solve when nonlinear_continuation_method == 1.
      • Route --nl-write-cloud through the same two-stage method-1 workflow, with the progress CSV tracking the fixed-load strength-factor stage.
      • Keep default *NONLINEAR CONTINUATION behavior as method 1 and continue writing the selected method id to nonlinear chain/cloud outputs.
      • Reduce method-1 runtime and nonlinear iteration cost enough for the 0.75 m PDF cloud case to run to full target factor in a documented longrun command.
    • Implement method 2 / ADAPTIVE_TARGET_NEWTON as a production nonlinear static step-size controller that targets a bounded Newton iteration count, grows after cheap accepted steps and shrinks after expensive accepted steps, cutbacks or failed convergence.
      • Add INP controls TARGET_NEWTON, GROWTH/GROWTH_FACTOR and SHRINK/SHRINK_FACTOR, with validation before state mutation.
      • Add production diagnostics for target increment, accepted increment, next target increment, accepted Newton count and adjustment reason.
      • Write method-2 diagnostics to strength-reduction nonlinear chain/cloud/progress CSV files and validate them in the example checker.
      • Add module tests for production adaptive stepping and INP parsing, including invalid-control preservation.
    • Implement method 3 / TRUST_REGION_DAMPED_NEWTON as a safeguarded Newton path with correction-size limits and residual-merit damping for high-load nonlinear segments.
      • Add INP controls TRUST_RADIUS, TRUST_MIN_RADIUS, TRUST_MAX_RADIUS, TRUST_GROWTH, TRUST_SHRINK, TRUST_ACCEPT_RATIO and TRUST_GOOD_RATIO.
      • Clip Newton corrections by the active trust radius before the residual-merit line search.
      • Reject residual-increasing damped corrections with a reproducible solver error, allowing the existing cutback/rollback path to respond.
      • Update the trust radius from residual merit reduction, damping and line-search rejection count.
      • Record trust radius, next radius, damping factor, merit ratio, rejection count and trust adjustment in production diagnostics and strength-reduction CSV/summary output.
    • Implement method 4 / ARC_LENGTH_OR_DISPLACEMENT_CONTROL for limit-point paths where pure load or strength-factor continuation cannot pass snapback or localization events.
      • Add production accepted-increment path storage in fem_control, including control parameter, controlled DOF count, prescribed/actual displacement norms, constraint residual, reaction path, generalized work, Newton iteration and convergence status.
      • Record direct prescribed-displacement continuation in implicit_solve_nonlinear_static for METHOD=4, using the same load_factor * amplitude boundary value that the solver enforces.
      • Expose the path through fem_get_continuation_path_count, fem_get_continuation_path_row and continuation_path.csv.
      • Add low-level solver and INP/API regression coverage for accepted increments, reaction output and zero constraint residual.
      • Add production Riks/arc-length controls ARC_LENGTH/ARC_RADIUS and ARC_LOAD_SCALE/RIKS_LOAD_SCALE, with validation before mutating the previous valid control state.
      • Implement the load-proportional Riks augmented equation in implicit_solve_nonlinear_static: extended unknowns are displacement and global load_factor; the reference load vector is computed as dF_ext/dlambda; each Newton iteration solves residual and load directions with the same constrained tangent and enforces the spherical arc constraint.
      • Remove the old simplified interpretation for load-controlled method 4 cases: load-type problems no longer use ordinary Newton plus accepted-path recording as Riks evidence. The direct path is retained only for explicit nonzero prescribed-displacement control, and cases with neither a proportional load nor nonzero prescribed displacement now fail instead of using a simplified fallback.
      • Prove method 4 on a real nonmonotonic or limit-point structure path, so snapback and localization events can be followed without benchmark-specific orchestration.
    • Implement method 5 / MC_SUBSTEPPING_SEMISMOOTH for local Mohr-Coulomb material stability, including stress-point substepping, active-set diagnostics and semismooth branch handling around corners.
      • Add INP controls MC_MIN_SUBSTEPS, MC_MAX_SUBSTEPS, MC_TARGET_STRAIN, MC_YIELD_TOL and MC_PLASTIC_LIMIT, with validation before mutating the previous valid control state.
      • Route production MOHR_COULOMB material updates through fem_material_mc_driver when METHOD=MC_SUBSTEPPING_SEMISMOOTH.
      • Store material-point aggregate diagnostics in statev(27:32): accepted substeps, requested substeps, driver status, branch mask, maximum yield residual and maximum plastic increment.
      • Keep the default and other continuation methods on the direct single-step Mohr-Coulomb update, while writing consistent single-step diagnostics.
      • Add structure-level aggregation of MC substep/branch diagnostics to strengthReduction nonlinear chain/cloud output.
      • Prove on the 0.75 m PDF cloud longrun that NC-5 reduces material corner cutbacks or local return failures when used as a documented stabilization component.
    • Keep the first production implementation mutually exclusive through the METHOD= selector; if later evidence shows the strongest path is a composition such as 1+2+5, add explicit secondary flags instead of overloading the primary method id.
  • Tests:
    • Add INP parser tests proving omitted keyword selects method 1, all ids 1..5 and symbolic names are accepted, and invalid values fail before solving.
    • Add solver diagnostics tests proving the selected method is reported and that method 1 does not regress the existing nonlinear static path.
    • Add checker coverage for displacement cloud scale and equivalent plastic strain/plastic-zone behavior once the full nonlinear continuation path is available.
    • Reject linear-static VTK displacement output as reference evidence.
  • Acceptance:
    • examples/strengthReduction can choose any planned nonlinear continuation method from the INP file, and the default deck uses method 1 without a command-line override.
    • Method 1 reaches the target FOS=1.525 PDF route, or the run summary reports a reproducible nonlinear/material failure instead of stopping at an ambiguous partial accepted_time.
    • Strength reduction moves from compact FOS-curve validation to a documented nonlinear structural workflow with PDF displacement/plasticity evidence.
  • Partial completion evidence for method 1:
    • cmake --build build-win-gcc-16 --config Release --target strength_reduction_benchmark test_implicit_inp passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -C Release -R "implicit_inp|example_strength_reduction_benchmark" --output-on-failure passed on 2026-06-27.
    • Path smoke passed: build-win-gcc-16\strength_reduction_benchmark.exe examples\strengthReduction\strength_reduction_slope_static.inp build-win-gcc-16\strength_reduction_twostage_smoke --nonlinear-chain --nl-max-trials 1 --nl-increments 2 --nl-max-newton 3 --nl-linear-iter 100 --nl-tol 1.0e-3.
    • Cloud smoke passed: build-win-gcc-16\strength_reduction_benchmark.exe examples\strengthReduction\strength_reduction_slope_static.inp build-win-gcc-16\strength_reduction_twostage_cloud_smoke --nl-write-cloud --nl-cloud-factor 1.525 --nl-cloud-step 1525 --nl-increments 2 --nl-max-newton 3 --nl-linear-iter 100 --nl-tol 1.0e-3.
    • Medium 0.75 m method-1 cloud probe with --nl-increments 10 --nl-max-newton 20 --nl-linear-iter 1000 --nl-tol 1.0e-3 --nl-preconditioner ilu0 exceeded 120 s and was stopped; full accepted_time=1.0 remains open.
  • Completion evidence for method 5 material-point and structure-level diagnostics:
    • METHOD=MC_SUBSTEPPING_SEMISMOOTH routes production MOHR_COULOMB updates through fem_material_mc_driver and writes statev(27:32).
    • strength_reduction_benchmark now aggregates MC point count, updated points, accepted/requested substeps, limited points, branch mask, maximum yield residual and maximum plastic step into nonlinear chain/cloud/progress rows and summary CSV output.
    • examples/strengthReduction/check_strength_reduction_results.py rejects missing or invalid MC row/summary diagnostics.
    • cmake --build build-win-gcc-16 --config Release --target strength_reduction_benchmark passed on 2026-06-27.
    • Nonlinear chain/cloud smoke output under build-win-gcc-16\strength_reduction_mc_diag_smoke passed examples\strengthReduction\check_strength_reduction_results.py, including optional MC chain/cloud/progress diagnostics.
    • ctest --test-dir build-win-gcc-16 -C Release -R "material_mohr_coulomb|implicit_inp|example_strength_reduction_benchmark" --output-on-failure passed on 2026-06-27.
  • Completion evidence for method 2:
    • cmake --build build-win-gcc-16 --config Release --target test_solver_implicit test_implicit_inp strength_reduction_benchmark passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -C Release -R "solver_implicit|implicit_inp|example_strength_reduction_benchmark" --output-on-failure passed on 2026-06-27.
    • solver_implicit now verifies adaptive growth reaches the final static time with fewer accepted increments than the fixed initial step would use.
    • implicit_inp verifies METHOD=ADAPTIVE_TARGET_NEWTON, TARGET_NEWTON, GROWTH and SHRINK, including failure without changing previous valid settings.
    • examples/strengthReduction/check_strength_reduction_results.py now rejects malformed nonlinear chain/cloud diagnostics for target increment, accepted increment, next target increment and adjustment reason.
  • Completion evidence for method 3:
    • cmake --build build-win-gcc-16 --config Release --target test_solver_implicit test_implicit_inp strength_reduction_benchmark passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -C Release -R "solver_implicit|implicit_inp|example_strength_reduction_benchmark" --output-on-failure passed on 2026-06-27.
    • solver_implicit now verifies that METHOD=TRUST_REGION_DAMPED_NEWTON limits the applied correction norm, converges through multiple damped Newton iterations, updates trust diagnostics and preserves the expected displacement solution.
    • implicit_inp verifies all trust-region control parameters and confirms invalid trust radius bounds fail without mutating previous valid settings.
    • examples/strengthReduction/check_strength_reduction_results.py now rejects missing or invalid trust-radius, damping, merit-ratio and rejection-count diagnostics in nonlinear chain/cloud/progress output.
  • Partial completion evidence for method 4:
    • fem_control now owns a dynamically sized accepted-increment continuation path table; fem_solver_implicit records direct displacement-control rows after nonlinear static increments converge, while the active load factor is still the one used by the solved increment.
    • fem_control also stores nlc_arc_length_radius, nlc_arc_load_scale, nlc_last_arc_constraint, nlc_last_arc_lambda and nlc_last_arc_length.
    • fem_inp_nlc parses ARC_LENGTH/ARC_RADIUS and ARC_LOAD_SCALE/RIKS_LOAD_SCALE for METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL.
    • fem_solver_implicit now routes load-type method 4 cases to a Riks augmented equation with displacement plus load_factor unknowns and keeps direct displacement-control path recording separate from Riks evidence. Method 4 inputs with neither proportional load nor nonzero prescribed displacement return a solver error instead of falling back to ordinary Newton path recording.
    • fem_api exposes row-by-row continuation path access and fem_output_csv writes continuation_path.csv when path data exists.
    • tests/data/c3d4_static_arc_disp_continuation.inp selects METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL; implicit_inp verifies the API path rows and solver_implicit verifies the in-memory direct displacement path, the load-type Riks path and the no-control rejection.
    • cmake --build build-win-gcc-16 --config Release --target test_solver_implicit test_implicit_inp passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -C Release -R "solver_implicit|implicit_inp" --output-on-failure passed on 2026-06-27.
  • Partial completion evidence for method 5:
    • src/base/fem_control.f90 now stores MC substep controls and src/input/fem_inp_nlc.f90 parses/validates them from *NONLINEAR CONTINUATION.
    • src/material/fem_material_j2.f90 now dispatches production MOHR_COULOMB updates to fem_material_mc_driver only when METHOD=MC_SUBSTEPPING_SEMISMOOTH.
    • src/material/fem_material_mohr_coulomb.f90 now writes consistent single-step state diagnostics and reserves statev(27:32) for MC substep aggregates.
    • cmake --build build-win-gcc-16 --config Release --target test_material_mohr_coulomb test_implicit_inp passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -C Release -R "material_mohr_coulomb|implicit_inp" --output-on-failure passed on 2026-06-27.

[ ] TODO V5.12-4: Move buckling and cyclic symmetry into the main solver path

  • Source:
    • V5.5 and examples/buckling_corrugated_shell remain PARTIAL.
  • Implementation:
    • Add a main-solver Euler column buckling workflow through femlite --buckling and the dedicated *BUCKLING COLUMN input block.
    • Move Euler column input, assembly, dense buckling solve and CSV output into production src/solver/fem_buckling_column.f90.
    • Delete the old duplicate Euler helper-side assembly/solve algorithm from tools/benchmarks/euler_column_buckling_benchmark.f90; keep only a compatibility wrapper around the production module.
    • Complete a general *BUCKLING step in the main femlite input/solve flow.
    • Assemble shell and solid geometric stiffness after static preload through the production element/solver path.
    • Integrate modal output with the normal output workflow.
    • Bring cyclic sector constraints into the main solve path, including node pairing, coordinate rotation and shell rotational DOF mapping.
    • Upgrade corrugated shell coverage from compact cyclic benchmark to a full shell FE preload-buckling high-fidelity model.
  • Tests:
    • Add module coverage for Euler column parsing, validation, solve diagnostics, output writing and mode boundary conditions.
    • Update examples/euler_column_buckling checker and double-click script so the regression runs femlite --buckling, not the benchmark helper.
    • Run targeted CLI regression after adding the new analysis mode.
    • Add general input-level *BUCKLING tests, preload-to-buckling tests and cyclic sector shell/solid mapping tests.
    • Keep Euler column benchmark as regression coverage through CTest.
    • Keep compact corrugated benchmark as regression coverage while adding main-solver cyclic/preload coverage.
  • Acceptance:
    • Users can run the Euler column buckling workflow through femlite --buckling, not only through benchmark helper tools.
    • Users can run a general preload-to-buckling workflow for shell/solid models through normal INP input.
    • Cyclic sector constraints work through the main solver path.
  • Completion evidence:
    • build-win-gcc-16\femlite.exe examples\euler_column_buckling\euler_column_buckling.inp --buckling --output-dir build-win-gcc-16\app_buckling passed on 2026-06-27 with first mode 1.84239E+06, Euler reference 1.84233E+06, residual 1.50015E-11 and relative error 3.27661E-05.
    • ctest --test-dir build-win-gcc-16 -R "^(buckling_support|example_euler_column_buckling_benchmark|smoke)$" --output-on-failure passed on 2026-06-27.
    • ctest --test-dir build-win-gcc-16 -R "^(cli_implicit_linear|cli_static_linear|cli_static_nonlinear|cli_implicit_newmark|cli_implicit_newmark_nonlinear)$" --output-on-failure passed on 2026-06-27.

[ ] TODO V5.12-5: Promote roll forming from benchmark helpers to production workflow

  • Source:
    • V5.6 and examples/roll_forming remain PARTIAL.
  • Implementation:
    • Add a main-solver roll-forming process step or equivalent production workflow for rigid roller kinematics, rotation, friction, plastic forming and unloading/springback.
    • Support full 3D workpiece meshes, not only compact section benchmarks.
    • Define restart-driven multi-step process semantics for forming and springback.
    • Add larger longrun stability checks for the process flow.
  • Tests:
    • Keep roller kinematics and compact J2 springback benchmarks as regression.
    • Add a full 3D workpiece run with restart, unloading, residual displacement and plastic-zone checks.
  • Acceptance:
    • Roll forming no longer depends on benchmark-specific orchestration for the core process path.

[ ] TODO V5.12-6: Integrate cohesive contact into the main contact workflow

  • Source:
    • V5.7 and examples/ball_adhesion_decohesion remain PARTIAL.
  • Implementation:
    • Integrate cohesive law/state/metrics into the production contact solve, including normal/tangential traction, damage evolution, unloading/reload and energy output.
    • Implement ordinary contact to cohesive contact switching rules and the reverse/released-state handling where applicable.
    • Add tangent support for cohesive contact and restart persistence for damage, maximum opening, adhesion energy and decohesion state.
    • Upgrade the ball-adhesion example from compact cohesive ring benchmark to a full ball-membrane FE cohesive contact long path.
  • Tests:
    • Extend restart tests to cohesive damage/history fields.
    • Add full FE force-displacement, hysteresis, dissipated energy, damage and decohesion-area checks.
  • Acceptance:
    • Cohesive behavior is available through the main contact workflow and not only through single-integration-point or benchmark-only drivers.

[ ] TODO V5.12-7: Upgrade deferred and partial high-fidelity examples

  • Source:
    • docs/v5_development_plan.md lists several example directories as DEFERRED or PARTIAL.
  • Implementation:
    • Upgrade examples/shell_solid_connection from shared-node smoke to a high-fidelity shell-solid connection/contact benchmark with transition-zone stress and contact-pressure checks.
    • Upgrade examples/buckling_corrugated_shell to a complete shell FE preload-buckling model after main solver *BUCKLING support exists.
    • Upgrade examples/roll_forming to a full 3D workpiece benchmark after the production roll-forming workflow exists.
    • Upgrade examples/ball_adhesion_decohesion to a full FE cohesive ball-membrane benchmark after main contact integration exists.
    • Extend examples/Dynamic_Grain_Packing_of_a_Flexible_Container with larger particle counts, neighbor-search performance checks and longrun energy stability.
  • Tests:
    • Each upgraded example needs a README, input/generator, run script, checker, CTest entry and documented reference metrics/tolerances.
  • Acceptance:
    • No example is listed as V5 PASS if it is still a compact surrogate, fallback path or smoke-only run.

[ ] TODO V5.12-8: Complete longrun and performance close-out

  • Source:
    • V5.9/V5.10 remain PARTIAL in the development plan because larger longrun and full performance close-out remain recommended.
  • Implementation:
    • Define longrun tiers for contact, Mohr-Coulomb, buckling, roll forming, cohesive contact and particle-container coupling.
    • Record memory, iteration, residual, timing and platform stability metrics.
    • Update docs/v5_benchmark_matrix.md when new longrun/performance tests are formalized.
    • Restore source_size governance after the Riks/NLC and buckling work: split *NONLINEAR CONTINUATION parsing into production src/input/fem_inp_nlc.f90, keep fem_inp_helpers as generic keyword/data helpers, shorten the dense solver, CG solver, S4 stiffness and NLC parser test routines below the hard routine threshold, and document remaining structural exceptions with explicit split reasons in tests/source_size_exceptions.txt.
    • Split implicit constraint/tangent application out of fem_solver_implicit: added production src/solver/fem_implicit_constraints.f90 for Dirichlet, Robin, MPC, follower-load tangent and contact tangent application, removed the old private duplicate routines from the main implicit solver, and kept the nonlinear/static/Newmark behavior covered by targeted regression.
    • Split database lifecycle cleanup out of fem_database: added production src/mesh/fem_database_lifecycle.f90, kept database_finalize(ierr) as the stable public wrapper, removed stale contact/free helper wrappers, and removed the now-stale hard file exception for src/mesh/fem_database.f90 after the file dropped below 2000 lines. database_finalize_storage is now split into private model-array, material-array and step/load-array release helpers, so fem_database_lifecycle.f90 no longer appears in the source-size routine review-warning list.
    • Split stable time-step support out of the public API facade: added production src/base/fem_api_stable_dt.f90 for material wave speed, element characteristic length and current-position helper logic, kept fem_estimate_stable_dt as the stable public API wrapper, and removed the now-stale hard file exception for src/base/fem_api.f90 after the file dropped below 2000 lines.
    • Split the strengthReduction benchmark orchestration outside src: added tools/benchmarks/strength_reduction_benchmark_cli.f90 for CLI and nonlinear-chain option parsing, added tools/benchmarks/strength_reduction_benchmark_report.f90 for CSV/summary naming and report formatting, and split cloud/two-stage progress helpers inside the benchmark driver so all benchmark routines are below the hard 128-line threshold.
    • Split the hard routine-size exceptions in fem_solver_implicit: implicit_solve_nonlinear_static is now a thin dispatcher over begin, fixed/adaptive scheduling and arc driver helpers; Riks/arc-length initialization, predictor and constraint-measure updates are separated from static_arc_increment; nonlinear static Newton correction, line search and trust-region update are separated from nonlinear_static_increment. All routine entries were removed from tests/source_size_exceptions.txt.
    • Clear the remaining file-level source_size exception for fem_solver_implicit: added production src/solver/fem_solver_implicit_support.f90 for shared convergence, nonlinear linear-solver fallback, stiffness/external assembly, CSR/mass and trust-region helpers; added production src/solver/fem_solver_newmark.f90 for linear and nonlinear Newmark integration; kept the public Newmark entry points re-exported by fem_solver_implicit. The active entries in tests/source_size_exceptions.txt are now empty.
    • Continue review-threshold cleanup for the current implicit solver split: arc driver initialization, Riks iteration evaluation/correction and Newmark nonlinear initialization/correction/success/failure handling were moved into helpers. implicit_solve_static_arc, static_arc_increment and implicit_newmark_nonlinear_step no longer appear in the source_size review-warning list.
    • Continue file-level review-target cleanup for fem_solver_implicit: added production src/solver/fem_solver_static_nonlinear.f90 for nonlinear static fixed/adaptive scheduling, static predictor history, direct displacement-control path recording, load-type Riks/arc-length and nonlinear static Newton increments. fem_solver_implicit now keeps linear static plus dispatcher/public-entry ownership and no longer appears in the source-size review-warning list.
    • Continue review-target cleanup on other large production modules only where it clarifies ownership and preserves full algorithms, especially fem_api, fem_database, fem_element_internal and benchmark tool files.
      • fem_api: extracted shared Newmark run preparation for implicit and nonlinear Newmark API runs; fem_run_newmark_nonlinear no longer appears in the source-size routine warning list.
      • fem_api: split the public API facade into production support modules: fem_api_state owns the initialized flag, fem_api_coupling owns SPH/contact/surface/facet API routines, fem_api_diagnostics owns convergence/continuation/linear-solver/shell-stability API routines, and fem_api_state_access owns node/element state query API routines. The original fem_api module keeps initialization, model I/O, solve/output orchestration and re-exports the moved public entries; fem_api.f90 no longer appears in the source-size file-level review-warning list.
      • fem_control: split control_set_defaults into private grouped reset helpers for time/nonlinear controls, solver controls, diagnostics and feature flags. The public default-reset entry remains unchanged, and control_set_defaults no longer appears in the source-size routine review-warning list.
      • fem_material_j2: split J2 plastic state update into update_j2_plastic_state, keeping the return-mapping algorithm intact; changed stress_dependent_modulus to preserve the caller-provided Young's modulus value on error returns. material_update_j2 no longer appears in the source-size routine review-warning list, and the Windows GCC maybe-uninitialized warning for SDE Young's modulus is gone.
      • fem_database: moved database initialization storage reset into database_initialize_storage in fem_database_lifecycle, keeping the public database_initialize(ierr) wrapper stable; added production fem_database_lookup for ID/name queries and surface face helpers, added production fem_database_validation for full model validation, and kept database_validate_model(ierr) as a stable wrapper. fem_database.f90, database_initialize, validate_materials and validate_contact_data no longer appear in the source-size review-warning list.
      • fem_material_mohr_coulomb: initialized MC parameter and Lame parameter outputs on all error paths, clearing the Windows GCC maybe-uninitialized warnings for tension, lambda and shear without changing the return-mapping or tangent algorithms.
      • fem_linear_solver_dense: split dense CSR copy, partial-pivot elimination/back-substitution, pivot selection and residual calculation into private helpers while preserving the internal dense pivoting fallback algorithm. linear_dense_solve no longer appears in the source-size routine review-warning list.
      • fem_linear_solver_iterative: split CG preconditioner/initialization setup, BiCGSTAB initialization and omega correction, and GMRES initialization into private helpers while preserving the production iteration formulas and internal preconditioner dispatch. linear_cg_solve, linear_bicgstab_solve and linear_gmres_solve no longer appear in the source-size routine review-warning list.
      • fem_assembly_csr: split CSR pattern row counting and row-column population into private helpers while preserving element/MPC/contact sparsity insertion and row sorting. assembly_build_csr_pattern no longer appears in the source-size routine review-warning list.
      • fem_inp_helpers: moved Mohr-Coulomb material line parsing into production fem_inp_material_parser, moved contact pair/property/friction parsing into production fem_inp_contact_parser, and kept fem_inp_helpers focused on generic token/keyword helpers and shared INP utilities. parse_mc_line, parse_contact_pair_header and the file-level fem_inp_helpers.f90 warning no longer appear in the source-size review-warning list.
      • fem_inp_reader: split count-model state reset and node/element total validation out of the first-pass INP counting routine. The first-pass keyword/data counting behavior remains unchanged, and inp_count_model no longer appears in the source-size routine review-warning list.
      • fem_output_csv: split contact CSV header, summary row and pair row writing into private helpers while preserving the existing CSV schema and contact diagnostics fields. output_csv_write_contact no longer appears in the source-size routine review-warning list.
      • fem_particle_config_check: split particle check limit parsing into pcheck_parse_limits, keeping line cleaning, CHECK data-line handling and final validation unchanged. pcheck_parse_line no longer appears in the source-size routine review-warning list.
  • Tests:
    • Add documented extended commands for longrun/performance suites, separate from default fast CTest.
    • Re-run relevant Windows GCC, Windows Intel/MSVC and WSL GNU subsets when longrun coverage changes.
    • Run targeted source-size and behavior regression after the parser/solver cleanup. Completion evidence on 2026-06-27: ctest --test-dir build-win-gcc-16 -R "^(implicit_inp|linear_solver_cg|shell_internal|source_size)$" --output-on-failure and ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|linear_solver_cg|shell_internal|buckling_support|example_euler_column_buckling_benchmark|cli_implicit_linear|cli_static_linear|cli_static_nonlinear|cli_implicit_newmark|cli_implicit_newmark_nonlinear)$" --output-on-failure both passed.
    • Run targeted regression after splitting implicit constraint helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 and ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure both passed.
    • Run targeted build and source-size cleanup after splitting database lifecycle. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_implicit_inp test_solver_implicit -j 4 passed; source-size was rerun and exposed the stale src/mesh/fem_database.f90 file exception, which was removed; rerun ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed.
    • Run targeted build and source-size cleanup after splitting API stable time-step support. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_implicit_inp test_solver_implicit -j 4 passed; source-size was rerun and exposed the stale src/base/fem_api.f90 file exception, which was removed; rerun ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed.
    • Run targeted build and source-size cleanup after splitting strengthReduction benchmark CLI/report/cloud helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target strength_reduction_benchmark -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(source_size|example_strength_reduction_benchmark)$" --output-on-failure passed after removing stale benchmark routine exceptions.
    • Run targeted build and source-size cleanup after splitting fem_solver_implicit nonlinear static and Riks routine helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed after removing stale implicit_solve_nonlinear_static, static_arc_increment and nonlinear_static_increment routine exceptions.
    • Run targeted build and source-size cleanup after splitting implicit support and Newmark into focused production modules. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed after removing the stale src/solver/fem_solver_implicit.f90 file exception. tests/source_size_exceptions.txt now contains no active exceptions.
    • Run targeted build and source-size cleanup after reducing the current implicit solver review-size routines. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed after implicit_solve_static_arc, static_arc_increment and implicit_newmark_nonlinear_step disappeared from the source-size warning list.
    • Run targeted build and source-size cleanup after moving nonlinear static scheduling, Riks/arc-length and static Newton increments into fem_solver_static_nonlinear. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size)$" --output-on-failure passed, and fem_solver_implicit.f90 no longer appears in the source_size warning list.
    • Run targeted build and API/source-size cleanup after extracting shared Newmark run preparation inside fem_api. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(solver_implicit|implicit_inp|source_size|c_api)$" --output-on-failure passed, and fem_run_newmark_nonlinear no longer appears in the source_size routine warning list.
    • Run targeted build and API facade/source-size cleanup after splitting coupling, diagnostics and state-access API routines out of fem_api. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_c_api test_smoke test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(smoke|c_api|solver_implicit|implicit_inp|source_size)$" --output-on-failure passed, and fem_api.f90 no longer appears in the source_size file-level review-warning list.
    • Run targeted build and source-size cleanup after splitting database lifecycle release categories. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_smoke test_restart test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(smoke|restart|implicit_inp|source_size)$" --output-on-failure passed, and database_finalize_storage no longer appears in the source_size routine review-warning list.
    • Run targeted build and source-size cleanup after splitting control_set_defaults. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_implicit_inp test_solver_implicit test_element_stiffness test_linear_solver_cg -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(implicit_inp|solver_implicit|element_stiffness|linear_solver_cg|source_size)$" --output-on-failure passed, and control_set_defaults no longer appears in the source_size routine review-warning list.
    • Run targeted build and source-size cleanup after splitting J2 plastic state update and clearing the SDE Young's modulus warning. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_material_j2 test_material_mohr_coulomb test_implicit_inp -j 4 passed without the previous young may be used uninitialized warning; ctest --test-dir build-win-gcc-16 -R "^(material_j2|material_mohr_coulomb|implicit_inp|source_size)$" --output-on-failure passed, and fem_material_j2.f90 no longer appears in the source_size warning list.
    • Run targeted build and source-size cleanup after moving database initialization into lifecycle storage helpers and splitting database validation routines. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_database_topology test_smoke test_restart test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(database_topology|smoke|restart|implicit_inp|source_size)$" --output-on-failure passed, and database_initialize no longer appears in the source_size warning list. After splitting validation helpers and clearing MC maybe-uninitialized warnings, cmake --build build-win-gcc-16 --target test_material_mohr_coulomb test_database_topology test_implicit_inp -j 4 passed without the previous MC warnings, and ctest --test-dir build-win-gcc-16 -R "^(material_mohr_coulomb|database_topology|implicit_inp|source_size)$" --output-on-failure passed.
    • Run targeted build and source-size cleanup after moving database lookup and validation into dedicated production modules. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_database_topology test_smoke test_implicit_inp test_contact -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(database_topology|smoke|implicit_inp|contact|source_size)$" --output-on-failure passed. Direct check_source_size.py output no longer lists src/mesh/fem_database.f90 or its validation routines.
    • Run targeted build and source-size cleanup after splitting the dense solver fallback. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_linear_solver_cg test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(linear_solver_cg|solver_implicit|implicit_inp|source_size)$" --output-on-failure passed, and direct check_source_size.py output no longer lists linear_dense_solve.
    • Run targeted build and source-size cleanup after splitting the iterative CG/BiCGSTAB/GMRES solver routines. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_linear_solver_cg test_solver_implicit -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(linear_solver_cg|solver_implicit|source_size)$" --output-on-failure passed. Direct check_source_size.py output no longer lists linear_cg_solve, linear_bicgstab_solve or linear_gmres_solve.
    • Run targeted build and source-size cleanup after splitting CSR assembly pattern helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_assembly_csr test_solver_implicit test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(assembly_csr|solver_implicit|implicit_inp|source_size)$" --output-on-failure passed, and direct check_source_size.py output no longer lists assembly_build_csr_pattern.
    • Run targeted build and source-size cleanup after moving material/contact INP parsing out of fem_inp_helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_implicit_inp test_contact test_material_mohr_coulomb -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(implicit_inp|contact|material_mohr_coulomb|source_size)$" --output-on-failure passed. Direct check_source_size.py output no longer lists src/input/fem_inp_helpers.f90, parse_mc_line or parse_contact_pair_header.
    • Run targeted build and source-size cleanup after splitting the INP first-pass counter. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(implicit_inp|source_size)$" --output-on-failure passed, and direct check_source_size.py output no longer lists inp_count_model.
    • Run targeted build and source-size cleanup after splitting contact CSV output helpers. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_vtk_output test_contact test_implicit_inp -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(vtk_output|contact|implicit_inp|source_size)$" --output-on-failure passed, and direct check_source_size.py output no longer lists output_csv_write_contact.
    • Run targeted build and source-size cleanup after splitting particle check parsing. Completion evidence on 2026-06-27: cmake --build build-win-gcc-16 --target test_particle_config_check test_particle_config_suite -j 4 passed; ctest --test-dir build-win-gcc-16 -R "^(particle_config_check|particle_config_suite|source_size)$" --output-on-failure passed, and direct check_source_size.py output no longer lists pcheck_parse_line.
  • Acceptance:
    • V5 performance and longrun coverage has clear commands, output metrics, tolerances and platform records.