Files
CCLite/docs/06_test_and_verification_plan.md
T
2026-07-05 16:34:52 +08:00

58 KiB
Raw Blame History

CCLite 测试与验证计划

Coupling & Contact Lite for SPHLite and FEMLite

1. 文档定位

1.1 编写目的

本文档定义 CCLite 的测试、验证和验收计划,用于约束从 0.1.x 到 0.10.x 的持续开发过程。

CCLite 是基于 SPHLite 和 FEMLite 的 SPH-FEM 耦合、接触联合仿真软件。其第一阶段采用 Windows/gfortran/本机共享内存通信,算法核心采用 Fortran95,数据和通信层可采用 Fortran2018,必要时可使用 C/C++ 薄层封装系统 IPC。

本文档的目的不是替代 04 号数学模型文档,也不是替代 05 号接口控制文档,而是把数学模型、接口协议和工程实现转化为可执行、可复现、可验收的测试体系。

1.2 文档边界

本文档覆盖:

  1. 单元测试;
  2. 接口测试;
  3. 集成测试;
  4. 验证算例;
  5. 回归测试;
  6. 性能与稳定性测试;
  7. 版本验收矩阵;
  8. 测试数据、输出文件和检查工具要求。

本文档不覆盖:

  1. SPHLite 和 FEMLite 各自独立求解器内部算法的完整验证;
  2. 商业软件级别的标准认证;
  3. Linux/MPI 分布式执行的第一阶段验收;
  4. 未进入 04 号数学模型文档的扩展算法。

SPHLite 和 FEMLite 的内部求解准确性应由各自项目负责。CCLite 只验证三程序联合运行、接口数据一致性、耦合算法正确性和联合算例结果合理性。

1.3 与其他文档的关系

01 号需求规格说明书定义 CCLite 要做什么。

02 号概要设计说明书定义 CCLite 的总体结构和模块边界。

03 号详细设计说明书定义 CCLite 的实现结构、数据类型和运行流程。

04 号数学模型与算法说明书定义接触、耦合、FSI、时间同步和稳定性算法的理论基础。

05 号接口控制文档定义 CCLite、SPHLite worker、FEMLite worker 之间的外部接口协议。

本文档负责回答:

  1. 如何确认 04 号算法实现正确;
  2. 如何确认 05 号接口实现兼容;
  3. 如何确认三程序联合运行稳定;
  4. 每个版本需要通过哪些验收项;
  5. 测试失败时如何定位责任边界。

1.4 测试原则

CCLite 测试体系采用以下原则:

  1. 先接口闭环,后物理精度;
  2. 先 mock solver,后真实 solver;
  3. 先小算例可解释,后工程算例覆盖;
  4. 先确定性验收,后性能优化;
  5. 先守恒和一致性检查,后复杂现象拟合;
  6. 每个版本只冻结已经实现并通过测试的能力;
  7. 所有测试输入和测试输出都应可重复、可追踪、可自动检查。

2. 测试对象与范围

2.1 程序对象

CCLite 测试体系包含三个程序对象:

对象 测试责任
CCLite 主控流程、.inp 解析、IPC 调度、共享内存管理、界面数据、接触与耦合算法、诊断输出
SPHLite worker CCLite worker/service 模式、SPH 界面数据导出、外力导入、命令响应
FEMLite worker CCLite worker/service 模式、FEM 界面数据导出、面载荷导入、命令响应

此外,测试体系必须提供 mock solver:

  1. mock_sph_worker;
  2. mock_fem_worker;
  3. 必要时提供 mock_combined_worker,用于极简 IPC 和时序测试。

mock solver 不承担真实物理计算责任,只承担可控数据生成、命令响应、故障注入和结果校验责任。

2.2 功能范围

测试范围包括:

  1. .inp 关键词解析;
  2. CCLite 主控状态机;
  3. worker/service 启动与退出;
  4. named event 控制同步;
  5. command shared block;
  6. data block header;
  7. AoR v1 payload;
  8. 接口版本检查;
  9. SPH 粒子与 FEM facet 几何搜索;
  10. point-triangle、point-quad、point-edge 最近点;
  11. 壳厚度接触判定;
  12. penalty 接触力;
  13. 法向阻尼;
  14. Coulomb 摩擦;
  15. FEM 节点力分配;
  16. tied coupling;
  17. release;
  18. pressure projection;
  19. boundary/ghost particle;
  20. Riemann FSI;
  21. 显式同步;
  22. 异步子循环;
  23. 弱耦合和强耦合迭代;
  24. 诊断输出;
  25. 非有限值、超时和异常处理;
  26. 回归与性能测试。

2.3 第一阶段平台范围

0.1.x 第一版验收平台为:

  1. Windows;
  2. gfortran;
  3. 本机运行;
  4. named event;
  5. Windows shared memory;
  6. CCLite、SPHLite worker、FEMLite worker 三独立进程。

Linux、MPI、socket、跨机器通信只作为预留方向,不进入 0.1.x 验收。

2.4 测试通过定义

一个测试项通过必须同时满足:

  1. 程序正常退出,返回码符合预期;
  2. 日志没有未解释的 ERROR;
  3. 诊断 CSV 字段完整;
  4. 数值结果满足该测试项容差;
  5. 共享内存和事件资源被释放;
  6. 失败路径测试能够给出预期错误码;
  7. 测试结果可由自动检查脚本重复判定。

3. 测试分层

3.1 单元测试

单元测试面向单个模块、单个函数或单个数据结构,重点验证局部逻辑正确性。

单元测试不依赖真实 SPHLite 和 FEMLite 主程序,不依赖三进程调度。必要时可直接构造内存数据结构。

单元测试覆盖:

  1. .inp 解析器;
  2. keyword 参数校验;
  3. vector、AABB、hash grid;
  4. 最近点算法;
  5. 接触穿透量计算;
  6. 接触力计算;
  7. FEM 节点力分配;
  8. 接触诊断量;
  9. data block header 校验;
  10. command block 字段编码;
  11. 错误码映射;
  12. 非有限值检查。

3.2 接口测试

接口测试面向 05 号文档定义的外部接口协议。

接口测试关注:

  1. worker 启动参数;
  2. command block 字段;
  3. named event wait/signal/reset 责任;
  4. heartbeat 和 ack;
  5. shared memory block 创建、打开、关闭;
  6. data block header;
  7. AoR v1 payload;
  8. block role;
  9. layout id;
  10. 版本兼容;
  11. 超时和异常处理。

接口测试必须优先使用 mock solver,因为 mock solver 能稳定构造正常路径和错误路径。

3.3 集成测试

集成测试面向 CCLite 与 worker 的联合运行。

集成测试分三类:

  1. CCLite + mock SPH worker + mock FEM worker;
  2. CCLite + 真实 SPHLite worker + mock FEM worker,或反向组合;
  3. CCLite + 真实 SPHLite worker + 真实 FEMLite worker。

0.1.x 必须完成第一类集成测试。

0.2.x 起逐步增加真实 worker 集成测试。

3.4 验证算例

验证算例面向数学模型和物理行为。

验证算例应优先选择:

  1. 有解析解的简单问题;
  2. 可用手工计算复核的极小问题;
  3. 可与独立脚本结果比较的问题;
  4. 经典文献或工程常用 benchmark;
  5. 可稳定重复的工程简化问题。

验证算例不追求一开始覆盖所有复杂现象,而应确保每个算法能力进入版本时有对应的最小可信证据。

3.5 回归测试

回归测试用于保证新版本没有破坏已有能力。

所有已经验收通过的用例应进入回归集合。若一个用例因为算法升级导致数值基线合理变化,必须记录:

  1. 变化原因;
  2. 影响范围;
  3. 新旧结果对比;
  4. 是否需要调整容差;
  5. 谁批准基线更新。

3.6 性能与稳定性测试

性能测试不作为 0.1.x 核心验收项,但必须从 0.2.x 开始保留基础指标。

性能与稳定性测试关注:

  1. 单步 IPC 延迟;
  2. data block 读写耗时;
  3. 几何搜索耗时;
  4. 接触对数量;
  5. 单步总耗时;
  6. 内存占用;
  7. 长时间运行稳定性;
  8. 大接触面数量下的退化行为。

