Files
FemLite/todo.md
T
shenw 75d4e735b1
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.5.2 V5 closeout
2026-07-01 14:51:40 +08:00

128 KiB

FemLite V5 Remaining TODO

Status date: 2026-06-30

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.

2026-06-30 V5 Release Scope Decision

The V5 release boundary is narrowed to a shippable V5.11 capability checkpoint. V5.11 must prove that the finite-membrane-strain S4 production route is present, tested, documented, and capable of a non-monotone spherical-cap postbuckling signature under the agreed Shell-4 translational-rim benchmark口径. It is not required to fully reproduce the entire uz=-6.2 m PDF curve or close all Shell-4/8/16 reference-shape differences before the V5 release.

The following items are explicitly deferred to the next version line and must not block V5 release:

  • Full spherical-cap PDF curve reproduction through uz=-6.2 m.
  • Strict Shell-4/8/16 curve-family comparison to digitized PDF values.
  • True pseudo-arclength / branch-following continuation beyond the default direct-displacement path improvements.
  • Late post-peak GMRES/performance optimization beyond documented diagnostics.
  • The V5.12 backlog: two_arches single reference-point check, industrial mortar/AL close-out, Mohr-Coulomb critical-instability cloud longrun, generic buckling/cyclic main-solver integration, roll forming production workflow, cohesive contact main-flow integration, high-fidelity example upgrades, and longrun/performance close-out.

V5.11 may be marked release-ready when its checker, documentation, and evidence validate the bounded capability claim: finite-strain S4 production dispatch, stable shell geometry inputs, continuation-path diagnostics, the fixed support 口径, and a reproducible post-peak load drop with documented remaining limits.

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:

  • V5.11 release acceptance is a finite-strain S4 production capability checkpoint, not a full PDF curve-reproduction claim. The spherical-cap case must demonstrate the agreed postbuckling口径 with a reproducible post-peak load drop, but full uz=-6.2 m curve matching to models.sme.spherical_cap_with_central_point_load.pdf is deferred.
  • 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 old S4 diagnostic route was temporary technical debt. It explained earlier failures, but it is not a stable interface and not acceptance evidence. V5.11-1 removes its production dispatch, input aliases, tests, documentation entry points, and 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.
  • The V5 checker must reject regressions to linear, small-strain, monotone-only or old corotational behavior. It does not need to pass strict Shell-4/8/16 PDF digitized-curve matching in this release.

Current facts:

  • examples/spherical_cap_with_central_point_load checks reference geometry, material scale and Shell-16 small-strain samples; the Shell-4 deck now uses the all-S4 finite-strain target route with translational rim support as the V5.11 postbuckling capability proof.
  • continuation_path.csv records accepted displacement/reaction rows, linear solver diagnostics, path-control diagnostics and trust diagnostics, so the checker can validate the bounded V5 post-peak signature and preserve evidence for the deferred full-curve work.
  • SHELL_GEOMETRIC=YES, GEOMETRIC_SHELL, COROTATIONAL_SHELL, and S4_COROTATIONAL are removed 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.

[x] DONE 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.
  • Completion evidence:
    • Removed src/element/fem_shell_corotational.f90 from source and CMake.
    • Removed old shell corotational production dispatch and FD tangent/resultant helper routines from fem_element_internal and fem_element_stiffness.
    • Replaced shell_geometric_nonlinear with shell_finite_strain_requested; SHELL_GEOMETRIC now accepts only FINITE_STRAIN or LINEAR.
    • Old GEOMETRIC_SHELL/COROTATIONAL_SHELL/S4_COROTATIONAL aliases are rejected with a clear input error and parser rollback is tested.
    • Removed the old curved S4 nonlinear patch input and tests that only served the deleted route.
    • Updated spherical-cap Shell-16 deck to SHELL_GEOMETRIC=LINEAR and Shell-4 target deck to SHELL_GEOMETRIC=FINITE_STRAIN; finite-strain shell requests now fail clearly until V5.11-4 through V5.11-6 are implemented.
    • Build passed: cmake --build build-win-gcc-16 --target femlite test_implicit_inp test_shell_internal -j 4.
    • Targeted CTest passed: ctest --test-dir build-win-gcc-16 -R "^(implicit_inp|shell_internal|source_size|example_spherical_cap_point_load_benchmark)$" --output-on-failure.

[x] DONE 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 finite-kinematics strain once the rotation state is consumed by the V5.11-3 S4 kinematics module.
    • 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.
  • Completion evidence:
    • Added production fem_shell_rotation with per-node quaternion committed, trial and backup state; nodal DOF 4:6 remain incremental Newton rotation corrections and update trial orientation by exponential-map quaternion increments.
    • element_state_ensure/reset/begin/restore/commit/abort now includes shell rotation lifecycle so cutback, rejected trial steps and Newmark rollback restore the finite-rotation state together with integration-point state.
    • Restart format version 3 writes and reads the committed shell rotation block; version 1/2 restarts initialize the rotation state to identity.
    • test_element_state verifies identity initialization, 90-degree finite-rotation vector behavior, commit, restore and abort rollback. test_restart verifies shell rotation restart persistence and vector rotation after reload.
    • Build passed: cmake --build build-win-gcc-16 --target test_element_state test_restart femlite -j 4.
    • Targeted CTest passed: ctest --test-dir build-win-gcc-16 -R "^(element_state|restart|implicit_inp|shell_internal|source_size|example_spherical_cap_point_load_benchmark)$" --output-on-failure.

[x] DONE 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 kinematics.
    • MITC transverse shear patch is verified at the kinematic projection level.
    • Warped/curved reference patch has no spurious initial strain.
  • Acceptance:
    • The formulation works for the spherical-cap mesh geometry, not only flat plates.
  • Completion evidence:
    • Added production fem_shell_finite_kinematics for S4 reference/current covariant bases, director interpolation, surface metrics, finite membrane strain, Koiter-Sanders-style curvature increment, local engineering strain projection and direct/MITC transverse shear sampling.
    • The module consumes arbitrary reference/current director fields, including directors generated from fem_shell_rotation; it does not accumulate small angle DOF values as finite orientation history.
    • Added CTest shell_finite_kinematics, covering small membrane strain, small bending curvature, MITC constant shear projection, warped reference zero strain, quaternion-state rigid rotation zero strain and spherical-cap patch geometry.
    • Build passed: cmake --build build-win-gcc-16 --target test_shell_finite_kinematics test_shell_internal test_element_state test_restart test_implicit_inp femlite -j 4.
    • Targeted CTest passed: ctest --test-dir build-win-gcc-16 -R "^(shell_finite_kinematics|shell_internal|element_state|restart|implicit_inp|source_size|example_spherical_cap_point_load_benchmark)$" --output-on-failure.

