Files
2026-07-05 21:41:34 +08:00

13 KiB
Raw Permalink Blame History

SPHLite TODO

当前目标:根据 docs/12_cclite_integration_suggestions.md 推进真实 CCLite worker 通信闭环、数据契约补强和联调验收。

执行边界:

  • 只修改 SPHLite 仓库内文件。
  • 不把 SPHLite 改造成 CCLite 内部库。
  • 不新增 FEMLite 直接依赖。
  • 不在 SPHLite 内部实现 FEM-SPH 接触搜索或 CCLite 接触算法核心。
  • 不让 worker adapter 侵入 Water、Gas、Explosive、Solid、Shell 等核心物理模块。
  • 不把 mock worker、真实 IPC worker、真实接触/FSI 三类能力混同。
  • 算法核心保持 Fortran 95,包括求解器、粒子/单元语义、材料和物理模块;worker、CLI、IPC 等外围集成层及其测试/工具性 Fortran 代码可使用 Fortran 2018。
  • 保持现有 CLI、Fortran API、C ABI、C++ wrapper、Python wrapper 和 release gate 不退化。

颗粒度约定:每个待办事项应对应一个清晰的小变更、一个测试、一个接口行为或一处文档同步;按阶段顺序推进,非必须不要跳过。

阶段 A:基线和边界复核

  • 复核 docs/12_cclite_integration_suggestions.md 中 SPHLite、CCLite、FEMLite 的职责边界。
  • 复核当前 worker mock 与真实 IPC 未闭合的边界表述。
  • 复核现有 CouplingInterface C ABI 清单。
  • 复核现有 C++ wrapper coupling 暴露清单。
  • 复核现有 Python debug coupling 暴露清单。
  • 复核当前 CLI 普通运行、--check、--run 行为。
  • 复核当前 worker CLI 参数解析行为。
  • 复核当前 worker 状态枚举和命令枚举。
  • 复核当前 worker mock command/data block 契约。
  • 复核当前 coupling diagnostics 和 load balance 字段。
  • 复核当前 CSV、VTU、PVD、restart 输出能力。
  • 复核当前 source size 例外清单。

阶段 B:CCLite 能力查询入口

  • 设计 --cclite-capabilities CLI 参数语义。
  • 增加 --cclite-capabilities 与普通输入文件参数的冲突检查。
  • 增加 --cclite-capabilities 与 --cclite-worker 的组合规则。
  • 定义 capabilities 输出的 solver 字段。
  • 定义 capabilities 输出的 cclite_worker 字段。
  • 定义 capabilities 输出的 ipc_backend 字段。
  • 定义 capabilities 输出的 command_block_version 字段。
  • 定义 capabilities 输出的 data_layout 字段。
  • 定义 capabilities 输出的 supports_real_ipc 字段。
  • 定义 capabilities 输出的 supports_sph_to_ccl_particle 字段。
  • 定义 capabilities 输出的 supports_ccl_to_sph_force 字段。
  • 定义 capabilities 输出的 max_particle_records 字段。
  • 实现 capabilities 文本输出。
  • 增加 capabilities CLI 正常路径测试。
  • 增加 capabilities CLI 参数冲突测试。
  • 将 capabilities 测试接入 CTest。

阶段 C:真实 IPC 适配层骨架

  • 设计真实 IPC adapter 与 mock adapter 的共同接口。
  • 增加 Windows shared memory 句柄结构。
  • 增加 Windows named event 句柄结构。
  • 增加 command block 打开函数。
  • 增加 data block 打开函数。
  • 增加 command event 打开函数。
  • 增加 done event 打开函数。
  • 增加 command event wait 函数。
  • 增加 done event signal 函数。
  • 增加 shared memory 关闭函数。
  • 增加 named event 关闭函数。
  • 增加 wait 超时错误路径。
  • 增加句柄打开失败错误路径。
  • 增加非 Windows 平台真实 IPC unsupported 路径。
  • 增加真实 IPC adapter 编译开关。
  • 增加 IPC adapter 单元测试。

阶段 D:真实 worker 主循环

  • 将 worker 启动参数传入真实 IPC adapter。
  • 在 worker 启动后写入 READY 状态。
  • 在 worker 启动失败时写入受控错误消息。
  • 实现 worker 等待 command event 的主循环。
  • 实现 command sequence 读取。
  • 实现 command kind 读取。
  • 实现未知 command 的受控错误响应。
  • 实现 INIT 命令真实 IPC 路径。
  • 实现 READ_INPUT 命令真实 IPC 路径。
  • 实现 BUILD_MODEL 命令真实 IPC 路径。
  • 实现 EXPORT_INTERFACE 命令真实 IPC 路径。
  • 实现 IMPORT_LOADS 命令真实 IPC 路径。
  • 实现 ADVANCE 命令真实 IPC 路径。
  • 实现 WRITE_OUTPUT 命令真实 IPC 路径。
  • 实现 STOP 命令真实 IPC 路径。
  • 每条命令后回写 ack_seq。
  • 每条命令后回写 worker_state。
  • 每条命令后回写 error_code。
  • 每条命令后回写短消息。
  • 每条命令后 signal done event。