0.8.x 起,性能测试应覆盖 AoR v1 与 SoA v2 block 的对比。

4. 测试环境与工具

4.1 编译环境

第一阶段推荐测试环境:

项目 要求
操作系统 Windows
Fortran 编译器 gfortran
C/C++ 编译器 仅 IPC 薄层必要时使用
构建方式 批处理、Makefile 或 CMake 均可,实际以仓库实现为准
字符编码 UTF-8 without BOM

测试脚本和测试数据必须避免依赖开发者本机绝对路径。

4.2 运行模式

测试应覆盖三种运行模式:

模式 说明
check 只检查输入、接口配置和资源可用性
dry-run 创建 IPC 资源、启动 worker、执行空耦合或有限步模拟,不做完整物理计算
run 执行真实联合仿真

0.1.x 必须完成 check 和 dry-run 测试。

0.2.x 起 run 模式进入接触验证。

4.3 Python checker

允许使用 Python 编写测试检查脚本,用于:

  1. 读取 CSV;
  2. 检查误差;
  3. 比较基线;
  4. 生成简短测试报告;
  5. 检查日志关键字;
  6. 统计性能指标。

允许借助仓库中的 .\Python\ 目录实现以下辅助能力:

  1. 生成小规模验证算例的 .inp 输入文件;
  2. 生成 mock worker 使用的可控输入数据;
  3. 计算解析解或独立参考解;
  4. 检查 CCLite 输出 CSV;
  5. 汇总 verification_report.json 或 verification_report.txt;
  6. 对真实 SPHLite/FEMLite worker 输出进行调试性解析。

Python checker 不应替代 Fortran 核心算法实现。Python 只用于测试、验证、参考解、算例生成和自动化检查。

建议 .\Python\ 后续按以下职责细分:

Python/
  checkers/
  references/
  casegen/
  runners/

其中 checkers 负责输出检查,references 负责解析解或独立参考值,casegen 负责生成小算例输入,runners 负责封装外部程序运行。已有调试脚本可在不破坏其用途的前提下逐步迁入该结构。

4.4 推荐目录

建议测试目录采用:

tests/
  unit/
  interface/
  integration/
  verification/
  regression/
  performance/
  data/
  baselines/
  checkers/

建议算例目录采用:

cases/
  v0_1_ipc_empty_coupling/
  v0_2_single_particle_wall/
  v0_3_shell_edge_contact/
  v0_4_friction_slide/
  v0_5_tied_release/
  v0_6_pressure_plate/
  v0_7_riemann_interface/
  v0_8_stability_suite/
  v0_9_engineering_cases/

目录名称中的版本号表示该算例第一次进入验收的版本,不表示该算例只在该版本运行。

4.5 输出文件

每个测试算例至少应生成:

  1. run.log;
  2. ipc_report.csv;
  3. contact_report.csv,若该算例涉及接触;
  4. force_balance.csv,若该算例涉及力交换;
  5. timestep_report.csv,若该算例涉及时间步控制;
  6. verification_report.json 或 verification_report.txt。

CSV 文件用于数值自动检查,日志用于人工定位。

4.6 容差约定

测试容差分为四类:

类型 含义
bitwise 字段、枚举、layout、错误码必须完全一致
absolute 使用绝对误差检查
relative 使用相对误差检查
statistical 用于长时间或大规模算例的统计指标

接口测试默认使用 bitwise 判定。

几何测试优先使用 absolute 判定。

物理验证测试根据变量量级同时使用 absolute 和 relative 判定。

初始建议:

项目 默认容差
坐标最近点 1.0e-10 到 1.0e-8,按精度实现调整
力平衡相对误差 1.0e-8 到 1.0e-5,按算例规模调整
能量诊断误差 1.0e-6 到 1.0e-3,按模型和时间步调整
接触穿透量 不超过用户设定接触尺度的指定比例
IPC 字段 完全一致

正式容差应在具体测试用例中写明,不应只依赖本文档默认值。

5. 测试数据与诊断输出

5.1 输入文件

CCLite 测试输入采用 Abaqus 风格 .inp。

每个联合测试至少包含:

  1. CCLite .inp;
  2. SPHLite 输入文件,真实 worker 测试需要;
  3. FEMLite 输入文件,真实 worker 测试需要;
  4. 期望输出说明;
  5. 自动检查配置。

mock solver 测试可只提供 CCLite .inp 和 mock 数据配置。

5.2 基线数据

基线数据用于回归比较。

基线数据应包含:

  1. 输入文件版本;
  2. CCLite 版本;
  3. SPHLite 和 FEMLite 版本;
  4. 编译器信息;
  5. 平台信息;
  6. 关键输出 CSV;
  7. 检查报告;
  8. 容差配置。

基线更新必须有明确原因,不能因为测试失败而直接覆盖旧基线。

5.3 诊断量

接触和耦合测试至少检查以下诊断量:

诊断量 说明
num_candidate_pairs 宽相候选对数量
num_active_contacts 活跃接触数量
max_penetration 最大穿透量
sum_force_sph CCLite 写给 SPH 的总力
sum_force_fem CCLite 写给 FEM 的总力
force_balance_error 作用反作用误差
moment_balance_error 力矩平衡误差
contact_work 接触功
ipc_latency IPC 同步耗时
step_status 步状态
error_code 错误码

0.6.x 起,应增加 FSI 诊断量。

0.7.x 起,应增加 Riemann FSI 和子循环诊断量。

5.4 日志要求

日志必须记录:

  1. 程序版本;
  2. 输入文件路径;
  3. worker 启动命令;
  4. shared memory block 名称;
  5. named event 名称;
  6. layout id;
  7. command id;
  8. step id;
  9. substep id;
  10. iteration id;
  11. worker state;
  12. 超时与错误码;
  13. 资源释放结果。

日志中的错误信息应足以判断错误属于输入、接口、算法、worker 还是系统资源。

6. 单元测试计划

6.1 .inp 解析测试

.inp 解析测试覆盖:

  1. 正常关键词;
  2. 参数顺序变化;
  3. 大小写兼容;
  4. 注释行;
  5. 空行;
  6. 重复关键词;
  7. 缺失必需参数;
  8. 未知关键词;
  9. 非法枚举;
  10. 非法数值范围;
  11. 文件路径参数;
  12. 多 solver 配置。

通过标准:

  1. 合法输入生成正确 case 对象;
  2. 非法输入生成明确错误码;
  3. 错误行号和关键词名可定位;
  4. 不因空行、注释、大小写造成误判。

6.2 几何基础测试

几何基础测试覆盖:

  1. vector 点积、叉积、长度、归一化;
  2. AABB 合并、扩展、相交;
  3. hash grid cell index;
  4. 点到线段最近点;
  5. 点到三角形最近点;
  6. 点到四边形最近点;
  7. barycentric 坐标;
  8. 边缘 fallback;
  9. 退化三角形;
  10. 退化四边形;
  11. 壳厚度间隙;
  12. 法向翻转。

通过标准:

  1. 最近点坐标满足容差;
  2. 穿透量符号与 04 号文档一致;
  3. 退化几何不产生未定义结果;
  4. edge fallback 能识别边缘接触;
  5. 法向方向可解释并可诊断。

6.3 搜索算法测试

搜索算法测试覆盖:

  1. 单粒子单 facet;
  2. 多粒子单 facet;
  3. 单粒子多 facet;
  4. cell 边界上的粒子;
  5. 搜索半径变化;
  6. 空集合;
  7. 大量非接触对象;
  8. 候选对去重;
  9. surface id 过滤;
  10. 接触 pair id 稳定性。

通过标准:

  1. 候选对不漏检指定接触;
  2. 候选对不出现重复记录;
  3. 空输入返回空结果;
  4. 搜索耗时随规模增长符合预期;
  5. 候选对数量可诊断。

6.4 接触力测试

接触力单元测试覆盖:

  1. 零穿透;
  2. 正穿透;
  3. 负间隙;
  4. 法向 penalty;
  5. 法向阻尼;
  6. 切向相对速度;
  7. Coulomb 粘着区;
  8. Coulomb 滑移区;
  9. 力限幅;
  10. 非有限值保护;
  11. FEM 三角形节点分配;
  12. FEM 四边形节点分配;
  13. 力矩一致性。

