Files
SPHLite/todo.md
T
2026-07-05 17:00:13 +08:00

11 KiB
Raw Blame History

SPHLite TODO

当前目标:根据 docs/12_cclite_integration_suggestions.md 推进 CCLite 集成预研、worker 通信闭环和数据契约补强。

执行边界:

  • 只修改 SPHLite 仓库内文件。
  • 不把 SPHLite 改造成 CCLite 内部库。
  • 不新增 FEMLite 直接依赖。
  • 不在 SPHLite 内部实现 FEM-SPH 接触搜索或 CCLite 接触算法核心。
  • 优先保持现有 CLI、Fortran API、C ABI、C++ wrapper、Python wrapper 和 release gate 不退化。

阶段 A:范围收敛和现状复核

  • 复核 12 号文档中的 SPHLite/CCLite/FEMLite 职责边界。
  • 复核 0.8.0 coupling region 输入解析能力。
  • 复核 0.8.1 facet pressure/traction/resultant 导入能力。
  • 复核现有 contact state 导入和诊断能力。
  • 复核现有 motion boundary direct 模式能力。
  • 复核现有 CSV、VTU、PVD 和 restart 输出能力。
  • 复核现有 C ABI coupling 接口清单。
  • 复核现有 C++ wrapper coupling 接口清单。
  • 复核现有 Python debug coupling 接口清单。
  • 复核现有 CLI coupling 诊断输出字段。
  • 明确 worker/service adapter 不侵入核心物理模块。
  • 明确 CCLite shared memory 和 event 生命周期不由 SPHLite 管理。
  • 明确 worker 通信闭环不等同于真实接触算法完成。
  • 明确下一阶段不交付生产级 FSI 和连续体强耦合。
  • 记录当前 release gate 和 source size 基线。
  • 准备阶段 A 变更小结。

阶段 B:CCLite 数据契约 manifest

  • 建立 CCLite 集成数据契约 manifest 文档。
  • 在 manifest 中列出 region info 字段。
  • 在 manifest 中列出 region modes 字段。
  • 在 manifest 中列出现有 particle export 字段。
  • 在 manifest 中列出现有 facet export 字段。
  • 在 manifest 中列出现有 particle force import 字段。
  • 在 manifest 中列出现有 facet load import 字段。
  • 在 manifest 中列出现有 contact state import 字段。
  • 在 manifest 中列出现有 motion boundary import 字段。
  • 在 manifest 中列出现有 load balance 诊断字段。
  • 在 manifest 中列出现有 contact diagnostics 字段。
  • 在 manifest 中标记尚未暴露的 body_id 字段。
  • 在 manifest 中标记尚未暴露的 contact_radius 字段。
  • 在 manifest 中标记尚未暴露的 sound_speed 字段。
  • 在 manifest 中标记尚未暴露的 source_id 和 pair_id 字段。
  • 在 manifest 中标记尚未暴露的 valid_flags 字段。
  • 在 manifest 中标记 boundary/ghost 预留字段。
  • 在 manifest 中说明数组展开顺序。
  • 在 manifest 中说明 external id 与 export index 的使用边界。
  • 将 manifest 接入 docs 索引或 12 号文档引用。

阶段 C:Worker CLI 入口设计

  • 设计 --cclite-worker CLI 参数语义。
  • 设计 --solver-id CLI 参数语义。
  • 设计 --case CLI 参数语义。
  • 设计 --ipc-name CLI 参数语义。
  • 设计 --command-block CLI 参数语义。
  • 设计 --data-prefix CLI 参数语义。
  • 设计 --log CLI 参数语义。
  • 设计 --timeout-ms CLI 参数语义。
  • 设计 --worker-id CLI 参数语义。
  • 设计 worker 参数缺失时的错误码和错误消息。
  • 设计 worker 参数冲突时的错误码和错误消息。
  • 确认未启用 worker 时现有 CLI 行为不变。
  • 增加 worker CLI 参数解析单元测试。
  • 增加普通 CLI 回归测试。
  • 增加 worker 参数错误路径测试。
  • 将 worker CLI 测试接入 CTest。