[x] DONE 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.
    • Connect the GP tangent to the S4 element/global assembly only after the solver synchronizes nodal rotation DOF increments into shell_rotation_trial at every residual/tangent evaluation.
  • Tests:
    • Finite-difference column audit passes for elastic S4.
    • J2/J2_JC/composite section tangent audit passes under large rotation.
    • S4 element-level tangent audit passes; spherical-cap Newton/cutback evidence is tracked in V5.11-6 because the current target deck contains unsupported S3 crown fan elements.
  • Acceptance:
    • The tangent is analytic, documented, and does not rely on hidden benchmark-only code.
  • Progress evidence:
    • Added shell4_finite_bmat_at and shell4_finite_derivs_at in fem_shell_finite_kinematics; the derivative tensor is the algorithmic finite-rotation linearization used by the residual, not a symmetric coordinate Hessian.
    • Added production fem_shell_finite_tangent, assembling K = B^T D_alg B + sum_i R_i dB_i/du at S4 integration-point level for membrane, bending and MITC transverse shear resultants.
    • Added CTest shell_finite_tangent; shell_finite_kinematics now audits finite-strain values, B columns and dB/du, while shell_finite_tangent audits the 24-by-24 elastic GP tangent against internal-force column finite differences.
    • Build passed: cmake --build build-win-gcc-16 --target test_shell_finite_tangent test_shell_finite_kinematics -j 4.
    • Targeted CTest passed: ctest --test-dir build-win-gcc-16 -R "^(shell_finite_kinematics|shell_finite_tangent)$" --output-on-failure.
    • Added production fem_shell_finite_element: SHELL_GEOMETRIC=FINITE_STRAIN now dispatches S4 elements through finite-strain internal force and tangent assembly, including averaged nodal reference directors, current director trial rotations, section resultants, geometric/rotation tangent and energy-consistent drilling energy.
    • fem_shell_rotation now synchronizes rotation DOFs incrementally inside an active trial: each residual/tangent evaluation multiplies only the newest Newton rotation correction into shell_rotation_trial, matching the dB/du linearization.
    • Added CTest shell_finite_element, covering S4 production dispatch, element 24-column finite-difference tangent, drilling residual/stiffness energy consistency, unsymmetric composite membrane-bending coupling, J2/J2_JC large rotation section tangents, composite plastic layer state, and plastic rollback.
    • Targeted CTest passed: ctest --test-dir build-win-gcc-16 -R "^(shell_finite_element|shell_finite_kinematics|shell_finite_tangent|shell_internal|element_state|implicit_inp|restart|source_size|example_spherical_cap_point_load_benchmark)$" --output-on-failure.
    • Remaining spherical-cap postbuckling evidence is deferred to V5.11-6: the Shell-4 target deck has since been converted to all-S4 topology, but the nonlinear curve still fails the PDF load drop/restiffening signature.

[x] DONE 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.
  • Completion evidence:
    • fem_shell_section now owns the public production APIs shell_section_update_resultants and shell_section_tangent_at; finite and small-strain shell paths share the same state update, through-thickness layer integration, algorithmic tangent and rollback storage.
    • shell_finite_element covers ELASTIC, unsymmetric elastic composite, J2, J2_JC and composite-with-J2-layer finite-strain S4 paths under large rotations, plus rollback after a rejected plastic trial.
    • Targeted CTest passed as listed in V5.11-4.