通过标准:

  1. 接触开启和关闭条件正确;
  2. 法向力方向正确;
  3. 摩擦力不超过 Coulomb 上限;
  4. 分配到 FEM 节点的合力等于接触反力;
  5. 分配后总力矩误差满足容差;
  6. 非有限输入被拒绝或安全处理。

6.5 Tied 与 Release 测试

Tied 与 release 单元测试覆盖:

  1. tie 初始绑定;
  2. tie 位移约束;
  3. penalty tie 力;
  4. release 阈值;
  5. release 后转入 contact;
  6. 多点 tie;
  7. tie 诊断输出;
  8. 能量记录。

通过标准:

  1. tie 对象在未 release 前保持绑定关系;
  2. release 条件满足时状态只转换一次;
  3. release 后接触状态与普通 contact 一致;
  4. 诊断量能追踪状态变化。

6.6 FSI 数学测试

FSI 单元测试覆盖:

  1. pressure projection;
  2. 面法向压力转节点载荷;
  3. FEM 运动边界速度导出;
  4. boundary particle 数据构造;
  5. ghost particle 数据构造;
  6. 声阻抗 Riemann 近似;
  7. 界面压力;
  8. 界面速度;
  9. 载荷方向;
  10. 单位一致性。

通过标准:

  1. 均匀压力载荷积分正确;
  2. 界面速度和压力符号与 04 号文档一致;
  3. Riemann 简化解在退化输入下稳定;
  4. 单位换算不引入隐藏比例因子。

6.7 时间耦合测试

时间耦合单元测试覆盖:

  1. 显式同步步进;
  2. 异步子循环步进;
  3. macro step;
  4. substep id;
  5. iteration id;
  6. force relaxation;
  7. 强耦合残差;
  8. 时间步拒绝;
  9. 时间步重试;
  10. 最大迭代失败。

通过标准:

  1. 时间不倒退;
  2. step id、substep id、iteration id 单调可解释;
  3. 子循环结束时间与 macro step 对齐;
  4. 失败路径给出可追踪错误码。

7. 接口测试计划

7.1 Worker/Service 启动测试

worker 启动测试覆盖:

  1. 正常启动;
  2. 缺少 worker 参数;
  3. 非法 solver id;
  4. shared memory 名称错误;
  5. event 名称错误;
  6. worker 初始化超时;
  7. worker 主动退出;
  8. CCLite 请求退出;
  9. 重复启动;
  10. 资源清理。

通过标准:

  1. worker 能进入 READY 状态;
  2. heartbeat_seq 能递增;
  3. CCLite 能收到 ack_seq;
  4. 异常启动返回明确错误码;
  5. 退出后 IPC 资源被释放。

7.2 Command Shared Block 测试

command block 测试覆盖 05 号文档中的字段:

  1. magic;
  2. abi_version;
  3. layout_id;
  4. solver_id;
  5. command_id;
  6. command_seq;
  7. ack_seq;
  8. step_id;
  9. substep_id;
  10. iteration_id;
  11. command_flags;
  12. heartbeat_seq;
  13. worker_state;
  14. int_param[16];
  15. real_param[16];
  16. macro_dt;
  17. error_code。

通过标准:

  1. 所有字段按 05 号文档布局编码;
  2. 字节数、偏移和对齐满足接口定义;
  3. command seq 与 ack seq 配对正确;
  4. worker state 转换合法;
  5. 错误码不被覆盖;
  6. 旧版本字段兼容策略符合预期。

7.3 Named Event 测试

named event 测试覆盖:

  1. COMMAND_EVENT;
  2. DONE_EVENT;
  3. CCLite reset command event;
  4. CCLite reset done event;
  5. worker wait command event;
  6. worker signal done event;
  7. 超时;
  8. signal 丢失;
  9. 重复 signal;
  10. worker 异常退出。

通过标准:

  1. reset 责任符合 05 号文档;
  2. 正常命令不丢失;
  3. 超时能被 CCLite 识别;
  4. worker 卡死时 CCLite 不永久等待;
  5. 日志记录事件名和 command seq。

7.4 Data Block Header 测试

data block header 测试覆盖:

  1. block magic;
  2. block role;
  3. layout id;
  4. header size;
  5. record size;
  6. record count;
  7. capacity;
  8. byte size;
  9. data state;
  10. producer id;
  11. consumer id;
  12. step id;
  13. substep id;
  14. checksum 或 header 校验;
  15. 保留字段置零。

通过标准:

  1. CCLite 能拒绝非法 header;
  2. 生产者和消费者 id 匹配;
  3. record count 不超过 capacity;
  4. record size 与 layout id 匹配;
  5. buffer state 转换合法。

7.5 AoR v1 Payload 测试

AoR v1 payload 测试覆盖:

  1. SPH_TO_CCL_PARTICLE;
  2. SPH_TO_CCL_FACET;
  3. FEM_TO_CCL_FACET;
  4. CCL_TO_SPH_FORCE;
  5. CCL_TO_FEM_LOAD;
  6. CCL_DIAGNOSTIC。

重点字段包括:

  1. id;
  2. position;
  3. velocity;
  4. mass;
  5. radius 或 smoothing length;
  6. density;
  7. pressure;
  8. sound_speed;
  9. node ids;
  10. facet normal;
  11. surface_id;
  12. shell_thickness;
  13. mass_per_area;
  14. valid_flags;
  15. source id;
  16. load_mode;
  17. distribution_mode。

通过标准:

  1. payload 字段与 05 号文档一致;
  2. 空 payload 可被接受;
  3. 最大 capacity payload 可被处理;
  4. 无效 record 被跳过或报错,行为必须符合定义;
  5. CCLite 不读取未初始化字段。

7.6 版本兼容测试

版本兼容测试覆盖:

  1. 相同 ABI 版本;
  2. minor 版本差异;
  3. 不支持的 layout id;
  4. 不支持的 block role;
  5. AoR v1;
  6. SoA v2 预留;
  7. 字段扩展;
  8. worker 版本低于 CCLite;
  9. worker 版本高于 CCLite;
  10. 强制拒绝不兼容版本。

通过标准:

  1. 可兼容版本继续运行;
  2. 不兼容版本在初始化阶段停止;
  3. 错误信息写出双方版本;
  4. 不发生 silent fallback。

7.7 故障注入接口测试

故障注入测试覆盖:

  1. worker 不启动;
  2. worker 启动后不响应;
  3. worker 写入错误 header;
  4. worker 写入错误 layout id;
  5. worker 写入 NaN;
  6. worker record count 超限;
  7. worker command seq 不匹配;
  8. worker heartbeat 停止;
  9. shared memory 打开失败;
  10. named event 打开失败;
  11. CCLite 中途请求终止;
  12. worker 中途崩溃。

通过标准:

  1. CCLite 不崩溃;
  2. 错误码符合定义;
  3. 资源释放;
  4. 日志可定位故障点;
  5. 后续测试不受残留资源影响。

8. 集成测试计划

8.1 CCLite + mock workers

0.1.x 必须完成 CCLite + mock SPH worker + mock FEM worker 的集成测试。

测试场景包括:

  1. 三进程正常启动;
  2. worker ready;
  3. 初始化 data block;
  4. 执行空耦合 step;
  5. 写入 mock SPH 粒子;
  6. 写入 mock FEM facet;
  7. CCLite 读取数据;
  8. CCLite 写回空载荷;
  9. worker ack;
  10. CCLite 正常退出;
  11. 多步循环;
  12. 中途终止。

通过标准:

  1. 至少连续运行指定步数;
  2. 每步 command seq 和 ack seq 匹配;
  3. 所有 data block header 合法;
  4. IPC 诊断完整;
  5. 退出后没有残留 worker 进程。

8.2 CCLite + 单真实 worker

单真实 worker 集成测试用于分阶段接入 SPHLite 和 FEMLite。

组合包括:

  1. CCLite + 真实 SPHLite worker + mock FEM worker;
  2. CCLite + mock SPH worker + 真实 FEMLite worker。

通过标准:

  1. 真实 worker 能进入 CCLite worker/service 模式;
  2. 真实 worker 能按 05 号接口写出 payload;
  3. CCLite 能读取真实 worker 数据;
  4. CCLite 写回载荷后真实 worker 能接受;
  5. 单真实 worker 的异常不会破坏另一 mock worker。

