# SPHLite TODO 当前目标版本:0.8.0 本文档根据 `docs/v8.0_development_plan.md` 生成。0.8.0 定位为 SPHLite 侧中立接触耦合接口起步版,目标是将 `CouplingInterface` 从占位推进到可由外部耦合模块逐步驱动的接触耦合接口。 所有事项均应限制在 SPHLite 文件夹内完成,不修改外部模块,不引入 FEMLite 直接依赖,不新增几何、网格或粒子生成能力。0.8.0 不交付真实 FEMLite 联合运行,不交付外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite,不交付连续体耦合,不宣称工程级水下接触爆炸破坏 benchmark。核心代码继续遵守 Fortran95 约束,C/C++/Python 接口采用追加式扩展。执行约定:每完成一个阶段,进行一次本地 git 提交,暂不推送远端,除非用户另行要求。 ## 阶段 A:0.8.0 基线、范围收敛和版本更新 - [x] 确认当前 git 工作区状态并记录已有未提交内容。 - [x] 确认 `v0.7.1` 标签和远端发布提交可作为 0.8.0 开发基线。 - [x] 复核 `docs/v8.0_development_plan.md` 的版本定位和非交付范围。 - [x] 确认 0.8.0 只交付 SPHLite 侧中立接触耦合接口。 - [x] 确认 0.8.0 不实现真实 FEMLite 联合运行。 - [x] 确认 0.8.0 不实现外部 CouplingModule。 - [x] 确认 0.8.0 不实现连续体耦合。 - [x] 确认 0.8.0 不新增几何、网格或粒子生成能力。 - [x] 复核现有 `CouplingInterface` 占位模块能力。 - [x] 复核现有 coupling region 输入解析能力。 - [x] 复核现有数据库 coupling region 字段。 - [x] 复核现有外部粒子力进入显式步的路径。 - [x] 复核现有 C ABI、C++ wrapper、Python ctypes 和 CLI 的接口边界。 - [x] 将 CMake 项目版本更新为 `0.8.0`。 - [x] 将核心 Fortran 版本号更新为 `0.8.0`。 - [x] 更新 Fortran smoke 测试中的版本期望。 - [x] 更新 C API 测试中的版本期望。 - [x] 更新 C++ wrapper 测试中的版本期望。 - [x] 更新 Python debug 测试中的版本期望。 - [x] 更新 CLI `--version` 或 inspect 版本期望。 - [x] 更新 README 当前开发版本为 `0.8.0`。 - [x] 在 README 中说明 0.8.0 的接触耦合接口范围。 - [x] 在 README 中说明 0.8.0 的不交付边界。 - [x] 准备 0.8.0 coupling 专项 gate 的初始测试名称清单。 - [x] 运行 0.7.1 关键 smoke 或版本相关测试。 - [x] 运行 `git diff --check`。 - [x] 准备阶段 A 本地提交说明。 ## 阶段 B:Coupling Region 输入语义和运行时表 - [ ] 复核现有 `*SPHLITE COUPLING REGION` 关键词字段。 - [ ] 定义 `TYPE=CONTACT` 为 0.8.0 唯一启用耦合类型。 - [ ] 定义 `TYPE=CONTINUUM` 的预留错误路径。 - [ ] 定义 coupling region 名称唯一性规则。 - [ ] 定义 `EXPORT=PARTICLE` 的输入语义。 - [ ] 定义 `EXPORT=FACET` 的输入语义。 - [ ] 定义 `EXPORT=BOTH` 的输入语义。 - [ ] 定义 `IMPORT=FORCE` 的输入语义。 - [ ] 定义 `IMPORT=FACET_LOAD` 的输入语义。 - [ ] 定义 `IMPORT=MOTION` 的输入语义。 - [ ] 定义 `ENABLED` 字段的默认值和布尔解析规则。 - [ ] 支持读取 coupling region 的 `NAME` 字段。 - [ ] 支持读取 coupling region 的 `TYPE` 字段。 - [ ] 支持读取 coupling region 的 `SET` 字段。 - [ ] 支持读取 coupling region 的 `SURFACE` 字段占位。 - [ ] 支持读取 coupling region 的 `PHASE` 过滤字段。 - [ ] 支持读取 coupling region 的 `MATERIAL` 过滤字段。 - [ ] 支持读取 coupling region 的 `SECTION` 过滤字段。 - [ ] 支持读取 coupling region 的 `EXPORT` 字段。 - [ ] 支持读取 coupling region 的 `IMPORT` 字段。 - [ ] 支持读取 coupling region 的 `ENABLED` 字段。 - [ ] 对空 region 名称报 error。 - [ ] 对重复 region 名称报 error。 - [ ] 对非法 `TYPE` 报 error。 - [ ] 对非法 `EXPORT` 报 error。 - [ ] 对非法 `IMPORT` 报 error。 - [ ] 对非法 `ENABLED` 报 error。 - [ ] 对缺失或不存在的 `SET` 报 error。 - [ ] 对无法选中粒子的 active region 报 error。 - [ ] 对 disabled region 保留输入记录但不参与导出。 - [ ] 保持 `tests/data/coupling_region_011.inp` 兼容。 - [ ] 在数据库中保存 region type、export mode、import mode 和 enabled 状态。 - [ ] 在数据库中保存 region set、surface、phase、material 和 section 过滤条件。 - [ ] 建立运行时 region 内部 id。 - [ ] 建立运行时 region 粒子索引表。 - [ ] 建立运行时 region active 粒子计数。 - [ ] 建立运行时 region 禁用状态计数。 - [ ] 确认 coupling region 构建不污染 Blast region。 - [ ] 确认 coupling region 构建不污染 Gas source region。 - [ ] 新增 `input_coupling_region_080` 测试。 - [ ] 新增 `input_coupling_errors_080` 测试。 - [ ] 新增 `coupling_region_build_080` 测试。 - [ ] 将阶段 B 新测试接入 CTest。 - [ ] 运行阶段 B coupling 输入专项测试。 - [ ] 运行 `git diff --check`。 - [ ] 准备阶段 B 本地提交说明。 ## 阶段 C:粒子导出和 Facet Proxy 导出 - [ ] 定义 coupling 粒子导出字段顺序。 - [ ] 定义 coupling 粒子 scalar 缓冲区字段顺序。 - [ ] 定义 coupling 粒子三维数组展开顺序。 - [ ] 实现按 region 查询 coupling 粒子数量。 - [ ] 实现按 region 导出 external particle id。 - [ ] 实现按 region 导出 internal particle index。 - [ ] 实现按 region 导出 particle phase。 - [ ] 实现按 region 导出 particle status。 - [ ] 实现按 region 导出 material id。 - [ ] 实现按 region 导出 section id。 - [ ] 实现按 region 导出 mass。 - [ ] 实现按 region 导出 volume。 - [ ] 实现按 region 导出 density。 - [ ] 实现按 region 导出 pressure。 - [ ] 实现按 region 导出 internal energy。 - [ ] 实现按 region 导出 temperature。 - [ ] 实现按 region 导出 smoothing length `h`。 - [ ] 实现按 region 导出 position `x`。 - [ ] 实现按 region 导出 velocity `v`。 - [ ] 实现按 region 导出 acceleration `a`。 - [ ] 对非法 region 名称返回 error。 - [ ] 对 disabled region 返回 0 个导出粒子。 - [ ] 对调用方容量不足返回 error。 - [ ] 对非有限导出状态记录诊断或返回 error。 - [ ] 定义 facet proxy 导出字段顺序。 - [ ] 定义 facet proxy 三维数组展开顺序。 - [ ] 实现 Shell coupling region 的 facet proxy 计数。 - [ ] 实现 Shell facet proxy 的 facet id。 - [ ] 实现 Shell facet proxy 的关联粒子 id。 - [ ] 实现 Shell facet proxy 的中心坐标。 - [ ] 实现 Shell facet proxy 的平均速度。 - [ ] 实现 Shell facet proxy 的法向。 - [ ] 实现 Shell facet proxy 的面积。 - [ ] 实现 Shell facet proxy 的 material 和 section 信息。 - [ ] 支持受控 surface/facet 输入的 facet proxy 占位导出。 - [ ] 明确 Solid 无 surface 时不自动重构复杂外表面。 - [ ] 对 `EXPORT=FACET` 但无 facet proxy 的 region 报 error。 - [ ] 对零面积 facet proxy 报 error。 - [ ] 对非有限法向或面积报 error。 - [ ] 新增 `coupling_particle_export_080` 测试。 - [ ] 新增 `coupling_facet_export_080` 测试。 - [ ] 新增 `coupling_facet_errors_080` 测试。 - [ ] 将阶段 C 新测试接入 CTest。 - [ ] 运行阶段 C coupling 导出专项测试。 - [ ] 运行 `git diff --check`。 - [ ] 准备阶段 C 本地提交说明。 ## 阶段 D:外部粒子力、Facet Load 和运动边界导入 - [ ] 设计 coupling 外部粒子力缓存数组。 - [ ] 设计 coupling facet load 缓存数组或分配后粒子力缓存。 - [ ] 设计 coupling 运动边界缓存数组。 - [ ] 设计 coupling step 或 epoch 状态。 - [ ] 设计 stale load 计数状态。 - [ ] 设计 skipped particle 计数状态。 - [ ] 设计 nonfinite import 计数状态。 - [ ] 在初始化阶段分配 coupling 导入缓存。 - [ ] 在 finalize 阶段释放 coupling 导入缓存。 - [ ] 在模型重建阶段清空 coupling 导入缓存。 - [ ] 实现按 external particle id 导入粒子力。 - [ ] 实现按 region export index 导入粒子力。 - [ ] 对非法 region 导入返回 error。 - [ ] 对非法粒子 id 导入返回 error。 - [ ] 对 disabled region 导入返回 error。 - [ ] 对非有限 force 导入返回 error 并记录计数。 - [ ] 对质量非正粒子导入返回 error。 - [ ] 对 inactive 粒子导入执行跳过并记录计数。 - [ ] 对 failed Solid 粒子导入执行受控跳过或受控接受。 - [ ] 对 failed Shell 粒子导入执行受控跳过或受控接受。 - [ ] 实现同一 epoch 内粒子力累加语义。 - [ ] 实现新 epoch 自动清零或显式清零语义。 - [ ] 实现 facet 粒子力导入。 - [ ] 实现 facet load 关联粒子映射。 - [ ] 对非法 facet id 返回 error。 - [ ] 对 facet 粒子数不匹配返回 error。 - [ ] 对 facet load 非有限值返回 error。 - [ ] 实现目标速度运动边界导入。 - [ ] 实现目标位置或位移运动边界导入。 - [ ] 定义 direct assignment 运动边界模式。 - [ ] 定义 penalty 运动边界模式占位或错误路径。 - [ ] 对运动边界非法 mode 返回 error。 - [ ] 对运动边界非有限目标值返回 error。 - [ ] 对运动边界作用于 inactive 粒子记录跳过计数。 - [ ] 新增 `coupling_particle_force_import_080` 测试。 - [ ] 新增 `coupling_facet_load_import_080` 测试。 - [ ] 新增 `coupling_motion_boundary_080` 测试。 - [ ] 将阶段 D 新测试接入 CTest。 - [ ] 运行阶段 D coupling 导入专项测试。 - [ ] 运行 `git diff --check`。 - [ ] 准备阶段 D 本地提交说明。 ## 阶段 E:显式求解器接入和耦合诊断 - [ ] 定义 coupling 外部力进入总加速度的位置。 - [ ] 定义 coupling 运动边界进入 Velocity-Verlet 的位置。 - [ ] 确认 coupling 外部力缓存独立于 Blast 外载荷缓存。 - [ ] 确认 coupling 外部力和 Blast 外载荷可叠加。 - [ ] 将 coupling 粒子力转换为加速度贡献。 - [ ] 将 coupling facet load 转换为粒子加速度贡献。 - [ ] 将 coupling 加速度贡献接入 Water 粒子路径。 - [ ] 将 coupling 加速度贡献接入 Gas 粒子路径。 - [ ] 将 coupling 加速度贡献接入 Solid 粒子路径。 - [ ] 将 coupling 加速度贡献接入 Shell 粒子平动路径。 - [ ] 确认 coupling 力不改变 Shell director 和 moment 占位状态。 - [ ] 在显式步中施加目标速度运动边界。 - [ ] 在显式步中施加目标位置运动边界。 - [ ] 计算 coupling 当前步总外部力。 - [ ] 计算 coupling 当前步总外部力矩或等价力矩。 - [ ] 计算 coupling 当前步冲量。 - [ ] 计算 coupling 累计冲量。 - [ ] 计算 coupling 当前步做功。 - [ ] 计算 coupling 累计做功。 - [ ] 计算 coupling 动量交换。 - [ ] 计算 coupling 能量交换。 - [ ] 计算 coupling 最大外部力。 - [ ] 计算 coupling 最大加速度贡献。 - [ ] 计算 coupling 最大目标速度误差。 - [ ] 计算 coupling 最大目标位置误差。 - [ ] 记录 coupling stale load 计数。 - [ ] 记录 coupling skipped particle 计数。 - [ ] 记录 coupling nonfinite import 计数。 - [ ] 在步末标记 step-local coupling 载荷已消费。 - [ ] 确认无 active coupling region 时安全跳过。 - [ ] 确认 disabled coupling region 不影响显式步。 - [ ] 确认空导入不产生虚假加速度。 - [ ] 确认 Water-only 回归不被 coupling 路径污染。 - [ ] 确认 Gas-only 回归不被 coupling 路径污染。 - [ ] 确认 Explosive 回归不被 coupling 路径污染。 - [ ] 确认 Solid-only 回归不被 coupling 路径污染。 - [ ] 确认 Shell-only 回归不被 coupling 路径污染。 - [ ] 新增 `coupling_diagnostics_080` 测试。 - [ ] 新增 `coupling_solver_order_080` 测试。 - [ ] 新增 `coupling_solid_response_080` 测试。 - [ ] 新增 `coupling_shell_response_080` 测试。 - [ ] 新增 `coupling_noop_regression_080` 测试。 - [ ] 将阶段 E 新测试接入 CTest。 - [ ] 运行阶段 E coupling 求解器专项测试。 - [ ] 运行 `git diff --check`。 - [ ] 准备阶段 E 本地提交说明。 ## 阶段 F:Output、Restart、Fortran API 和外部接口层 - [ ] 定义 summary CSV 的 coupling 字段清单。 - [ ] 追加 `coupling_regions` summary CSV 字段。 - [ ] 追加 `coupling_particles` summary CSV 字段。 - [ ] 追加 `coupling_facets` summary CSV 字段。 - [ ] 追加 `coupling_force_x/y/z` summary CSV 字段。 - [ ] 追加 `coupling_impulse_x/y/z` summary CSV 字段。 - [ ] 追加 `coupling_work` summary CSV 字段。 - [ ] 追加 `coupling_energy_exchange` summary CSV 字段。 - [ ] 追加 `coupling_nonfinite_imports` summary CSV 字段。 - [ ] 追加 `coupling_stale_loads` summary CSV 字段。 - [ ] 定义粒子 CSV 的 coupling 字段清单。 - [ ] 追加粒子 CSV 的 `coupling_force_x/y/z` 字段。 - [ ] 追加粒子 CSV 的 `coupling_motion_flag` 字段。 - [ ] 追加粒子 CSV 的 `coupling_region_id` 字段。 - [ ] 明确 0.8.0 restart 状态版本名称。 - [ ] 实现 `STATE_0_8` 或等价 0.8 restart 写入。 - [ ] 在 restart 中保存 coupling region 定义和映射。 - [ ] 在 restart 中保存 coupling export/import mode。 - [ ] 在 restart 中保存未消费外部力缓存。 - [ ] 在 restart 中保存未消费 facet load 缓存。 - [ ] 在 restart 中保存未消费运动边界缓存。 - [ ] 在 restart 中保存累计冲量和做功。 - [ ] 在 restart 中保存动量和能量交换诊断。 - [ ] 在 restart 中保存 stale、skipped 和 nonfinite 计数。 - [ ] 实现 `STATE_0_8` 或等价 0.8 restart 读回。 - [ ] 实现 0.7.1 或既有 restart 兼容读入后的空 coupling 状态。 - [ ] 实现 restart 读回后继续显式步的 coupling 状态恢复。 - [ ] 新增 `sph_coupling_get_region_count` Fortran API。 - [ ] 新增 `sph_coupling_get_region_info` Fortran API。 - [ ] 新增 `sph_coupling_export_particles` Fortran API。 - [ ] 新增 `sph_coupling_export_facets` Fortran API。 - [ ] 新增 `sph_coupling_apply_particle_forces` Fortran API。 - [ ] 新增 `sph_coupling_apply_facet_loads` Fortran API。 - [ ] 新增 `sph_coupling_apply_motion_boundary` Fortran API。 - [ ] 新增 `sph_coupling_clear_imports` Fortran API。 - [ ] 新增 `sph_coupling_get_diagnostics` Fortran API。 - [ ] 在 C 头文件中声明 coupling region 查询接口。 - [ ] 在 C 头文件中声明 coupling particle export 接口。 - [ ] 在 C 头文件中声明 coupling facet export 接口。 - [ ] 在 C 头文件中声明 coupling force import 接口。 - [ ] 在 C 头文件中声明 coupling facet load import 接口。 - [ ] 在 C 头文件中声明 coupling motion import 接口。 - [ ] 在 C 头文件中声明 coupling diagnostics 接口。 - [ ] 实现 C ABI 的空指针错误路径。 - [ ] 实现 C ABI 的小容量错误路径。 - [ ] 实现 C ABI 的非法 region 错误路径。 - [ ] 实现 C ABI 的非有限输入错误路径。 - [ ] 在 C++ wrapper 中追加 coupling region 查询薄包装。 - [ ] 在 C++ wrapper 中追加 coupling export 薄包装。 - [ ] 在 C++ wrapper 中追加 coupling import 薄包装。 - [ ] 在 Python ctypes 中追加 coupling region 查询。 - [ ] 在 Python ctypes 中追加 coupling particle export。 - [ ] 在 Python ctypes 中追加 coupling force import。 - [ ] 在 Python ctypes 中追加 coupling diagnostics 查询。 - [ ] 在 CLI inspect 中追加 coupling region 列表字段。 - [ ] 在 CLI inspect 中追加 coupling export/import mode 字段。 - [ ] 在 CLI inspect 中追加 coupling diagnostics 字段。 - [ ] 新增 `coupling_output_080` 测试。 - [ ] 新增 `coupling_restart_080` 测试。 - [ ] 新增 `coupling_restart_071_compat` 测试。 - [ ] 新增 `coupling_fortran_api_080` 测试。 - [ ] 新增 `coupling_c_api_080` 测试。 - [ ] 新增 `coupling_cpp_api_080` 测试。 - [ ] 新增 `coupling_python_080` 测试。 - [ ] 新增 `coupling_cli_080` 测试。 - [ ] 将阶段 F 新测试接入 CTest。 - [ ] 运行阶段 F output、restart 和接口专项测试。 - [ ] 运行 `git diff --check`。 - [ ] 准备阶段 F 本地提交说明。 ## 阶段 G:Mock Coupling Smoke、门禁、文档和发布准备 - [ ] 设计 Solid mock contact coupling smoke 样例。 - [ ] 设计 Shell mock contact coupling smoke 样例。 - [ ] 设计 Solid/Shell 混合 coupling smoke 样例。 - [ ] 设计 disabled coupling region smoke 样例。 - [ ] 设计 no-active coupling region smoke 样例。 - [ ] 设计 stale load 或重复导入 smoke 样例。 - [ ] 新增 Solid mock contact coupling 输入文件。 - [ ] 新增 Shell mock contact coupling 输入文件。 - [ ] 新增 Solid/Shell 混合 coupling 输入文件。 - [ ] 新增 disabled coupling region 输入文件。 - [ ] 新增 no-active coupling region 输入文件。 - [ ] 新增 stale load 或重复导入输入文件。 - [ ] 验证 smoke 中所有粒子状态保持有限。 - [ ] 验证 smoke 中 coupling 外部力方向受控。 - [ ] 验证 smoke 中 coupling 运动边界方向受控。 - [ ] 验证 smoke 中 Solid 响应方向受控。 - [ ] 验证 smoke 中 Shell 平动响应方向受控。 - [ ] 验证 smoke 中冲量和做功诊断有限。 - [ ] 验证 smoke 中动量和能量交换诊断有限。 - [ ] 验证 disabled region 不产生 coupling 响应。 - [ ] 验证 no-active region 不产生 coupling 响应。 - [ ] 验证 stale load 诊断按预期变化。 - [ ] 新增 `coupling_smoke_080` 测试。 - [ ] 新增 `coupling_source_size_080` 测试。 - [ ] 将阶段 G 新测试接入 CTest。 - [ ] 运行 0.8.0 coupling 专项 gate。 - [ ] 运行 Water 回归 gate。 - [ ] 运行 Gas 回归 gate。 - [ ] 运行 Explosive 回归 gate。 - [ ] 运行 Solid 回归 gate。 - [ ] 运行 Shell 回归 gate。 - [ ] 运行 0.7.0 blast 回归 gate。 - [ ] 运行 0.7.1 blast 专项 gate。 - [ ] 运行完整 CTest。 - [ ] 运行 source size 相关 gate。 - [ ] 运行 `git diff --check`。 - [ ] 检查代码、构建脚本、测试和工具目录未新增 FEMLite 直接依赖。 - [ ] 检查输出目录、CSV、VTK、restart 和临时结果未被提交。 - [ ] 更新 README 的 0.8.0 当前状态和不交付范围。 - [ ] 更新 `docs/06_test_and_verification_plan.md` 的 0.8.0 release gate。 - [ ] 更新 `docs/09_release_history.md` 的 0.8.0 本地验收记录。 - [ ] 更新 `docs/11_benchmark_matrix.md` 的 0.8.0 gate 矩阵。 - [ ] 确认文档不宣称真实 FEMLite 联合运行。 - [ ] 确认文档不宣称连续体耦合。 - [ ] 确认文档不宣称工程级船舱破坏 benchmark。 - [ ] 准备 0.8.0 发布提交说明。 - [ ] 准备阶段 G 本地提交说明。