阶段 E:SPH_TO_CCL_PARTICLE 数据块

  • 定义 SPH_TO_CCL_PARTICLE 数据块版本号。
  • 定义 SPH_TO_CCL_PARTICLE 记录容量字段。
  • 定义 SPH_TO_CCL_PARTICLE 有效记录数字段。
  • 定义粒子 external id 字段。
  • 定义粒子 internal/export index 字段。
  • 定义粒子 phase 字段。
  • 定义粒子 status 字段。
  • 定义粒子 material id 字段。
  • 定义粒子 section id 字段。
  • 定义粒子 body id 占位字段。
  • 定义粒子位置字段。
  • 定义粒子速度字段。
  • 定义粒子质量字段。
  • 定义粒子密度字段。
  • 定义粒子体积字段。
  • 定义粒子光滑长度字段。
  • 定义粒子接触半径字段。
  • 定义粒子压力字段。
  • 定义粒子声速字段。
  • 定义粒子 valid_flags 字段。
  • 实现空粒子导出。
  • 实现固定粒子导出。
  • 映射真实 coupling region 粒子导出。
  • 增加粒子导出容量不足错误路径。

阶段 F:导出粒子校验和报告

  • 增加导出粒子坐标有限值检查。
  • 增加导出粒子速度有限值检查。
  • 增加导出粒子质量有效性检查。
  • 增加导出粒子密度有效性检查。
  • 增加导出粒子体积有效性检查。
  • 增加导出粒子光滑长度有效性检查。
  • 增加导出粒子接触半径有效性检查。
  • 增加导出粒子压力有限值检查。
  • 增加导出粒子声速有效性检查。
  • 增加导出粒子 phase 有效性检查。
  • 增加导出粒子 status 有效性检查。
  • 增加导出粒子 external id 有效性检查。
  • 增加导出粒子 internal/export index 有效性检查。
  • 将被拒绝导出粒子计入诊断。
  • 将被拒绝导出粒子写入 particle report。
  • 增加导出粒子校验单元测试。

阶段 G:CCL_TO_SPH_FORCE 数据块

  • 定义 CCL_TO_SPH_FORCE 数据块版本号。
  • 定义 CCL_TO_SPH_FORCE 记录容量字段。
  • 定义 CCL_TO_SPH_FORCE 有效记录数字段。
  • 定义 force record 的 particle id 字段。
  • 定义 force record 的 internal/export index 字段。
  • 定义 force record 的 force[3] 字段。
  • 定义 force record 的 moment[3] 字段。
  • 定义 force record 的 source id 字段。
  • 定义 force record 的 pair id 字段。
  • 定义 force record 的 load mode 字段。
  • 定义 force record 的 contact state 字段。
  • 定义 force record 的 step id 字段。
  • 定义 force record 的 valid flags 字段。
  • 实现空 force block 导入。
  • 映射粒子力导入到现有 CouplingInterface。
  • 映射接触状态导入到现有 CouplingInterface。
  • 增加 force block 容量越界错误路径。
  • 增加 force block 版本不匹配错误路径。

阶段 H:导入载荷校验和诊断

  • 增加 force record particle id 匹配检查。
  • 增加 force record internal/export index 匹配检查。
  • 增加 force record force[3] 有限值检查。
  • 增加 force record moment[3] 有限值检查。
  • 增加 force record source id 有效性检查。
  • 增加 force record pair id 诊断记录。
  • 增加 force record load mode 有效性检查。
  • 增加 force record contact state 有效性检查。
  • 增加 force record step id 检查。
  • 增加 force record valid flags 检查。
  • 增加无法匹配 force record 的拒绝计数。
  • 增加非有限 force record 的拒绝计数。
  • 增加过期 step force record 的拒绝计数。
  • 增加重复 force record 的诊断计数。
  • 将导入总力写入 load balance 诊断。
  • 将导入总力矩写入 load balance 诊断。
  • 将拒绝原因写入 force report。
  • 增加导入载荷校验单元测试。

