# 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 当前能力说明。