58 KiB
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 文档边界
本文档覆盖:
- 单元测试;
- 接口测试;
- 集成测试;
- 验证算例;
- 回归测试;
- 性能与稳定性测试;
- 版本验收矩阵;
- 测试数据、输出文件和检查工具要求。
本文档不覆盖:
- SPHLite 和 FEMLite 各自独立求解器内部算法的完整验证;
- 商业软件级别的标准认证;
- Linux/MPI 分布式执行的第一阶段验收;
- 未进入 04 号数学模型文档的扩展算法。
SPHLite 和 FEMLite 的内部求解准确性应由各自项目负责。CCLite 只验证三程序联合运行、接口数据一致性、耦合算法正确性和联合算例结果合理性。
1.3 与其他文档的关系
01 号需求规格说明书定义 CCLite 要做什么。
02 号概要设计说明书定义 CCLite 的总体结构和模块边界。
03 号详细设计说明书定义 CCLite 的实现结构、数据类型和运行流程。
04 号数学模型与算法说明书定义接触、耦合、FSI、时间同步和稳定性算法的理论基础。
05 号接口控制文档定义 CCLite、SPHLite worker、FEMLite worker 之间的外部接口协议。
本文档负责回答:
- 如何确认 04 号算法实现正确;
- 如何确认 05 号接口实现兼容;
- 如何确认三程序联合运行稳定;
- 每个版本需要通过哪些验收项;
- 测试失败时如何定位责任边界。
1.4 测试原则
CCLite 测试体系采用以下原则:
- 先接口闭环,后物理精度;
- 先 mock solver,后真实 solver;
- 先小算例可解释,后工程算例覆盖;
- 先确定性验收,后性能优化;
- 先守恒和一致性检查,后复杂现象拟合;
- 每个版本只冻结已经实现并通过测试的能力;
- 所有测试输入和测试输出都应可重复、可追踪、可自动检查。
2. 测试对象与范围
2.1 程序对象
CCLite 测试体系包含三个程序对象:
| 对象 | 测试责任 |
|---|---|
| CCLite | 主控流程、.inp 解析、IPC 调度、共享内存管理、界面数据、接触与耦合算法、诊断输出 |
| SPHLite worker | CCLite worker/service 模式、SPH 界面数据导出、外力导入、命令响应 |
| FEMLite worker | CCLite worker/service 模式、FEM 界面数据导出、面载荷导入、命令响应 |
此外,测试体系必须提供 mock solver:
mock_sph_worker;mock_fem_worker;- 必要时提供
mock_combined_worker,用于极简 IPC 和时序测试。
mock solver 不承担真实物理计算责任,只承担可控数据生成、命令响应、故障注入和结果校验责任。
2.2 功能范围
测试范围包括:
.inp关键词解析;- CCLite 主控状态机;
- worker/service 启动与退出;
- named event 控制同步;
- command shared block;
- data block header;
- AoR v1 payload;
- 接口版本检查;
- SPH 粒子与 FEM facet 几何搜索;
- point-triangle、point-quad、point-edge 最近点;
- 壳厚度接触判定;
- penalty 接触力;
- 法向阻尼;
- Coulomb 摩擦;
- FEM 节点力分配;
- tied coupling;
- release;
- pressure projection;
- boundary/ghost particle;
- Riemann FSI;
- 显式同步;
- 异步子循环;
- 弱耦合和强耦合迭代;
- 诊断输出;
- 非有限值、超时和异常处理;
- 回归与性能测试。
2.3 第一阶段平台范围
0.1.x 第一版验收平台为:
- Windows;
- gfortran;
- 本机运行;
- named event;
- Windows shared memory;
- CCLite、SPHLite worker、FEMLite worker 三独立进程。
Linux、MPI、socket、跨机器通信只作为预留方向,不进入 0.1.x 验收。
2.4 测试通过定义
一个测试项通过必须同时满足:
- 程序正常退出,返回码符合预期;
- 日志没有未解释的
ERROR; - 诊断 CSV 字段完整;
- 数值结果满足该测试项容差;
- 共享内存和事件资源被释放;
- 失败路径测试能够给出预期错误码;
- 测试结果可由自动检查脚本重复判定。
3. 测试分层
3.1 单元测试
单元测试面向单个模块、单个函数或单个数据结构,重点验证局部逻辑正确性。
单元测试不依赖真实 SPHLite 和 FEMLite 主程序,不依赖三进程调度。必要时可直接构造内存数据结构。
单元测试覆盖:
.inp解析器;- keyword 参数校验;
- vector、AABB、hash grid;
- 最近点算法;
- 接触穿透量计算;
- 接触力计算;
- FEM 节点力分配;
- 接触诊断量;
- data block header 校验;
- command block 字段编码;
- 错误码映射;
- 非有限值检查。
3.2 接口测试
接口测试面向 05 号文档定义的外部接口协议。
接口测试关注:
- worker 启动参数;
- command block 字段;
- named event wait/signal/reset 责任;
- heartbeat 和 ack;
- shared memory block 创建、打开、关闭;
- data block header;
- AoR v1 payload;
- block role;
- layout id;
- 版本兼容;
- 超时和异常处理。
接口测试必须优先使用 mock solver,因为 mock solver 能稳定构造正常路径和错误路径。
3.3 集成测试
集成测试面向 CCLite 与 worker 的联合运行。
集成测试分三类:
- CCLite + mock SPH worker + mock FEM worker;
- CCLite + 真实 SPHLite worker + mock FEM worker,或反向组合;
- CCLite + 真实 SPHLite worker + 真实 FEMLite worker。
0.1.x 必须完成第一类集成测试。
0.2.x 起逐步增加真实 worker 集成测试。
3.4 验证算例
验证算例面向数学模型和物理行为。
验证算例应优先选择:
- 有解析解的简单问题;
- 可用手工计算复核的极小问题;
- 可与独立脚本结果比较的问题;
- 经典文献或工程常用 benchmark;
- 可稳定重复的工程简化问题。
验证算例不追求一开始覆盖所有复杂现象,而应确保每个算法能力进入版本时有对应的最小可信证据。
3.5 回归测试
回归测试用于保证新版本没有破坏已有能力。
所有已经验收通过的用例应进入回归集合。若一个用例因为算法升级导致数值基线合理变化,必须记录:
- 变化原因;
- 影响范围;
- 新旧结果对比;
- 是否需要调整容差;
- 谁批准基线更新。
3.6 性能与稳定性测试
性能测试不作为 0.1.x 核心验收项,但必须从 0.2.x 开始保留基础指标。
性能与稳定性测试关注:
- 单步 IPC 延迟;
- data block 读写耗时;
- 几何搜索耗时;
- 接触对数量;
- 单步总耗时;
- 内存占用;
- 长时间运行稳定性;
- 大接触面数量下的退化行为。
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 编写测试检查脚本,用于:
- 读取 CSV;
- 检查误差;
- 比较基线;
- 生成简短测试报告;
- 检查日志关键字;
- 统计性能指标。
允许借助仓库中的 .\Python\ 目录实现以下辅助能力:
- 生成小规模验证算例的
.inp输入文件; - 生成 mock worker 使用的可控输入数据;
- 计算解析解或独立参考解;
- 检查 CCLite 输出 CSV;
- 汇总
verification_report.json或verification_report.txt; - 对真实 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 输出文件
每个测试算例至少应生成:
run.log;ipc_report.csv;contact_report.csv,若该算例涉及接触;force_balance.csv,若该算例涉及力交换;timestep_report.csv,若该算例涉及时间步控制;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。
每个联合测试至少包含:
- CCLite
.inp; - SPHLite 输入文件,真实 worker 测试需要;
- FEMLite 输入文件,真实 worker 测试需要;
- 期望输出说明;
- 自动检查配置。
mock solver 测试可只提供 CCLite .inp 和 mock 数据配置。
5.2 基线数据
基线数据用于回归比较。
基线数据应包含:
- 输入文件版本;
- CCLite 版本;
- SPHLite 和 FEMLite 版本;
- 编译器信息;
- 平台信息;
- 关键输出 CSV;
- 检查报告;
- 容差配置。
基线更新必须有明确原因,不能因为测试失败而直接覆盖旧基线。
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 日志要求
日志必须记录:
- 程序版本;
- 输入文件路径;
- worker 启动命令;
- shared memory block 名称;
- named event 名称;
- layout id;
- command id;
- step id;
- substep id;
- iteration id;
- worker state;
- 超时与错误码;
- 资源释放结果。
日志中的错误信息应足以判断错误属于输入、接口、算法、worker 还是系统资源。
6. 单元测试计划
6.1 .inp 解析测试
.inp 解析测试覆盖:
- 正常关键词;
- 参数顺序变化;
- 大小写兼容;
- 注释行;
- 空行;
- 重复关键词;
- 缺失必需参数;
- 未知关键词;
- 非法枚举;
- 非法数值范围;
- 文件路径参数;
- 多 solver 配置。
通过标准:
- 合法输入生成正确 case 对象;
- 非法输入生成明确错误码;
- 错误行号和关键词名可定位;
- 不因空行、注释、大小写造成误判。
6.2 几何基础测试
几何基础测试覆盖:
- vector 点积、叉积、长度、归一化;
- AABB 合并、扩展、相交;
- hash grid cell index;
- 点到线段最近点;
- 点到三角形最近点;
- 点到四边形最近点;
- barycentric 坐标;
- 边缘 fallback;
- 退化三角形;
- 退化四边形;
- 壳厚度间隙;
- 法向翻转。
通过标准:
- 最近点坐标满足容差;
- 穿透量符号与 04 号文档一致;
- 退化几何不产生未定义结果;
- edge fallback 能识别边缘接触;
- 法向方向可解释并可诊断。
6.3 搜索算法测试
搜索算法测试覆盖:
- 单粒子单 facet;
- 多粒子单 facet;
- 单粒子多 facet;
- cell 边界上的粒子;
- 搜索半径变化;
- 空集合;
- 大量非接触对象;
- 候选对去重;
- surface id 过滤;
- 接触 pair id 稳定性。
通过标准:
- 候选对不漏检指定接触;
- 候选对不出现重复记录;
- 空输入返回空结果;
- 搜索耗时随规模增长符合预期;
- 候选对数量可诊断。
6.4 接触力测试
接触力单元测试覆盖:
- 零穿透;
- 正穿透;
- 负间隙;
- 法向 penalty;
- 法向阻尼;
- 切向相对速度;
- Coulomb 粘着区;
- Coulomb 滑移区;
- 力限幅;
- 非有限值保护;
- FEM 三角形节点分配;
- FEM 四边形节点分配;
- 力矩一致性。
通过标准:
- 接触开启和关闭条件正确;
- 法向力方向正确;
- 摩擦力不超过 Coulomb 上限;
- 分配到 FEM 节点的合力等于接触反力;
- 分配后总力矩误差满足容差;
- 非有限输入被拒绝或安全处理。
6.5 Tied 与 Release 测试
Tied 与 release 单元测试覆盖:
- tie 初始绑定;
- tie 位移约束;
- penalty tie 力;
- release 阈值;
- release 后转入 contact;
- 多点 tie;
- tie 诊断输出;
- 能量记录。
通过标准:
- tie 对象在未 release 前保持绑定关系;
- release 条件满足时状态只转换一次;
- release 后接触状态与普通 contact 一致;
- 诊断量能追踪状态变化。
6.6 FSI 数学测试
FSI 单元测试覆盖:
- pressure projection;
- 面法向压力转节点载荷;
- FEM 运动边界速度导出;
- boundary particle 数据构造;
- ghost particle 数据构造;
- 声阻抗 Riemann 近似;
- 界面压力;
- 界面速度;
- 载荷方向;
- 单位一致性。
通过标准:
- 均匀压力载荷积分正确;
- 界面速度和压力符号与 04 号文档一致;
- Riemann 简化解在退化输入下稳定;
- 单位换算不引入隐藏比例因子。
6.7 时间耦合测试
时间耦合单元测试覆盖:
- 显式同步步进;
- 异步子循环步进;
- macro step;
- substep id;
- iteration id;
- force relaxation;
- 强耦合残差;
- 时间步拒绝;
- 时间步重试;
- 最大迭代失败。
通过标准:
- 时间不倒退;
- step id、substep id、iteration id 单调可解释;
- 子循环结束时间与 macro step 对齐;
- 失败路径给出可追踪错误码。
7. 接口测试计划
7.1 Worker/Service 启动测试
worker 启动测试覆盖:
- 正常启动;
- 缺少 worker 参数;
- 非法 solver id;
- shared memory 名称错误;
- event 名称错误;
- worker 初始化超时;
- worker 主动退出;
- CCLite 请求退出;
- 重复启动;
- 资源清理。
通过标准:
- worker 能进入
READY状态; heartbeat_seq能递增;- CCLite 能收到
ack_seq; - 异常启动返回明确错误码;
- 退出后 IPC 资源被释放。
7.2 Command Shared Block 测试
command block 测试覆盖 05 号文档中的字段:
magic;abi_version;layout_id;solver_id;command_id;command_seq;ack_seq;step_id;substep_id;iteration_id;command_flags;heartbeat_seq;worker_state;int_param[16];real_param[16];macro_dt;error_code。
通过标准:
- 所有字段按 05 号文档布局编码;
- 字节数、偏移和对齐满足接口定义;
- command seq 与 ack seq 配对正确;
- worker state 转换合法;
- 错误码不被覆盖;
- 旧版本字段兼容策略符合预期。
7.3 Named Event 测试
named event 测试覆盖:
COMMAND_EVENT;DONE_EVENT;- CCLite reset command event;
- CCLite reset done event;
- worker wait command event;
- worker signal done event;
- 超时;
- signal 丢失;
- 重复 signal;
- worker 异常退出。
通过标准:
- reset 责任符合 05 号文档;
- 正常命令不丢失;
- 超时能被 CCLite 识别;
- worker 卡死时 CCLite 不永久等待;
- 日志记录事件名和 command seq。
7.4 Data Block Header 测试
data block header 测试覆盖:
- block magic;
- block role;
- layout id;
- header size;
- record size;
- record count;
- capacity;
- byte size;
- data state;
- producer id;
- consumer id;
- step id;
- substep id;
- checksum 或 header 校验;
- 保留字段置零。
通过标准:
- CCLite 能拒绝非法 header;
- 生产者和消费者 id 匹配;
- record count 不超过 capacity;
- record size 与 layout id 匹配;
- buffer state 转换合法。
7.5 AoR v1 Payload 测试
AoR v1 payload 测试覆盖:
SPH_TO_CCL_PARTICLE;SPH_TO_CCL_FACET;FEM_TO_CCL_FACET;CCL_TO_SPH_FORCE;CCL_TO_FEM_LOAD;CCL_DIAGNOSTIC。
重点字段包括:
- id;
- position;
- velocity;
- mass;
- radius 或 smoothing length;
- density;
- pressure;
- sound_speed;
- node ids;
- facet normal;
- surface_id;
- shell_thickness;
- mass_per_area;
- valid_flags;
- source id;
- load_mode;
- distribution_mode。
通过标准:
- payload 字段与 05 号文档一致;
- 空 payload 可被接受;
- 最大 capacity payload 可被处理;
- 无效 record 被跳过或报错,行为必须符合定义;
- CCLite 不读取未初始化字段。
7.6 版本兼容测试
版本兼容测试覆盖:
- 相同 ABI 版本;
- minor 版本差异;
- 不支持的 layout id;
- 不支持的 block role;
- AoR v1;
- SoA v2 预留;
- 字段扩展;
- worker 版本低于 CCLite;
- worker 版本高于 CCLite;
- 强制拒绝不兼容版本。
通过标准:
- 可兼容版本继续运行;
- 不兼容版本在初始化阶段停止;
- 错误信息写出双方版本;
- 不发生 silent fallback。
7.7 故障注入接口测试
故障注入测试覆盖:
- worker 不启动;
- worker 启动后不响应;
- worker 写入错误 header;
- worker 写入错误 layout id;
- worker 写入 NaN;
- worker record count 超限;
- worker command seq 不匹配;
- worker heartbeat 停止;
- shared memory 打开失败;
- named event 打开失败;
- CCLite 中途请求终止;
- worker 中途崩溃。
通过标准:
- CCLite 不崩溃;
- 错误码符合定义;
- 资源释放;
- 日志可定位故障点;
- 后续测试不受残留资源影响。
8. 集成测试计划
8.1 CCLite + mock workers
0.1.x 必须完成 CCLite + mock SPH worker + mock FEM worker 的集成测试。
测试场景包括:
- 三进程正常启动;
- worker ready;
- 初始化 data block;
- 执行空耦合 step;
- 写入 mock SPH 粒子;
- 写入 mock FEM facet;
- CCLite 读取数据;
- CCLite 写回空载荷;
- worker ack;
- CCLite 正常退出;
- 多步循环;
- 中途终止。
通过标准:
- 至少连续运行指定步数;
- 每步 command seq 和 ack seq 匹配;
- 所有 data block header 合法;
- IPC 诊断完整;
- 退出后没有残留 worker 进程。
8.2 CCLite + 单真实 worker
单真实 worker 集成测试用于分阶段接入 SPHLite 和 FEMLite。
组合包括:
- CCLite + 真实 SPHLite worker + mock FEM worker;
- CCLite + mock SPH worker + 真实 FEMLite worker。
通过标准:
- 真实 worker 能进入 CCLite worker/service 模式;
- 真实 worker 能按 05 号接口写出 payload;
- CCLite 能读取真实 worker 数据;
- CCLite 写回载荷后真实 worker 能接受;
- 单真实 worker 的异常不会破坏另一 mock worker。
8.3 CCLite + 双真实 workers
双真实 worker 集成测试用于真实联合仿真。
测试阶段:
- 空耦合;
- 单步接触;
- 多步接触;
- 简单 FSI;
- tied/release;
- 子循环;
- 长时间运行。
通过标准:
- 三程序按主控顺序运行;
- 两个 worker 不直接通信;
- 所有数据交换都经过 CCLite;
- 接口载荷方向正确;
- 诊断量可解释;
- 程序能够正常结束。
8.4 check / dry-run / run 集成测试
每个关键算例应尽量覆盖:
| 模式 | 检查内容 |
|---|---|
| check | 输入、路径、关键词、接口配置 |
| dry-run | IPC 资源、worker 启动、空耦合循环 |
| run | 真实联合计算和结果验证 |
check 和 dry-run 是定位问题的第一层防线,不能只依赖 run 模式。
9. 验证算例计划
9.1 总体约定
验证算例是算法和工程行为进入版本验收的最小可信证据。验证算例不同于演示算例:验证算例必须有明确输入、参考值、检查指标和通过判据;演示算例可以展示功能效果,但不能单独作为算法正确性证据。
每个验证算例必须包含:
- 算例编号;
- 首次进入验收的版本;
- 验证目标;
- 使用的 CCLite
.inp; - 使用 mock worker 还是真实 worker;
- SPH 输入或 mock SPH 数据;
- FEM 输入或 mock FEM 数据;
- 参考值来源;
- 输出文件清单;
- Python checker;
- 通过判据;
- 失败分类建议。
凡是没有解析值、独立脚本参考值或可手算参考值的算例,只能作为演示、稳定性观察或工程趋势算例,不能作为核心算法正确性验收算例。
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
报告至少包含:
case_id;case_version;status;tolerance;metrics;failed_checks;input_files;output_files;reference_source。
Python 参考解必须独立于 CCLite Fortran 实现,不应直接复制 Fortran 源码逻辑。若参考解也是同一公式实现,应在报告中说明其参考公式来自 04 号文档的具体章节。
9.4 0.1.x 空耦合与 IPC 验证算例
算例编号:V010_EMPTY_COUPLING
验证目标:
- CCLite 可独立启动;
- SPHLite mock worker 和 FEMLite mock worker 可进入 worker/service 模式;
- Windows shared memory 和 named event 可形成闭环;
- command block、data block header 和 AoR v1 payload 可完成最小读写;
- 空耦合循环可重复执行。
输入模型:
- CCLite
.inp指定两个 worker、共享内存名称、event 名称、总步数和输出目录; - mock SPH worker 每步写入 0 个或少量固定粒子;
- mock FEM worker 每步写入 0 个或少量固定 facet;
- CCLite 不产生真实接触力,只写回空载荷或零载荷。
参考值:
command_seq与ack_seq应逐步配对;step_id应从 1 到指定步数连续递增;num_active_contacts = 0;sum_force_sph = 0;sum_force_fem = 0。
输出文件:
run.log;ipc_report.csv;force_balance.csv;verification_report.json。
Python 检查:
- 检查
ipc_report.csv中每步 seq/ack 配对; - 检查 worker state 合法;
- 检查超时次数为 0;
- 检查空耦合载荷为 0;
- 检查进程正常退出。
通过判据:
- 连续运行不少于 100 个空耦合 step;
- 无 IPC 超时;
- 无未解释错误码;
- 退出后没有残留 worker;
- 资源释放日志完整。
9.5 几何验证算例
算例编号:V020_GEOMETRY_PRIMITIVES
首次验收版本:0.2.x,0.3.x 扩展 shell、edge 和 quad。
验证目标:
- 验证 04 号第 4 章的几何 primitive;
- 验证最近点、法向间隙和穿透量;
- 验证退化几何处理;
- 验证后续接触力计算的几何输入可靠。
输入模型:
| 子算例 | 输入 |
|---|---|
| 点到三角形内部 | 一个粒子位于三角形法向上方,投影点在三角形内部 |
| 点到三角形边 | 一个粒子投影到三角形外部且最近点在线段上 |
| 点到三角形顶点 | 一个粒子最近点为三角形顶点 |
| 点到四边形内部 | 一个粒子投影到四边形内部 |
| 非平面四边形 | 四边形四点轻微非共面 |
| 壳中面接触 | 设置 shell thickness,粒子接近壳中面 |
| 退化 facet | 三角形面积为 0 或四边形两点重合 |
参考值:
- 最近点坐标由 Python
references脚本按解析几何公式计算; - barycentric 坐标可手工复核;
- 壳厚度穿透量按 04 号第 4.6 节公式计算;
- 退化 facet 的期望行为为诊断并跳过。
输出文件:
contact_report.csv;geometry_report.csv,若实现提供;verification_report.json。
Python 检查:
- 比较最近点坐标;
- 比较法向间隙;
- 比较穿透量;
- 检查退化 facet 数量;
- 检查 active contact 状态。
通过判据:
- 最近点误差满足几何容差;
- 接触状态符合穿透量定义;
- quad 与等价 triangle 组合结果一致;
- 壳厚度改变接触开启位置;
- 退化几何不产生接触力。
9.6 单粒子撞刚性面
算例编号:V020_SINGLE_PARTICLE_WALL
首次验收版本:0.2.x。
验证目标:
- 作为 0.2.x 第一个真实物理验收算例;
- 验证 SPH 粒子到 FEM facet 的 penalty 接触主链路;
- 验证接触开启、法向力、冲量、力平衡和诊断输出;
- 为真实 SPHLite/FEMLite worker 接入提供最小联合算例。
实现层级:
- A 层:mock SPH 粒子和 mock FEM facet,先验证 CCLite 接触算法;
- B 层:真实 SPHLite worker + mock FEM worker,验证 SPH 外力写回;
- B 层:mock SPH worker + 真实 FEMLite worker,验证 FEM 面载荷写回;
- C 层:真实 SPHLite worker + 真实 FEMLite worker,验证完整联合运行。
输入模型:
- 一个 SPH 粒子;
- 一个固定 FEM 三角形 facet;
- 粒子初始位置在 facet 法向外侧;
- 粒子速度指向 facet;
- 首个验收版本不启用摩擦;
- 阻尼可分为关闭和开启两个子算例。
参考值:
- 接触开启条件由粒子半径、facet 位置和法向间隙手算;
- 法向 penalty 力由 04 号第 5.3 节公式计算;
- 阻尼子算例由 04 号第 5.4 节公式计算;
- 冲量参考值可由 Python 按离散时间积分计算;
- 力平衡参考值为 SPH 力与 FEM 反力相加为 0。
输出文件:
contact_report.csv;force_balance.csv;timestep_report.csv;verification_report.json。
Python 检查:
- 检查接触开启步;
- 检查最大穿透量;
- 检查法向力方向;
- 检查法向力幅值;
- 检查冲量;
- 检查 force balance;
- 检查无阻尼和有阻尼能量趋势。
通过判据:
- 未接触前接触力为 0;
- 穿透后法向力阻止继续穿透;
- SPH 力与 FEM 反力满足平衡容差;
- 无阻尼时能量误差满足容差;
- 有阻尼时能量耗散方向正确;
- 真实 worker 算例中载荷方向与 mock 算例一致。
9.7 多粒子压平面
算例编号:V020_MULTI_PARTICLE_PLANE
首次验收版本:0.2.x。
验证目标:
- 验证多接触对搜索;
- 验证接触力累加;
- 验证 FEM 节点载荷分配;
- 验证总力和总力矩平衡;
- 验证接触对去重。
输入模型:
- 多个 SPH 粒子按规则阵列布置;
- 一个或多个 FEM facet 构成平面;
- 粒子垂直压向平面;
- FEM 平面保持固定或做规定运动;
- 初始可使用 mock 数据,随后接入真实 worker。
参考值:
- 每个粒子的穿透量可由几何关系手算;
- 每个粒子的 penalty 力由 04 号第 5 章公式计算;
- FEM 节点载荷由 barycentric 或面积权重计算;
- 总力矩以选定参考点计算。
输出文件:
contact_report.csv;force_balance.csv;verification_report.json。
Python 检查:
- 检查活跃接触数量;
- 检查每个粒子接触力;
- 检查 FEM 节点力之和;
- 检查总力矩;
- 检查重复 pair id。
通过判据:
- 总力等于各粒子接触力累加;
- 节点力分配后总力和总力矩一致;
- 无重复接触对;
- 接触诊断 CSV 完整;
- 接触 pair id 在连续步中可追踪。
9.8 边缘与壳厚度接触
算例编号:V030_SHELL_EDGE_CONTACT
首次验收版本:0.3.x。
验证目标:
- 验证 shell thickness;
- 验证 edge fallback;
- 验证 triangle 和 quad facet;
- 验证接触状态连续性;
- 验证法向跳变诊断。
输入模型:
- 粒子靠近 FEM 壳边缘;
- 设置非零 shell thickness;
- 同时构造 triangle 和 quad 子算例;
- 粒子轨迹经过面内部、边缘和角点;
- quad 子算例应提供等价 triangle 拆分参考。
参考值:
- 壳厚度修正由 04 号第 4.6 节计算;
- edge 最近点由点到线段公式计算;
- quad 参考值由两个 triangle 子问题取一致结果;
- 接触状态连续性由连续步 active contact 变化检查。
输出文件:
contact_report.csv;geometry_report.csv,若实现提供;verification_report.json。
Python 检查:
- 检查边缘附近是否漏检;
- 检查 shell thickness 对接触开启位置的影响;
- 检查 quad 与 triangle 组合一致性;
- 检查法向跳变幅度;
- 检查异常几何诊断。
通过判据:
- 边缘附近不漏检;
- 壳厚度改变接触开启位置;
- quad 与等价 triangle 组合结果一致;
- 接触力不出现非物理尖峰,或尖峰被诊断;
- 退化 facet 不产生有效接触力。
9.9 摩擦滑移
算例编号:V040_FRICTION_SLIDE
首次验收版本:0.4.x。
验证目标:
- 验证 Coulomb 摩擦;
- 验证粘着和滑移状态;
- 验证切向力方向;
- 验证摩擦耗能;
- 验证稳定时间步和阻尼对结果的影响。
输入模型:
- 一个粒子或粒子组与 FEM 平面接触;
- 设置法向预压或重力等效载荷;
- 设置切向相对速度;
- 设置多个摩擦系数;
- 分别运行粘着子算例和滑移子算例。
参考值:
- 摩擦上限为
mu * normal_force; - 滑移方向由相对切向速度确定;
- 粘着区切向力由 penalty 切向模型或历史位移计算;
- 摩擦功应为非正值,具体符号按 04 号文档约定。
输出文件:
contact_report.csv;force_balance.csv;timestep_report.csv;verification_report.json。
Python 检查:
- 检查切向力方向;
- 检查摩擦力上限;
- 检查粘着到滑移转换;
- 检查接触功;
- 检查能量耗散方向。
通过判据:
- 摩擦力反向于相对滑移趋势;
- 摩擦力不超过 Coulomb 上限;
- 能量不因摩擦非物理增加;
- 诊断输出区分 normal 和 tangential 分量;
- 关闭摩擦时结果退化到无摩擦算例。
9.10 Tied Coupling 与 Release
算例编号:V050_TIED_RELEASE
首次验收版本:0.5.x。
验证目标:
- 验证 tied coupling;
- 验证 release 阈值;
- 验证 release 后转入普通 contact;
- 验证状态转换诊断;
- 验证 tied/release 能量记录。
输入模型:
- SPH 粒子初始绑定到 FEM 面;
- FEM 面发生规定运动或受载运动;
- 设置 release 位移、力或能量阈值;
- release 后粒子继续与 FEM 面接触;
- 至少包含 release 和不 release 两个子算例。
参考值:
- tie 位移由初始局部坐标和 FEM 面运动计算;
- tie 力由 04 号第 6 章 penalty tie 模型计算;
- release 触发步由阈值条件计算;
- release 后接触力参考普通 contact 公式。
输出文件:
contact_report.csv;tie_release_report.csv,若实现提供;force_balance.csv;verification_report.json。
Python 检查:
- 检查初始绑定关系;
- 检查 release 前 tie 状态;
- 检查 release 触发步;
- 检查 release 只触发一次;
- 检查 release 后不再施加 tie 约束;
- 检查 release 后 contact 状态。
通过判据:
- release 前绑定对象稳定;
- release 条件可复现;
- release 后状态转换不可逆,除非输入显式允许重新绑定;
- release 后接触力与普通 contact 一致;
- 诊断能还原状态变化。
9.11 均匀压力作用于 FEM 面
算例编号:V060_PRESSURE_TO_FEM
首次验收版本:0.6.x。
验证目标:
- 验证 pressure projection;
- 验证 SPH 压力到 FEM 面载荷;
- 验证节点载荷分配;
- 验证载荷方向和单位;
- 验证 FSI 基础诊断输出。
输入模型:
- SPH 侧提供均匀压力场;
- FEM 侧提供一个或多个平面 facet;
- CCLite 将压力转换为 FEM 面载荷;
- FEM 可固定,只验证载荷积分;
- 子算例可覆盖 triangle 和 quad。
参考值:
- 总载荷为
pressure * area; - 节点载荷由面积坐标或形函数权重分配;
- 载荷方向由 FEM facet 法向和 04 号约定决定;
- 力矩由节点位置和节点载荷计算。
输出文件:
force_balance.csv;fsi_report.csv,若实现提供;verification_report.json。
Python 检查:
- 检查总载荷;
- 检查节点载荷;
- 检查力矩;
- 检查载荷方向;
- 检查单位换算。
通过判据:
- 总载荷等于压力乘面积;
- 节点分配保持总力和总力矩;
- 载荷方向与法向约定一致;
- 单位不出现比例错误;
- 压力为 0 时载荷为 0。
9.12 运动边界与 Boundary/Ghost Particle
算例编号:V060_MOVING_BOUNDARY
首次验收版本:0.6.x。
验证目标:
- 验证 FEM 运动边界到 SPH 的传递;
- 验证 boundary particle 数据;
- 验证 ghost particle 数据;
- 验证边界速度和时间同步;
- 验证数据生命周期。
输入模型:
- FEM 边界做规定速度运动;
- CCLite 读取 FEM 边界位置和速度;
- SPH worker 接收边界速度或 ghost/boundary 数据;
- 使用小规模规则粒子分布;
- 包含静止边界和运动边界两个子算例。
参考值:
- 边界速度由规定运动函数计算;
- boundary/ghost 位置由 FEM facet 和法向偏移计算;
- step 和 substep 对应关系由时间同步规则计算。
输出文件:
fsi_report.csv;ipc_report.csv;verification_report.json。
Python 检查:
- 检查 SPH 接收的边界速度;
- 检查 ghost/boundary 数据位置;
- 检查 step 与 substep 对应;
- 检查数据不跨步误用;
- 检查数据数量。
通过判据:
- SPH 接收到的边界速度与 FEM 规定运动一致;
- ghost/boundary 数据不越界;
- step、substep 数据对应正确;
- 边界静止时速度为 0;
- 运动边界不破坏 IPC 同步。
9.13 一维声阻抗 Riemann 界面
算例编号:V070_RIEMANN_INTERFACE_1D
首次验收版本:0.7.x。
验证目标:
- 验证 Riemann FSI 主算法;
- 验证界面压力;
- 验证界面速度;
- 验证声阻抗极限状态;
- 验证非物理输入保护。
输入模型:
- SPH 侧和 FEM 侧各给定一维等效状态;
- 指定密度、声速、压力和法向速度;
- CCLite 计算界面压力和界面速度;
- 子算例覆盖左右状态相同、高阻抗差、低阻抗差和反向速度。
参考值:
- Python
references按 04 号第 8 章声阻抗近似公式计算; - 左右状态相同时界面状态应等于原状态;
- 高阻抗侧速度响应应小于低阻抗侧;
- 非物理密度或声速应触发错误或安全降级。
输出文件:
fsi_report.csv;force_balance.csv;verification_report.json。
Python 检查:
- 检查界面压力;
- 检查界面速度;
- 检查载荷方向;
- 检查声阻抗极限情况;
- 检查异常输入处理。
通过判据:
- Riemann 输出与参考计算一致;
- 左右状态相同时不产生虚假扰动;
- 高阻抗极限趋势正确;
- 非物理输入被拒绝或安全处理;
- 诊断记录界面状态。
9.14 异步子循环
算例编号:V070_ASYNC_SUBCYCLING
首次验收版本:0.7.x。
验证目标:
- 验证显式-显式异步子循环;
- 验证 macro step、substep 和 iteration id;
- 验证数据交换时刻;
- 验证 force hold 或 interpolation 策略;
- 验证失败定位到具体 substep。
输入模型:
- SPHLite 使用较小时间步;
- FEMLite 使用较大时间步;
- CCLite 以 macro step 调度;
- 一个 solver 在 macro step 内执行多个 substep;
- 初始可使用 mock worker 控制各自时间步。
参考值:
- macro step 结束时两个 solver 时间应一致;
- substep id 应连续;
- force hold 或 interpolation 结果由 Python 根据策略计算;
- 数据交换次数由步长比决定。
输出文件:
ipc_report.csv;timestep_report.csv;force_balance.csv;verification_report.json。
Python 检查:
- 检查 substep 数量;
- 检查每个 worker 的时间;
- 检查数据交换时刻;
- 检查 force hold 或 interpolation 值;
- 检查失败定位信息。
通过判据:
- macro step 结束时两个 solver 时间一致;
- substep id 连续;
- 数据不会跨步误用;
- 失败时能定位到具体 substep;
- 真实 worker 接入后仍保持相同调度语义。
9.15 稳定性套件
算例编号:V080_STABILITY_SUITE
首次验收版本:0.8.x。
验证目标:
- 验证 force relaxation;
- 验证接触历史补强;
- 验证异常输入保护;
- 验证长时间运行稳定性;
- 验证 AoR v1 与 SoA v2 性能对比。
套件组成:
| 子算例 | 验证点 |
|---|---|
| 大 penalty 刚度 | 接触稳定时间步和非有限值保护 |
| 小时间步 | 长时间步进和诊断输出体量 |
| 大速度冲击 | 最大穿透量、力峰值和 relaxation |
| 多接触对 | 搜索性能和 pair 管理 |
| 接触反复开启关闭 | persistence 和历史状态 |
| 摩擦滑移 | 摩擦历史变量稳定性 |
| tied release 后接触 | 状态转换和历史清理 |
| FSI 压力波 | pressure projection 和时间同步 |
| worker 延迟 | timeout、heartbeat、ack |
| 非有限值故障注入 | NaN/Inf 捕获和错误码 |
输出文件:
run.log;ipc_report.csv;contact_report.csv;force_balance.csv;timestep_report.csv;performance_report.csv;verification_report.json。
Python 检查:
- 检查非有限值;
- 检查错误码;
- 检查最大穿透量;
- 检查能量和冲量趋势;
- 检查长时间运行步数;
- 检查 AoR v1 与 SoA v2 性能差异;
- 检查 worker 延迟场景的超时处理。
通过判据:
- 程序不崩溃;
- 非有限值被捕获;
- 诊断能指出不稳定来源;
- force relaxation 生效;
- 接触历史不发生错误串扰;
- SoA v2 优化不改变物理验收结果。
9.16 工程简化算例
算例编号:V090_ENGINEERING_CASES
首次验收版本:0.9.x。
验证目标:
- 验证工程趋势;
- 建立参数推荐范围;
- 建立性能基线;
- 验证长时间运行稳定性;
- 为 0.10.x 发布候选提供工程证据。
工程简化算例从 0.9.x 起作为硬验收,不提前作为 0.6.x 或 0.7.x 的基础正确性验收。
建议方向:
- 水下爆炸冲击简化模型;
- 粒子流冲击薄板;
- SPH 颗粒堆积与 FEM 壁面;
- 流固压力作用下的弹性板;
- 局部破坏或 release 后接触。
水下爆炸 FSI 在本路线中放入 0.9.x 工程简化算例。0.6.x 只验证 pressure projection、边界速度和 boundary/ghost 数据;0.7.x 只验证 Riemann FSI 与时间耦合的可拆解小问题。
参考值:
- 工程趋势可来自独立脚本、简化理论或既有试算结果;
- 若没有严格解析解,应明确标记为趋势验证;
- 参数推荐范围必须来自参数扫描结果;
- 关键诊断量必须可复现。
输出文件:
run.log;contact_report.csv;fsi_report.csv;force_balance.csv;timestep_report.csv;performance_report.csv;verification_report.json。
Python 检查:
- 检查关键趋势量;
- 检查参数扫描结果;
- 检查长时间运行稳定性;
- 检查性能指标;
- 检查回归基线。
通过判据:
- 结果趋势符合工程认知;
- 关键诊断量稳定;
- 参数推荐范围可复用;
- 长时间运行无资源泄漏;
- 回归基线稳定;
- 算例说明足够让用户复现。
9.17 0.10.x 全量回归算例
算例编号:V100_RELEASE_REGRESSION
首次验收版本:0.10.x。
验证目标:
- 冻结 0.x 开发线接口;
- 冻结文档与测试基线;
- 确认 0.1.x 到 0.9.x 的已验收能力未退化;
- 在干净环境中重建并运行全量测试;
- 形成工程发布候选证据。
输入模型:
- 0.1.x 到 0.9.x 所有已验收算例;
- AoR v1 和 SoA v2 相关接口测试;
- 真实 SPHLite/FEMLite worker 的代表算例;
- 版本兼容和错误路径算例;
- 文档一致性检查。
参考值:
- 已冻结回归基线;
- 每个算例自己的解析值或参考解;
- 接口布局和枚举来自 05 号文档;
- 算法公式和判据来自 04 号文档。
输出文件:
release_test_report.json;release_test_summary.txt;- 全量 CSV 输出;
- 性能基线;
- 文档一致性检查结果。
Python 检查:
- 汇总全量测试结果;
- 检查回归差异;
- 检查接口兼容;
- 检查文档章节追踪;
- 生成发布候选测试摘要。
通过判据:
- 全量单元测试通过;
- 全量接口测试通过;
- 全量集成测试通过;
- 全量验证算例通过;
- 全量回归测试通过;
- 性能指标不低于已批准基线;
- 文档、接口和测试矩阵一致。
10. 验收判据
10.1 通用验收判据
所有版本通用验收判据:
- 文档与实现一致;
.inp输入可复现;- 测试用例可一键或按说明运行;
- 自动检查报告给出通过或失败;
- 失败时错误码和日志可定位;
- 已通过测试进入回归集合;
- 不引入未说明的接口破坏。
10.2 接口验收判据
接口验收采用严格判定:
- magic、version、layout、role 完全一致;
- record size 完全一致;
- 枚举值完全一致;
- 字节序和对齐符合 05 号文档;
- command seq 与 ack seq 正确;
- worker state 合法;
- timeout 行为可复现;
- 错误码可追踪。
接口测试失败时,不应继续执行物理验证算例。
10.3 几何验收判据
几何验收关注:
- 最近点;
- 接触法向;
- 穿透量;
- 候选对;
- edge fallback;
- 壳厚度;
- 退化处理。
几何错误会直接影响接触力方向和稳定性,因此几何验收是 0.2.x 之后所有接触版本的前置条件。
10.4 接触验收判据
接触验收关注:
- 接触开启和关闭;
- 法向力方向;
- 阻尼力方向;
- 摩擦力上限;
- 作用反作用;
- 力矩一致性;
- 接触功;
- 最大穿透量;
- 非有限值保护。
接触力可以根据不同算法参数改变幅值,但不得违反方向、守恒和约束激活逻辑。
10.5 FSI 验收判据
FSI 验收关注:
- 压力积分;
- 速度边界;
- ghost/boundary 数据;
- Riemann 界面压力;
- Riemann 界面速度;
- 载荷方向;
- 时间同步;
- 稳定性。
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 主控与通信闭环
目标:
- CCLite 独立主控;
- SPHLite worker/service 模式;
- FEMLite worker/service 模式;
- Windows shared memory;
- named event;
- command block;
- AoR v1 data block;
- 空耦合循环;
- CSV 诊断。
必须通过:
.inpcheck 测试;- worker 启动测试;
- command block 测试;
- event 同步测试;
- data block header 测试;
- mock workers 空耦合集成测试;
- timeout 和错误码测试;
- 资源释放测试。
0.1.x 不要求真实接触力验收。
11.2 0.2.x 基础 SPH-FEM Penalty 接触
目标:
- SPH 粒子到 FEM 三角形 facet;
- 基础宽相搜索;
- 点到三角形最近点;
- 法向 penalty 接触;
- FEM 节点力分配;
- force balance 诊断。
必须通过:
- 几何基础单元测试;
- 搜索算法单元测试;
- 单粒子撞刚性面;
- 多粒子压平面;
- 力平衡测试;
V020_SINGLE_REAL_WORKER_SMOKE:至少一条真实 worker 路径通过,或输出包含阻塞字段的CONTROLLED_PROTOCOL_GAP报告。
0.2.x 的 A 层算法验收以 mock worker 为主。真实 worker gate 用于防止接口风险被隐藏;在 adapter 通过前,不把 supports_real_ipc=yes 解释为真实 SPH-FEM 外部物理联调完成。
11.3 0.3.x 壳、边缘与四边形接触
目标:
- shell thickness;
- edge fallback;
- quad facet;
- 接触 persistence 初步;
- 接触诊断增强。
必须通过:
- 点到四边形几何测试;
- 边缘接触测试;
- 壳厚度测试;
- quad 与 triangle 组合一致性测试;
- 接触状态连续性测试。
11.4 0.4.x 阻尼、摩擦与稳定时间步
目标:
- 法向阻尼;
- Coulomb 摩擦;
- penalty 参数估计;
- 接触稳定时间步;
- 接触能量诊断。
必须通过:
- 阻尼单元测试;
- 摩擦滑移验证;
- 能量耗散检查;
- penalty 参数范围测试;
- 稳定时间步诊断测试。
11.5 0.5.x Tied Coupling 与 Release
目标:
- tied coupling;
- release;
- tie-to-contact;
- 状态转换诊断;
- 能量记录。
必须通过:
- tie 单元测试;
- release 阈值测试;
- tied/release 集成算例;
- release 后接触验证;
- 状态转换回归测试。
11.6 0.6.x Pressure Projection 与 Boundary/Ghost Particle
目标:
- SPH 压力到 FEM 面载荷;
- FEM 运动边界到 SPH;
- boundary particle;
- ghost particle;
- FSI 基础诊断。
必须通过:
- 均匀压力作用于 FEM 面;
- 运动边界传递测试;
- boundary/ghost 数据测试;
- FSI 载荷方向测试;
- 单位一致性测试。
11.7 0.7.x Riemann FSI 与时间耦合
目标:
- Riemann FSI 主算法;
- 异步子循环;
- 显式-隐式弱耦合框架;
- 强耦合迭代框架;
- 算法主体完成。
必须通过:
- 一维声阻抗 Riemann 界面;
- Riemann 极限状态测试;
- 异步子循环测试;
- 弱耦合流程测试;
- 强耦合迭代状态机测试;
- 算法章节到测试项的覆盖审查。
0.7.x 完成后,04 号文档中的主要算法应均有实现入口和基本验证。
11.8 0.8.x 稳定化、性能优化与 SoA v2
目标:
- force relaxation;
- 接触历史补强;
- 能量修正;
- 异常处理补强;
- AoR v1 与 SoA v2 性能对比;
- 长时间运行稳定性。
必须通过:
- 稳定性套件;
- 非有限值故障注入;
- worker 延迟测试;
- 长时间运行测试;
- AoR v1 / SoA v2 对比测试;
- 回归测试全量通过。
11.9 0.9.x 工程算例与参数推荐
目标:
- 工程简化算例集合;
- 参数推荐范围;
- 性能目标;
- 工程验收矩阵;
- 文档和测试闭环。
必须通过:
- 工程简化算例;
- 参数敏感性测试;
- 性能基线测试;
- 长时间稳定性测试;
- 回归测试全量通过;
- 用户可复现实验说明。
11.10 0.10.x 接口冻结与工程发布候选
目标:
- 接口冻结;
- 文档冻结;
- 回归体系冻结;
- 版本兼容策略冻结;
- 工程发布候选。
必须通过:
- 全量单元测试;
- 全量接口测试;
- 全量集成测试;
- 全量验证算例;
- 全量回归测试;
- 性能测试;
- 文档一致性审查;
- 干净环境重建测试。
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 测试执行层级
建议执行层级:
quick:单元测试和基础接口测试;standard:quick + mock 集成 + 小验证算例;full:standard + 真实 worker + 回归测试;release:full + 性能测试 + 工程算例 + 文档一致性检查。
日常开发至少运行 quick。
合并关键接口或算法变更前应运行 standard。
版本验收前应运行 release。
13.2 自动检查报告
自动检查报告至少包含:
- 测试名称;
- 测试版本;
- 运行时间;
- 平台;
- 编译器;
- CCLite commit;
- SPHLite commit 或版本;
- FEMLite commit 或版本;
- 通过数量;
- 失败数量;
- 跳过数量;
- 失败原因摘要;
- 输出路径。
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 的数据生命周期、时间步和异常行为。
对策:
- 0.2.x 起引入单真实 worker 集成测试;
- 真实 worker 输出必须经过同一套接口检查;
- mock solver 增加故障注入;
- 用真实 worker 数据回放构造回归测试。
14.2 接口变化破坏回归
风险:
共享内存 layout 一旦变化,旧测试和旧 worker 可能无法运行。
对策:
- 所有 layout 变化必须更新 05 号文档;
- layout id 必须递增或明确兼容;
- 版本兼容测试必须先于集成测试;
- 0.10.x 前冻结接口。
14.3 数值结果依赖参数
风险:
接触刚度、阻尼、时间步和摩擦参数会显著影响结果。
对策:
- 验证算例固定参数;
- 参数写入输入文件;
- 输出参数摘要;
- 0.9.x 建立参数推荐范围;
- 回归测试允许有记录的基线更新。
14.4 工程算例过早进入硬验收
风险:
复杂工程算例问题来源多,难以判断失败属于接口、算法还是模型设置。
对策:
- 0.1.x 到 0.7.x 以小算例为主;
- 0.9.x 再建立工程算例硬验收;
- 工程算例必须拆分出可验证的子问题;
- 不用复杂工程算例替代基础验证。
14.5 性能优化影响正确性
风险:
SoA v2、并行搜索或缓存优化可能改变接触对顺序和浮点累加结果。
对策:
- 0.8.x 才引入 SoA v2 性能优化;
- 保留 AoR v1 作为对照;
- 对排序无关结果使用合力、力矩和误差判据;
- 对顺序敏感诊断明确排序规则。
15. 第一阶段冻结项
0.1.x 第一阶段测试计划冻结以下内容:
- 测试分层采用单元测试、接口测试、集成测试、验证算例四层主结构;
- 0.1.x 以 mock solver、IPC、worker、空耦合为主要验收目标;
- 0.2.x 以单粒子和小规模 SPH-FEM penalty contact 为主要接触验收目标;
- 允许使用 Python checker 检查 CSV 和数值结果;
- 验收计划按 0.1.x 到 0.10.x 组织;
- 第一阶段平台为 Windows/gfortran/本机共享内存;
- Linux/MPI 只作为预留测试方向;
- 接口测试必须严格追踪 05 号文档;
- 算法验证必须严格追踪 04 号文档;
- 0.2.x 第一个真实物理验收算例定为单粒子撞刚性面;
- 核心物理算例应先用 mock 数据验证 CCLite 算法,再逐步接入真实 SPHLite/FEMLite worker;
- 工程简化算例从 0.9.x 起作为硬验收;
- 核心验证算例必须有解析值、独立脚本参考值或可手算参考值;
- 水下爆炸 FSI 暂定为 0.9.x 工程简化算例;
- 允许借助
.\Python\实现算例生成、参考解、runner 和 checker; - 0.10.x 是 0.x 开发线的工程发布候选阶段,不自动跳转为 1.0.x。
16. 待细化事项
以下事项应在代码和测试框架建立后进一步细化:
- 具体测试目录是否与最终源码目录合并;
- gfortran 单元测试框架选择;
- Python checker 的最终报告 schema;
- CSV 字段最终名称;
- 每个验证算例的默认数值参数;
- 每个版本的测试运行时间目标;
- 工程算例数据是否纳入仓库;
- 大文件测试数据的管理方式;
- 0.8.x SoA v2 的性能基准;
- 0.9.x 工程验收矩阵。
本文档后续应随 03、04、05 号文档和代码实现同步维护。