# 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\` 后续按以下职责细分: ```text Python/ checkers/ references/ casegen/ runners/ ``` 其中 `checkers` 负责输出检查,`references` 负责解析解或独立参考值,`casegen` 负责生成小算例输入,`runners` 负责封装外部程序运行。已有调试脚本可在不破坏其用途的前提下逐步迁入该结构。 ## 4.4 推荐目录 建议测试目录采用: ```text tests/ unit/ interface/ integration/ verification/ regression/ performance/ data/ baselines/ checkers/ ``` 建议算例目录采用: ```text 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 的输出建议统一为: ```text 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 测试命名 建议测试命名使用: ```text test___ ``` 示例: ```text 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 号文档和代码实现同步维护。