8.3 CCLite + 双真实 workers

双真实 worker 集成测试用于真实联合仿真。

测试阶段:

  1. 空耦合;
  2. 单步接触;
  3. 多步接触;
  4. 简单 FSI;
  5. tied/release;
  6. 子循环;
  7. 长时间运行。

通过标准:

  1. 三程序按主控顺序运行;
  2. 两个 worker 不直接通信;
  3. 所有数据交换都经过 CCLite;
  4. 接口载荷方向正确;
  5. 诊断量可解释;
  6. 程序能够正常结束。

8.4 check / dry-run / run 集成测试

每个关键算例应尽量覆盖:

模式 检查内容
check 输入、路径、关键词、接口配置
dry-run IPC 资源、worker 启动、空耦合循环
run 真实联合计算和结果验证

check 和 dry-run 是定位问题的第一层防线,不能只依赖 run 模式。

9. 验证算例计划

9.1 总体约定

验证算例是算法和工程行为进入版本验收的最小可信证据。验证算例不同于演示算例:验证算例必须有明确输入、参考值、检查指标和通过判据;演示算例可以展示功能效果,但不能单独作为算法正确性证据。

每个验证算例必须包含:

  1. 算例编号;
  2. 首次进入验收的版本;
  3. 验证目标;
  4. 使用的 CCLite .inp;
  5. 使用 mock worker 还是真实 worker;
  6. SPH 输入或 mock SPH 数据;
  7. FEM 输入或 mock FEM 数据;
  8. 参考值来源;
  9. 输出文件清单;
  10. Python checker;
  11. 通过判据;
  12. 失败分类建议。

凡是没有解析值、独立脚本参考值或可手算参考值的算例,只能作为演示、稳定性观察或工程趋势算例,不能作为核心算法正确性验收算例。

9.2 算例实现层级

验证算例按三层推进:

层级 说明 适用版本
A 层:mock 算例 使用 mock worker 或直接构造接口数据,验证 CCLite 算法和接口 0.1.x 起
B 层:单真实 worker 算例 一侧真实 SPHLite/FEMLite worker,另一侧 mock worker 0.2.x 起
C 层:双真实 worker 算例 SPHLite 和 FEMLite 都以 worker/service 模式参与 0.2.x 后逐步增加

所有核心物理算例应先完成 A 层,再进入 B 层和 C 层。这样可以先排除 CCLite 算法和接口错误,再讨论真实求解器内部误差。

9.3 Python 辅助算例约定

允许借助 .\Python\ 实现验证算例辅助能力,但 Fortran 仍是 CCLite 算法核心。

建议 Python 脚本职责如下:

目录 职责
Python/casegen/ 生成小规模 .inp、mock 数据和固定参数表
Python/references/ 计算解析解、半解析参考解或独立公式结果
Python/checkers/ 读取 CSV、检查误差、生成验证报告
Python/runners/ 封装 CCLite、SPHLite、FEMLite 或 mock worker 的运行

Python checker 的输出建议统一为:

verification_report.json

报告至少包含:

  1. case_id;
  2. case_version;
  3. status;
  4. tolerance;
  5. metrics;
  6. failed_checks;
  7. input_files;
  8. output_files;
  9. reference_source。

Python 参考解必须独立于 CCLite Fortran 实现,不应直接复制 Fortran 源码逻辑。若参考解也是同一公式实现,应在报告中说明其参考公式来自 04 号文档的具体章节。

9.4 0.1.x 空耦合与 IPC 验证算例

算例编号:V010_EMPTY_COUPLING

验证目标:

  1. CCLite 可独立启动;
  2. SPHLite mock worker 和 FEMLite mock worker 可进入 worker/service 模式;
  3. Windows shared memory 和 named event 可形成闭环;
  4. command block、data block header 和 AoR v1 payload 可完成最小读写;
  5. 空耦合循环可重复执行。

输入模型:

  1. CCLite .inp 指定两个 worker、共享内存名称、event 名称、总步数和输出目录;
  2. mock SPH worker 每步写入 0 个或少量固定粒子;
  3. mock FEM worker 每步写入 0 个或少量固定 facet;
  4. CCLite 不产生真实接触力,只写回空载荷或零载荷。

参考值:

  1. command_seq 与 ack_seq 应逐步配对;
  2. step_id 应从 1 到指定步数连续递增;
  3. num_active_contacts = 0;
  4. sum_force_sph = 0;
  5. sum_force_fem = 0。

输出文件:

  1. run.log;
  2. ipc_report.csv;
  3. force_balance.csv;
  4. verification_report.json。

Python 检查:

  1. 检查 ipc_report.csv 中每步 seq/ack 配对;
  2. 检查 worker state 合法;
  3. 检查超时次数为 0;
  4. 检查空耦合载荷为 0;
  5. 检查进程正常退出。

通过判据:

  1. 连续运行不少于 100 个空耦合 step;
  2. 无 IPC 超时;
  3. 无未解释错误码;
  4. 退出后没有残留 worker;
  5. 资源释放日志完整。

9.5 几何验证算例

算例编号:V020_GEOMETRY_PRIMITIVES

首次验收版本:0.2.x,0.3.x 扩展 shell、edge 和 quad。

验证目标:

  1. 验证 04 号第 4 章的几何 primitive;
  2. 验证最近点、法向间隙和穿透量;
  3. 验证退化几何处理;
  4. 验证后续接触力计算的几何输入可靠。

输入模型:

子算例 输入
点到三角形内部 一个粒子位于三角形法向上方,投影点在三角形内部
点到三角形边 一个粒子投影到三角形外部且最近点在线段上
点到三角形顶点 一个粒子最近点为三角形顶点
点到四边形内部 一个粒子投影到四边形内部
非平面四边形 四边形四点轻微非共面
壳中面接触 设置 shell thickness,粒子接近壳中面
退化 facet 三角形面积为 0 或四边形两点重合

参考值:

  1. 最近点坐标由 Python references 脚本按解析几何公式计算;
  2. barycentric 坐标可手工复核;
  3. 壳厚度穿透量按 04 号第 4.6 节公式计算;
  4. 退化 facet 的期望行为为诊断并跳过。

输出文件:

  1. contact_report.csv;
  2. geometry_report.csv,若实现提供;
  3. verification_report.json。

Python 检查:

  1. 比较最近点坐标;
  2. 比较法向间隙;
  3. 比较穿透量;
  4. 检查退化 facet 数量;
  5. 检查 active contact 状态。

通过判据:

  1. 最近点误差满足几何容差;
  2. 接触状态符合穿透量定义;
  3. quad 与等价 triangle 组合结果一致;
  4. 壳厚度改变接触开启位置;
  5. 退化几何不产生接触力。

9.6 单粒子撞刚性面

算例编号:V020_SINGLE_PARTICLE_WALL

首次验收版本:0.2.x。

验证目标:

  1. 作为 0.2.x 第一个真实物理验收算例;
  2. 验证 SPH 粒子到 FEM facet 的 penalty 接触主链路;
  3. 验证接触开启、法向力、冲量、力平衡和诊断输出;
  4. 为真实 SPHLite/FEMLite worker 接入提供最小联合算例。

实现层级:

  1. A 层:mock SPH 粒子和 mock FEM facet,先验证 CCLite 接触算法;
  2. B 层:真实 SPHLite worker + mock FEM worker,验证 SPH 外力写回;
  3. B 层:mock SPH worker + 真实 FEMLite worker,验证 FEM 面载荷写回;
  4. C 层:真实 SPHLite worker + 真实 FEMLite worker,验证完整联合运行。

输入模型:

  1. 一个 SPH 粒子;
  2. 一个固定 FEM 三角形 facet;
  3. 粒子初始位置在 facet 法向外侧;
  4. 粒子速度指向 facet;
  5. 首个验收版本不启用摩擦;
  6. 阻尼可分为关闭和开启两个子算例。

参考值:

  1. 接触开启条件由粒子半径、facet 位置和法向间隙手算;
  2. 法向 penalty 力由 04 号第 5.3 节公式计算;
  3. 阻尼子算例由 04 号第 5.4 节公式计算;
  4. 冲量参考值可由 Python 按离散时间积分计算;
  5. 力平衡参考值为 SPH 力与 FEM 反力相加为 0。

