Files
FemLite/docs/06_test_and_verification_plan.md
T

830 lines
40 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.
# FEM Test and Verification Plan
文档状态:测试验证基线草稿
适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序
## 1. 文档目的
本文档定义 FemLite 各阶段的测试层级、测试工具、验证算例、确认算例、回归测试、性能测试、误差容限和发布阻断条件。
本文档用于判断各阶段是否达到可开发、可联调、可回归和可验收状态。
## 2. 测试目标
第一版测试目标:
- 验证有限元形函数、积分和单元公式实现正确。
- 验证材料更新算法正确,包括线弹性、J2、Johnson-Cook、温升和失效。
- 验证显式动力学时间推进稳定可靠。
- 验证 Abaqus inp 子集解析正确。
- 验证 SPH-FEM 边界接口可用。
- 验证单元删除后内存、质量、状态和外载处理符合设计。
- 建立可重复运行的回归测试基准。
- 建立第一版验收算例集合。
## 3. 测试工具与环境
第一版测试工具:
- Fortran 独立测试程序。
- CMake/CTest 统一管理测试。
- Python 辅助 CSV 对比和报告生成,可选执行。
Python 环境约定:
- 在 `.\Python\` 中建立本软件专用 Python 虚拟环境。
- 建议虚拟环境路径为 `.\Python\.venv`。
- 虚拟环境只用于测试辅助脚本、CSV 对比和报告生成。
- 虚拟环境本体不应提交到 git。
- 只提交必要的脚本、依赖说明和测试数据。
第二版扩展:
- 接入 CI。
- Python 调试接口测试。
- C ABI 包装层接口测试。
第三版扩展:
- 线性静力和非线性静力测试。
- 壳单元静力基准测试。
- 隐式 Newmark 动力学测试。
- 通用接触测试。
- 静力反力、收敛历史和 VTK 输出测试。
- 源码规模检查:普通过程/函数尽量不超过 100 行,超过 128 行必须登记审查理由;源文件尽量不超过 1500 行,超过 2000 行必须审查是否拆分。
第四版扩展:
- surface/contact 输入增强测试,包括 node-based surface、analytical rigid plane surface 和 contact property。
- active set、gap residual 和 augmented penalty 诊断测试。
- 摩擦正则化、摩擦功和最大累计滑移输出测试。
- 接触示例 smoke 测试应覆盖刚性平面压入、两实体块面-面压缩和壳-刚性平面接触。
- 线性求解器分发测试应覆盖 CG、BiCGSTAB、GMRES、DENSE、none/Jacobi/Gauss-Seidel/ILU0 预条件、非法 method 拒绝和最近一次求解统计。
- 壳 V4.7 测试应覆盖 drilling 稳定参数、S3 剪切锁定折减诊断、J2 剪切/弯曲塑性、trial/rollback 和 Scordelis-Lo 静力基准 smoke。
## 4. 测试目录结构
建议目录结构:
```text
tests/unit
tests/module
tests/integration
tests/verification
tests/coupling
tests/performance
tests/data
tests/reference
tools/testing
```
目录说明:
- `tests/unit`:形函数、材料点、数学工具等小粒度测试。
- `tests/module`:单元、边界、输出、输入解析等模块测试。
- `tests/integration`:完整 inp 读取、建模、求解、输出流程测试。
- `tests/verification`:解析解、手算解、Abaqus 可选参考和冻结基准算例。
- `tests/coupling`:SPH-FEM 接口测试。
- `tests/performance`:规模和耗时测试。
- `tests/data`:测试输入文件。
- `tests/reference`:小型参考结果和抽样基准。
- `tools/testing`:Python 辅助脚本。
## 5. 测试优先级
测试分为三类:
```text
P0 每次提交前必须运行并通过
P1 阶段性运行,发布前必须通过
P2 长算例、性能测试或专项测试,发布前或专项评审时运行
```
P0 包括:
- 编译测试。
- 核心单元测试。
- 材料单点测试。
- 小型 INP 解析测试。
- 小型显式单步/多步测试。
- SPH 总力映射测试。
P1 包括:
- 第一版验收验证算例。
- 中等规模动力学回归测试。
- 小型线性静力和非线性静力回归测试。
- 阶段性能测试。
- 跨平台编译检查。
P2 包括:
- 性能长跑。
- 长时间动力学稳定测试。
- Scordelis-Lo 壳静力基准和网格收敛测试。
- Abaqus/Explicit 可选对比。
- 复杂耦合流程测试。
## 6. 误差容限
默认误差容限:
```text
单元级解析测试 relative tolerance 1.0e-10 to 1.0e-8
材料单点测试 relative tolerance 1.0e-8
输入解析测试 exact match unless floating data are involved
SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8
动力学回归测试 key history relative tolerance 1.0e-5
工程验证算例 displacement/energy relative tolerance 1.0e-3 to 1.0e-2
```
说明:
- 解析测试应使用更严格阈值。
- 动力学测试允许不同编译器和平台导致的小幅历史量漂移。
- 工程验证算例应同时检查趋势、数量级和能量合理性。
## 7. 参考结果来源
允许的参考结果来源:
- 解析解。
- 手算结果。
- Abaqus/Explicit 可选参考。
- 内部冻结基准 CSV。
- 网格收敛趋势。
优先级:
```text
解析解/手算结果 > Abaqus/Explicit 可选参考 > 冻结基准 CSV > 收敛趋势
```
说明:
- Abaqus/Explicit 结果作为可选参考,不作为开发环境强依赖。
- 冻结基准 CSV 应尽量小,只保存关键历史量和抽样结果。
## 8. 单元测试计划
形函数测试:
- C3D4 形函数 Kronecker delta 性质。
- C3D8 形函数 Kronecker delta 性质。
- S4 形函数 Kronecker delta 性质。
- partition of unity。
- 自然坐标导数正确性。
积分与几何测试:
- C3D4 体积。
- C3D8 2x2x2 积分。
- S4 面积和厚度。
- Jacobian 正负检查。
- 退化单元检测。
质量测试:
- C3D4 集中质量守恒。
- C3D8 集中质量守恒。
- S4 平动质量守恒。
- S4 简化对角转动惯量非负。
压力等效节点力测试:
- 均布压力总力正确。
- 压力符号符合 `t = -p n`。
- 等效节点力矩平衡在简单面片上合理。
## 9. 材料算法测试
第一版材料测试必须包含:
- 线弹性单轴拉伸。
- 线弹性纯剪切。
- 小应变 J2 弹性步。
- 小应变 J2 塑性步。
- 小应变 J2 加载卸载。
- 大变形 J2 加载卸载。
- Jaumann 客观率刚体转动测试。
- Johnson-Cook 应变率敏感测试。
- Johnson-Cook 温度软化测试。
- 绝热塑性温升测试。
- 等效塑性应变阈值失效测试。
- Johnson-Cook 损伤失效测试。
材料测试要求:
- 单点材料测试优先使用解析或半解析参考。
- 每个材料测试应检查应力、等效塑性应变、温度、损伤和失效标志。
- 失效测试应检查 fail_flag 是否正确设置。
第五版 Mohr-Coulomb 材料点测试还必须覆盖:
- 输入解析:`*MOHR COULOMB` 参数、残余参数和强度折减系数。
- 屈服包络:弹性点、剪切屈服、张拉截断和 mixed 分支分类。
- 返回映射:三轴压缩、三轴伸展、纯剪、张拉截断和 mixed return。
- 活动集算法一致切线:shear、tension 和 mixed 分支必须用小扰动有限差分
审计 `D_alg * Delta epsilon` 对实际返回映射应力增量的预测误差。
- 状态变量:`statev(11)` 分支号、`statev(12:13)` 最终屈服值、
`statev(22)` 塑性增量、`statev(26)` 强度折减系数,以及方法 5 下
`statev(27:32)` 的子步数、请求子步数、driver 状态、分支 mask、最大屈服残差和
最大塑性增量。
- 强度折减:摩擦角、黏聚力、膨胀角和张拉强度折减,并检查残余参数下限。
- driver 诊断:substep 数、limited 状态、branch count、final branch、
final yield values、plastic total 和 tangent 对角诊断。
- 生产分发:`METHOD=MC_SUBSTEPPING_SEMISMOOTH` 必须让 `MOHR_COULOMB` 材料点通过
`fem_material_mc_driver` 更新;默认方法和其他方法仍保持单步更新并写一致诊断。
- 容限:返回映射后的剪切屈服值不得超过 `1.0e-7 * max(1, cohesion)`,
张拉截断不得超过材料点容限;材料点测试不得出现 substep 爆炸。
- 算例验收:`examples/mohr_coulomb_yield_surface` 必须输出屈服面 CSV、
代表性应力点 CSV 和 summary,并验证压缩/伸展包络、张拉截断、强度折减
和 elastic/shear/tension/mixed 分支覆盖。
## 10. 模块测试计划
实体单元测试:
- C3D4 单元质量。
- C3D4 单元内力。
- C3D4 patch test。
- C3D8 单元质量。
- C3D8 单元内力。
- C3D8 patch test。
- C3D8 全积分路径。
- 第一版不支持 C3D8R,应返回明确错误或不支持信息。
壳单元测试:
- S4 单元质量。
- S4 膜响应。
- S4 弯曲响应。
- S4 横向剪切响应。
- S4 选择性减缩积分路径。
- S4 patch test。
- S3/S4/S6/S8 线性静力刚度测试。
- S4 J2/J2_JC 膜内塑性状态更新和膜内/弯曲/剪切 section tangent 对称性测试。
- V4.7 增加 drilling 稳定参数敏感性、S3 剪切锁定诊断、S4 J2 剪切塑性、代表性外纤维弯曲塑性和 trial rollback 回归。
- V5.11 增加 opt-in S4 corotational 几何非线性基础回归:刚体转动对象性、
小转角与线性 S4 一致性、弹性 algorithmic tangent 有限差分列一致性、
非对称切线可接受性、prestress-delta 膜几何刚度激活检查、shell `DLOAD P`
follower-pressure tangent 有限差分一致性检查、非 `ELASTIC` 壳材料显式拒绝检查,
以及默认线性壳路径不被该开关回退。
- Scordelis-Lo 壳静力位移基准测试。
- 板壳弯曲静力基准测试。
静力与隐式求解测试:
- CSR 线性静力装配。
- Dirichlet 约束施加后的反力平衡。
- 线性静力实体 patch test。
- 线性静力壳 patch test。
- 非线性静力 Newton 收敛。
- 非线性静力收敛状态查询,检查最新增量、迭代号、残差范数、修正范数、cutback 次数、最后步长、最后有效时间、状态码、失败原因码和收敛标志。
- 非线性静力步长缩减。
- 非线性静力线搜索和失败回滚测试。
- 隐式 Newmark 单步预测校正。
- C3D4 单步隐式 Newmark 拉伸解析对照。
- Rayleigh 质量比例阻尼解析对照。
- `--implicit-newmark` 命令行回归测试。
- 非线性 Newmark-Newton 线弹性退化解析对照。
- 实体 J2 算法切线基本性质测试。
- 非线性 Newmark-Newton 失败后 trial rollback 测试。
- 非线性 Newmark-Newton Robin/MPC/contact 切线解析对照。
- 非线性 Newmark-Newton 线搜索和动态步长缩减测试。
- `--implicit-newmark-nonlinear` 命令行回归测试。
- 隐式动力弹性波传播。
- V5.5 线性屈曲支撑测试:内部对称 Jacobi 特征值、SPD 广义特征值、模态
`K_G` 归一化、残差计算、Euler 柱解析临界载荷和梁柱几何刚度矩阵。
边界与载荷测试:
- Dirichlet 位移约束。
- 节点力施加。
- 面压力等效节点力。
- amplitude 常值和表格插值。
- 刚性平面 contact penalty/damping 力和切线。
- 面-面 contact pair 法向力、阻尼项、Coulomb 粘滑历史、多 master 分摊、投影裁剪 mortar 权重、空间网格候选、BVH 宽相搜索、空间 broad-phase、CSR 图案、切线块和壳 `SPOS`/`SNEG` 侧向语义。
- contact pair active set 的 activated/maintained/released 状态切换、gap residual、augmented penalty 乘子更新和释放后清零。
- contact pair Coulomb 摩擦默认路径、正则化 Coulomb 路径、正则化切线折减、滑移耗散功和累计滑移。
- 0.5.1 contact multiplier 审计:`contact_multiplier_audit` 必须覆盖
active/released/open 状态计数、duplicate/invalid 为零、最大乘子、最大 gap
和 commit/trial 差异;`contact_mult_report_summary` 必须输出审计字段。
- 0.5.1 mortar tangent 审计:`mortar_tan_audit_matrix` 必须覆盖 row/column
balance、刚体平移残差、stick 对称切线、slip 非对称切线和能量 probe。
工程卫生测试:
- `source_size` CTest 调用 `tools/testing/check_source_size.py`,检查 `src`、`tests` 和 `tools` 下 `.f90/.c/.h/.py` 源文件规模。
- 普通过程/函数 review target 为 100 行,超过 128 行必须在 `tests/source_size_exceptions.txt` 中登记具体审查理由和后续拆分方向。
- 源文件 review target 为 1500 行,超过 2000 行必须在 `tests/source_size_exceptions.txt` 中登记是否拆分、为何暂缓拆分及后续计划。
- 例外表只允许登记当前仍超过硬阈值的项目;过期例外会使 `source_size` 失败。
- 0.4.3 当前无 active hard-threshold exception;剩余输出为 review-target warning,不阻断发布。
输出测试:
- `history.csv` 字段存在。
- `nodes_step_xxxxx.csv` 字段存在。
- `elements_step_xxxxx.csv` 字段存在。
- `contact_XXXXXXXX.csv` 字段存在,并包含 summary 与逐 contact pair 行、stick/slip 计数、累计滑移、切向力历史、summary 和 pair 级搜索统计、BVH 候选缓存统计和 CPU 时间统计。
- `fem_get_contact_summary` 返回激活数、单步/累计接触功、最大穿透量和接触力范数。
- `fem_get_contact_diagnostics` 返回 active pair 数、activated/maintained/released pair 数、最大 gap residual 和最大 augmented penalty 乘子;C ABI 包装函数与 Fortran API 结果一致。
- `fem_get_contact_friction` 和 C ABI `femlite_get_contact_friction_summary` 返回摩擦 step/total 功和最大累计滑移。
- `fem_get_contact_hist_stats` 和 C ABI `femlite_get_contact_history_stats` 返回 mortar 积分点历史槽数、单槽最大滑移、单槽最大摩擦功和单槽最大切向力。
- `fem_get_contact_search_stats` 和 C ABI `femlite_get_contact_search_stats` 返回 contact pair 搜索 facet/master/candidate/active/BVH 节点统计。
- `fem_get_contact_perf_stats` 和 C ABI `femlite_get_contact_perf_stats` 返回 contact search/force/tangent CPU 时间统计。
- `fem_get_contact_cache_stats` 和 C ABI `femlite_get_contact_cache_stats` 返回 BVH 候选缓存使用和溢出统计。
- `fem_get_convergence_status` / `fem_get_convergence_metrics` / `fem_get_convergence_diagnostics` 和 C ABI 对应包装返回最近一次求解的增量、迭代、残差、相对残差、修正范数、contact gap residual、combined norm、cutback 次数、最后步长、最后有效时间、状态码、失败原因码和收敛标志;空模型零状态、非线性静力收敛状态、contact gap 非零状态和 cutback 失败状态均需覆盖。
- `fem_set_linear_solver` / `fem_get_linear_solver_settings` / `fem_get_linear_solver_stats` 和 C ABI 对应包装返回当前线性求解器、预条件器、最近一次迭代数、残差和状态;模块测试覆盖 CG、BiCGSTAB、GMRES 和 DENSE,BiCGSTAB/GMRES 使用非对称小系统,DENSE 使用非正定小系统,`implicit_inp` 覆盖隐式路径切换到 BiCGSTAB,C ABI 覆盖切换到 GMRES + Jacobi。
- 删除单元状态可输出。
示例结果留存策略:
- Git 中保留网格/输入生成脚本、`.inp` 文件、`README.md` 和小型 summary/check 文件。
- 不提交每一步全场 `VTK/CSV/contact` 结果;这些文件通过 `.gitignore` 忽略。
- 对需要回归比较的案例,只保留抽样结果或紧凑统计量。
- 大型长跑结果由本地复现实验生成,并在 README 中记录命令、版本和关键误差指标。
壳基准扩展矩阵:
- Scordelis-Lo:输入位于 `examples/scordelis_lo_roof/`,S3/S4 smoke 检查自由角竖向位移符号和最小量级;网格收敛和参考误差记录作为后续长跑扩展。
- Kirsch plate:记录 S3/S4 孔边应力集中和远场应力误差。
- shell patch test:记录 S3/S4 位移误差和局部应力误差,作为线性精度回归。
- clamped square plate pressure pulse:记录 S3/S4 中心位移峰值、能量历史和稳定时间步。
- V4.7 模块回归已覆盖剪切锁定折减和钻转稳定参数敏感性;后续补充更密网格基准误差表。
接触验证扩展矩阵:
- `*CONTACT PAIR` 合法/缺参/空格/引号/大小写输入解析。
- `*SURFACE` element-target 子集、混合 elset/element-id 数据行、省略 face label、face label 筛选、`OP=ADD/NEW` 同名 surface 追加/覆盖、node-based surface、analytical rigid plane surface、壳 `SPOS`/`SNEG` 法向符号和 slave 侧向筛选、非法 TYPE 拒绝与数据行式 `*CONTACT PAIR` 输入解析。
- `*SURFACE INTERACTION` / `*CONTACT PROPERTY` 中 penalty、damping、search、friction、friction regularization、augment 参数解析和 contact pair 继承。
- contact CSV schema 和 summary/pair 行字段检查,包括 search facet/master/candidate/active/BVH 节点统计列、BVH 候选缓存列、CPU 时间统计列和逐 `PAIR` 行统计值。
- contact diagnostics API 和 C ABI 包装层检查。
- contact friction summary API 和 C ABI 包装层检查。
- contact history stats Fortran API 和 C ABI 包装层检查。
- contact search stats Fortran API 和 C ABI 包装层检查;小算例要求候选数和 active 候选数非零,空模型要求全零。
- contact performance stats Fortran API 和 C ABI 包装层检查;小算例要求非负,空模型要求全零。
- contact cache stats Fortran API 和 C ABI 包装层检查;BVH 小算例要求 cache used 非零且 overflow 为零,空模型要求全零。
- BVH 跨调用候选缓存检查;第一次 BVH 力计算应建立缓存,第二次同几何力计算应命中缓存且 `search_bvh_nodes=0`,后续切线装配应复用同一候选缓存,slave facet 移动超过失效阈值后应失效并重新构建 BVH。
- restart v2 写读 mortar 积分点摩擦历史,验证重启后历史槽、累计滑移、摩擦功和切向力保持一致。
- 0.5.x restart 写读 `CONTACT_MULTIPLIER` 段,验证 active/released/open
乘子状态、已提交 lambda、trial gap 和 commit/trial 一致性在重启后保持。
- 法向接触功、摩擦功、stick/slip 计数、mortar 积分点历史槽、正则化摩擦切线和累计滑移 sanity check。
- V4.2 新增示例:rigid plane indentation、two blocks compression、shell rigid plane contact;每个示例应可通过目录内 `run_case.bat` 自动运行和检查结果。
- V4.3 新增示例:contact block sliding friction;检查正则化参数、累计滑移、切向力、摩擦功非负和 VTK 输出。
- V4.8 补齐文档型示例目录的可运行输入和 `run_case.bat`,新增 `examples_layout` CTest 检查“有文档无 `.inp`”和“有 `.inp` 无双击脚本”的回退;文档后缀包含 `.md`、`.pdf`、`.ppt`、`.pptx`、`.txt` 和 `.rst`。
- V5.3 新增 `example_contact_two_blocks_compression_benchmark`:运行非匹配两块体压缩接触,并调用 `examples/contact_two_blocks_compression/check_contact_results.py` 检查压力、max gap、weighted gap、multiplier residual、augmented multiplier、master facet 覆盖和 VTK 输出。
- V5.3 新增 `example_contact_block_sliding_benchmark`:运行非匹配大滑移 mortar-friction 接触,并调用 `examples/contact_block_sliding/check_contact_results.py` 检查多 master、多 active、stick/slip、累计滑移、摩擦功、切向力和 VTK 输出。
- V5.3 新增 `example_shell_shell_contact_benchmark` 和 `example_shell_solid_contact_benchmark`:分别运行 S4-to-S4 shell-shell 接触和 S4-to-C3D8 shell-solid 接触,并调用各自示例目录内 checker 检查 active contact、force、gap、augmented multiplier、master search 和 VTK 输出。
- V5.3 0.5.1 新增 `contact_mortar_tangent` 和 `restart` 审计场景:
检查 `contact_multiplier_audit`、`mortar_tan_audit_matrix`、
`contact_mult_report_summary`,并用 OpenMP 1/4 线程 contact/performance
smoke 防止接触统计在并行路径回退。
- V5.4 新增 `example_strength_reduction_benchmark`:运行 `examples/strengthReduction` 中按 `models.geomech.strength_reduction_method.pdf` 生成的 0.75 m 网格 C3D8 Mohr-Coulomb 坡体输入,并调用 checker 生成和检查 `strength_reduction_path.csv`、`strength_reduction_cases.csv`、summary、塑性区和位移探针;checker 同时验证输入记录 `CONFORMING_INTERFACE=YES`,并检查 `z=H1`、`x>=L2` 的上下土体界面节点被 lower/upper 元素共享。当前 FOS 参考为 8 个 PDF 工况全部收敛、最大 FOS 误差 `6.9392E-03`、86 个 trial、52 个 stable trial 和 34 个 unstable trial。可选 `--nonlinear-chain` 输出会检查 `continuation_method`、`last_dt`、`accepted_time`、`correction_norm`、目标/实际/下一 continuation 步长、adaptive adjust、trust radius、damping、merit ratio、trust rejection count、线性迭代数、线性残差和线性状态列;method 1 的两阶段 load-strength continuation 通过小参数 chain/cloud smoke 验证输出路径,NC-2 目标 Newton 步长控制和 NC-3 trust-region damped Newton 已由 `solver_implicit`、`implicit_inp` 与本 example checker 覆盖,目标 cloud 的中等 0.75 m 探针仍超过 120 s,PDF 位移云图 material case 2、`alpha=45 deg`、`FOS=1.525` 的 0.3 m 量级结果尚未作为 CTest 验收项。
- V5.5 新增 `example_euler_column_buckling_benchmark`:运行 `examples/euler_column_buckling` 的 Euler pinned-pinned column 输入,并调用 checker 生成和检查 `buckling_summary.csv` 与 `buckling_mode_1.csv`;当前参考为一阶临界载荷相对误差 `3.27660856E-05`、残差 `1.50014805E-11` 和 `phi^T K_G phi = 1.0`。
- V5.5 新增 `example_buckling_corrugated_shell_benchmark`:运行 `examples/buckling_corrugated_shell` 的紧凑循环波纹壳屈曲输入,并调用 checker 生成和检查 summary、wave sweep、modal CSV 和 profile;当前参考为 selected wave 4 load `453.031407`、critical wave 8 load `393.369677`、循环/全模型相对误差 `1.25473461E-16` 和 modal residual `1.31855319E-12`。
- V5.6 新增 `example_roll_forming_kinematics_benchmark`:运行 `examples/roll_forming` 的 roller kinematics 输入,并调用 checker 生成和检查 `roller_kinematics_history.csv` 与 summary;当前参考为 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` 和 positive torque `14.4604137`。
- V5.6 新增 `example_roll_forming_springback_benchmark`:运行 `examples/roll_forming` 的 springback 输入,并调用 checker 生成和检查 `springback_history.csv`、`springback_summary.csv` 与 `plastic_zone.csv`;当前参考为 springback ratio `0.473154068`、residual displacement `0.0316107559`、plastic work `1.11591736e-05`、56/81 个 active plastic points 和 residual moment 绝对值 `8.92778801e-11`。
- 已接入 `example_smoke`/`benchmark` CTest 分组:shell patch S3/S4 静力 smoke、Scordelis-Lo S3/S4 静力 smoke、clamped square plate pressure pulse S4 短步数动力 smoke、rigid sphere impact plate S3/S4 短步数动力 smoke、contact two blocks nonmatching benchmark、contact block sliding large-sliding benchmark、shell-shell contact benchmark、shell-solid contact benchmark、Mohr-Coulomb strength reduction PDF benchmark、Euler column buckling benchmark、corrugated shell cyclic buckling benchmark、roll forming kinematics benchmark、roll forming springback benchmark、ball adhesion cohesive benchmark、dynamic grain container particle benchmark、two arches reference-geometry benchmark、elliptic membrane、membrane uniaxial、shell-solid connection、golf ball impact、node analytical contact、block-on-arch、cylinder roller contact、sliding wedge、roll forming friction smoke、falling objects、ball adhesion contact、dynamic grain container pressure smoke、membrane airbag、spherical cap displacement-control benchmark、blasting rock、nonlinear harmonic、layered shell、pinched hemisphere 和 stress dependent elasticity benchmark;接触类 smoke 检查 active contact,摩擦滑移类 smoke 检查正摩擦耗散,壳/静力基准 smoke 通过节点位移探针检查方向和最小量级,two arches benchmark 通过 checker 验证 PDF 参考坐标、30/75 壳网格、1.2 mm 上拱中点位移和 active contact,strengthReduction benchmark 通过 checker 验证 PDF 几何、0.75 m 网格、8 工况 FOS 曲线、Davis B/关联材料单调性、塑性区和位移停止准则,但不验收 PDF 位移云图,屈曲 benchmark 检查特征值、残差和模态输出,滚压 benchmark 检查旋转对 slip/traction/energy/torque 以及 J2 塑性区/回弹指标的影响,cohesive benchmark 检查拉脱力、滞回、耗散能、损伤和脱粘面积,dynamic grain benchmark 检查粒子数、粒子-facet 接触、映射节点力、容器位移、质量守恒和能量。thick plate 作为独立 NAFEMS LE10 benchmark 接入 `benchmark` 标签,检查 D 点恢复应力、位移方向和压力反力平衡;spherical cap benchmark 检查 PDF 几何、16 段经向壳网格、`SHELL_GEOMETRIC=YES` 位移控制输入、冠点反力和无量纲曲线采样,可选 nonlinear route 还要求 post-peak load drop 与 restiffening 以防单调小应变曲线误判通过,但完整 Shell-4/8/16 postbuckling 路径仍需 V5.11 后续验收。
- rigid sphere impact plate 的长步数结果保留为示例复现实验。
## 11. 输入解析测试
第一版支持 keyword 均应有最小 inp 测试:
- *NODE
- *ELEMENT
- *NSET
- *ELSET
- *MATERIAL
- *DENSITY
- *ELASTIC
- *PLASTIC
- *SOLID SECTION
- *SHELL SECTION
- *BOUNDARY
- *CLOAD
- *DLOAD(壳面压力 `P`、实体体力 `GRAV`)
- *AMPLITUDE
- *STEP
- *DYNAMIC
第三版新增 keyword 测试:
- *STATIC
- *CONTROLS
- *SURFACE
- *CONTACT PAIR
- *TIE
- *OUTPUT
- *NODE PRINT
- *EL PRINT
- *NODE FILE
- *EL FILE
第四版新增 keyword 和参数测试:
- *SURFACE, TYPE=NODE
- *SURFACE, TYPE=ANALYTICAL
- *SURFACE INTERACTION
- *CONTACT PROPERTY
- *FRICTION
- *CONTACT PAIR, INTERACTION=...
- *CONTACT PAIR, AUGMENT=...
集合测试:
- *NSET, GENERATE。
- *ELSET, GENERATE。
- 普通显式集合。
- 空集合错误处理。
错误处理测试:
- 不支持 keyword warning 后跳过。
- 关键数据缺失返回 error。
- 缺失材料返回 error。
- 缺失密度返回 error。
- 非法单元类型返回 error。
- 原始编号到内部编号映射正确。
## 12. SPH-FEM 接口测试
SPH 接口第一版必须测试三类输入:
- facet 压力。
- facet 压力加剪切。
- 节点力。
facet 导出测试:
- facet 数量正确。
- facet 编号稳定。
- facet 节点连接使用 Abaqus 原始节点编号。
- facet 所属单元使用 Abaqus 原始单元编号。
- facet 外法向方向正确。
- facet 面积正确。
- facet 节点坐标和速度维度正确。
力映射测试:
- 压力映射总力正确。
- 压力符号符合受压为正。
- 剪切映射总力正确。
- 节点力直接累加正确。
- 删除单元不会导出有效 facet。
- 删除单元不再接受 SPH facet 外载。
## 13. 单元删除与失效测试
必须测试:
- C3D4 使用 ANY_FAILED_GP 删除。
- C3D8 使用 FRACTION_FAILED_GP,fraction = 0.5 删除。
- S4 使用 FRACTION_FAILED_GP,fraction = 0.5 删除。
- 删除后单元仍在内存中且可查询。
- 删除后单元不贡献内力。
- 删除后单元不接受面压力。
- 删除后单元不接受 SPH facet 外载。
- 删除后质量保留。
- 删除后不触发自由度重编号。
- 输出中记录 deleted 状态。
## 14. 集成测试计划
集成测试覆盖:
- inp 读取到数据库构建。
- 数据库到自由度编号。
- facet 构造。
- 集中质量初始化。
- 显式单步推进。
- 显式多步推进。
- CSV 输出。
- 错误日志检查。
- 独立 femlite 程序运行。
- 外部 SPH 驱动式调用流程。
- 静力线性完整求解流程。
- 静力非线性完整求解流程。
- 隐式 Newmark 动力学完整求解流程。
典型流程测试:
```text
fem_initialize
fem_read_inp
fem_build_model
fem_compute_lumped_mass
fem_estimate_stable_dt
fem_advance_explicit
fem_write_output
fem_finalize
```
SPH 驱动流程测试:
```text
fem_get_boundary_facet_count
fem_get_boundary_facets
fem_clear_sph_forces
fem_apply_sph_facet_pressure / fem_apply_sph_facet_tractions / fem_apply_sph_nodal_forces
fem_advance_explicit
fem_get_nodal_kinematics
```
第三版静力流程测试:
```text
fem_initialize
fem_read_inp
fem_build_model
fem_solve_static_linear / fem_solve_static_nonlinear
fem_get_nodal_reactions
fem_get_convergence_status
fem_write_output
fem_finalize
```
## 15. 第一版验证算例
第一版验收算例:
- 单元 patch test。
- 单轴拉伸。
- 弹塑性加载卸载。
- 弹性波传播。
- 板受压力脉冲。
- 简化 SPH-FEM 边界力传递接口。
覆盖要求:
- patch test 覆盖 C3D4、C3D8、S4。
- 单轴拉伸覆盖线弹性和 J2 弹塑性。
- 弹塑性加载卸载覆盖小应变 J2 和大变形 J2。
- 弹性波传播覆盖 C3D8 和 C3D4。
- 板受压力脉冲覆盖第一版所有板壳单元。
- SPH 接口覆盖压力、剪切力和节点力三类载荷。
每个验证算例应包含:
- 输入文件。
- 运行命令。
- 参考结果来源。
- 允许误差。
- 关键输出字段。
- 日志检查项。
- 回归判据。
## 16. 确认算例
第一版可选确认算例:
- 板受冲击压力载荷。
- 简化船体板架爆炸响应。
- 简化 SPH-FEM 压力传递。
第二版或后续确认算例:
- Taylor impact。
- 接触冲击算例。
- 壳-实体混合模型响应。
- Abaqus/Explicit 对比算例。
第三版确认算例:
- Scordelis-Lo 屋面壳体静力基准。
- 板壳弯曲静力基准。
- 实体单元线弹性静力 patch test。
- 实体单元 J2 弹塑性静力加载卸载。
- 隐式动力弹性波传播。
- 简化接触静力压入。
- 简化接触动力冲击。
## 17. 回归测试
基准结果目录:
```text
tests/reference
```
允许存储:
- 小型 `history.csv`。
- 抽样节点结果。
- 抽样单元结果。
- 日志关键模式。
- 小型参考输入文件。
不应提交:
- 每一步全场大 CSV。
- 大型二进制结果。
- Python 虚拟环境本体。
- 临时构建目录。
回归比较:
- P0 回归比较关键标量和少量抽样场变量。
- P1 回归比较完整历史量和更多抽样节点/单元。
- P2 回归重点检查性能、稳定性和长期漂移。
## 18. 性能测试
第一版性能目标:
```text
目标节点数 10000
目标单元数 10000
目标时间步数 10000
```
阶段性能测试 P1:
```text
10000 节点
10000 单元
100 步
```
性能长跑 P2:
```text
10000 节点
10000 单元
10000 步
```
性能指标:
- INP 读取耗时。
- 数据库构建耗时。
- 集中质量计算耗时。
- 显式单步平均耗时。
- 总耗时。
- 峰值内存。
- 删除单元数量。
- 最小稳定时间步。
- contact pair 全局与逐 pair facet/master/candidate/active/BVH 节点统计。
- contact pair 全局与逐 pair BVH 候选缓存命中和溢出统计。
- contact 全局与逐 pair search/force/tangent CPU 时间统计。
V4.4 contact pair 性能 smoke:
- `perf_contact_pair_smoke` 使用程序内生成的 S4 master/slave 面对,默认 CTest 规模为 32 对面片;`perf_contact_pair_medium` 使用 64 对面片覆盖更厚的 BVH/cache/tangent 路径。
- smoke 必须触发 BVH 搜索、active 接触和 BVH 候选缓存命中。
- `perf_contact_pair_omp_consistency` 通过 `tools/testing/check_perf_contact_pair_omp.py` 分别以 `OMP_NUM_THREADS=1/4` 运行同一性能 smoke,并要求 active、broad/active 候选、BVH 节点和缓存命中等非计时统计一致;该用例覆盖缩短后的 force 全局提交临界区和 tangent CSR 合并临界区。
- 可执行程序 `perf_contact_pair <facet_count> <do_tangent>` 可用于放大到中等规模专项测试;`facet_count` 必须大于 16 才能触发 BVH 路径。
- `linear_solver_cg` 和 `test_c_api` 覆盖内部 CG/BiCGSTAB/GMRES/DENSE 设置、统计查询、CSR 矩阵分类诊断、非法 method 拒绝,以及旧外部 method 数值不改变现有设置;`solver_implicit` 覆盖非线性修正内部 fallback 后恢复用户配置。
- `solver_implicit` 和 `implicit_inp` 覆盖线性静力、隐式 Newmark 和非线性接触修正路径通过同一内部 dispatch 记录矩阵分类、初始残差、最终残差、相对残差和收敛状态;`implicit_inp` 同时覆盖 `*NONLINEAR CONTINUATION, METHOD=value` 的默认 `METHOD=1`、数字 `1..5`、符号名、非法值拒绝和失败时状态保持,并覆盖 NC-2 的 `TARGET_NEWTON/GROWTH/SHRINK`、NC-3 的 trust radius/min/max、growth/shrink 和 merit ratio 参数,以及 `SHELL_GEOMETRIC`/`COROTATIONAL_SHELL` 等 S4 corotational 布尔开关。`solver_implicit` 覆盖 NC-2 自适应步长到达最终时间、NC-3 trust radius 限制实际修正范数、damping/merit/rejection 诊断和收敛结果;0.5.2 追加 NC-4 直接位移控制 accepted path 覆盖,验证每个 accepted increment 的控制 DOF、目标/实际位移、约束残差、反力、状态码和 Fortran API 查询。
- `strength_reduction_driver` 覆盖强度折减搜索状态机、trial 分类、bracket/convergence/limited 状态和历史查询;`strength_reduction_report` 覆盖 trial CSV、summary line 和报告文件写出。
- `eigensolver` 和 `buckling_support` 覆盖内部 dense 特征值、广义 SPD
特征值、模态残差、Euler 解析临界载荷和梁柱几何刚度;`example_euler_column_buckling_benchmark`
覆盖解析屈曲相对误差、残差、模态归一化和模态 CSV 输出。
- `rigid_roller` 覆盖圆柱接触几何、辊位姿、feed/down/spin 调度、角速度
表面速度、正则化滚压牵引和 roll metrics;`example_roll_forming_kinematics_benchmark`
覆盖关闭角速度会改变切向滑移、正则化牵引和摩擦能。
- `example_roll_forming_springback_benchmark` 覆盖滚压工件多层 J2 材料点成形、
卸载弯矩平衡、残余位移、springback ratio、塑性功和塑性区输出。
- `cohesive_contact` 覆盖 cohesive law、cohesive state 和 metrics:单积分点
bonded loading、mixed-mode damage、unloading、reload、complete decohesion、
非负耗散、损伤不可逆、失效牵引清零、failed-area metrics,以及 restart 后
damage、最大开口、最大有效分离、能量和 failed status 保持。
- `particle_acceptance` 覆盖 V5.8 颗粒基础验收:自由落体、阻尼墙碰撞、
三颗粒堆积和颗粒-facet 载荷平衡;检查质量守恒、有界重叠、非负步耗散能、
动量/动能诊断和 facet 节点力平衡。
- `example_dynamic_grain_container_benchmark` 运行
`examples/Dynamic_Grain_Packing_of_a_Flexible_Container` 的真实粒子-柔性容器
benchmark,检查结构输入不含 pressure surrogate、粒子数、facet contact
count、mapped steps、映射节点力、中心节点位移、质量守恒、最大重叠和能量;
当前参考为 4 个粒子、4 个 facet contacts、`mapped_steps=40`、最大竖向映射
载荷 `3.68E+01`、中心节点最小位移 `-7.29240354E-06` 和最大重叠
`3.00615680E-03`。
- `example_ball_adhesion_cohesive_benchmark` 运行
`examples/ball_adhesion_decohesion` 的 compact cohesive ring benchmark,检查
force-displacement hysteresis、peak pull-off force、min compression force、
dissipated energy、damage monotonicity、decohesion area 和 profile/summary
一致性。
第一版不要求:
- OpenMP。
- MPI。
- GPU。
- 第三方或外部线性求解器加速。
## 19. 鲁棒性测试
必须覆盖:
- 输入文件不存在。
- 缺失材料。
- 缺失密度。
- 非法材料参数。
- 非法塑性曲线。
- 非法 Johnson-Cook 参数。
- 非法温度参数。
- 退化单元。
- 负 Jacobian。
- 非法边界自由度。
- 不支持 keyword。
- 空集合。
- 时间步小于等于零。
- SPH facet_id 非法。
- SPH node_id 非法。
- 输出目录不可写。
鲁棒性判据:
- 错误必须通过 ierr 返回。
- 关键错误必须写入日志。
- warning 不应导致程序异常终止。
- 不支持 keyword 应 warning 后跳过。
- 关键数据缺失应 error 并终止当前分析。
## 20. 本地测试与 CI 策略
第一版:
- 使用本地 CTest。
- P0 作为每次提交前必须通过的测试集合。
- P1 作为阶段评审和发布前测试集合。
- P2 作为专项长跑和发布候选验证。
第二版:
- 接入 CI。
- 增加 Windows/Linux 自动编译。
- 增加 C ABI 和 Python 接口测试。
- 增加 VTK/restart 回归测试;V4.3 已覆盖接触摩擦历史 restart 回归。
第三版:
- CI 增加静力学和隐式求解 P0/P1 测试。
- CI 增加壳静力小型基准测试。
- 本地发布前运行 Scordelis-Lo 和接触 P2 测试。
- 保留 Windows GCC、WSL gfortran 和 Intel Fortran 兼容性检查记录。
- 0.4.2 本地发布记录:Windows GCC 16 CTest 33/33,WSL Ubuntu + gfortran 13.3 CTest 33/33,Windows Intel oneAPI `ifx` 2026.0 + MSVC `cl` 19.44 CTest 33/33;Intel/NMake `/machine:x64` ifx warning 已清理。
- 0.4.3 当前 Windows GCC 16 回归记录:CTest 34/34。
- V4.4 开发态新增 `contact_omp1` / `contact_omp4`,用 `OMP_NUM_THREADS=1/4` 重跑 contact 模块回归;新增 `perf_contact_pair_smoke` 和 `perf_contact_pair_medium` 覆盖 BVH contact pair 性能 smoke;新增 `perf_contact_pair_omp_consistency` 对比性能 smoke 在 OpenMP 1/4 线程下的非计时统计;contact CSV 已覆盖 summary 和逐 pair 统计;BVH force 权重准备统计改为 OpenMP reduction 后由 contact 定向回归覆盖;BVH force 并行装配已将法向/mortar/接触面积准备移出全局提交临界区,BVH tangent 并行装配已将 mortar/切线块准备移出 CSR 临界区;`contact` 覆盖跨调用候选缓存 force/tangent 命中和失效条件。
- V4.8 阶段验收新增 `examples_layout`、GMRES 回归、node analytical contact、P1 contact 性能 smoke,以及完整文档派生 `example_smoke` 矩阵;Python 可用时 Windows GCC 16 CTest 当前记录为 66/66 passed。
- V5.2-V5.8 当前 Windows GCC 16 Release 回归记录:内部 solver 诊断、no-external-solver 策略、非匹配 two-block contact benchmark、大滑移摩擦 benchmark、shell-shell/shell-solid contact benchmark、0.5.1 contact multiplier/tangent audit、Mohr-Coulomb 材料点验收、strength reduction benchmark、Euler column buckling benchmark、corrugated shell cyclic buckling benchmark、roll forming kinematics benchmark、roll forming springback benchmark、cohesive 单积分点验收、ball adhesion cohesive benchmark、particle acceptance primitives 和 dynamic grain container particle benchmark 已接入;`ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` 记录为 106/106 passed。当前 V5 验收子集可通过 `ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure` 运行,记录为 35/35 passed。
## 21. 发布阻断条件
以下任一情况应阻断第一版发布:
- P0 测试失败。
- 输入解析关键测试失败。
- 材料单点测试失败。
- 显式动力学稳定测试失败。
- SPH 接口总力映射失败。
- 单元删除关键测试失败。
- 跨平台编译失败。
- 输出结果字段缺失。
- 核心接口未通过 ierr 返回错误。
- 文档与实现明显不一致。
## 22. 第一版验收准则
第一版完成条件:
- P0 全部通过。
- P1 验证算例全部通过。
- P2 性能长跑完成并形成报告。
- Windows 和 Linux 均可编译。
- gfortran 默认可用。
- Intel Fortran 兼容性检查通过或记录明确限制。
- SPH 三类接口均通过测试。
- CSV 输出符合接口文档。
- 所有第一版文档更新到与实现一致。
## 23. 第三版验收准则
第三版完成条件:
- 第一版和第二版全部 P0/P1 测试无回退。
- 线性静力实体单元 patch test 通过。
- 线性静力壳单元 patch test 通过。
- Scordelis-Lo 壳静力基准通过参考位移容限检查。
- 实体单元 J2 弹塑性静力加载卸载通过。
- 非线性静力 Newton 收敛历史和失败回退测试通过。
- 隐式 Newmark 动力学小算例通过。
- 简化接触静力和动力算例通过。
- 静力 VTK、CSV、反力和收敛历史输出字段完整。
- Windows 和 Linux 均可编译并通过第三版 P0 测试。
## 24. 第四版 V4.2 阶段验收准则
V4.2 阶段完成条件:
- V4.1 的 surface/contact 输入增强无回退。
- contact pair active set 可区分 open、activated、maintained 和 released。
- augmented penalty 参数可由 contact property 或 contact pair 输入,并按 pair 级优先级继承。
- 刚性平面 analytical contact pair 和面-面 contact pair 均使用统一的 penalty + augmented multiplier 法向压力路径。
- contact CSV 输出包含状态、激活/释放次数、gap residual、augment factor 和 augmented multiplier。
- Fortran API 和 C ABI 可查询接触诊断统计。
- rigid plane indentation、two blocks compression 和 shell rigid plane contact 三个小算例可运行并生成 VTK 与接触结果。
- CTest 全量回归通过,`source_size` 无 hard-threshold 失败。