阶段 D:Worker 状态机和命令枚举

  • 定义 worker 状态枚举。
  • 定义 worker 命令枚举。
  • 定义 worker ack 序号语义。
  • 定义 worker error code 映射语义。
  • 定义 INIT 命令处理流程。
  • 定义 READ_INPUT 命令处理流程。
  • 定义 BUILD_MODEL 命令处理流程。
  • 定义 EXPORT_INTERFACE 命令处理流程。
  • 定义 IMPORT_LOADS 命令处理流程。
  • 定义 ADVANCE 命令处理流程。
  • 定义 WRITE_OUTPUT 命令处理流程。
  • 定义 STOP 命令处理流程。
  • 定义未知命令处理流程。
  • 定义命令超时处理流程。
  • 增加 worker 状态机纯逻辑测试。
  • 增加 worker 命令分发表测试。

阶段 E:IPC 适配层预研

  • 设计 IPC 适配层模块边界。
  • 设计 command block 句柄抽象。
  • 设计 data block 句柄抽象。
  • 设计 command event 句柄抽象。
  • 设计 done event 句柄抽象。
  • 设计 READY 状态写入流程。
  • 设计 DONE 状态写入流程。
  • 设计 wait command event 流程。
  • 设计 signal done event 流程。
  • 设计 event 不 reset 的约束检查。
  • 设计 shared memory 打开失败错误路径。
  • 设计 event 打开失败错误路径。
  • 设计 wait 超时错误路径。
  • 设计 Windows 平台条件编译策略。
  • 设计非 Windows 平台的明确错误路径。
  • 增加 IPC adapter mock 测试。

阶段 F:Worker 命令与现有 API 映射

  • 将 READ_INPUT 映射到 sphlite_read_inp。
  • 将 BUILD_MODEL 映射到 sphlite_build_model。
  • 将 ADVANCE 映射到 sphlite_advance_explicit。
  • 将 WRITE_OUTPUT 映射到 sphlite_write_output。
  • 将 EXPORT_INTERFACE 映射到 region count 查询。
  • 将 EXPORT_INTERFACE 映射到 region info 查询。
  • 将 EXPORT_INTERFACE 映射到 particle export。
  • 将 EXPORT_INTERFACE 映射到 facet export。
  • 将 IMPORT_LOADS 映射到 particle force import。
  • 将 IMPORT_LOADS 映射到 facet pressure import。
  • 将 IMPORT_LOADS 映射到 facet traction import。
  • 将 IMPORT_LOADS 映射到 facet resultant import。
  • 将 IMPORT_LOADS 映射到 contact state import。
  • 将 IMPORT_LOADS 映射到 motion boundary import。
  • 将 worker error code 映射到 SPHLite last error。
  • 增加 worker API 映射 mock 测试。

阶段 G:数据契约 v2 预留

  • 设计 v2 particle export 接口草案。
  • 设计 v2 particle force import 接口草案。
  • 设计 v2 contact state import 接口草案。
  • 设计 v2 boundary state import 接口草案。
  • 设计 source_id 存储和诊断语义。
  • 设计 pair_id 存储和诊断语义。
  • 设计 contact_radius 计算和导出语义。
  • 设计 sound_speed 计算和导出语义。
  • 设计 valid_flags 位定义。
  • 设计 body_id 占位策略。
  • 设计 moment[3] 导入和诊断语义。
  • 设计 interface_pressure 预留语义。
  • 设计 interface_velocity 预留语义。
  • 设计 v2 接口与现有 ABI 共存策略。
  • 设计 v2 C++ wrapper 暴露策略。
  • 设计 v2 Python wrapper 暴露策略。

