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

130 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FemLite V5 Benchmark And Acceptance Matrix
日期:2026-06-26
本文档记录当前 V5 已完成能力对应的测试入口、示例目录、参考指标和容差。
状态标记仍只维护在 `docs/v5_development_plan.md`;本文件只给出可执行验收矩阵。
## 2026-07-01 V5.12 Close-Out Note
This matrix records executable V5 acceptance entries for the bounded delivery
subset. It does not treat deferred high-fidelity production workflows as V5
acceptance failures.
Included in the V5 close-out subset: selected `two_arches` reference-point
coverage, bounded spherical-cap continuation/Riks evidence, compact
Mohr-Coulomb strength-reduction diagnostics, Euler and compact corrugated
buckling checks, small dense generic `*BUCKLING`, static-preload-to-buckling for
explicit line and C3D4/C3D8 solid initial-stress `K_G`, WAVE=0 explicit-pair
cyclic symmetry for solid/shell nodes, compact roll-forming and cohesive
benchmarks, and source-size governance regression.
Excluded from V5 acceptance and deferred after V5: full shell preload-buckling
geometric stiffness, higher-order solid geometric stiffness, full shell FE
corrugated preload buckling, automatic cyclic pairing, nonzero harmonic-wave
cyclic semantics, production roll-forming workflow, production cohesive contact
workflow, high-fidelity example upgrades dependent on those algorithms, and
broad longrun/performance matrices.
Current local V5.12 targeted regression evidence on `build-codex-gcc`: the
bounded buckling/cyclic subset command with `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`, and
`example_buckling_corrugated_shell_benchmark` passed 8/8.
Current local V5 acceptance subset evidence on `build-codex-gcc`:
`ctest --test-dir build-codex-gcc -L v5_acceptance --output-on-failure` passed
39/39.
Current local 0.5.3 diagnostic evidence on `build-codex-gcc`:
- `cmake --build build-codex-gcc --parallel` passed.
- `ctest --test-dir build-codex-gcc -R "^(solver_implicit|implicit_inp|linear_solver_cg|restart|contact_mortar_report|contact_mortar_tangent|contact_multiplier_report|perf_contact_pair_omp_consistency)$" --output-on-failure` passed 8/8.
- `ctest --test-dir build-codex-gcc -R "^(example_contact_two_blocks_compression_benchmark|example_contact_block_sliding_benchmark|example_shell_shell_contact_benchmark|example_shell_solid_contact_benchmark)$" --output-on-failure` passed 4/4.
## 测试层级
| 层级 | 用途 | 推荐命令 |
|---|---|---|
| 默认回归 | 快速确认全部单元、模块、CLI、示例和 benchmark 不回退 | `ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` |
| V5 验收子集 | 只运行当前 V5 已完成能力的核心测试和 benchmark | `ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure` |
| 示例 benchmark | 只运行带 benchmark 标签的示例级检查 | `ctest --test-dir build-win-gcc-16 -C Release -L benchmark --output-on-failure` |
| 定向调试 | 调试单个能力或相邻能力 | `ctest --test-dir build-win-gcc-16 -C Release -R "<test-name>" --output-on-failure` |
默认回归当前 Windows GCC 16 Release 记录为 `106/106 passed`。V5 验收子集
当前记录为 `35/35 passed`。
## 多平台复测矩阵
| 平台 | 构建目录 | 工具链 | 默认 CTest | V5 验收子集 | 备注 |
|---|---|---|---|---|---|
| Windows GCC | `build-win-gcc-16` | GNU Fortran 16.1.0 | 106/106 passed | 35/35 passed | 20.1 clean clone 和 20.2 后本地回归均通过 |
| WSL GNU | `build-wsl-gfortran-v5-20-2` | GNU Fortran 13.3.0、GNU C 13.3.0、CMake 3.28.3 | 106/106 passed | 35/35 passed | benchmark 工具已修正跨平台路径分隔符 |
| Windows Intel/MSVC | `build-win-ifx-v5-20-2` | VS DevCmd 17.14.33、MSVC 19.44.35227.0、IntelLLVM ifx 2026.0.0 | 106/106 passed | 35/35 passed | CTest 环境优先加载 ifx compiler runtime;Mohr-Coulomb 边界分类容差已稳定 |
| Windows GCC OpenMP | `build-win-gcc-16` | GNU Fortran 16.1.0,OpenMP enabled | `contact_omp1`、`contact_omp4`、`perf_contact_pair_omp_consistency` 3/3 passed | n/a | 1/4 线程 contact/performance smoke 非计时统计一致;`perf_contact_pair_omp_consistency` 当前覆盖 64 面片 4 步 force/tangent/cache 路径 |
## V5 验收矩阵
| V5 项 | 能力 | 目录或模块 | CTest 名称 | 参考指标 | 容差/验收条件 |
|---|---|---|---|---|---|
| V5.2 | 内部 solver 诊断、no-external-solver 策略 | `src/solver`, `tests/module`, `tests/interface` | `linear_solver_cg`, `csr_diagnostics`, `solver_implicit`, `implicit_inp`, `c_api`, CLI implicit/static tests | CG/BiCGSTAB/GMRES/dense pivoting、残差、CSR matrix class、legacy external id rejection、非线性修正 fallback | 旧外部 method/backend id 被拒绝且不改变设置;静力、隐式和非线性路径通过内部 solver dispatch;非线性修正可在内部求解器间 fallback 且恢复用户设置 |
| V5.3 | 非匹配实体 mortar 压缩 | `examples/contact_two_blocks_compression` | `example_contact_two_blocks_compression_benchmark` | `pressure_profile.csv`, active contact, master coverage, weighted gap, multiplier residual, state/status, active-set flip, gap mean/L2, augmentation diagnostics | 多 master facet 覆盖;weighted penetration、gap norm、state count、active-set flip 和 multiplier/augmentation diagnostics 在 checker 容差内;VTK 输出存在 |
| V5.3 | 大滑移 mortar-friction | `examples/contact_block_sliding` | `example_contact_block_sliding_benchmark` | `sliding_profile.csv`, stick/slip, accumulated slip, tangential force, friction work, slip/friction residuals, gap L2, augmentation diagnostics | 多 master/active candidate;累计滑移和摩擦功为正且非负耗散;slip/friction/gap/augmentation diagnostics 存在且内部一致;VTK 输出存在 |
| V5.3 | shell-shell contact | `examples/shell_shell_contact` | `example_shell_shell_contact_benchmark` | contact profile, active contact, force norm, gap residual, augmented multiplier, state/status, active-set flip, failed projection count | active contact 大于零;gap/force/multiplier/state/flip/projection 指标通过 checker |
| V5.3 | shell-solid contact | `examples/shell_solid_contact` | `example_shell_solid_contact_benchmark` | contact profile, master search, shell-to-solid force transfer, state/status, active-set flip, gap L2, failed projection count, augmentation diagnostics | active contact 大于零;master search、nodal force 和 shared diagnostic 指标通过 checker |
| V5.3 | 接触状态、restart、非线性诊断和并行路径连续性 | `tests/module`, `tests/performance` | `contact_mortar_al`, `contact_mortar_iter`, `contact_mortar_report`, `contact_mortar_tangent`, `contact_multiplier_report`, `restart`, `solver_implicit`, `implicit_inp`, `linear_solver_cg`, `perf_contact_pair_omp_consistency` | failure reason taxonomy, residual breakdown API/path CSV, AL multiplier, tangent audit split, contact report diagnostics, restart v4 restored diagnostics, 64 面片 4 步 OpenMP path stats | nonlinear/contact failure reason 与 residual breakdown 被测试消费;contact state/gap/slip/friction/multiplier/augmentation diagnostics 在 report/checker 中消费;restart 后接触诊断连续;normal/stick/slip tangent audit 分开报告;OpenMP 1/2/4 线程下 force/tangent/cache/state/residual 路径非计时统计一致 |
| V5.4 | Mohr-Coulomb 材料点 | `tests/unit` | `material_mohr_coulomb`, `material_mc_driver`, `material_mc_envelope` | 三轴压缩/伸展、纯剪、张拉截断、branch id、plastic multiplier | yield margin、分支号、塑性增量和 envelope safety ratio 通过测试容差 |
| V5.4 | Mohr-Coulomb 屈服面算例 | `examples/mohr_coulomb_yield_surface` | `example_mc_yield_surface_benchmark` | `yield_surface.csv`, `yield_points.csv`, `yield_summary.csv`; 原始材料和 `F=2` 折减材料 | 压缩包络、伸展包络和张拉截断符合解析公式;强度折减降低承载力;elastic/shear/tension/mixed 分支全部被代表性应力点激活 |
| V5.4 | Mohr-Coulomb 边坡强度折减 benchmark | `examples/strengthReduction` | `example_strength_reduction_benchmark` | 8 个参考工况,最大 FOS 误差 `6.9392E-03`,86 trials,52 stable,34 unstable;`--nonlinear-chain` 可选输出真实 FE trial、cutback、accepted-time 和线性求解诊断;`--nl-write-cloud` 可选输出目标 FOS 云图 summary 与 VTK;0.75 m cloud route 支持内部 BiCGSTAB/ILU0、静力 predictor、自适应跳步和 accepted segment 后 VTK 刷新 | 0.75 m 网格和参考几何记录;输入使用原生实体 `DLOAD, GRAV`;上下土体界面必须为共享节点 conforming mesh;FOS 曲线在 0.02 容差内;FOS 随坡角单调降低;关联工况不弱于 Davis B 工况;plastic zone 和 displacement probe 激活;optional nonlinear chain 不伪造 VTK;optional partial/target cloud VTK 必须含 displacement/eqps 字段且网格计数匹配;0.75 m 临界失稳位移/eqps 云图属于后续 longrun/研究验证,不作为 V5 交付验收项 |
| V5.5 | Euler column 解析屈曲 | `examples/euler_column_buckling` | `example_euler_column_buckling_benchmark` | first load relative error `3.27660856E-05`, residual `1.50014805E-11`, `phi^T K_G phi=1` | 相对误差、残差和几何刚度归一化通过 checker |
| V5.5 | 波纹壳循环屈曲 benchmark | `examples/buckling_corrugated_shell` | `example_buckling_corrugated_shell_benchmark` | selected wave 4 load `453.031407`, critical wave 8 load `393.369677`, cyclic/full relative error `1.25473461E-16` | 循环边界残差、模态残差、wave sweep 和 modal CSV 通过 checker |
| V5.5 | 屈曲/循环模块 | `tests/module`; CLI | `buckling_support`, `cyclic_symmetry`, `implicit_inp`, `cli_buckling_generic_dense`, `cli_buckling_static_preload_dense`, `cli_buckling_solid_preload_dense` | geometric stiffness helper, cyclic map residual, small dense generic `*BUCKLING` solve, WAVE=0 cyclic MPC expansion, C3D4/C3D8 solid initial-stress KG | 内部 dense 特征值、Euler helper、周期映射、通用 buckling 小规模 dense 路径、预载派生线 KG、实体 initial-stress KG 和实体/壳 cyclic 映射通过模块/CLI 容差 |
| V5.6 | 辊运动学和正则化牵引 | `examples/roll_forming` | `example_roll_forming_kinematics_benchmark`, `rigid_roller` | mean slip `0.4` with spin vs `0.2` without spin; mean traction `289.208274` vs `228.478247`; torque `14.4604137` | 有/无角速度路径必须产生不同 slip/traction;摩擦能和扭矩为正 |
| V5.6 | 塑性成形和回弹 benchmark | `examples/roll_forming` | `example_roll_forming_springback_benchmark` | springback ratio `0.473154068`, residual displacement `0.0316107559`, plastic work `1.11591736E-05`, 56/81 plastic points | 塑性功为正;塑性区激活;残余弯矩接近零;回弹比例在 checker 范围内 |
| V5.7 | cohesive 单积分点 | `tests/module` | `cohesive_contact` | bonded loading, mixed-mode damage, unloading/reload, complete decohesion, restart | 损伤不可逆;耗散非负;failed 状态 traction 清零;restart 保持状态 |
| V5.7 | 球-膜粘附/脱粘 benchmark | `examples/ball_adhesion_decohesion` | `example_ball_adhesion_cohesive_benchmark` | peak pull-off `119.246023`, min compression `-362.051100`, dissipated energy `0.451891017`, final failed fraction `1.0` | 滞回面积、耗散能、损伤和脱粘面积通过 checker |
| V5.8 | 颗粒基础验收 | `tests/module` | `particle_acceptance`, `particle_fem_coupling` | free fall, wall collision, three-particle pile, particle-facet force balance | 质量守恒;重叠有界;耗散非负;facet 节点力平衡残差在容差内 |
| V5.8 | 动态颗粒柔性容器 benchmark | `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | `example_dynamic_grain_container_benchmark` | 4 particles, 4 facet contacts, `mapped_steps=40`, max load `3.68E+01`, min center `uz=-7.29240354E-06`, max overlap `3.00615680E-03` | 结构输入不得含 `*DLOAD` pressure surrogate;映射节点力和容器位移非零;质量守恒、重叠和能量通过 checker |
| V5.11 | finite-strain S4 bounded spherical-cap postbuckling | `examples/spherical_cap_with_central_point_load` | default: `example_spherical_cap_point_load_benchmark`; extended: `FEMLITE_SPHERICAL_CAP_NONLINEAR=1 python examples/spherical_cap_with_central_point_load/check_spherical_cap_results.py ...` | Shell-16 baseline geometry and samples; Shell-4 all-S4 finite-strain target with translational rim support; bounded nonlinear run to `uz=-3.24 m`, 54 accepted increments, final `wn=15.89482`, final `Fn=1.058395`, sampled `Fn=1.340817` at `wn=13.642` | Default CTest remains fast and checks baseline/target口径. Extended nonlinear command validates continuation-path columns, production finite-strain S4 dispatch and a post-peak load drop. Full `uz=-6.2 m` PDF curve matching, Shell-4/8/16 digitized comparison, pseudo-arclength and late GMRES optimization are deferred. |
| V5.12 | method-4 load-control Riks post-limit branch evidence | `examples/spherical_cap_with_central_point_load` | optional: `FEMLITE_SPHERICAL_CAP_RIKS=1 python examples/spherical_cap_with_central_point_load/check_spherical_cap_results.py ...` | Shell-4 finite-strain target converted to proportional crown `CLOAD`; 80 accepted increments; `peak_lambda=0.6909629`, `final_lambda=0.6017746`, final displacement magnitude `1.3973472 m` | Validates the production load-type Riks augmented equation and predictor direction memory on a real shell structure limit point and post-limit branch segment. Broader branch-following generalization on a second independent structure remains deferred. |
## 示例输出文件
| 示例目录 | 主要输出 | checker |
|---|---|---|
| `examples/contact_two_blocks_compression` | `pressure_profile.csv`, VTK, 0.5.3 contact state/gap/augmentation diagnostics | `check_contact_results.py` |
| `examples/contact_block_sliding` | `sliding_profile.csv`, VTK, 0.5.3 slip/friction/gap/augmentation diagnostics | `check_contact_results.py` |
| `examples/shell_shell_contact` | shell contact profile, VTK, 0.5.3 shared contact diagnostics | `check_contact_results.py` |
| `examples/shell_solid_contact` | shell-solid contact profile, VTK, 0.5.3 shared contact diagnostics | `check_contact_results.py` |
| `examples/mohr_coulomb_yield_surface` | `yield_surface.csv`, `yield_points.csv`, `yield_summary.csv` | `check_mc_yield_surface_results.py` |
| `examples/strengthReduction` | `strength_reduction_path.csv`, `strength_reduction_cases.csv`, summary, `plastic_zone.csv`, `displacement_probe.csv`; optional `strength_reduction_nonlinear_chain.csv` and nonlinear summary when `--nonlinear-chain` is used; optional `strength_reduction_cloud_summary.csv`, progress/trace CSV and refreshed partial/target VTK when `--nl-write-cloud` is used | `check_strength_reduction_results.py` |
| `examples/euler_column_buckling` | `buckling_summary.csv`, `buckling_mode_1.csv` | `check_buckling_results.py` |
| `examples/buckling_corrugated_shell` | summary, wave sweep, modes, profile | `check_buckling_results.py` |
| `examples/roll_forming` | roller kinematics history/summary, springback history/summary, `plastic_zone.csv` | `check_roller_kinematics.py`, `check_springback_results.py` |
| `examples/ball_adhesion_decohesion` | `adhesion_history.csv`, `adhesion_summary.csv`, `decohesion_profile.csv` | `check_cohesive_results.py` |
| `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | `grain_container_history.csv`, `grain_container_summary.csv` | `check_grain_container_results.py` |
| `examples/two_arches` | nodes/elements/contact/history CSV from the two-arches geometry/contact smoke; optional single displacement reference-point run writes `two_arches_reference_point.csv` with `para`, `disp_upper`, reference mode, contact status and contact force | smoke: `check_two_arches_results.py`; optional reference point: `run_two_arches_reference_point.py` and `check_two_arches_reference_point.py` |
| `examples/spherical_cap_with_central_point_load` | `continuation_path.csv`, `spherical_cap_load_displacement.csv` | `check_spherical_cap_results.py` |
| `examples/spherical_cap_with_central_point_load` optional Riks | `continuation_path.csv`, `spherical_cap_riks_load_path.csv` | `check_spherical_cap_results.py` with `FEMLITE_SPHERICAL_CAP_RIKS=1` |
## Smoke 与 benchmark 边界
- V4 smoke 仍用于快速确认旧路径,例如动态颗粒容器目录中的 pressure/ground
smoke、roll forming friction smoke 和 ball adhesion contact smoke。
- V5 完成项必须至少有模块级验收或示例级 checker;不能只依赖 smoke。
- benchmark 编排工具放在 `tools/benchmarks`,示例输入和 checker 放在对应
`examples/<case>/` 目录,生产功能代码仍保留在 `src`。
- 当前模块不引入第三方 solver 或外部求解器进程;相关验收只覆盖内部 solver。
## 文档治理边界
- 状态标记只在 `docs/v5_development_plan.md` 维护;本矩阵只记录可运行入口、
指标和容差,避免多个文档出现互相冲突的 PASS/PARTIAL 口径。
- 每次新增或修正 benchmark 时,必须同步本文件中的 CTest 名称、示例目录、
checker、参考指标和容差说明。
- 每次完成发布确认、多平台复测或 longrun 后,必须同步本文件的测试层级和
多平台复测矩阵,并同步 `docs/v5_acceptance_report.md` 的验收结论。
- 若某项仅为 smoke、surrogate 或 debug fallback,不得在本矩阵中列为 V5
完成项;只能在边界说明或 DEFERRED/PARTIAL 说明中登记。