输出文件:

  1. contact_report.csv;
  2. force_balance.csv;
  3. timestep_report.csv;
  4. verification_report.json。

Python 检查:

  1. 检查接触开启步;
  2. 检查最大穿透量;
  3. 检查法向力方向;
  4. 检查法向力幅值;
  5. 检查冲量;
  6. 检查 force balance;
  7. 检查无阻尼和有阻尼能量趋势。

通过判据:

  1. 未接触前接触力为 0;
  2. 穿透后法向力阻止继续穿透;
  3. SPH 力与 FEM 反力满足平衡容差;
  4. 无阻尼时能量误差满足容差;
  5. 有阻尼时能量耗散方向正确;
  6. 真实 worker 算例中载荷方向与 mock 算例一致。

9.7 多粒子压平面

算例编号:V020_MULTI_PARTICLE_PLANE

首次验收版本:0.2.x。

验证目标:

  1. 验证多接触对搜索;
  2. 验证接触力累加;
  3. 验证 FEM 节点载荷分配;
  4. 验证总力和总力矩平衡;
  5. 验证接触对去重。

输入模型:

  1. 多个 SPH 粒子按规则阵列布置;
  2. 一个或多个 FEM facet 构成平面;
  3. 粒子垂直压向平面;
  4. FEM 平面保持固定或做规定运动;
  5. 初始可使用 mock 数据,随后接入真实 worker。

参考值:

  1. 每个粒子的穿透量可由几何关系手算;
  2. 每个粒子的 penalty 力由 04 号第 5 章公式计算;
  3. FEM 节点载荷由 barycentric 或面积权重计算;
  4. 总力矩以选定参考点计算。

输出文件:

  1. contact_report.csv;
  2. force_balance.csv;
  3. verification_report.json。

Python 检查:

  1. 检查活跃接触数量;
  2. 检查每个粒子接触力;
  3. 检查 FEM 节点力之和;
  4. 检查总力矩;
  5. 检查重复 pair id。

通过判据:

  1. 总力等于各粒子接触力累加;
  2. 节点力分配后总力和总力矩一致;
  3. 无重复接触对;
  4. 接触诊断 CSV 完整;
  5. 接触 pair id 在连续步中可追踪。

9.8 边缘与壳厚度接触

算例编号:V030_SHELL_EDGE_CONTACT

首次验收版本:0.3.x。

验证目标:

  1. 验证 shell thickness;
  2. 验证 edge fallback;
  3. 验证 triangle 和 quad facet;
  4. 验证接触状态连续性;
  5. 验证法向跳变诊断。

输入模型:

  1. 粒子靠近 FEM 壳边缘;
  2. 设置非零 shell thickness;
  3. 同时构造 triangle 和 quad 子算例;
  4. 粒子轨迹经过面内部、边缘和角点;
  5. quad 子算例应提供等价 triangle 拆分参考。

参考值:

  1. 壳厚度修正由 04 号第 4.6 节计算;
  2. edge 最近点由点到线段公式计算;
  3. quad 参考值由两个 triangle 子问题取一致结果;
  4. 接触状态连续性由连续步 active contact 变化检查。

输出文件:

  1. contact_report.csv;
  2. geometry_report.csv,若实现提供;
  3. verification_report.json。

Python 检查:

  1. 检查边缘附近是否漏检;
  2. 检查 shell thickness 对接触开启位置的影响;
  3. 检查 quad 与 triangle 组合一致性;
  4. 检查法向跳变幅度;
  5. 检查异常几何诊断。

通过判据:

  1. 边缘附近不漏检;
  2. 壳厚度改变接触开启位置;
  3. quad 与等价 triangle 组合结果一致;
  4. 接触力不出现非物理尖峰,或尖峰被诊断;
  5. 退化 facet 不产生有效接触力。

9.9 摩擦滑移

算例编号:V040_FRICTION_SLIDE

首次验收版本:0.4.x。

验证目标:

  1. 验证 Coulomb 摩擦;
  2. 验证粘着和滑移状态;
  3. 验证切向力方向;
  4. 验证摩擦耗能;
  5. 验证稳定时间步和阻尼对结果的影响。

输入模型:

  1. 一个粒子或粒子组与 FEM 平面接触;
  2. 设置法向预压或重力等效载荷;
  3. 设置切向相对速度;
  4. 设置多个摩擦系数;
  5. 分别运行粘着子算例和滑移子算例。

参考值:

  1. 摩擦上限为 mu * normal_force;
  2. 滑移方向由相对切向速度确定;
  3. 粘着区切向力由 penalty 切向模型或历史位移计算;
  4. 摩擦功应为非正值,具体符号按 04 号文档约定。

输出文件:

  1. contact_report.csv;
  2. force_balance.csv;
  3. timestep_report.csv;
  4. verification_report.json。

Python 检查:

  1. 检查切向力方向;
  2. 检查摩擦力上限;
  3. 检查粘着到滑移转换;
  4. 检查接触功;
  5. 检查能量耗散方向。

通过判据:

  1. 摩擦力反向于相对滑移趋势;
  2. 摩擦力不超过 Coulomb 上限;
  3. 能量不因摩擦非物理增加;
  4. 诊断输出区分 normal 和 tangential 分量;
  5. 关闭摩擦时结果退化到无摩擦算例。

9.10 Tied Coupling 与 Release

算例编号:V050_TIED_RELEASE

首次验收版本:0.5.x。

验证目标:

  1. 验证 tied coupling;
  2. 验证 release 阈值;
  3. 验证 release 后转入普通 contact;
  4. 验证状态转换诊断;
  5. 验证 tied/release 能量记录。

输入模型:

  1. SPH 粒子初始绑定到 FEM 面;
  2. FEM 面发生规定运动或受载运动;
  3. 设置 release 位移、力或能量阈值;
  4. release 后粒子继续与 FEM 面接触;
  5. 至少包含 release 和不 release 两个子算例。

参考值:

  1. tie 位移由初始局部坐标和 FEM 面运动计算;
  2. tie 力由 04 号第 6 章 penalty tie 模型计算;
  3. release 触发步由阈值条件计算;
  4. release 后接触力参考普通 contact 公式。

输出文件:

  1. contact_report.csv;
  2. tie_release_report.csv,若实现提供;
  3. force_balance.csv;
  4. verification_report.json。

Python 检查:

  1. 检查初始绑定关系;
  2. 检查 release 前 tie 状态;
  3. 检查 release 触发步;
  4. 检查 release 只触发一次;
  5. 检查 release 后不再施加 tie 约束;
  6. 检查 release 后 contact 状态。

通过判据:

  1. release 前绑定对象稳定;
  2. release 条件可复现;
  3. release 后状态转换不可逆,除非输入显式允许重新绑定;
  4. release 后接触力与普通 contact 一致;
  5. 诊断能还原状态变化。

9.11 均匀压力作用于 FEM 面

算例编号:V060_PRESSURE_TO_FEM

首次验收版本:0.6.x。

验证目标:

  1. 验证 pressure projection;
  2. 验证 SPH 压力到 FEM 面载荷;
  3. 验证节点载荷分配;
  4. 验证载荷方向和单位;
  5. 验证 FSI 基础诊断输出。

输入模型:

  1. SPH 侧提供均匀压力场;
  2. FEM 侧提供一个或多个平面 facet;
  3. CCLite 将压力转换为 FEM 面载荷;
  4. FEM 可固定,只验证载荷积分;
  5. 子算例可覆盖 triangle 和 quad。

参考值:

  1. 总载荷为 pressure * area;
  2. 节点载荷由面积坐标或形函数权重分配;
  3. 载荷方向由 FEM facet 法向和 04 号约定决定;
  4. 力矩由节点位置和节点载荷计算。

输出文件:

  1. force_balance.csv;
  2. fsi_report.csv,若实现提供;
  3. verification_report.json。

Python 检查:

  1. 检查总载荷;
  2. 检查节点载荷;
  3. 检查力矩;
  4. 检查载荷方向;
  5. 检查单位换算。

通过判据:

  1. 总载荷等于压力乘面积;
  2. 节点分配保持总力和总力矩;
  3. 载荷方向与法向约定一致;
  4. 单位不出现比例错误;
  5. 压力为 0 时载荷为 0。