阶段 H:外部载荷和接触诊断加固

  • 增加 particle id 未匹配计数设计。
  • 增加 force record 拒绝原因分类设计。
  • 增加非有限 force record 诊断设计。
  • 增加非有限 contact record 诊断设计。
  • 增加 per-region 输入总力诊断设计。
  • 增加 per-region 输入总力矩诊断设计。
  • 增加 per-region 分配后总力诊断设计。
  • 增加 per-region 分配后总力矩诊断设计。
  • 增加 per-region 分配误差诊断设计。
  • 增加 contact state 枚举扩展设计。
  • 增加 tied/release 只读诊断映射设计。
  • 增加 stale epoch 行为复核测试。
  • 增加 repeated import 行为复核测试。
  • 增加 load balance 回归测试。
  • 增加 contact diagnostics 回归测试。
  • 将新增诊断字段写入 manifest。

阶段 I:Boundary/Ghost 与 FSI 预留

  • 定义 boundary state id 语义。
  • 定义 ghost state id 语义。
  • 定义 boundary position 字段。
  • 定义 boundary velocity 字段。
  • 定义 boundary normal 字段。
  • 定义 boundary pressure 字段。
  • 定义 boundary density 字段。
  • 定义 boundary sound speed 字段。
  • 定义 interface pressure 字段。
  • 定义 interface velocity 字段。
  • 定义 boundary state mode 字段。
  • 定义 boundary valid flags 字段。
  • 设计 boundary state 导入缓存。
  • 设计 boundary state 清零策略。
  • 设计 boundary/ghost smoke 测试。
  • 将 boundary/ghost 能力标记为预留而非生产 FSI。

阶段 J:Worker 诊断和输出

  • 设计 sphlite_cclite_worker.log 内容。
  • 设计 sphlite_cclite_particle_report.csv 内容。
  • 设计 sphlite_cclite_force_report.csv 内容。
  • 设计 worker 启动参数日志。
  • 设计 command block 名称日志。
  • 设计 data block 名称日志。
  • 设计 command id 日志。
  • 设计 step id 日志。
  • 设计 ack seq 日志。
  • 设计 worker state 日志。
  • 设计导出粒子数量日志。
  • 设计导出 facet 数量日志。
  • 设计接收 force 数量日志。
  • 设计错误码和错误消息日志。
  • 确认 VTU/PVD 输出可用于 worker 结果复核。
  • 增加 worker 诊断文件 smoke 测试。

阶段 K:CCLite Mock 联调

  • 设计 CCLite mock command block 数据。
  • 设计 CCLite mock data block 数据。
  • 设计 INIT mock 测试。
  • 设计 READ_INPUT mock 测试。
  • 设计 BUILD_MODEL mock 测试。
  • 设计空 EXPORT_INTERFACE mock 测试。
  • 设计固定粒子 EXPORT_INTERFACE mock 测试。
  • 设计空 IMPORT_LOADS mock 测试。
  • 设计粒子力 IMPORT_LOADS mock 测试。
  • 设计 facet load IMPORT_LOADS mock 测试。
  • 设计 ADVANCE 单步 mock 测试。
  • 设计 WRITE_OUTPUT mock 测试。
  • 设计 STOP mock 测试。
  • 设计 100 step 空耦合 mock 测试。
  • 设计异常命令 mock 测试。
  • 将 CCLite mock 联调测试接入 CTest。

阶段 L:发布和回归验收

  • 更新 README 中 Output 描述为 CSV、VTU、PVD、restart 和诊断输出。
  • 更新 02 号架构文档中的 Output 描述。
  • 更新 05 号接口文档中的 coupling 当前接口清单。
  • 更新 06 号测试文档中的 worker gate 建议。
  • 更新 09 号版本历史中的 CCLite 集成预研记录。
  • 更新 12 号文档中的已完成/待完成状态。
  • 验证 examples/infinite_underwater_explosion 双击脚本仍可运行。
  • 验证无限水域爆炸案例仍生成 VTU。
  • 验证无限水域爆炸案例仍生成 PVD。
  • 验证 tools/publish_to_cclite.bat dry run。
  • 验证发布版 examples 脚本路径自动调整。
  • 运行 worker/coupling 专项 CTest。
  • 运行完整 CTest。
  • 运行 source size gate。
  • 运行 git diff --check。
  • 准备阶段 L 本地提交说明。