Files
SPHLite/docs/06_test_and_verification_plan.md
T
2026-07-03 11:31:28 +08:00

188 lines
7.0 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.
# 06 测试与验证计划
文档状态:规划确认稿
## 1. 测试原则
SPHLite 测试体系仿照 FEMLite,采用 CMake + CTest + Python checker + release gate。核心求解器使用 Fortran 95,因此单元测试和模块测试以 Fortran 小程序为主。C ABI、C++ wrapper、Python API 和 CLI 作为接口层分别测试。
测试设计原则:
- 新物理能力必须配套小型、可重复测试或 checker。
- 默认 release gate 只包含快速、稳定、小规模测试。
- 长跑、工程 benchmark 和研究项不进入默认 gate。
- C ABI 是第一优先接口测试对象。
- C++ wrapper 测试保留,但不作为 0.1 最小 gate 必选项。
- Python 基础 smoke 纳入默认 gate。
- 从第一版开始启用 source size 门禁。
## 2. 测试分层
| 层级 | 目标 |
|---|---|
| 单元测试 | 核函数、邻域搜索、EOS、Velocity-Verlet、Johnson-Cook 材料点、Mindlin-Reissner 局部量 |
| 输入测试 | Abaqus `.inp` 子集、`*SPHLITE ...` 扩展关键词、warning/error 路径 |
| 模块测试 | Water、Gas、Explosive、Solid、Shell、CouplingInterface |
| 接口测试 | Fortran API、C ABI、C++ wrapper、Python `ctypes`、CLI |
| 示例 smoke | 小型可运行模型,检查方向、量级和关键输出 |
| benchmark | 带 checker 的紧凑工程验收 |
| 外部集成测试 | 与外部 CouplingModule/FEMLite 的联合验证,不属于 SPHLite 默认 gate |
| release gate | 当前版本发布前必须通过的组合测试 |
## 3. 第一批默认测试
第一批默认测试按长期能力逐步扩展。0.1.0 的默认 gate 只覆盖工程骨架、接口、最小输入、最小显式步进和 source size;下列物理项在对应版本实现后再进入默认 gate:
- Wendland C2 核函数归一性和梯度反对称性。
- Wendland C4 和 cubic spline 对比/回归测试。
- uniform cell/bin 邻域搜索与朴素搜索一致性。
- Tait EOS 压力计算。
- JWL EOS 压力计算。
- 理想气体 EOS 压力计算。
- Stiffened gas EOS 压力计算。
- Monaghan 人工黏性方向和量级。
- Velocity-Verlet 自由运动、恒力或简化振动步进。
- 水相连续性方程小算例。
- 小型压力波 smoke。
- 解析爆轰到达时间。
- programmed burn 反应进度 `lambda`。
- 气体团簇体积和等效气泡半径统计。
- Johnson-Cook 材料点。
- Johnson-Cook 失效与渐进软化材料点。
- Mindlin-Reissner 板壳小变形 smoke。
- C ABI 空指针、非正容量和小缓冲区错误。
- Python `ctypes` 基础 smoke。
## 4. 输入解析测试
SPHLite 支持 Abaqus `.inp` 明确子集,不追求完整 Abaqus 兼容。输入测试必须覆盖:
- `*NODE`。
- `*ELEMENT`。
- `*NSET`。
- `*ELSET`。
- `*MATERIAL`。
- `*SECTION` 或等价 section 关键词。
- `*SPHLITE ...` 扩展关键词。
- 未支持但不影响运行的关键词 warning。
- 缺失关键数据或无法继续运行的 error。
- set 只表示集合,不作为类型判断依据。
- material 和 section 对 phase/物理路径的识别。
输入解析测试应同时覆盖 CLI 路径和 API 路径。
## 5. 模块测试顺序
模块测试按开发路线递进:
1. `Water`:核函数、邻域、Tait EOS、连续性方程、压力波 smoke。
2. `Gas`:JWL、理想气体、Stiffened gas、气体团簇和气泡诊断。
3. `Explosive`:爆轰到达时间、反应进度、质量/动量/能量源项。
4. `Solid`:Johnson-Cook 材料点、失效和渐进软化。
5. `Shell`:Mindlin-Reissner 小变形、厚度积分点选择。
6. `CouplingInterface`:中立耦合状态导出、外力导入、耦合功和能量诊断。
## 6. CouplingInterface 测试边界
SPHLite 默认 gate 不包含真正 FEM-SPH 联合测试。外部 CouplingModule、FEMLite 或其他求解器的联合运行属于外部集成测试。
SPHLite 仓库内只测试中立接口:
- coupling region 解析。
- coupling particles 导出。
- coupling facets 或近似面片导出。
- 外部粒子力、面力或体力导入。
- 显式步内载荷施加。
- 耦合功、动量交换和能量交换统计。
- 接触耦合和连续体耦合诊断字段区分。
## 7. 0.1 Release Gate 草案
0.1 release gate 建议包含:
```powershell
cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(smoke|input|c_api|python_debug)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure
git diff --check
```
其中:
- `smoke` 覆盖 Fortran 生命周期、数据库、最小显式步。
- `input` 覆盖 `.inp` 支持子集和 warning/error。
- `c_api` 覆盖 C ABI 生命周期、查询和错误路径。
- `python_debug` 覆盖 Python `ctypes` 基础调用。
- `source_size` 控制单文件和单过程持续膨胀。
实际 build 目录和测试名称可在代码实现阶段按 CMake 配置调整。
## 7.1 0.3.1 Release Gate
0.3.1 在 0.3.0 默认 gate 基础上新增 Gas 多材料、material/EOS 分派、Gas 源项占位、扩展诊断、restart 兼容和接口扩展测试。默认 gate 包含:
- `input_gas_multimaterial`
- `gas_eos_dispatch`
- `gas_extended_summary`
- `gas_source`
- `gas_source_errors`
- `gas_restart_031`
- `gas_restart_030_compat`
- `gas_python_extended`
- `gas_cli_extended`
- `gas_source_size_cleanup`
0.3.1 本地 release gate:
```powershell
ctest --test-dir build-codex-unix --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
```
2026-07-03 本地结果:默认 gate 37/37 通过,`source_size` 1/1 通过,`git diff --check` 通过。
## 8. Source Size 门禁
从第一版开始设置 source size 门禁。建议沿用 FEMLite 风格:
- 普通过程设置 review target 和 hard limit。
- 普通源文件设置 review target 和 hard limit。
- 必要例外登记到例外清单。
- stale exception 应被检查。
具体阈值可在实现阶段与 FEMLite 保持一致或按 SPHLite 文件结构微调。
## 9. 非默认长跑和研究项
以下内容不进入默认 release gate:
- 自由场水下爆炸工程曲线。
- 气泡多周期脉动。
- 板壳穿孔、撕裂和碎片云。
- 舱段局部水下接触爆炸破坏。
- FEM-SPH 联合长算例。
- 大规模粒子数性能测试。
- 近场强冲击 Riemann-SPH 对比。
- 多材料复杂断裂和焊缝失效。
这些内容应作为非默认 benchmark、研究项或外部集成测试维护,并配套独立 checker 和运行说明。
## 10. 文档与产物检查
发布前必须确认:
- README 和 01-11 文档与当前版本能力一致。
- 默认 gate 结果写入版本历史和 benchmark 矩阵。
- 输出目录、CSV、VTK、restart 和大型临时结果不提交。
- Python 生成器仅作为测试/示例辅助工具,不宣传为求解器几何或粒子生成功能。
- 文档使用 UTF-8 without BOM。
## 11. 待讨论问题
- 0.1 source size 具体阈值。
- 第一批 CTest 测试名称和 label。
- Python checker 的目录组织。
- 非默认 benchmark 的运行入口和命名。
- 外部集成测试与 CouplingModule 仓库的边界。