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

282 lines
13 KiB
Markdown
Raw Permalink 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 接触算法核心。
- 不让 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:基线和边界复核
- [x] 复核 `docs/12_cclite_integration_suggestions.md` 中 SPHLite、CCLite、FEMLite 的职责边界。
- [x] 复核当前 worker mock 与真实 IPC 未闭合的边界表述。
- [x] 复核现有 `CouplingInterface` C ABI 清单。
- [x] 复核现有 C++ wrapper coupling 暴露清单。
- [x] 复核现有 Python debug coupling 暴露清单。
- [x] 复核当前 CLI 普通运行、`--check`、`--run` 行为。
- [x] 复核当前 worker CLI 参数解析行为。
- [x] 复核当前 worker 状态枚举和命令枚举。
- [x] 复核当前 worker mock command/data block 契约。
- [x] 复核当前 coupling diagnostics 和 load balance 字段。
- [x] 复核当前 CSV、VTU、PVD、restart 输出能力。
- [x] 复核当前 source size 例外清单。
## 阶段 B:CCLite 能力查询入口
- [x] 设计 `--cclite-capabilities` CLI 参数语义。
- [x] 增加 `--cclite-capabilities` 与普通输入文件参数的冲突检查。
- [x] 增加 `--cclite-capabilities` 与 `--cclite-worker` 的组合规则。
- [x] 定义 capabilities 输出的 `solver` 字段。
- [x] 定义 capabilities 输出的 `cclite_worker` 字段。
- [x] 定义 capabilities 输出的 `ipc_backend` 字段。
- [x] 定义 capabilities 输出的 `command_block_version` 字段。
- [x] 定义 capabilities 输出的 `data_layout` 字段。
- [x] 定义 capabilities 输出的 `supports_real_ipc` 字段。
- [x] 定义 capabilities 输出的 `supports_sph_to_ccl_particle` 字段。
- [x] 定义 capabilities 输出的 `supports_ccl_to_sph_force` 字段。
- [x] 定义 capabilities 输出的 `max_particle_records` 字段。
- [x] 实现 capabilities 文本输出。
- [x] 增加 capabilities CLI 正常路径测试。
- [x] 增加 capabilities CLI 参数冲突测试。
- [x] 将 capabilities 测试接入 CTest。
## 阶段 C:真实 IPC 适配层骨架
- [x] 设计真实 IPC adapter 与 mock adapter 的共同接口。
- [x] 增加 Windows shared memory 句柄结构。
- [x] 增加 Windows named event 句柄结构。
- [x] 增加 command block 打开函数。
- [x] 增加 data block 打开函数。
- [x] 增加 command event 打开函数。
- [x] 增加 done event 打开函数。
- [x] 增加 command event wait 函数。
- [x] 增加 done event signal 函数。
- [x] 增加 shared memory 关闭函数。
- [x] 增加 named event 关闭函数。
- [x] 增加 wait 超时错误路径。
- [x] 增加句柄打开失败错误路径。
- [x] 增加非 Windows 平台真实 IPC unsupported 路径。
- [x] 增加真实 IPC adapter 编译开关。
- [x] 增加 IPC adapter 单元测试。
## 阶段 D:真实 worker 主循环
- [x] 将 worker 启动参数传入真实 IPC adapter。
- [x] 在 worker 启动后写入 `READY` 状态。
- [x] 在 worker 启动失败时写入受控错误消息。
- [x] 实现 worker 等待 command event 的主循环。
- [x] 实现 command sequence 读取。
- [x] 实现 command kind 读取。
- [x] 实现未知 command 的受控错误响应。
- [x] 实现 `INIT` 命令真实 IPC 路径。
- [x] 实现 `READ_INPUT` 命令真实 IPC 路径。
- [x] 实现 `BUILD_MODEL` 命令真实 IPC 路径。
- [x] 实现 `EXPORT_INTERFACE` 命令真实 IPC 路径。
- [x] 实现 `IMPORT_LOADS` 命令真实 IPC 路径。
- [x] 实现 `ADVANCE` 命令真实 IPC 路径。
- [x] 实现 `WRITE_OUTPUT` 命令真实 IPC 路径。
- [x] 实现 `STOP` 命令真实 IPC 路径。
- [x] 每条命令后回写 `ack_seq`。
- [x] 每条命令后回写 `worker_state`。
- [x] 每条命令后回写 `error_code`。
- [x] 每条命令后回写短消息。
- [x] 每条命令后 signal done event。
## 阶段 E:`SPH_TO_CCL_PARTICLE` 数据块
- [x] 定义 `SPH_TO_CCL_PARTICLE` 数据块版本号。
- [x] 定义 `SPH_TO_CCL_PARTICLE` 记录容量字段。
- [x] 定义 `SPH_TO_CCL_PARTICLE` 有效记录数字段。
- [x] 定义粒子 `external id` 字段。
- [x] 定义粒子 `internal/export index` 字段。
- [x] 定义粒子 `phase` 字段。
- [x] 定义粒子 `status` 字段。
- [x] 定义粒子 `material id` 字段。
- [x] 定义粒子 `section id` 字段。
- [x] 定义粒子 `body id` 占位字段。
- [x] 定义粒子位置字段。
- [x] 定义粒子速度字段。
- [x] 定义粒子质量字段。
- [x] 定义粒子密度字段。
- [x] 定义粒子体积字段。
- [x] 定义粒子光滑长度字段。
- [x] 定义粒子接触半径字段。
- [x] 定义粒子压力字段。
- [x] 定义粒子声速字段。
- [x] 定义粒子 `valid_flags` 字段。
- [x] 实现空粒子导出。
- [x] 实现固定粒子导出。
- [x] 映射真实 coupling region 粒子导出。
- [x] 增加粒子导出容量不足错误路径。
## 阶段 F:导出粒子校验和报告
- [x] 增加导出粒子坐标有限值检查。
- [x] 增加导出粒子速度有限值检查。
- [x] 增加导出粒子质量有效性检查。
- [x] 增加导出粒子密度有效性检查。
- [x] 增加导出粒子体积有效性检查。
- [x] 增加导出粒子光滑长度有效性检查。
- [x] 增加导出粒子接触半径有效性检查。
- [x] 增加导出粒子压力有限值检查。
- [x] 增加导出粒子声速有效性检查。
- [x] 增加导出粒子 phase 有效性检查。
- [x] 增加导出粒子 status 有效性检查。
- [x] 增加导出粒子 external id 有效性检查。
- [x] 增加导出粒子 internal/export index 有效性检查。
- [x] 将被拒绝导出粒子计入诊断。
- [x] 将被拒绝导出粒子写入 particle report。
- [x] 增加导出粒子校验单元测试。
## 阶段 G:`CCL_TO_SPH_FORCE` 数据块
- [x] 定义 `CCL_TO_SPH_FORCE` 数据块版本号。
- [x] 定义 `CCL_TO_SPH_FORCE` 记录容量字段。
- [x] 定义 `CCL_TO_SPH_FORCE` 有效记录数字段。
- [x] 定义 force record 的 particle id 字段。
- [x] 定义 force record 的 internal/export index 字段。
- [x] 定义 force record 的 force[3] 字段。
- [x] 定义 force record 的 moment[3] 字段。
- [x] 定义 force record 的 source id 字段。
- [x] 定义 force record 的 pair id 字段。
- [x] 定义 force record 的 load mode 字段。
- [x] 定义 force record 的 contact state 字段。
- [x] 定义 force record 的 step id 字段。
- [x] 定义 force record 的 valid flags 字段。
- [x] 实现空 force block 导入。
- [x] 映射粒子力导入到现有 CouplingInterface。
- [x] 映射接触状态导入到现有 CouplingInterface。
- [x] 增加 force block 容量越界错误路径。
- [x] 增加 force block 版本不匹配错误路径。
## 阶段 H:导入载荷校验和诊断
- [x] 增加 force record particle id 匹配检查。
- [x] 增加 force record internal/export index 匹配检查。
- [x] 增加 force record force[3] 有限值检查。
- [x] 增加 force record moment[3] 有限值检查。
- [x] 增加 force record source id 有效性检查。
- [x] 增加 force record pair id 诊断记录。
- [x] 增加 force record load mode 有效性检查。
- [x] 增加 force record contact state 有效性检查。
- [x] 增加 force record step id 检查。
- [x] 增加 force record valid flags 检查。
- [x] 增加无法匹配 force record 的拒绝计数。
- [x] 增加非有限 force record 的拒绝计数。
- [x] 增加过期 step force record 的拒绝计数。
- [x] 增加重复 force record 的诊断计数。
- [x] 将导入总力写入 load balance 诊断。
- [x] 将导入总力矩写入 load balance 诊断。
- [x] 将拒绝原因写入 force report。
- [x] 增加导入载荷校验单元测试。
## 阶段 I:v2 数据契约和预留接口
- [x] 复核 `cclite_coupling_manifest.md` 的 v2 字段清单。
- [x] 明确 `body_id` 的默认值和长期语义。
- [x] 明确 `contact_radius` 与 `h` 的关系。
- [x] 明确 `sound_speed` 的来源和默认值。
- [x] 明确 `valid_flags` 位定义。
- [x] 明确 `source_id` 与 CCLite contact pair 的关系。
- [x] 明确 `pair_id` 与 contact state 的关系。
- [x] 明确 `moment[3]` 对 Solid/Shell 的预留语义。
- [x] 明确 `interface_pressure` 的预留语义。
- [x] 明确 `interface_velocity` 的预留语义。
- [x] 设计 `sphlite_coupling_apply_boundary_states` 草案。
- [x] 设计 boundary/ghost state 缓存容量策略。
- [x] 设计 boundary/ghost state 清零策略。
- [x] 增加 boundary/ghost 数据契约 smoke 测试。
- [x] 标记 boundary/ghost 为预留能力而非生产 FSI。
- [x] 更新 v2 契约文档。
## 阶段 J:Worker 诊断输出
- [x] 实现 `sphlite_cclite_worker.log` 文件路径解析。
- [x] 记录 worker 启动参数。
- [x] 记录 command block 名称。
- [x] 记录 data block 名称。
- [x] 记录 command event 名称。
- [x] 记录 done event 名称。
- [x] 记录当前 command id。
- [x] 记录当前 step id。
- [x] 记录当前 ack seq。
- [x] 记录当前 worker state。
- [x] 记录导出粒子数量。
- [x] 记录导出 facet 数量。
- [x] 记录接收 force 数量。
- [x] 记录接收总力。
- [x] 记录接收总力矩。
- [x] 记录非有限粒子状态数量。
- [x] 记录错误码和错误消息。
- [x] 实现 `sphlite_cclite_particle_report.csv`。
- [x] 实现 `sphlite_cclite_force_report.csv`。
- [x] 增加 worker 诊断输出测试。
## 阶段 K:输入关键词和配置开关
- [x] 复核现有 `*SPHLITE COUPLING REGION` 语法是否满足 CCLite 引用需求。
- [x] 复核 `EXPORT=PARTICLE/FACET/BOTH` 与 worker 数据块的映射。
- [x] 复核 `IMPORT=FORCE/FACET_LOAD/MOTION` 与 worker 数据块的映射。
- [x] 复核 `CONTACT_STATE=OFF/IMPORT` 与 contact state 导入的映射。
- [x] 设计 `*SPHLITE CCLITE` 关键词草案。
- [x] 定义 `*SPHLITE CCLITE, WORKER=YES` 语义。
- [x] 定义 `*SPHLITE CCLITE, REGION=...` 语义。
- [x] 定义 `EXPORT_RADIUS=YES/NO` 语义。
- [x] 定义 `EXPORT_SOUND_SPEED=YES/NO` 语义。
- [x] 定义 `ACCEPT_CONTACT_STATE=YES/NO` 语义。
- [x] 定义 `ACCEPT_BOUNDARY_STATE=YES/NO` 语义。
- [x] 明确 `*SPHLITE CCLITE` 不替代 CCLite 配置文件。
- [x] 增加输入关键词文档。
- [x] 增加输入关键词解析测试。
## 阶段 L:Worker self-test 和 CCLite mock 联调
- [x] 设计 SPHLite 侧真实 IPC self-test 启动方式。
- [x] 准备 self-test 用最小输入文件。
- [x] 验证 self-test worker 启动。
- [x] 验证 self-test IPC attach。
- [x] 验证 self-test `READY` 写入。
- [x] 验证 self-test 空粒子导出。
- [x] 验证 self-test 固定粒子导出。
- [x] 验证 self-test 空 force 导入。
- [x] 验证 self-test `STOP` 正常退出。
- [x] 验证 self-test 超时可控退出。
- [x] 与 CCLite mock FEM 验收 1 step 空耦合。
- [x] 与 CCLite mock FEM 验收 100 step 空耦合。
- [x] 与 CCLite mock FEM 验收异常输入退出。
- [x] 与 CCLite mock FEM 验收超时退出。
- [x] 记录真实 SPHLite + mock FEM 联调日志。
- [x] 将可本地执行的 self-test 接入 CTest。
## 阶段 M:回归测试和发布准备
- [x] 增加 capabilities CLI 回归到 release gate。
- [x] 增加真实 IPC unsupported 路径回归到 release gate。
- [x] 增加 worker self-test 回归到 release gate。
- [x] 增加 particle export 数据块回归到 release gate。
- [x] 增加 force import 数据块回归到 release gate。
- [x] 增加粒子校验拒绝路径回归到 release gate。
- [x] 增加载荷校验拒绝路径回归到 release gate。
- [x] 增加 worker diagnostics 回归到 release gate。
- [x] 运行 worker/coupling 专项 CTest。
- [x] 运行完整 CTest。
- [x] 运行 source size gate。
- [x] 运行 `git diff --check`。
- [x] 运行无限水域爆炸示例脚本。
- [x] 验证示例 VTU/PVD 输出。
- [x] 验证 `tools/publish_to_cclite.bat` dry run。
- [x] 更新 06 号测试与验证计划。
- [x] 更新 09 号版本历史。
- [x] 更新 11 号 benchmark matrix。
- [x] 更新 12 号 CCLite 集成建议状态。
- [x] 更新 README 当前能力说明。