阶段 I:v2 数据契约和预留接口

  • 复核 cclite_coupling_manifest.md 的 v2 字段清单。
  • 明确 body_id 的默认值和长期语义。
  • 明确 contact_radius 与 h 的关系。
  • 明确 sound_speed 的来源和默认值。
  • 明确 valid_flags 位定义。
  • 明确 source_id 与 CCLite contact pair 的关系。
  • 明确 pair_id 与 contact state 的关系。
  • 明确 moment[3] 对 Solid/Shell 的预留语义。
  • 明确 interface_pressure 的预留语义。
  • 明确 interface_velocity 的预留语义。
  • 设计 sphlite_coupling_apply_boundary_states 草案。
  • 设计 boundary/ghost state 缓存容量策略。
  • 设计 boundary/ghost state 清零策略。
  • 增加 boundary/ghost 数据契约 smoke 测试。
  • 标记 boundary/ghost 为预留能力而非生产 FSI。
  • 更新 v2 契约文档。

阶段 J:Worker 诊断输出

  • 实现 sphlite_cclite_worker.log 文件路径解析。
  • 记录 worker 启动参数。
  • 记录 command block 名称。
  • 记录 data block 名称。
  • 记录 command event 名称。
  • 记录 done event 名称。
  • 记录当前 command id。
  • 记录当前 step id。
  • 记录当前 ack seq。
  • 记录当前 worker state。
  • 记录导出粒子数量。
  • 记录导出 facet 数量。
  • 记录接收 force 数量。
  • 记录接收总力。
  • 记录接收总力矩。
  • 记录非有限粒子状态数量。
  • 记录错误码和错误消息。
  • 实现 sphlite_cclite_particle_report.csv。
  • 实现 sphlite_cclite_force_report.csv。
  • 增加 worker 诊断输出测试。

阶段 K:输入关键词和配置开关

  • 复核现有 *SPHLITE COUPLING REGION 语法是否满足 CCLite 引用需求。
  • 复核 EXPORT=PARTICLE/FACET/BOTH 与 worker 数据块的映射。
  • 复核 IMPORT=FORCE/FACET_LOAD/MOTION 与 worker 数据块的映射。
  • 复核 CONTACT_STATE=OFF/IMPORT 与 contact state 导入的映射。
  • 设计 *SPHLITE CCLITE 关键词草案。
  • 定义 *SPHLITE CCLITE, WORKER=YES 语义。
  • 定义 *SPHLITE CCLITE, REGION=... 语义。
  • 定义 EXPORT_RADIUS=YES/NO 语义。
  • 定义 EXPORT_SOUND_SPEED=YES/NO 语义。
  • 定义 ACCEPT_CONTACT_STATE=YES/NO 语义。
  • 定义 ACCEPT_BOUNDARY_STATE=YES/NO 语义。
  • 明确 *SPHLITE CCLITE 不替代 CCLite 配置文件。
  • 增加输入关键词文档。
  • 增加输入关键词解析测试。

阶段 L:Worker self-test 和 CCLite mock 联调

  • 设计 SPHLite 侧真实 IPC self-test 启动方式。
  • 准备 self-test 用最小输入文件。
  • 验证 self-test worker 启动。
  • 验证 self-test IPC attach。
  • 验证 self-test READY 写入。
  • 验证 self-test 空粒子导出。
  • 验证 self-test 固定粒子导出。
  • 验证 self-test 空 force 导入。
  • 验证 self-test STOP 正常退出。
  • 验证 self-test 超时可控退出。
  • 与 CCLite mock FEM 验收 1 step 空耦合。
  • 与 CCLite mock FEM 验收 100 step 空耦合。
  • 与 CCLite mock FEM 验收异常输入退出。
  • 与 CCLite mock FEM 验收超时退出。
  • 记录真实 SPHLite + mock FEM 联调日志。
  • 将可本地执行的 self-test 接入 CTest。

阶段 M:回归测试和发布准备

  • 增加 capabilities CLI 回归到 release gate。
  • 增加真实 IPC unsupported 路径回归到 release gate。
  • 增加 worker self-test 回归到 release gate。
  • 增加 particle export 数据块回归到 release gate。
  • 增加 force import 数据块回归到 release gate。
  • 增加粒子校验拒绝路径回归到 release gate。
  • 增加载荷校验拒绝路径回归到 release gate。
  • 增加 worker diagnostics 回归到 release gate。
  • 运行 worker/coupling 专项 CTest。
  • 运行完整 CTest。
  • 运行 source size gate。
  • 运行 git diff --check。
  • 运行无限水域爆炸示例脚本。
  • 验证示例 VTU/PVD 输出。
  • 验证 tools/publish_to_cclite.bat dry run。
  • 更新 06 号测试与验证计划。
  • 更新 09 号版本历史。
  • 更新 11 号 benchmark matrix。
  • 更新 12 号 CCLite 集成建议状态。
  • 更新 README 当前能力说明。