9.12 运动边界与 Boundary/Ghost Particle

算例编号:V060_MOVING_BOUNDARY

首次验收版本:0.6.x。

验证目标:

  1. 验证 FEM 运动边界到 SPH 的传递;
  2. 验证 boundary particle 数据;
  3. 验证 ghost particle 数据;
  4. 验证边界速度和时间同步;
  5. 验证数据生命周期。

输入模型:

  1. FEM 边界做规定速度运动;
  2. CCLite 读取 FEM 边界位置和速度;
  3. SPH worker 接收边界速度或 ghost/boundary 数据;
  4. 使用小规模规则粒子分布;
  5. 包含静止边界和运动边界两个子算例。

参考值:

  1. 边界速度由规定运动函数计算;
  2. boundary/ghost 位置由 FEM facet 和法向偏移计算;
  3. step 和 substep 对应关系由时间同步规则计算。

输出文件:

  1. fsi_report.csv;
  2. ipc_report.csv;
  3. verification_report.json。

Python 检查:

  1. 检查 SPH 接收的边界速度;
  2. 检查 ghost/boundary 数据位置;
  3. 检查 step 与 substep 对应;
  4. 检查数据不跨步误用;
  5. 检查数据数量。

通过判据:

  1. SPH 接收到的边界速度与 FEM 规定运动一致;
  2. ghost/boundary 数据不越界;
  3. step、substep 数据对应正确;
  4. 边界静止时速度为 0;
  5. 运动边界不破坏 IPC 同步。

9.13 一维声阻抗 Riemann 界面

算例编号:V070_RIEMANN_INTERFACE_1D

首次验收版本:0.7.x。

验证目标:

  1. 验证 Riemann FSI 主算法;
  2. 验证界面压力;
  3. 验证界面速度;
  4. 验证声阻抗极限状态;
  5. 验证非物理输入保护。

输入模型:

  1. SPH 侧和 FEM 侧各给定一维等效状态;
  2. 指定密度、声速、压力和法向速度;
  3. CCLite 计算界面压力和界面速度;
  4. 子算例覆盖左右状态相同、高阻抗差、低阻抗差和反向速度。

参考值:

  1. Python references 按 04 号第 8 章声阻抗近似公式计算;
  2. 左右状态相同时界面状态应等于原状态;
  3. 高阻抗侧速度响应应小于低阻抗侧;
  4. 非物理密度或声速应触发错误或安全降级。

输出文件:

  1. fsi_report.csv;
  2. force_balance.csv;
  3. verification_report.json。

Python 检查:

  1. 检查界面压力;
  2. 检查界面速度;
  3. 检查载荷方向;
  4. 检查声阻抗极限情况;
  5. 检查异常输入处理。

通过判据:

  1. Riemann 输出与参考计算一致;
  2. 左右状态相同时不产生虚假扰动;
  3. 高阻抗极限趋势正确;
  4. 非物理输入被拒绝或安全处理;
  5. 诊断记录界面状态。

9.14 异步子循环

算例编号:V070_ASYNC_SUBCYCLING

首次验收版本:0.7.x。

验证目标:

  1. 验证显式-显式异步子循环;
  2. 验证 macro step、substep 和 iteration id;
  3. 验证数据交换时刻;
  4. 验证 force hold 或 interpolation 策略;
  5. 验证失败定位到具体 substep。

输入模型:

  1. SPHLite 使用较小时间步;
  2. FEMLite 使用较大时间步;
  3. CCLite 以 macro step 调度;
  4. 一个 solver 在 macro step 内执行多个 substep;
  5. 初始可使用 mock worker 控制各自时间步。

参考值:

  1. macro step 结束时两个 solver 时间应一致;
  2. substep id 应连续;
  3. force hold 或 interpolation 结果由 Python 根据策略计算;
  4. 数据交换次数由步长比决定。

输出文件:

  1. ipc_report.csv;
  2. timestep_report.csv;
  3. force_balance.csv;
  4. verification_report.json。

Python 检查:

  1. 检查 substep 数量;
  2. 检查每个 worker 的时间;
  3. 检查数据交换时刻;
  4. 检查 force hold 或 interpolation 值;
  5. 检查失败定位信息。

通过判据:

  1. macro step 结束时两个 solver 时间一致;
  2. substep id 连续;
  3. 数据不会跨步误用;
  4. 失败时能定位到具体 substep;
  5. 真实 worker 接入后仍保持相同调度语义。

9.15 稳定性套件

算例编号:V080_STABILITY_SUITE

首次验收版本:0.8.x。

验证目标:

  1. 验证 force relaxation;
  2. 验证接触历史补强;
  3. 验证异常输入保护;
  4. 验证长时间运行稳定性;
  5. 验证 AoR v1 与 SoA v2 性能对比。

套件组成:

子算例 验证点
大 penalty 刚度 接触稳定时间步和非有限值保护
小时间步 长时间步进和诊断输出体量
大速度冲击 最大穿透量、力峰值和 relaxation
多接触对 搜索性能和 pair 管理
接触反复开启关闭 persistence 和历史状态
摩擦滑移 摩擦历史变量稳定性
tied release 后接触 状态转换和历史清理
FSI 压力波 pressure projection 和时间同步
worker 延迟 timeout、heartbeat、ack
非有限值故障注入 NaN/Inf 捕获和错误码

输出文件:

  1. run.log;
  2. ipc_report.csv;
  3. contact_report.csv;
  4. force_balance.csv;
  5. timestep_report.csv;
  6. performance_report.csv;
  7. verification_report.json。

Python 检查:

  1. 检查非有限值;
  2. 检查错误码;
  3. 检查最大穿透量;
  4. 检查能量和冲量趋势;
  5. 检查长时间运行步数;
  6. 检查 AoR v1 与 SoA v2 性能差异;
  7. 检查 worker 延迟场景的超时处理。

通过判据:

  1. 程序不崩溃;
  2. 非有限值被捕获;
  3. 诊断能指出不稳定来源;
  4. force relaxation 生效;
  5. 接触历史不发生错误串扰;
  6. SoA v2 优化不改变物理验收结果。

9.16 工程简化算例

算例编号:V090_ENGINEERING_CASES

首次验收版本:0.9.x。

验证目标:

  1. 验证工程趋势;
  2. 建立参数推荐范围;
  3. 建立性能基线;
  4. 验证长时间运行稳定性;
  5. 为 0.10.x 发布候选提供工程证据。

工程简化算例从 0.9.x 起作为硬验收,不提前作为 0.6.x 或 0.7.x 的基础正确性验收。

建议方向:

  1. 水下爆炸冲击简化模型;
  2. 粒子流冲击薄板;
  3. SPH 颗粒堆积与 FEM 壁面;
  4. 流固压力作用下的弹性板;
  5. 局部破坏或 release 后接触。

水下爆炸 FSI 在本路线中放入 0.9.x 工程简化算例。0.6.x 只验证 pressure projection、边界速度和 boundary/ghost 数据;0.7.x 只验证 Riemann FSI 与时间耦合的可拆解小问题。

参考值:

  1. 工程趋势可来自独立脚本、简化理论或既有试算结果;
  2. 若没有严格解析解,应明确标记为趋势验证;
  3. 参数推荐范围必须来自参数扫描结果;
  4. 关键诊断量必须可复现。

输出文件:

  1. run.log;
  2. contact_report.csv;
  3. fsi_report.csv;
  4. force_balance.csv;
  5. timestep_report.csv;
  6. performance_report.csv;
  7. verification_report.json。

Python 检查:

  1. 检查关键趋势量;
  2. 检查参数扫描结果;
  3. 检查长时间运行稳定性;
  4. 检查性能指标;
  5. 检查回归基线。

通过判据:

  1. 结果趋势符合工程认知;
  2. 关键诊断量稳定;
  3. 参数推荐范围可复用;
  4. 长时间运行无资源泄漏;
  5. 回归基线稳定;
  6. 算例说明足够让用户复现。

9.17 0.10.x 全量回归算例

算例编号:V100_RELEASE_REGRESSION

首次验收版本:0.10.x。