[x] DONE V5.11-6: Close bounded spherical-cap postbuckling capability benchmark

  • Implementation:
    • Generate Shell-16 baseline and Shell-4 finite-strain target decks with a = 10 m, th = 0.203840 m, E = 210 GPa, nu = 0.3, cap angle pi/4, and documented support口径.
    • Output nondimensional curve data: wn = -w/th, Fn = -F*a/(E*th^3*2*pi).
    • Use production continuation and finite-strain shell code only.
    • Resolve the Shell-4 target mesh blocker: the deck no longer contains S3 crown fan elements and now uses an all-S4 square-disk crown remesh matching the PDF radius, thickness, cap angle and fixed rim geometry.
    • Resolve the release-blocking physics question at bounded scope: the all-S4 Shell-4 translational-rim target shows a clear post-peak load drop, so V5.11 has evidence of nonlinear postbuckling behavior and is no longer blocked by the absence of a limit-point signature.
    • Diagnose the main reference口径 differences before changing more production physics: top-surface offset is not the dominant scale error, while rim rotational clamping strongly changes the curve and masks the post-peak branch. The V5.11 Shell-4 target therefore uses translational rim support; full PDF curve matching remains deferred.
    • Update the spherical-cap checker so the V5 bounded nonlinear route validates the bounded capability claim: Shell-16 baseline geometry, Shell-4 finite-strain all-S4 target, translational rim support, continuation-path columns, non-monotone post-peak load drop and documented known limits.
    • Move strict Shell-4/8/16 PDF curve matching, full uz=-6.2 m reproduction and restiffening-window tuning into the next-version backlog.
    • Expose nonlinear stage tracing through femlite --trace-nonlinear so long spherical-cap runs show whether time is spent in pattern assembly, stiffness assembly or linear solves.
    • Avoid the expensive CG-first path for finite-strain shell nonlinear corrections: small finite-shell systems now use the internal dense solver directly, while larger finite-shell systems switch to GMRES before the existing fallback chain.
    • Expose femlite --linear-iter so benchmark and diagnostic runs can bound nonlinear correction solve attempts before fallback handling.
    • Expose femlite --shell-drilling and wire the spherical-cap nonlinear checker to FEMLITE_SPHERICAL_CAP_SHELL_DRILLING so drilling-stabilization sensitivity can be audited without changing defaults.
    • Confirm on the rebuilt E-drive GCC build that Shell-4 direct displacement reaches uz=-2 m with a post-peak load drop and restiffening in the accepted continuation path; the remaining blocker is the larger displacement/path and reference-shape mismatch, not the absence of any limit-point signature.
    • Run a short drilling-stabilization sensitivity probe: the default Shell-4 uz=-2 m path completed with the same load-drop/restiffening signature, while zero drilling stabilization did not complete within the diagnostic timeout, so the next fix should not be a simple stabilization reduction.
    • Add shell strain diagnostic columns to elements_*.csv (shell_mem_max, shell_ben_max, shell_shr_max, shell_k11, shell_k22, shell_k12) so spherical-cap runs can separate membrane, bending and shear contributions without adding benchmark-only code.
    • Confirm on the Shell-4 uz=-2 m diagnostic run that the final state is not dominated by transverse shear locking: at wn ~= 9.8, the largest element values are approximately membrane 4.1e-2, bending curvature 3.9e-1, and shear 1.1e-2; the next audit should focus on membrane/ bending coupling, curvature sign/scale, and mesh/path effects.
    • Add a finite-kinematics unit audit for spherical normal offset so the membrane and bending curvature signs are checked on a curved reference patch, not only on flat bending patches.
    • Tighten that finite-kinematics audit so the same spherical offset also checks membrane and bending curvature scale (offset/R and offset/R^2). This passed on the E-drive GCC build, so the current Shell-4 over-stiffening is unlikely to be a basic curved-patch strain-scale amplification.
    • Test angle-weighted production reference-director averaging. It is a generic robustness improvement and passes finite-shell regressions, but the Shell-4 uz=-2 m curve is essentially unchanged (Fn at wn ~= 9.8 changes from about 0.83302 to 0.83289), so the dominant V5.11-6 issue is unlikely to be nodal director averaging alone.
    • Run a Shell-8 uz=-2 m square-disk finite-strain diagnostic. It completed in about 130 s with 10 increments and 85 Newton iterations. The early curve is much softer than Shell-4 and closer to the PDF/Shell-16 reference scale (Fn ~= 0.591 at wn ~= 6.28, versus Shell-4 Fn ~= 0.653 at the same displacement), but it is still monotone through wn ~= 9.8. This points to a combined mesh/path-resolution issue rather than a single obvious curvature-sign bug.
    • Re-run the Shell-8 short diagnostic after the displacement-amplitude correction. A temporary all-S4 Shell-8 deck to uz=-1.984 m completed in about 113 s with 13 accepted increments and 91 Newton iterations; at wn ~= 9.73, Fn ~= 0.804. This confirms that mesh refinement softens the response but does not by itself close the PDF-scale mismatch.
    • Add an experimental finite S4 membrane-locking control path: --shell-membrane-locking center uses an element-center assumed membrane strain and matching membrane tangent rows, while the default remains off. The switch is covered by shell_finite_element. A spherical-cap probe with the switch enabled reached heavy iteration near time ~= 0.78, so it is retained as a controlled diagnostic instead of becoming the production default.
    • Improve continuation path sampling for long diagnostics: displacement-control and arc-length accepted steps now refresh continuation_path.csv immediately after nlc_path_append, so a long run can be inspected before the full analysis finishes. Verified with c3d4_static_arc_disp_continuation.inp and --output-interval 0, producing a two-row path CSV.
    • Extend continuation_path.csv with per-row linear-solver diagnostics: method, preconditioner, iteration count, status, initial residual, final residual and relative residual. This makes long spherical-cap runs inspectable without enabling a separate trace file. Verified with the compact c3d4_static_arc_disp_continuation.inp path CSV.
    • Extend continuation_path.csv with accepted-step path-control diagnostics: target_dt, actual_dt, next_dt, adapt_adjust and cumulative cutback_count. Path rows are now recorded after the next-step decision is available, so long post-peak runs show whether the driver is growing, keeping, shrinking or recovering from cutback at each accepted increment. Covered by solver_implicit and a compact path-column probe.
    • Re-run the Shell-4 time=0.48 diagnostic with path-level linear-solver stats. It completed in about 40 s with 24 increments and 168 Newton iterations; the last accepted steps used GMRES/Jacobi with roughly 75-94 linear iterations and final relative residuals around 1e-7. The runtime issue is therefore repeated Newton corrections plus moderate GMRES work, not a single runaway linear solve.
    • Add controlled direct-displacement path adaptivity instead of making it unconditional: DISP_ADAPTIVE=YES in *NONLINEAR CONTINUATION or femlite --disp-path-adaptive on routes direct displacement control through the existing target-Newton adaptive loop. Later V5.11 post-peak diagnostics showed that the fixed-grid default was still too brittle for the translational-rim spherical-cap path, so this adaptive route was promoted to the default direct-displacement continuation behavior; explicit DISP_ADAPTIVE=NO / --disp-path-adaptive off remains available for old fixed-grid sampling.
    • Add femlite --linear-precond none|jacobi|gs|ilu0 for controlled nonlinear diagnostics. On the Shell-4 time=0.48 probe, ILU0 reduced the last-step GMRES iteration count from roughly 90 to roughly 15, but total runtime increased from about 40 s to about 62 s, so the default remains Jacobi for this benchmark size.
    • Create CSV/VTK output directories automatically in output_csv_set_directory, including nested paths. This covers immediate path flushing when --output-interval 0 is used and no output directory exists yet; vtk_output now exercises a fresh nested output directory.
    • Fix direct displacement-control path sampling for prescribed displacements that already carry an amplitude. *BOUNDARY, AMPLITUDE=... under METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL now uses the amplitude as the displacement path instead of multiplying it by the static load_factor a second time. The Shell-4 spherical cap target is therefore linear in time again (uz = -6.2*time, not -6.2*time^2), and solver_implicit covers the amplitude regression.
    • Lower the finite-strain shell nonlinear auto-dense threshold from 1000 DOF to 250 DOF. The 486-DOF Shell-4 spherical-cap diagnostic now routes to the nonsymmetric Krylov path instead of the slow dense pivot path; the time=0.48 diagnostic improved from roughly 94 s to roughly 63 s with the same 24 accepted increments and 168 Newton iterations.
    • Add femlite --static-predictor on|off so nonlinear static predictor behavior can be audited without changing defaults. On the Shell-4 time=0.48 diagnostic it did not reduce Newton iterations, so it is not a default spherical-cap fix.
    • Audit center crown rotation constraints by running a temporary input without CROWN, 4, 6, 0.0; the curve matched the fixed-rotation run through time=0.48, so crown rotations are not the observed stiffness source.
    • Capture a time=0.48 element diagnostic after the amplitude fix: at wn ~= 14.6, Fn ~= 2.108, max membrane strain is about 4.4e-2, max bending curvature about 4.75e-1, and max transverse shear about 8.4e-3. The remaining physics mismatch is therefore still dominated by membrane/bending path behavior rather than transverse shear.
    • Resolve the remaining reference-model口径 gap before changing more production physics: the COMSOL PDF shell setup uses a selected boundary with Thickness and Offset set to Top surface on boundary and notes that the shell normal points inward, while the current all-S4 deck treats the generated spherical geometry as the shell midsurface. The PDF also describes the shell fixed constraint as a point constraint in its axisymmetric setup, while the current 3D deck fixes the full rim node set in DOF 1-6. These differences need a controlled diagnostic deck before the curve mismatch is treated as a finite-shell formulation bug. The follow-up diagnostic deck showed that top-surface offset is not the dominant scale error, while translational rim support restores the expected bounded post-peak drop.
    • Run controlled reference-scope diagnostic decks at the same wn ~= 14.60 short target. Moving the spherical shell surface outward by th/2 changed the clamped-rim response only from Fn ~= 2.108 to Fn ~= 2.066, so the COMSOL top-surface offset is not the dominant scale error. Changing the rim from full DOF 1-6 clamping to translational DOF 1-3 support softened the response to Fn ~= 1.286 (Fn ~= 1.296 with the same outward half-thickness shift), much closer to the PDF interpolation Fn ~= 1.094 at the same wn. The next benchmark decision should focus on whether the 3D cap deck should represent the PDF shell rim as translational support rather than full rotational clamping.
    • Extend the rim-translational-support diagnostic toward uz=-4.0 m. The run accepted 42 increments before the long diagnostic was stopped/ ended at time ~= 0.84, reaching wn ~= 16.48 and Fn ~= 0.920. It shows a clear post-peak load drop: the accepted path peaked at Fn ~= 1.341 near wn ~= 13.74, then decreased through Fn ~= 1.296 at wn ~= 14.52, Fn ~= 1.097 at wn ~= 15.70, and Fn ~= 0.920 at wn ~= 16.48. This confirms that the previous full-rim rotational clamping was masking the benchmark's postbuckling signature. The remaining blocker is long-path robustness/restiffening capture for the translational-rim support deck, not the absence of a limit point.
    • Solidify the benchmark support口径 before further path-control work. The generator now writes RIM_DOF_MAX=6 for the historical Shell-16 small-strain baseline and RIM_DOF_MAX=3 plus RIM, 1, 3, 0.0 for the Shell-4 finite-strain postbuckling target. The checker now requires this split and rejects accidental Shell-4 full rotational rim clamping; the example README documents why the translational-rim support is the Shell-4 target after the offset/rim diagnostic.
    • Retry the same uz=-4.0 m rim-translational-support deck with --allow-cutback. Cutback crossed the formerly failing increment 43 by reducing the time step from 0.02 to 0.005, then accepted increment 44 at time ~= 0.846875, wn ~= 16.62, Fn ~= 0.807. The run was stopped after no additional accepted row appeared over the next observation window; the next improvement should make direct-displacement cutback/adaptivity less prone to very small late-path steps or reduce the heavy GMRES work in this post-peak region.
    • Try direct-displacement adaptive stepping on the rim-translational deck with DISP_ADAPTIVE=YES, TARGET_NEWTON=12, GROWTH=1.5 and --allow-cutback. A shorter uz=-3.5 m diagnostic advanced farther than fixed cutback, accepting to time ~= 0.965, uz ~= -3.3775 m; the path retained the same post-peak drop but still stalled before the target. This suggests the right production path is adaptive direct displacement plus a post-peak linear-solver/runtime improvement, not just enabling cutback.
    • Re-run that adaptive uz=-3.5 m diagnostic with --linear-precond ilu0. ILU0 reduced post-peak GMRES iterations dramatically (typical accepted rows near time=0.80..0.965 dropped from roughly 145..266 iterations with Jacobi to roughly 20..30 with ILU0), but the run still stalled after the same accepted row at time ~= 0.965. The remaining blocker is therefore primarily nonlinear path/step acceptance around the steep post-peak branch; ILU0 is useful for runtime once that path control is improved.
    • Expose CLI line-search diagnostics: --line-search-min-alpha, --line-search-reduction, and --line-search-accept-ratio. A smoke run accepts valid values and rejects an invalid zero min-alpha. Lowering min alpha to 0.03125 with adaptive displacement, cutback and ILU0 let the uz=-3.5 m diagnostic move slightly farther, from time ~= 0.965 to time ~= 0.9675, but it remained too slow to finish. This confirms line-search damping helps but is not sufficient; the next production change should focus on more robust post-peak step-size control rather than only exposing solver knobs.
    • Expose CLI cutback diagnostics: --max-cutback and --cutback-factor now override the retry count and shrink factor for a single run without changing benchmark inputs. A compact displacement-control smoke accepts --allow-cutback --max-cutback 12 --cutback-factor 0.25 and rejects invalid --cutback-factor 1.0.
    • Run one long Shell-4 rim-translational diagnostic with the new path columns before changing path-control algorithms. With adaptive displacement stepping, ILU0, --line-search-min-alpha 0.03125, --max-cutback 16 and --cutback-factor 0.35, the 15-minute diagnostic was stopped after 39 accepted rows at time ~= 0.5469, uz ~= -3.3907 m, wn ~= 16.63, Fn ~= 0.747. The path peaked at Fn ~= 1.339 near wn ~= 13.38 and dropped by about 44 percent, so the translational-rim benchmark口径 is still producing the expected post-peak branch. The new diagnostics show the blocker is step-size collapse after repeated cutbacks (actual_dt down to about 3.75e-5), not runaway linear solves: ILU0 linear iterations peaked at 115 and ended at 52 with relative residual around 5e-9.
    • Run a compact cutback-factor comparison before changing defaults. Keeping the same rim-translational Shell-4 setup and diagnostics, --cutback-factor 0.5 reached essentially the same post-peak point (wn ~= 16.63, Fn ~= 0.754) within the observation window but retained a larger final step (actual_dt ~= 6.25e-4, two cumulative cutbacks and max linear iterations 36). A more conservative --cutback-factor 0.7 retained an even larger accepted step (actual_dt ~= 1.75e-3) but moved fewer rows in the same time and pushed the last linear solve to about 111 iterations. This confirms the next production change should not be a fixed cutback factor default; it should be a guarded post-cutback recovery/growth policy that avoids both collapse to tiny increments and expensive over-large retries.
    • Try and reject an immediate/two-stage post-cutback recovery gate. The immediate version grew the accepted 0.00125 post-cutback step to 0.00153 and then produced no additional accepted row in the same observation window; the delayed two-stage version avoided that premature growth but still stopped at the same accepted row (time ~= 0.54625, wn ~= 16.61) and did not outperform the plain --cutback-factor 0.5 diagnostic. The production change was therefore reverted. The remaining path-control issue likely needs a more deliberate continuation strategy around the steep post-peak branch, not a local growth gate.
    • Add and probe an explicit trust-region diagnostic for direct displacement-control ARC_DISP paths. A positive TRUST_RADIUS on the continuation line, or CLI --trust-radius, now reuses the existing damped Newton correction limiter while keeping ARC_DISP path output; default ARC_DISP remains unchanged. Compact tests cover parsing, CLI validation and a direct-displacement path with trust enabled. Spherical-cap probes showed --trust-radius 0.05 was too conservative, accepting many small rows but only reaching about wn ~= 11.94 in the observation window. A looser --trust-radius 0.2 removed cutbacks and held dt ~= 0.0025 through wn ~= 16.58, but still did not outperform the plain --cutback-factor 0.5 run within the same wall-clock window. Keep this as a controlled diagnostic, not a default fix.
    • Extend continuation path output with trust-region diagnostics: trust_radius, next_trust_radius, trust_damping, trust_merit_ratio, trust_adjust and trust_rejections. The spherical cap checker carries these through to spherical_cap_load_displacement.csv, so future trust probes can distinguish "stable but slow because heavily damped" from ordinary step-size or linear-solver stalls.
    • Re-run a looser trust diagnostic with the new trust output columns. --trust-radius 0.4 reached time ~= 0.54625, wn ~= 16.61 and Fn ~= 0.816 with one cumulative cutback and max linear iterations 36. The trust columns showed no actual correction damping on accepted rows (trust_damping = 1.0), only radius adjustment near the last accepted increment (trust_radius ~= 0.0225, next ~= 0.03375). This makes the result useful diagnostically but not a better fix than the plain --cutback-factor 0.5 run, which reached a slightly farther/lower post-peak point in the same diagnostic window.
    • Start the explicit default continuation-path改造 instead of continuing local parameter probes. Direct prescribed-displacement ARC_LENGTH_OR_DISPLACEMENT_CONTROL now defaults to adaptive path spacing, and accepted path rows feed back into the next step size: if the generalized reaction changes by more than about 8 percent over the last accepted path segment, the next displacement increment is capped before the following Newton solve. The direct-displacement path also uses a relaxed default internal Newton target of 12 when the input keeps the historical default TARGET_NEWTON=6, so accepted 4-6 iteration steps can grow instead of staying stuck at an early limited step. In a 90 s Shell-4 spherical-cap observation window, the old default adaptive behavior produced 163 accepted rows by time ~= 0.5435 with dt ~= 0.0031; the new default reached the same post-peak region in 30 accepted rows by time ~= 0.5342, with no cutbacks and next_dt ~= 0.0146. The remaining cost is high late GMRES iteration count, not path fragmentation.
    • Test two follow-up post-peak path-control ideas and reject them as insufficient: keeping the accepted small step immediately after a cutback did not move the uz=-3.5 m diagnostic beyond the previous stalled region, so that production change was reverted; enabling the existing static predictor changed the accepted substep pattern but again stalled around time ~= 0.9675. The remaining work now requires a deliberate path-control design choice rather than another local parameter tweak.
    • Record the remaining full-curve limits in README/user docs instead of treating them as V5 release blockers: full uz=-6.2 m runtime, strict PDF mid-path scale matching, later restiffening capture and late GMRES cost.
  • Tests:
    • Checker validates the V5 bounded post-peak load-drop capability and writes the current curve metrics to spherical_cap_load_displacement.csv.
    • Checker records but does not require strict Shell-4/8/16 PDF digitized curve matching in this release.
    • Checker fails monotone curves, small-strain samples, and old corotational diagnostic decks.
  • Acceptance:
    • example_spherical_cap_point_load_benchmark validates the fast Shell-16/Shell-4口径 checks, and the documented extended nonlinear checker validates the bounded V5.11 finite-strain S4 postbuckling capability while documenting deferred full-curve limitations.
  • Current evidence:
    • cmake -S . -B build-codex-gcc -G "MinGW Makefiles" configured the current E:\Codex\FemLite checkout with GCC/GFortran 16.1.0.
    • cmake --build build-codex-gcc --target femlite test_shell_finite_kinematics test_shell_finite_tangent test_shell_finite_element test_shell_internal test_implicit_inp passed after the solver-dispatch changes.
    • ctest --test-dir build-codex-gcc -R "^(shell_finite_kinematics|shell_finite_tangent|shell_finite_element|shell_internal|implicit_inp)$" --output-on-failure passed 5/5.
    • python tools/testing/check_source_size.py . --warn-file-lines 1500 --max-file-lines 2000 --warn-routine-lines 100 --max-routine-lines 128 --exceptions tests/source_size_exceptions.txt passed.
    • After adding the direct-displacement trust diagnostics and path output columns, ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|example_spherical_cap_point_load_benchmark)$" --output-on-failure passed 3/3, and the direct source-size check passed with only the existing review warnings.
    • After rewriting the V5 release scope, the default spherical-cap benchmark passed with ctest --test-dir build-codex-gcc -R "^example_spherical_cap_point_load_benchmark$" --output-on-failure. The extended bounded nonlinear checker passed with FEMLITE_SPHERICAL_CAP_NONLINEAR=1, 54 accepted increments, final wn=15.89482, final Fn=1.058395, and sampled Fn=1.340817 at wn=13.642, proving a reproducible post-peak load drop without claiming full uz=-6.2 m PDF curve reproduction.

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

  • Implementation:
    • Update benchmark matrix with the bounded V5.11 spherical-cap acceptance: finite-strain S4 production path, translational-rim Shell-4 target, post-peak load-drop evidence, continuation diagnostics and deferred strict PDF full-curve matching.
    • Update acceptance report with exact commands, dates, curve metrics, Newton/cutback counts, path-control metrics and known limits.
    • Remove obsolete corotational/old shell tangent documentation references after code removal.
    • Add a next-version backlog note for full uz=-6.2 m PDF matching, pseudo-arclength/branch following and late post-peak GMRES optimization.
  • 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 release-ready when implementation, tests, docs, and benchmark evidence all align with the bounded V5 release claim and all full-curve limitations are explicitly deferred.

