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

244 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:范围收敛和现状复核
- [x] 复核 12 号文档中的 SPHLite/CCLite/FEMLite 职责边界。
- [x] 复核 0.8.0 coupling region 输入解析能力。
- [x] 复核 0.8.1 facet pressure/traction/resultant 导入能力。
- [x] 复核现有 contact state 导入和诊断能力。
- [x] 复核现有 motion boundary direct 模式能力。
- [x] 复核现有 CSV、VTU、PVD 和 restart 输出能力。
- [x] 复核现有 C ABI coupling 接口清单。
- [x] 复核现有 C++ wrapper coupling 接口清单。
- [x] 复核现有 Python debug coupling 接口清单。
- [x] 复核现有 CLI coupling 诊断输出字段。
- [x] 明确 worker/service adapter 不侵入核心物理模块。
- [x] 明确 CCLite shared memory 和 event 生命周期不由 SPHLite 管理。
- [x] 明确 worker 通信闭环不等同于真实接触算法完成。
- [x] 明确下一阶段不交付生产级 FSI 和连续体强耦合。
- [x] 记录当前 release gate 和 source size 基线。
- [x] 准备阶段 A 变更小结。
## 阶段 B:CCLite 数据契约 manifest
- [x] 建立 CCLite 集成数据契约 manifest 文档。
- [x] 在 manifest 中列出 region info 字段。
- [x] 在 manifest 中列出 region modes 字段。
- [x] 在 manifest 中列出现有 particle export 字段。
- [x] 在 manifest 中列出现有 facet export 字段。
- [x] 在 manifest 中列出现有 particle force import 字段。
- [x] 在 manifest 中列出现有 facet load import 字段。
- [x] 在 manifest 中列出现有 contact state import 字段。
- [x] 在 manifest 中列出现有 motion boundary import 字段。
- [x] 在 manifest 中列出现有 load balance 诊断字段。
- [x] 在 manifest 中列出现有 contact diagnostics 字段。
- [x] 在 manifest 中标记尚未暴露的 `body_id` 字段。
- [x] 在 manifest 中标记尚未暴露的 `contact_radius` 字段。
- [x] 在 manifest 中标记尚未暴露的 `sound_speed` 字段。
- [x] 在 manifest 中标记尚未暴露的 `source_id` 和 `pair_id` 字段。
- [x] 在 manifest 中标记尚未暴露的 `valid_flags` 字段。
- [x] 在 manifest 中标记 boundary/ghost 预留字段。
- [x] 在 manifest 中说明数组展开顺序。
- [x] 在 manifest 中说明 external id 与 export index 的使用边界。
- [x] 将 manifest 接入 docs 索引或 12 号文档引用。
## 阶段 C:Worker CLI 入口设计
- [x] 设计 `--cclite-worker` CLI 参数语义。
- [x] 设计 `--solver-id` CLI 参数语义。
- [x] 设计 `--case` CLI 参数语义。
- [x] 设计 `--ipc-name` CLI 参数语义。
- [x] 设计 `--command-block` CLI 参数语义。
- [x] 设计 `--data-prefix` CLI 参数语义。
- [x] 设计 `--log` CLI 参数语义。
- [x] 设计 `--timeout-ms` CLI 参数语义。
- [x] 设计 `--worker-id` CLI 参数语义。
- [x] 设计 worker 参数缺失时的错误码和错误消息。
- [x] 设计 worker 参数冲突时的错误码和错误消息。
- [x] 确认未启用 worker 时现有 CLI 行为不变。
- [x] 增加 worker CLI 参数解析单元测试。
- [x] 增加普通 CLI 回归测试。
- [x] 增加 worker 参数错误路径测试。
- [x] 将 worker CLI 测试接入 CTest。
## 阶段 D:Worker 状态机和命令枚举
- [x] 定义 worker 状态枚举。
- [x] 定义 worker 命令枚举。
- [x] 定义 worker ack 序号语义。
- [x] 定义 worker error code 映射语义。
- [x] 定义 `INIT` 命令处理流程。
- [x] 定义 `READ_INPUT` 命令处理流程。
- [x] 定义 `BUILD_MODEL` 命令处理流程。
- [x] 定义 `EXPORT_INTERFACE` 命令处理流程。
- [x] 定义 `IMPORT_LOADS` 命令处理流程。
- [x] 定义 `ADVANCE` 命令处理流程。
- [x] 定义 `WRITE_OUTPUT` 命令处理流程。
- [x] 定义 `STOP` 命令处理流程。
- [x] 定义未知命令处理流程。
- [x] 定义命令超时处理流程。
- [x] 增加 worker 状态机纯逻辑测试。
- [x] 增加 worker 命令分发表测试。
## 阶段 E:IPC 适配层预研
- [x] 设计 IPC 适配层模块边界。
- [x] 设计 command block 句柄抽象。
- [x] 设计 data block 句柄抽象。
- [x] 设计 command event 句柄抽象。
- [x] 设计 done event 句柄抽象。
- [x] 设计 READY 状态写入流程。
- [x] 设计 DONE 状态写入流程。
- [x] 设计 wait command event 流程。
- [x] 设计 signal done event 流程。
- [x] 设计 event 不 reset 的约束检查。
- [x] 设计 shared memory 打开失败错误路径。
- [x] 设计 event 打开失败错误路径。
- [x] 设计 wait 超时错误路径。
- [x] 设计 Windows 平台条件编译策略。
- [x] 设计非 Windows 平台的明确错误路径。
- [x] 增加 IPC adapter mock 测试。
## 阶段 F:Worker 命令与现有 API 映射
- [x] 将 `READ_INPUT` 映射到 `sphlite_read_inp`。
- [x] 将 `BUILD_MODEL` 映射到 `sphlite_build_model`。
- [x] 将 `ADVANCE` 映射到 `sphlite_advance_explicit`。
- [x] 将 `WRITE_OUTPUT` 映射到 `sphlite_write_output`。
- [x] 将 `EXPORT_INTERFACE` 映射到 region count 查询。
- [x] 将 `EXPORT_INTERFACE` 映射到 region info 查询。
- [x] 将 `EXPORT_INTERFACE` 映射到 particle export。
- [x] 将 `EXPORT_INTERFACE` 映射到 facet export。
- [x] 将 `IMPORT_LOADS` 映射到 particle force import。
- [x] 将 `IMPORT_LOADS` 映射到 facet pressure import。
- [x] 将 `IMPORT_LOADS` 映射到 facet traction import。
- [x] 将 `IMPORT_LOADS` 映射到 facet resultant import。
- [x] 将 `IMPORT_LOADS` 映射到 contact state import。
- [x] 将 `IMPORT_LOADS` 映射到 motion boundary import。
- [x] 将 worker error code 映射到 SPHLite last error。
- [x] 增加 worker API 映射 mock 测试。
## 阶段 G:数据契约 v2 预留
- [x] 设计 v2 particle export 接口草案。
- [x] 设计 v2 particle force import 接口草案。
- [x] 设计 v2 contact state import 接口草案。
- [x] 设计 v2 boundary state import 接口草案。
- [x] 设计 `source_id` 存储和诊断语义。
- [x] 设计 `pair_id` 存储和诊断语义。
- [x] 设计 `contact_radius` 计算和导出语义。
- [x] 设计 `sound_speed` 计算和导出语义。
- [x] 设计 `valid_flags` 位定义。
- [x] 设计 `body_id` 占位策略。
- [x] 设计 `moment[3]` 导入和诊断语义。
- [x] 设计 `interface_pressure` 预留语义。
- [x] 设计 `interface_velocity` 预留语义。
- [x] 设计 v2 接口与现有 ABI 共存策略。
- [x] 设计 v2 C++ wrapper 暴露策略。
- [x] 设计 v2 Python wrapper 暴露策略。
## 阶段 H:外部载荷和接触诊断加固
- [x] 增加 particle id 未匹配计数设计。
- [x] 增加 force record 拒绝原因分类设计。
- [x] 增加非有限 force record 诊断设计。
- [x] 增加非有限 contact record 诊断设计。
- [x] 增加 per-region 输入总力诊断设计。
- [x] 增加 per-region 输入总力矩诊断设计。
- [x] 增加 per-region 分配后总力诊断设计。
- [x] 增加 per-region 分配后总力矩诊断设计。
- [x] 增加 per-region 分配误差诊断设计。
- [x] 增加 contact state 枚举扩展设计。
- [x] 增加 tied/release 只读诊断映射设计。
- [x] 增加 stale epoch 行为复核测试。
- [x] 增加 repeated import 行为复核测试。
- [x] 增加 load balance 回归测试。
- [x] 增加 contact diagnostics 回归测试。
- [x] 将新增诊断字段写入 manifest。
## 阶段 I:Boundary/Ghost 与 FSI 预留
- [x] 定义 boundary state id 语义。
- [x] 定义 ghost state id 语义。
- [x] 定义 boundary position 字段。
- [x] 定义 boundary velocity 字段。
- [x] 定义 boundary normal 字段。
- [x] 定义 boundary pressure 字段。
- [x] 定义 boundary density 字段。
- [x] 定义 boundary sound speed 字段。
- [x] 定义 interface pressure 字段。
- [x] 定义 interface velocity 字段。
- [x] 定义 boundary state mode 字段。
- [x] 定义 boundary valid flags 字段。
- [x] 设计 boundary state 导入缓存。
- [x] 设计 boundary state 清零策略。
- [x] 设计 boundary/ghost smoke 测试。
- [x] 将 boundary/ghost 能力标记为预留而非生产 FSI。
## 阶段 J:Worker 诊断和输出
- [x] 设计 `sphlite_cclite_worker.log` 内容。
- [x] 设计 `sphlite_cclite_particle_report.csv` 内容。
- [x] 设计 `sphlite_cclite_force_report.csv` 内容。
- [x] 设计 worker 启动参数日志。
- [x] 设计 command block 名称日志。
- [x] 设计 data block 名称日志。
- [x] 设计 command id 日志。
- [x] 设计 step id 日志。
- [x] 设计 ack seq 日志。
- [x] 设计 worker state 日志。
- [x] 设计导出粒子数量日志。
- [x] 设计导出 facet 数量日志。
- [x] 设计接收 force 数量日志。
- [x] 设计错误码和错误消息日志。
- [x] 确认 VTU/PVD 输出可用于 worker 结果复核。
- [x] 增加 worker 诊断文件 smoke 测试。
## 阶段 K:CCLite Mock 联调
- [x] 设计 CCLite mock command block 数据。
- [x] 设计 CCLite mock data block 数据。
- [x] 设计 `INIT` mock 测试。
- [x] 设计 `READ_INPUT` mock 测试。
- [x] 设计 `BUILD_MODEL` mock 测试。
- [x] 设计空 `EXPORT_INTERFACE` mock 测试。
- [x] 设计固定粒子 `EXPORT_INTERFACE` mock 测试。
- [x] 设计空 `IMPORT_LOADS` mock 测试。
- [x] 设计粒子力 `IMPORT_LOADS` mock 测试。
- [x] 设计 facet load `IMPORT_LOADS` mock 测试。
- [x] 设计 `ADVANCE` 单步 mock 测试。
- [x] 设计 `WRITE_OUTPUT` mock 测试。
- [x] 设计 `STOP` mock 测试。
- [x] 设计 100 step 空耦合 mock 测试。
- [x] 设计异常命令 mock 测试。
- [x] 将 CCLite mock 联调测试接入 CTest。
## 阶段 L:发布和回归验收
- [x] 更新 README 中 Output 描述为 CSV、VTU、PVD、restart 和诊断输出。
- [x] 更新 02 号架构文档中的 Output 描述。
- [x] 更新 05 号接口文档中的 coupling 当前接口清单。
- [x] 更新 06 号测试文档中的 worker gate 建议。
- [x] 更新 09 号版本历史中的 CCLite 集成预研记录。
- [x] 更新 12 号文档中的已完成/待完成状态。
- [x] 验证 `examples/infinite_underwater_explosion` 双击脚本仍可运行。
- [x] 验证无限水域爆炸案例仍生成 VTU。
- [x] 验证无限水域爆炸案例仍生成 PVD。
- [x] 验证 `tools/publish_to_cclite.bat` dry run。
- [x] 验证发布版 examples 脚本路径自动调整。
- [x] 运行 worker/coupling 专项 CTest。
- [x] 运行完整 CTest。
- [x] 运行 source size gate。
- [x] 运行 `git diff --check`。
- [x] 准备阶段 L 本地提交说明。