验证目标:

  1. 冻结 0.x 开发线接口;
  2. 冻结文档与测试基线;
  3. 确认 0.1.x 到 0.9.x 的已验收能力未退化;
  4. 在干净环境中重建并运行全量测试;
  5. 形成工程发布候选证据。

输入模型:

  1. 0.1.x 到 0.9.x 所有已验收算例;
  2. AoR v1 和 SoA v2 相关接口测试;
  3. 真实 SPHLite/FEMLite worker 的代表算例;
  4. 版本兼容和错误路径算例;
  5. 文档一致性检查。

参考值:

  1. 已冻结回归基线;
  2. 每个算例自己的解析值或参考解;
  3. 接口布局和枚举来自 05 号文档;
  4. 算法公式和判据来自 04 号文档。

输出文件:

  1. release_test_report.json;
  2. release_test_summary.txt;
  3. 全量 CSV 输出;
  4. 性能基线;
  5. 文档一致性检查结果。

Python 检查:

  1. 汇总全量测试结果;
  2. 检查回归差异;
  3. 检查接口兼容;
  4. 检查文档章节追踪;
  5. 生成发布候选测试摘要。

通过判据:

  1. 全量单元测试通过;
  2. 全量接口测试通过;
  3. 全量集成测试通过;
  4. 全量验证算例通过;
  5. 全量回归测试通过;
  6. 性能指标不低于已批准基线;
  7. 文档、接口和测试矩阵一致。

10. 验收判据

10.1 通用验收判据

所有版本通用验收判据:

  1. 文档与实现一致;
  2. .inp 输入可复现;
  3. 测试用例可一键或按说明运行;
  4. 自动检查报告给出通过或失败;
  5. 失败时错误码和日志可定位;
  6. 已通过测试进入回归集合;
  7. 不引入未说明的接口破坏。

10.2 接口验收判据

接口验收采用严格判定:

  1. magic、version、layout、role 完全一致;
  2. record size 完全一致;
  3. 枚举值完全一致;
  4. 字节序和对齐符合 05 号文档;
  5. command seq 与 ack seq 正确;
  6. worker state 合法;
  7. timeout 行为可复现;
  8. 错误码可追踪。

接口测试失败时,不应继续执行物理验证算例。

10.3 几何验收判据

几何验收关注:

  1. 最近点;
  2. 接触法向;
  3. 穿透量;
  4. 候选对;
  5. edge fallback;
  6. 壳厚度;
  7. 退化处理。

几何错误会直接影响接触力方向和稳定性,因此几何验收是 0.2.x 之后所有接触版本的前置条件。

10.4 接触验收判据

接触验收关注:

  1. 接触开启和关闭;
  2. 法向力方向;
  3. 阻尼力方向;
  4. 摩擦力上限;
  5. 作用反作用;
  6. 力矩一致性;
  7. 接触功;
  8. 最大穿透量;
  9. 非有限值保护。

接触力可以根据不同算法参数改变幅值,但不得违反方向、守恒和约束激活逻辑。

10.5 FSI 验收判据

FSI 验收关注:

  1. 压力积分;
  2. 速度边界;
  3. ghost/boundary 数据;
  4. Riemann 界面压力;
  5. Riemann 界面速度;
  6. 载荷方向;
  7. 时间同步;
  8. 稳定性。

FSI 算例应优先使用小规模、可解释模型,避免过早使用复杂工程场景作为唯一验收依据。

10.6 性能验收判据

性能验收分阶段执行。

0.1.x 只记录 IPC 和启动耗时,不设置严格性能门槛。

0.2.x 到 0.7.x 记录每步耗时、搜索耗时、接触对数量和数据传输耗时。

0.8.x 起必须比较 AoR v1 与 SoA v2 的性能差异。

0.9.x 起建立工程算例性能目标。

性能测试不能以牺牲接口兼容性和数值正确性为代价。

11. 版本测试与验证路线

11.1 0.1.x 主控与通信闭环

目标:

  1. CCLite 独立主控;
  2. SPHLite worker/service 模式;
  3. FEMLite worker/service 模式;
  4. Windows shared memory;
  5. named event;
  6. command block;
  7. AoR v1 data block;
  8. 空耦合循环;
  9. CSV 诊断。

必须通过:

  1. .inp check 测试;
  2. worker 启动测试;
  3. command block 测试;
  4. event 同步测试;
  5. data block header 测试;
  6. mock workers 空耦合集成测试;
  7. timeout 和错误码测试;
  8. 资源释放测试。

0.1.x 不要求真实接触力验收。

11.2 0.2.x 基础 SPH-FEM Penalty 接触

目标:

  1. SPH 粒子到 FEM 三角形 facet;
  2. 基础宽相搜索;
  3. 点到三角形最近点;
  4. 法向 penalty 接触;
  5. FEM 节点力分配;
  6. force balance 诊断。

必须通过:

  1. 几何基础单元测试;
  2. 搜索算法单元测试;
  3. 单粒子撞刚性面;
  4. 多粒子压平面;
  5. 力平衡测试;
  6. CCLite + 至少一个真实 worker 集成测试。

11.3 0.3.x 壳、边缘与四边形接触

目标:

  1. shell thickness;
  2. edge fallback;
  3. quad facet;
  4. 接触 persistence 初步;
  5. 接触诊断增强。

必须通过:

  1. 点到四边形几何测试;
  2. 边缘接触测试;
  3. 壳厚度测试;
  4. quad 与 triangle 组合一致性测试;
  5. 接触状态连续性测试。

11.4 0.4.x 阻尼、摩擦与稳定时间步

目标:

  1. 法向阻尼;
  2. Coulomb 摩擦;
  3. penalty 参数估计;
  4. 接触稳定时间步;
  5. 接触能量诊断。

必须通过:

  1. 阻尼单元测试;
  2. 摩擦滑移验证;
  3. 能量耗散检查;
  4. penalty 参数范围测试;
  5. 稳定时间步诊断测试。

11.5 0.5.x Tied Coupling 与 Release

目标:

  1. tied coupling;
  2. release;
  3. tie-to-contact;
  4. 状态转换诊断;
  5. 能量记录。

必须通过:

  1. tie 单元测试;
  2. release 阈值测试;
  3. tied/release 集成算例;
  4. release 后接触验证;
  5. 状态转换回归测试。

11.6 0.6.x Pressure Projection 与 Boundary/Ghost Particle

目标:

  1. SPH 压力到 FEM 面载荷;
  2. FEM 运动边界到 SPH;
  3. boundary particle;
  4. ghost particle;
  5. FSI 基础诊断。

必须通过:

  1. 均匀压力作用于 FEM 面;
  2. 运动边界传递测试;
  3. boundary/ghost 数据测试;
  4. FSI 载荷方向测试;
  5. 单位一致性测试。

11.7 0.7.x Riemann FSI 与时间耦合

目标:

  1. Riemann FSI 主算法;
  2. 异步子循环;
  3. 显式-隐式弱耦合框架;
  4. 强耦合迭代框架;
  5. 算法主体完成。

必须通过:

  1. 一维声阻抗 Riemann 界面;
  2. Riemann 极限状态测试;
  3. 异步子循环测试;
  4. 弱耦合流程测试;
  5. 强耦合迭代状态机测试;
  6. 算法章节到测试项的覆盖审查。

0.7.x 完成后,04 号文档中的主要算法应均有实现入口和基本验证。

11.8 0.8.x 稳定化、性能优化与 SoA v2

目标:

  1. force relaxation;
  2. 接触历史补强;
  3. 能量修正;
  4. 异常处理补强;
  5. AoR v1 与 SoA v2 性能对比;
  6. 长时间运行稳定性。

必须通过:

  1. 稳定性套件;
  2. 非有限值故障注入;
  3. worker 延迟测试;
  4. 长时间运行测试;
  5. AoR v1 / SoA v2 对比测试;
  6. 回归测试全量通过。

11.9 0.9.x 工程算例与参数推荐

目标:

  1. 工程简化算例集合;
  2. 参数推荐范围;
  3. 性能目标;
  4. 工程验收矩阵;
  5. 文档和测试闭环。

必须通过:

  1. 工程简化算例;
  2. 参数敏感性测试;
  3. 性能基线测试;
  4. 长时间稳定性测试;
  5. 回归测试全量通过;
  6. 用户可复现实验说明。