V5.12 V5 Development Plan Open Backlog

Boundary for this module:

  • V5.12 is the next-version backlog and does not block the V5.11 release-ready checkpoint.
  • 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.

[x] DONE V5.12-1: Finish examples/two_arches single reference-point check

  • Source:
    • docs/v5_development_plan.md now marks examples/two_arches as PASS / 0.5.2.
    • Completed coverage now has two explicit layers: a geometry/contact smoke and a single displacement reference-point check at para = 0.02.
    • Scope correction on 2026-07-01: the COMSOL reference uses a parametric sweep, but FemLite V5 does not introduce a general parametric-sweep feature. V5.12-1 only needs one representative displacement reference point, not the complete sweep, a static edge-load solve or a full static path reproduction.
  • Implementation:
    • Split the current two-arches status into completed geometry/contact smoke coverage and a separate single reference-point check. The README and checker output now describe the existing case as a smoke check rather than a full reference-result pass.
    • 2026-06-30 diagnostic note: a direct static displacement-control conversion of the current micro-step deck was tried as a temporary probe, including a reduced contact penalty and an additional upper-end vertical constraint variant. Both runs reached the prescribed midpoint displacement but produced nonphysical residual/reaction magnitudes, so that temporary route cannot be used as single-point reference evidence.
    • Keep the default dynamic micro-step as geometry/contact binding regression, and use a separate run_two_arches_reference_point.py driver to generate the selected displacement reference-point evidence.
    • Use disp_upper as the upper-arch midpoint vertical displacement and max_disp = 60 mm. The single reference point uses para = 0.02, so the target displacement is 1.2 mm. This is an input/checker reference value, not a FemLite parameter-sweep feature.
    • 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 smoke-scope in-plane constraints, lower-end fixed constraints, out-of-plane y constraints and prescribed upper-midpoint displacement.
    • Do not add a V5 parameter-sweep or static edge-load requirement. The selected V5 reference point is the documented upper-midpoint displacement disp_upper = -1.2 mm.
    • Use frictionless shell-shell contact with upper arch as source/slave and lower arch as destination/master.
    • Output two_arches_reference_point.csv with para, disp_upper, reference mode, active contact count, max gap/penetration, contact force, residual and run status.
  • Tests:
    • Keep examples/two_arches/check_two_arches_results.py as a geometry/contact smoke checker and make its pass message explicit.
    • Add a separate reference-point checker that rejects parameter-sweep, static edge-load and non-displacement-control evidence for this V5 point.
    • Verify geometry coordinates, 30/75 mesh counts, the 1.2 mm midpoint displacement, active contact and bounded dynamic displacement for the smoke route.
    • Verify material values, disp_upper=max_disp*para residual, contact active set, bounded gap, nonnegative/bounded contact work and downward displacement sign. The checker now accepts exactly one final reference point rather than a parameter sweep.
    • Add a lightweight CTest entry for the optional reference-point deck: example_two_arches_reference_point_prepare validates displacement reference deck generation and two_arches_reference_point.csv schema.
    • Execute the optional single reference-point run to convergence and record the check_two_arches_reference_point.py PASS evidence through example_two_arches_reference_point and example_two_arches_reference_point_check.
      • 2026-06-30 probe: para=0.02, one outer solve, ILU0 preconditioner, static predictor on, initial_dt=0.10, max_dt=0.20 and a 90 s solve timeout still produced no accepted nodal output.
      • 2026-06-30 follow-up: --trace-nonlinear localized the first static edge-load cost to nonlinear linear solves. The default CG path repeatedly falls through to the 1284-DOF dense/regularized fallback, taking roughly 9-10 s per correction. The CLI and optional driver now expose --linear-solver; the single-point driver defaults to GMRES and records failure diagnostics parsed from stdout when no history.csv or nodal output exists.
      • 2026-06-30 follow-up probes with one-step tiny edge load (initial-load=-1e-3, initial_dt=max_dt=1.0) showed that GMRES avoids the dense fallback but still ends in cutback failure before a complete static solve (accepted_time about 0.044 to 0.140 depending on tolerance). BiCGSTAB/ILU0 failed earlier with a large correction norm, and dense solve reported a singular pivot.
      • 2026-07-01 scope decision: V5 does not need the static edge-load solve for this example. The accepted V5 reference is the single displacement point already present in the PDF-derived input, with independent reference-point CSV/checker evidence.
  • Acceptance:
    • examples/two_arches has a bounded geometry/contact smoke route that passes without claiming the full COMSOL sweep.
    • examples/two_arches passes a single displacement reference-point checker without relying on static edge-load convergence.
    • The checker compares the selected result fields against the documented reference point from models.sme.two_arches.pdf.

