Files
SPHLite/todo.md
T
2026-07-04 09:22:46 +08:00

351 lines
18 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
当前目标版本: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 输入语义和运行时表
- [x] 复核现有 `*SPHLITE COUPLING REGION` 关键词字段。
- [x] 定义 `TYPE=CONTACT` 为 0.8.0 唯一启用耦合类型。
- [x] 定义 `TYPE=CONTINUUM` 的预留错误路径。
- [x] 定义 coupling region 名称唯一性规则。
- [x] 定义 `EXPORT=PARTICLE` 的输入语义。
- [x] 定义 `EXPORT=FACET` 的输入语义。
- [x] 定义 `EXPORT=BOTH` 的输入语义。
- [x] 定义 `IMPORT=FORCE` 的输入语义。
- [x] 定义 `IMPORT=FACET_LOAD` 的输入语义。
- [x] 定义 `IMPORT=MOTION` 的输入语义。
- [x] 定义 `ENABLED` 字段的默认值和布尔解析规则。
- [x] 支持读取 coupling region 的 `NAME` 字段。
- [x] 支持读取 coupling region 的 `TYPE` 字段。
- [x] 支持读取 coupling region 的 `SET` 字段。
- [x] 支持读取 coupling region 的 `SURFACE` 字段占位。
- [x] 支持读取 coupling region 的 `PHASE` 过滤字段。
- [x] 支持读取 coupling region 的 `MATERIAL` 过滤字段。
- [x] 支持读取 coupling region 的 `SECTION` 过滤字段。
- [x] 支持读取 coupling region 的 `EXPORT` 字段。
- [x] 支持读取 coupling region 的 `IMPORT` 字段。
- [x] 支持读取 coupling region 的 `ENABLED` 字段。
- [x] 对空 region 名称报 error。
- [x] 对重复 region 名称报 error。
- [x] 对非法 `TYPE` 报 error。
- [x] 对非法 `EXPORT` 报 error。
- [x] 对非法 `IMPORT` 报 error。
- [x] 对非法 `ENABLED` 报 error。
- [x] 对缺失或不存在的 `SET` 报 error。
- [x] 对无法选中粒子的 active region 报 error。
- [x] 对 disabled region 保留输入记录但不参与导出。
- [x] 保持 `tests/data/coupling_region_011.inp` 兼容。
- [x] 在数据库中保存 region type、export mode、import mode 和 enabled 状态。
- [x] 在数据库中保存 region set、surface、phase、material 和 section 过滤条件。
- [x] 建立运行时 region 内部 id。
- [x] 建立运行时 region 粒子索引表。
- [x] 建立运行时 region active 粒子计数。
- [x] 建立运行时 region 禁用状态计数。
- [x] 确认 coupling region 构建不污染 Blast region。
- [x] 确认 coupling region 构建不污染 Gas source region。
- [x] 新增 `input_coupling_region_080` 测试。
- [x] 新增 `input_coupling_errors_080` 测试。
- [x] 新增 `coupling_region_build_080` 测试。
- [x] 将阶段 B 新测试接入 CTest。
- [x] 运行阶段 B coupling 输入专项测试。
- [x] 运行 `git diff --check`。
- [x] 准备阶段 B 本地提交说明。
## 阶段 C:粒子导出和 Facet Proxy 导出
- [x] 定义 coupling 粒子导出字段顺序。
- [x] 定义 coupling 粒子 scalar 缓冲区字段顺序。
- [x] 定义 coupling 粒子三维数组展开顺序。
- [x] 实现按 region 查询 coupling 粒子数量。
- [x] 实现按 region 导出 external particle id。
- [x] 实现按 region 导出 internal particle index。
- [x] 实现按 region 导出 particle phase。
- [x] 实现按 region 导出 particle status。
- [x] 实现按 region 导出 material id。
- [x] 实现按 region 导出 section id。
- [x] 实现按 region 导出 mass。
- [x] 实现按 region 导出 volume。
- [x] 实现按 region 导出 density。
- [x] 实现按 region 导出 pressure。
- [x] 实现按 region 导出 internal energy。
- [x] 实现按 region 导出 temperature。
- [x] 实现按 region 导出 smoothing length `h`。
- [x] 实现按 region 导出 position `x`。
- [x] 实现按 region 导出 velocity `v`。
- [x] 实现按 region 导出 acceleration `a`。
- [x] 对非法 region 名称返回 error。
- [x] 对 disabled region 返回 0 个导出粒子。
- [x] 对调用方容量不足返回 error。
- [x] 对非有限导出状态记录诊断或返回 error。
- [x] 定义 facet proxy 导出字段顺序。
- [x] 定义 facet proxy 三维数组展开顺序。
- [x] 实现 Shell coupling region 的 facet proxy 计数。
- [x] 实现 Shell facet proxy 的 facet id。
- [x] 实现 Shell facet proxy 的关联粒子 id。
- [x] 实现 Shell facet proxy 的中心坐标。
- [x] 实现 Shell facet proxy 的平均速度。
- [x] 实现 Shell facet proxy 的法向。
- [x] 实现 Shell facet proxy 的面积。
- [x] 实现 Shell facet proxy 的 material 和 section 信息。
- [x] 支持受控 surface/facet 输入的 facet proxy 占位导出。
- [x] 明确 Solid 无 surface 时不自动重构复杂外表面。
- [x] 对 `EXPORT=FACET` 但无 facet proxy 的 region 报 error。
- [x] 对零面积 facet proxy 报 error。
- [x] 对非有限法向或面积报 error。
- [x] 新增 `coupling_particle_export_080` 测试。
- [x] 新增 `coupling_facet_export_080` 测试。
- [x] 新增 `coupling_facet_errors_080` 测试。
- [x] 将阶段 C 新测试接入 CTest。
- [x] 运行阶段 C coupling 导出专项测试。
- [x] 运行 `git diff --check`。
- [x] 准备阶段 C 本地提交说明。
## 阶段 D:外部粒子力、Facet Load 和运动边界导入
- [x] 设计 coupling 外部粒子力缓存数组。
- [x] 设计 coupling facet load 缓存数组或分配后粒子力缓存。
- [x] 设计 coupling 运动边界缓存数组。
- [x] 设计 coupling step 或 epoch 状态。
- [x] 设计 stale load 计数状态。
- [x] 设计 skipped particle 计数状态。
- [x] 设计 nonfinite import 计数状态。
- [x] 在初始化阶段分配 coupling 导入缓存。
- [x] 在 finalize 阶段释放 coupling 导入缓存。
- [x] 在模型重建阶段清空 coupling 导入缓存。
- [x] 实现按 external particle id 导入粒子力。
- [x] 实现按 region export index 导入粒子力。
- [x] 对非法 region 导入返回 error。
- [x] 对非法粒子 id 导入返回 error。
- [x] 对 disabled region 导入返回 error。
- [x] 对非有限 force 导入返回 error 并记录计数。
- [x] 对质量非正粒子导入返回 error。
- [x] 对 inactive 粒子导入执行跳过并记录计数。
- [x] 对 failed Solid 粒子导入执行受控跳过或受控接受。
- [x] 对 failed Shell 粒子导入执行受控跳过或受控接受。
- [x] 实现同一 epoch 内粒子力累加语义。
- [x] 实现新 epoch 自动清零或显式清零语义。
- [x] 实现 facet 粒子力导入。
- [x] 实现 facet load 关联粒子映射。
- [x] 对非法 facet id 返回 error。
- [x] 对 facet 粒子数不匹配返回 error。
- [x] 对 facet load 非有限值返回 error。
- [x] 实现目标速度运动边界导入。
- [x] 实现目标位置或位移运动边界导入。
- [x] 定义 direct assignment 运动边界模式。
- [x] 定义 penalty 运动边界模式占位或错误路径。
- [x] 对运动边界非法 mode 返回 error。
- [x] 对运动边界非有限目标值返回 error。
- [x] 对运动边界作用于 inactive 粒子记录跳过计数。
- [x] 新增 `coupling_particle_force_import_080` 测试。
- [x] 新增 `coupling_facet_load_import_080` 测试。
- [x] 新增 `coupling_motion_boundary_080` 测试。
- [x] 将阶段 D 新测试接入 CTest。
- [x] 运行阶段 D coupling 导入专项测试。
- [x] 运行 `git diff --check`。
- [x] 准备阶段 D 本地提交说明。
## 阶段 E:显式求解器接入和耦合诊断
- [x] 定义 coupling 外部力进入总加速度的位置。
- [x] 定义 coupling 运动边界进入 Velocity-Verlet 的位置。
- [x] 确认 coupling 外部力缓存独立于 Blast 外载荷缓存。
- [x] 确认 coupling 外部力和 Blast 外载荷可叠加。
- [x] 将 coupling 粒子力转换为加速度贡献。
- [x] 将 coupling facet load 转换为粒子加速度贡献。
- [x] 将 coupling 加速度贡献接入 Water 粒子路径。
- [x] 将 coupling 加速度贡献接入 Gas 粒子路径。
- [x] 将 coupling 加速度贡献接入 Solid 粒子路径。
- [x] 将 coupling 加速度贡献接入 Shell 粒子平动路径。
- [x] 确认 coupling 力不改变 Shell director 和 moment 占位状态。
- [x] 在显式步中施加目标速度运动边界。
- [x] 在显式步中施加目标位置运动边界。
- [x] 计算 coupling 当前步总外部力。
- [x] 计算 coupling 当前步总外部力矩或等价力矩。
- [x] 计算 coupling 当前步冲量。
- [x] 计算 coupling 累计冲量。
- [x] 计算 coupling 当前步做功。
- [x] 计算 coupling 累计做功。
- [x] 计算 coupling 动量交换。
- [x] 计算 coupling 能量交换。
- [x] 计算 coupling 最大外部力。
- [x] 计算 coupling 最大加速度贡献。
- [x] 计算 coupling 最大目标速度误差。
- [x] 计算 coupling 最大目标位置误差。
- [x] 记录 coupling stale load 计数。
- [x] 记录 coupling skipped particle 计数。
- [x] 记录 coupling nonfinite import 计数。
- [x] 在步末标记 step-local coupling 载荷已消费。
- [x] 确认无 active coupling region 时安全跳过。
- [x] 确认 disabled coupling region 不影响显式步。
- [x] 确认空导入不产生虚假加速度。
- [x] 确认 Water-only 回归不被 coupling 路径污染。
- [x] 确认 Gas-only 回归不被 coupling 路径污染。
- [x] 确认 Explosive 回归不被 coupling 路径污染。
- [x] 确认 Solid-only 回归不被 coupling 路径污染。
- [x] 确认 Shell-only 回归不被 coupling 路径污染。
- [x] 新增 `coupling_diagnostics_080` 测试。
- [x] 新增 `coupling_solver_order_080` 测试。
- [x] 新增 `coupling_solid_response_080` 测试。
- [x] 新增 `coupling_shell_response_080` 测试。
- [x] 新增 `coupling_noop_regression_080` 测试。
- [x] 将阶段 E 新测试接入 CTest。
- [x] 运行阶段 E coupling 求解器专项测试。
- [x] 运行 `git diff --check`。
- [x] 准备阶段 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 本地提交说明。