11.10 0.10.x 接口冻结与工程发布候选

目标:

  1. 接口冻结;
  2. 文档冻结;
  3. 回归体系冻结;
  4. 版本兼容策略冻结;
  5. 工程发布候选。

必须通过:

  1. 全量单元测试;
  2. 全量接口测试;
  3. 全量集成测试;
  4. 全量验证算例;
  5. 全量回归测试;
  6. 性能测试;
  7. 文档一致性审查;
  8. 干净环境重建测试。

0.10.x 不表示进入 1.0.x,而是 0.x 开发线的第十个工程版本阶段。

12. 追踪矩阵

12.1 数学模型到测试项

04 号章节 测试覆盖
第 3 章 界面数据抽象 data block、payload、单位一致性测试
第 4 章 几何搜索与接触检测 几何单元测试、几何验证算例、边缘和壳测试
第 5 章 接触力与摩擦模型 接触力单元测试、单粒子撞面、多粒子压面、摩擦滑移
第 6 章 Tied Coupling 与 Release tied/release 单元测试和验证算例
第 7 章 FSI 压力、速度与边界粒子 均匀压力、运动边界、boundary/ghost 测试
第 8 章 Riemann FSI 一维声阻抗 Riemann 界面测试
第 9 章 时间耦合数学框架 显式同步、异步子循环、弱耦合、强耦合状态机测试
第 10 章 稳定性控制 稳定性套件、force relaxation、非有限值测试
第 11 章 守恒与诊断量 force balance、moment balance、contact work、impulse 测试

12.2 接口文档到测试项

05 号章节 测试覆盖
Worker/Service 模式接口 worker 启动、退出、心跳、异常测试
.inp 关键词接口 .inp 解析和 check 模式测试
控制 IPC 接口 named event 测试
Command Shared Block command block 字段、版本、seq/ack 测试
Data Block Header header、role、state、capacity、checksum 测试
AoR v1 Payload 各 record 布局和字段测试
命令与状态枚举 command id、worker state、load mode 测试
错误码与异常处理 timeout、非法 header、worker 崩溃、NaN 测试
版本兼容策略 ABI、layout、AoR/SoA 兼容测试

12.3 版本到验收项

版本 验收重点
0.1.x IPC、worker、mock solver、空耦合
0.2.x 基础 penalty contact
0.3.x 壳、边缘、四边形、接触状态
0.4.x 阻尼、摩擦、稳定时间步
0.5.x tied、release、tie-to-contact
0.6.x pressure projection、boundary/ghost
0.7.x Riemann FSI、子循环、弱/强耦合框架
0.8.x 稳定化、性能、SoA v2、异常处理
0.9.x 工程算例、参数推荐、性能目标
0.10.x 文档冻结、接口冻结、全量回归、发布候选

13. 自动化与执行策略

13.1 测试执行层级

建议执行层级:

  1. quick:单元测试和基础接口测试;
  2. standard:quick + mock 集成 + 小验证算例;
  3. full:standard + 真实 worker + 回归测试;
  4. release:full + 性能测试 + 工程算例 + 文档一致性检查。

日常开发至少运行 quick。

合并关键接口或算法变更前应运行 standard。

版本验收前应运行 release。

13.2 自动检查报告

自动检查报告至少包含:

  1. 测试名称;
  2. 测试版本;
  3. 运行时间;
  4. 平台;
  5. 编译器;
  6. CCLite commit;
  7. SPHLite commit 或版本;
  8. FEMLite commit 或版本;
  9. 通过数量;
  10. 失败数量;
  11. 跳过数量;
  12. 失败原因摘要;
  13. 输出路径。

13.3 测试命名

建议测试命名使用:

test_<layer>_<feature>_<condition>

示例:

test_unit_closest_point_triangle_inside
test_interface_command_block_seq_ack
test_integration_mock_empty_coupling_100_steps
test_verification_single_particle_wall_no_damping

13.4 失败分类

测试失败分为:

类型 说明
INPUT 输入文件或测试配置错误
BUILD 编译或链接错误
IPC shared memory、event、command block 错误
INTERFACE payload、layout、版本兼容错误
ALGORITHM 几何、接触、耦合算法错误
NUMERICAL 数值误差或稳定性错误
WORKER SPHLite/FEMLite worker 行为错误
SYSTEM 平台资源或系统调用错误
TEST 测试脚本或基线错误

失败分类应写入测试报告,便于定位责任边界。

14. 风险与对策

14.1 Mock 测试通过但真实 worker 失败

风险:

mock solver 可能过于理想,不能暴露真实 worker 的数据生命周期、时间步和异常行为。

对策:

  1. 0.2.x 起引入单真实 worker 集成测试;
  2. 真实 worker 输出必须经过同一套接口检查;
  3. mock solver 增加故障注入;
  4. 用真实 worker 数据回放构造回归测试。

14.2 接口变化破坏回归

风险:

共享内存 layout 一旦变化,旧测试和旧 worker 可能无法运行。

对策:

  1. 所有 layout 变化必须更新 05 号文档;
  2. layout id 必须递增或明确兼容;
  3. 版本兼容测试必须先于集成测试;
  4. 0.10.x 前冻结接口。

14.3 数值结果依赖参数

风险:

接触刚度、阻尼、时间步和摩擦参数会显著影响结果。

对策:

  1. 验证算例固定参数;
  2. 参数写入输入文件;
  3. 输出参数摘要;
  4. 0.9.x 建立参数推荐范围;
  5. 回归测试允许有记录的基线更新。

14.4 工程算例过早进入硬验收

风险:

复杂工程算例问题来源多,难以判断失败属于接口、算法还是模型设置。

对策:

  1. 0.1.x 到 0.7.x 以小算例为主;
  2. 0.9.x 再建立工程算例硬验收;
  3. 工程算例必须拆分出可验证的子问题;
  4. 不用复杂工程算例替代基础验证。

14.5 性能优化影响正确性

风险:

SoA v2、并行搜索或缓存优化可能改变接触对顺序和浮点累加结果。

对策:

  1. 0.8.x 才引入 SoA v2 性能优化;
  2. 保留 AoR v1 作为对照;
  3. 对排序无关结果使用合力、力矩和误差判据;
  4. 对顺序敏感诊断明确排序规则。

15. 第一阶段冻结项

0.1.x 第一阶段测试计划冻结以下内容:

  1. 测试分层采用单元测试、接口测试、集成测试、验证算例四层主结构;
  2. 0.1.x 以 mock solver、IPC、worker、空耦合为主要验收目标;
  3. 0.2.x 以单粒子和小规模 SPH-FEM penalty contact 为主要接触验收目标;
  4. 允许使用 Python checker 检查 CSV 和数值结果;
  5. 验收计划按 0.1.x 到 0.10.x 组织;
  6. 第一阶段平台为 Windows/gfortran/本机共享内存;
  7. Linux/MPI 只作为预留测试方向;
  8. 接口测试必须严格追踪 05 号文档;
  9. 算法验证必须严格追踪 04 号文档;
  10. 0.2.x 第一个真实物理验收算例定为单粒子撞刚性面;
  11. 核心物理算例应先用 mock 数据验证 CCLite 算法,再逐步接入真实 SPHLite/FEMLite worker;
  12. 工程简化算例从 0.9.x 起作为硬验收;
  13. 核心验证算例必须有解析值、独立脚本参考值或可手算参考值;
  14. 水下爆炸 FSI 暂定为 0.9.x 工程简化算例;
  15. 允许借助 .\Python\ 实现算例生成、参考解、runner 和 checker;
  16. 0.10.x 是 0.x 开发线的工程发布候选阶段,不自动跳转为 1.0.x。

16. 待细化事项

以下事项应在代码和测试框架建立后进一步细化:

  1. 具体测试目录是否与最终源码目录合并;
  2. gfortran 单元测试框架选择;
  3. Python checker 的最终报告 schema;
  4. CSV 字段最终名称;
  5. 每个验证算例的默认数值参数;
  6. 每个版本的测试运行时间目标;
  7. 工程算例数据是否纳入仓库;
  8. 大文件测试数据的管理方式;
  9. 0.8.x SoA v2 的性能基准;
  10. 0.9.x 工程验收矩阵。

本文档后续应随 03、04、05 号文档和代码实现同步维护。