[x] DONE V5.12-2: Close scoped mortar / AL contact gaps for V5

  • Source:
    • V5.3 remains PARTIAL in docs/v5_development_plan.md; V5.12-2 closes the bounded V5 hardening scope and explicitly defers the full production AL/mortar tangent rewrite to a later version.
  • Implementation:
    • Do not claim complete industrial-grade AL/mortar consistent tangent behavior for nonlinear contact paths in V5. The production contact tangent still uses the current compact ktan block; replacing it with the full fem_contact_mortar_tangent audit matrix is a later high-risk contact solver redesign item.
    • Expand restart coverage beyond current active/released/open multiplier audits where the development plan still calls for more scenarios.
      • test_restart now preserves and audits contact friction history stick/slip state counts in addition to slots, accumulated slip, friction work and tangential force.
    • Add a larger OpenMP contact path benchmark: perf_contact_pair accepts a third path_steps argument, and perf_contact_pair_omp_consistency now compares a 64-facet, 4-step force/tangent/cache path under 1/4 OpenMP threads.
    • Clarify node-based surface to general element master support: V5 now explicitly defers node-to-element-master contact pair support, documents the boundary and rejects TYPE=NODE slave with element master at model build time. tests/data/s4_node_surface_element_master.inp and implicit_inp cover the failure path.
  • Tests:
    • Add V5-scope contact hardening tests with force, tangent, restart and OpenMP consistency checks.
      • OpenMP force/tangent/cache path consistency is covered by perf_contact_pair_omp_consistency.
    • Ensure internal BiCGSTAB/GMRES paths expose true status for nonsymmetric or difficult tangent systems instead of hiding failures: linear_solver_cg now forces BiCGSTAB/GMRES nonconvergence through the dispatcher and checks LS_STATUS_FAILED, method/preconditioner, final residual and relative residual diagnostics.
  • Acceptance:
    • Contact mainline is closer to a production constraint solve, with documented convergence diagnostics, restart continuity and OpenMP path consistency. Full industrial AL/mortar nonlinear long-path tangent convergence is not claimed by V5 and remains deferred.

[x] DONE V5.12-3: Close scoped Mohr-Coulomb structural workflow gaps for V5

  • Source:
    • V5.4 and examples/strengthReduction are scoped as FOS PASS for V5: the delivered benchmark is the Mohr-Coulomb strength-reduction FOS curve, plastic-zone probes, displacement probes and nonlinear diagnostic schema.
    • The 0.75 m FOS = 1.525 displacement/eqps cloud is a large critical-instability validation problem. Its cost is inherent to the benchmark and it is not a V5 delivery target.
  • 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:
    • Keep V5 delivery at the FOS-curve and diagnostic-schema level for examples/strengthReduction; do not require the full critical-instability displacement/eqps cloud as release evidence.
    • Audit and document the Mohr-Coulomb engineering tangent in structural solves through convergence status, continuation diagnostics and substep counts.
    • Defer structure-level automatic trial re-solve and nonlinear instability criteria for full critical-instability cloud workflows to a later version.
    • 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.
      • Do not treat reducing method-1 cost enough for the full 0.75 m critical-instability cloud as a V5 requirement; keep the route as an optional diagnostic and defer full longrun validation.
    • 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 direct displacement-control path on a real nonmonotonic structure case: the bounded Shell-4 spherical-cap nonlinear checker uses ARC_LENGTH_OR_DISPLACEMENT_CONTROL, writes continuation_path.csv, verifies zero displacement constraint residual, samples generalized reaction, and rejects monotone/small-strain curves by requiring a post-peak load drop.
      • Prove the load-type Riks branch of method 4 on a real structure limit-point neighborhood: FEMLITE_SPHERICAL_CAP_RIKS=1 converts the Shell-4 spherical-cap target to proportional crown CLOAD, runs the production Riks augmented equation, writes spherical_cap_riks_load_path.csv and verifies an interior load-parameter peak followed by a load drop while displacement continues to grow.
      • Improve load-type Riks branch following beyond the local limit-point neighborhood. The Riks predictor now keeps a saved accepted augmented direction and chooses the next predictor sign to continue that direction, removing the local two-state oscillation on the Shell-4 spherical-cap route and advancing down a post-limit branch segment.
      • Defer broader load-type Riks branch-following generalization to the next-version backlog instead of blocking the current V5.12 checkpoint. A pinched-hemisphere screening probe remained monotonic through the accepted range, while the remaining block-on-arch route would couple the continuation question with contact snap-through. Current evidence is therefore scoped to the spherical-cap real shell limit point and post-limit branch segment.
    • 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.
      • Do not require a 0.75 m critical-instability cloud longrun proof for NC-5 in V5. NC-5 is accepted here as material-point and structure-level diagnostic hardening; full cloud-effect proof is deferred.
    • 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 in optional nonlinear cloud summaries.
    • Defer checker coverage for full-cloud equivalent plastic strain behavior until the later critical-instability validation track.
    • 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 target-cloud probes report reproducible nonlinear/material status instead of ambiguous partial results when optional diagnostics are requested.
    • Strength reduction remains a documented Mohr-Coulomb FOS benchmark in V5, with optional nonlinear structural diagnostics; full critical-instability displacement/plasticity evidence is not part of this version's delivery claim.
  • 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.
    • Cloud summary/checker now records and validates a 0.3 m reference displacement scale plus max_displacement / 0.3 m scale ratio, so optional probes cannot be mistaken for accepted critical-instability cloud matches without a quantitative displacement-scale field.
      • 2026-07-01 verification: build-codex-gcc\strength_reduction_benchmark.exe examples\strengthReduction\strength_reduction_slope_static.inp build-codex-gcc\strength_reduction_v5123_cloud_scale_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 generated strength_reduction_cloud_summary.csv with reference_displacement_scale=0.3, displacement_scale_ratio=0.0, nodes=13776 and elements=6645; the optional cloud checker accepted the diagnostic FAILED summary as a reproducible non-ambiguous trial.
    • The strengthReduction checker now rejects stale result_00000001.vtk files, so the old linear-static gravity precheck output cannot be used as nonlinear cloud evidence.
      • 2026-07-01 negative smoke: python examples\strengthReduction\check_strength_reduction_results.py build-codex-gcc\strength_reduction_linear_vtk_reject_smoke failed as expected with linear-static result_00000001.vtk is not valid nonlinear-cloud evidence.
    • 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; the full critical-instability cloud is deferred outside V5 instead of being treated as a release blocker.
  • 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.
    • The bounded Shell-4 spherical-cap nonlinear checker now provides the first real nonmonotonic structure evidence for the direct displacement-control branch: FEMLITE_SPHERICAL_CAP_NONLINEAR=1 runs the finite-strain S4 deck to uz=-3.24 m, writes continuation_path.csv and spherical_cap_load_displacement.csv, verifies the accepted displacement path and requires a post-peak generalized-reaction load drop. This closes the bounded direct-displacement evidence, while the load-type Riks evidence is tracked separately below.
    • The same checker now has an optional load-control Riks route via FEMLITE_SPHERICAL_CAP_RIKS=1. On 2026-06-30 it passed with 80 accepted increments, peak_lambda=0.6909629, final_lambda=0.6017746 and final displacement magnitude 1.3973472 m, proving a real finite-strain S4 limit-point and post-limit branch segment after adding predictor direction memory. Broader branch-following generalization on a second independent nonmonotonic structure is explicitly deferred to the next-version backlog.
    • 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.

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

  • Source:
    • V5.5 and examples/buckling_corrugated_shell remain PARTIAL by design: V5 now delivers a bounded production subset and defers the large shell / harmonic-wave / high-fidelity expansion to the next version line.
  • 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.
    • Add a main INP parser guard for generic *BUCKLING: the parser records a buckling analysis type and no longer falls through to static or dynamic analysis.
    • Add a small-scale dense generic *BUCKLING main-solver path for already assembled linear elastic K plus the limited *BUCKLING GEOMETRIC LINE truss-style K_G subset.
    • Add the first static-preload-to-buckling main-solver bridge: when a *STATIC step precedes *BUCKLING, run a linear static preload, update element stress/internal force state, then solve the current dense buckling subset.
    • Add the first preload-derived geometric stiffness subset: *BUCKLING GEOMETRIC LINE, PRELOAD projects host solid element stress onto the line direction, multiplies by the supplied area and assembles the truss-style K_G.
    • Add the first production element preload geometric stiffness subset: when *STATIC precedes *BUCKLING and no explicit geometric line is supplied, assemble C3D4/C3D8 solid initial-stress K_G from the preloaded element stress state.
    • Defer full preload-to-buckling *BUCKLING for shell production models and higher-order solid elements to post-V5. V5 delivery is bounded to explicit geometric lines, preload-derived line K_G, and C3D4/C3D8 solid initial-stress K_G.
    • Defer shell geometric stiffness and higher-order solid geometric stiffness after static preload to post-V5.
    • Integrate generic buckling modal output with the normal output workflow.
    • Bring the first cyclic sector constraint subset into the main solve path: *CYCLIC SYMMETRY accepts explicit master/slave node pairs and expands WAVE=0 sector rotation into MPC equations for 3-DOF solid nodes and 6-DOF shell nodes, including shell rotational DOF mapping.
    • Defer automatic cyclic boundary node pairing and nonzero harmonic-wave main-solver semantics to post-V5.
    • Defer full shell FE preload-buckling high-fidelity corrugated-shell coverage to post-V5.
  • 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 parser and small dense CLI solve tests.
    • Add static-preload-to-dense-buckling CLI smoke coverage.
    • Add static-preload-to-dense-buckling tests and cyclic sector shell/solid mapping tests.
    • Add C3D4 solid initial-stress preload-to-buckling CLI smoke coverage.
    • Defer full shell and higher-order solid preload-to-buckling tests to post-V5 with the corresponding algorithms.
    • 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 small dense generic *BUCKLING workflow through normal INP input when K_G is supplied by *BUCKLING GEOMETRIC LINE.
    • Users can run a linear static preload immediately before the small dense generic buckling subset.
    • Users can run a small C3D4/C3D8 solid preload-to-buckling workflow without manually supplying *BUCKLING GEOMETRIC LINE.
    • Defer general shell preload-to-buckling workflow through normal INP to post-V5; V5 explicitly supports the bounded solid/line subsets above.
    • WAVE=0 cyclic sector constraints work through the main solver path for explicit solid and shell node pairs.
  • 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.
    • 2026-07-01 small dense generic buckling evidence: ctest --test-dir build-codex-gcc -R "^(implicit_inp|cli_buckling_generic_dense|cli_buckling_static_preload_dense|buckling_support|example_euler_column_buckling_benchmark)$" --output-on-failure passed 5/5. cli_buckling_generic_dense now runs through a nested --output-dir and verifies buckling_summary.csv plus buckling_modes.csv are written by the normal output-directory workflow. femlite tests\data\c3d4_buckling_static_preload.inp --output-dir build-codex-gcc\manual_buckling_static_preload completed the preload bridge with first load factor 3.33333E-01 and residual 2.22045E-16.
    • 2026-07-01 corrugated benchmark regression evidence: ctest --test-dir build-codex-gcc -R "^example_buckling_corrugated_shell_benchmark$" --output-on-failure passed 1/1 and remains labeled v5_acceptance.
    • 2026-07-01 cyclic main-solver evidence: ctest --test-dir build-codex-gcc -R "^(implicit_inp|cyclic_symmetry|cli_buckling_generic_dense|cli_buckling_static_preload_dense|buckling_support|example_euler_column_buckling_benchmark|example_buckling_corrugated_shell_benchmark)$" --output-on-failure passed 7/7. implicit_inp covers *CYCLIC SYMMETRY expansion into MPC equations for a C3D4 3-DOF solid pair and an S4 6-DOF shell pair.
    • 2026-07-01 solid initial-stress buckling evidence: ctest --test-dir build-codex-gcc -R "^(implicit_inp|cyclic_symmetry|cli_buckling_generic_dense|cli_buckling_static_preload_dense|cli_buckling_solid_preload_dense|buckling_support|example_euler_column_buckling_benchmark|example_buckling_corrugated_shell_benchmark)$" --output-on-failure passed 8/8. femlite tests\data\c3d4_buckling_solid_preload.inp --output-dir build-codex-gcc\manual_buckling_solid_preload completed with first load factor 1.66667E+00, preload residual 0.00000E+00 and modal residual 0.00000E+00.

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

  • Source:
    • V5.6 and examples/roll_forming remain PARTIAL.
  • V5 decision:
    • Defer the production roll-forming workflow to post-V5.
    • Keep roller kinematics and compact J2 springback benchmarks as regression evidence only.
    • Do not claim full 3D workpiece rolling, restart-driven multi-step forming, unloading/springback production workflow, or longrun stability in V5.
  • Rationale:
    • This is an independent manufacturing process workflow with rigid roller kinematics, contact/friction, plastic forming, restart staging and longrun validation. It is too large to add safely during V5 close-out.

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

  • Source:
    • V5.7 and examples/ball_adhesion_decohesion remain PARTIAL.
  • V5 decision:
    • Defer production cohesive-contact integration to post-V5.
    • Keep cohesive law/state/metrics tests and the compact ball-adhesion benchmark as bounded regression evidence only.
    • Do not claim ordinary-contact/cohesive switching, cohesive contact tangent, full restart history integration, or full ball-membrane FE cohesive long path in V5.
  • Rationale:
    • This changes the main contact workflow, tangent assembly and restart persistence. It should be developed with a dedicated contact-integration plan rather than added during V5 close-out.

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

  • Source:
    • docs/v5_development_plan.md lists several example directories as DEFERRED or PARTIAL.
  • V5 decision:
    • Defer high-fidelity upgrades for shell_solid_connection, buckling_corrugated_shell, roll_forming, ball_adhesion_decohesion and larger particle-container longruns to post-V5.
    • Keep current compact benchmarks and smoke tests only as regression coverage.
    • Do not list compact surrogate, fallback or smoke-only examples as V5 PASS.
  • Rationale:
    • These examples depend on the larger deferred algorithms above. Upgrading the examples before the production algorithms would create misleading acceptance evidence.

[x] DEFERRED 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.
  • V5 decision:
    • Defer the larger longrun matrix, full performance matrix and multi-platform longrun records to post-V5.
    • Keep the completed source-size governance and targeted behavior regression as V5 close-out evidence.
    • Do not keep broad longrun/performance expansion on the V5 must-complete list.
  • Implementation:
    • Defer longrun tiers for contact, Mohr-Coulomb, buckling, roll forming, cohesive contact and particle-container coupling to post-V5.
    • Defer memory, iteration, residual, timing and platform stability metric collection for broad longruns to post-V5.
    • Update docs/v5_benchmark_matrix.md only when new longrun/performance tests are formalized after V5.
    • 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.
    • Defer any further review-target cleanup on other large production modules where it clarifies ownership and preserves full algorithms, especially fem_element_internal and benchmark tool files, to the next normal engineering cycle; do not keep it as a V5 release blocker.
      • 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:
    • Defer documented extended commands for broad longrun/performance suites until those suites are formalized after V5.
    • Re-run relevant Windows GCC, Windows Intel/MSVC and WSL GNU subsets when longrun coverage changes after V5.
    • 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.
    • Run V5 close-out regression for the completed subset. Completion evidence on 2026-07-01: ctest --test-dir build-codex-gcc -R "^(implicit_inp|cyclic_symmetry|cli_buckling_generic_dense|cli_buckling_static_preload_dense|cli_buckling_solid_preload_dense|buckling_support|example_euler_column_buckling_benchmark|example_buckling_corrugated_shell_benchmark)$" --output-on-failure passed 8/8, and ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure passed 39/39.
  • Acceptance:
    • V5 keeps the current targeted regression and source-size governance as close-out evidence.
    • Broad performance and longrun coverage is explicitly deferred and is not a V5 must-complete acceptance item.