Files
SPHLite/todo.md
T
2026-07-02 21:52:01 +08:00

20 KiB
Raw Blame History

SPHLite TODO

当前目标版本:0.2.0

本文档依据 docs/v2.0_development_plan.md 拆分。0.2.0 是 Water 基础 SPH 最小闭环版本,目标是打通 3D 水相弱可压 SPH 的真实计算链路,不交付 Gas、Explosive、Solid、Shell 生产路径,不交付真实 FEM-SPH 联合运行。

阶段 A:版本和构建骨架

  • 将 sph_precision 中的软件版本更新为 0.2.0。
  • 将 CMake 项目版本更新为 0.2.0。
  • 确认 sphlite_core 仍以 Fortran 95 核心源文件为主。
  • 确认 sphlite_c 仍为 C ABI 薄包装库。
  • 确认 sphlite CLI 仍通过公共接口调用求解器。
  • 在 CMake 中加入 kernel CTest 目标。
  • 在 CMake 中加入 neighbor CTest 目标。
  • 在 CMake 中加入 water_eos CTest 目标。
  • 在 CMake 中加入 water_density CTest 目标。
  • 在 CMake 中加入 water_viscosity CTest 目标。
  • 在 CMake 中加入 water_force CTest 目标。
  • 在 CMake 中加入 solver_water CTest 目标。
  • 在 CMake 中加入 pressure_wave_smoke CTest 目标。
  • 确认 0.1.1 既有测试目标仍保留。
  • 确认不新增 geometry/ 目录。
  • 确认不新增 mesh/ 目录。

阶段 B:0.2.0 输入数据文件

  • 创建最小 Water .inp 测试数据。
  • 创建 Tait EOS 参数完整的 .inp 测试数据。
  • 创建 Monaghan 人工黏性参数完整的 .inp 测试数据。
  • 创建粒子控制参数完整的 .inp 测试数据。
  • 创建 body force 参数测试 .inp。
  • 创建缺失 Tait EOS 参数错误测试 .inp。
  • 创建非法 Tait EOS 参数错误测试 .inp。
  • 创建缺失人工黏性参数错误测试 .inp。
  • 创建非法人工黏性参数错误测试 .inp。
  • 创建非法粒子控制参数错误测试 .inp。
  • 创建非 water phase 被 Water 计算跳过的测试 .inp。
  • 创建小型 3D pressure wave .inp。
  • 确认测试数据不依赖求解器内置几何生成。

阶段 C:Database 运行时状态

  • 确认 particle_id_ext 在 0.2.0 路径中完整初始化。
  • 确认 particle_phase 在 0.2.0 路径中完整初始化。
  • 确认 particle_status 在 0.2.0 路径中完整初始化。
  • 确认 material_id 在 0.2.0 路径中完整初始化。
  • 确认 section_id 在 0.2.0 路径中完整初始化。
  • 确认 x0(3,npart) 在 0.2.0 路径中完整初始化。
  • 确认 x(3,npart) 在 0.2.0 路径中完整初始化。
  • 确认 v(3,npart) 在 0.2.0 路径中完整初始化。
  • 确认 a(3,npart) 在 0.2.0 路径中完整初始化。
  • 确认 vhalf(3,npart) 在 0.2.0 路径中完整初始化。
  • 确认 mass(npart) 在 0.2.0 路径中完整初始化。
  • 确认 rho(npart) 在 0.2.0 路径中完整初始化。
  • 确认 volume(npart) 在 0.2.0 路径中完整初始化。
  • 确认 pressure(npart) 在 0.2.0 路径中完整初始化。
  • 确认 internal_energy(npart) 在 0.2.0 路径中完整初始化。
  • 确认 temperature(npart) 在 0.2.0 路径中完整初始化。
  • 确认 h(npart) 在 0.2.0 路径中完整初始化。
  • 增加 drho_dt(npart) 运行时状态。
  • 增加 acc_pressure(3,npart) 运行时状态。
  • 增加 acc_viscosity(3,npart) 运行时状态。
  • 增加外部体力或等效外载缓存。
  • 增加每粒子 cell id 存储。
  • 增加 cell 链表或压缩索引存储。
  • 增加邻域表或邻域对存储。
  • 增加每粒子邻居数量存储。
  • 增加水相诊断状态存储。
  • 确认 sph_finalize 释放 0.2.0 新增状态。
  • 确认重复 sph_initialize 后新增状态一致。
  • 确认重复读取模型前新增状态被释放。

阶段 D:Water 参数和输入解析

  • 在 input 中识别 water material 类型。
  • 复用 *DENSITY 读取参考密度。
  • 解析 *SPHLITE EOS 关键词。
  • 解析 *SPHLITE EOS 的 TYPE 字段。
  • 解析 *SPHLITE EOS 的 MATERIAL 字段。
  • 解析 *SPHLITE EOS 的 RHO0 字段。
  • 解析 *SPHLITE EOS 的 C0 字段。
  • 解析 *SPHLITE EOS 的 GAMMA 字段。
  • 解析 *SPHLITE EOS 的 P0 字段。
  • 解析 *SPHLITE EOS 的可选 B 字段。
  • 未给定 B 时由 rho0*c0*c0/gamma 推导。
  • 解析 *SPHLITE VISCOSITY 关键词。
  • 解析 *SPHLITE VISCOSITY 的 TYPE 字段。
  • 解析 *SPHLITE VISCOSITY 的 MATERIAL 字段。
  • 解析 *SPHLITE VISCOSITY 的 ALPHA 字段。
  • 解析 *SPHLITE VISCOSITY 的 BETA 字段。
  • 解析 *SPHLITE VISCOSITY 的 ETA2 字段。
  • 解析 *SPHLITE PARTICLE CONTROL 关键词。
  • 解析统一光滑长度 H 或等价字段。
  • 解析统一粒子质量 MASS 或等价字段。
  • 解析统一粒子体积 VOLUME 或等价字段。
  • 解析 *SPHLITE BODY FORCE 关键词。
  • 解析体力三维分量。
  • 对缺失 Tait EOS 关键字段报 error。
  • 对非法 Tait EOS 数值报 error。
  • 对缺失人工黏性关键字段报 error。
  • 对非法人工黏性数值报 error。
  • 对非法粒子控制数值报 error。
  • 对不影响运行的未知 Water 关键词报 warning。
  • 确认输入错误消息包含文件名。
  • 确认输入错误消息包含行号。

阶段 E:Kernel 模块

  • 创建 Particle 核函数模块文件。
  • 定义核函数类型常量。
  • 定义 Wendland C2 类型常量。
  • 定义 Wendland C4 类型常量。
  • 定义 cubic spline 类型常量。
  • 实现核函数支持半径查询。
  • 实现 Wendland C2 核函数值。
  • 实现 Wendland C2 核函数梯度。
  • 实现 Wendland C4 核函数值。
  • 实现 Wendland C4 核函数梯度。
  • 实现 cubic spline 核函数值。
  • 实现 cubic spline 核函数梯度。
  • 支持 3D 归一化系数。
  • 支持每粒子独立 h(i) 传入。
  • 对 h <= 0 返回明确错误。
  • 对未知核函数类型返回明确错误。
  • 将 Wendland C2 设置为默认核函数。
  • 增加 r = 0 核函数有限性测试。
  • 增加超出支持半径测试。
  • 增加梯度方向测试。
  • 增加梯度反对称性测试。
  • 增加不同 h(i) 测试。

阶段 F:Neighbor 模块

  • 创建 uniform cell/bin 邻域模块文件。
  • 实现当前坐标包围盒计算。
  • 实现最大支持半径计算。
  • 根据最大支持半径确定 cell 尺寸。
  • 实现 cell 网格维度计算。
  • 实现粒子到 cell 的映射。
  • 实现 cell 链表或压缩索引构建。
  • 实现相邻 cell 遍历。
  • 实现邻域表生成。
  • 支持每粒子独立 h(i) 的搜索半径。
  • 支持空模型邻域构建。
  • 支持单粒子模型邻域构建。
  • 支持负坐标粒子邻域构建。
  • 支持边界 cell 粒子邻域构建。
  • 支持粒子移动后重建邻域。
  • 对邻域表容量不足返回明确错误。
  • 增加朴素 O(n^2) 对比测试辅助例程。
  • 增加 uniform cell/bin 与朴素搜索一致性测试。
  • 增加不同 h(i) 邻域测试。
  • 增加空模型邻域测试。
  • 增加单粒子邻域测试。
  • 增加粒子移动后重建测试。
  • 增加负坐标和边界 cell 测试。
  • 增加邻域容量不足错误路径测试。

阶段 G:Water EOS 和诊断

  • 创建或完善 Water 参数存储模块。
  • 保存 Tait EOS 的 rho0。
  • 保存 Tait EOS 的 c0。
  • 保存 Tait EOS 的 gamma。
  • 保存 Tait EOS 的 p0。
  • 保存 Tait EOS 的 B。
  • 保存人工黏性 alpha。
  • 保存人工黏性 beta。
  • 保存人工黏性 eta2。
  • 保存 body force 三维分量。
  • 实现 Tait EOS 压力计算。
  • 实现 Tait EOS 声速或声速占位计算。
  • 实现 Tait EOS 参数校验。
  • 实现 water phase 粒子筛选。
  • 实现非 water phase 默认跳过。
  • 实现水相粒子数诊断。
  • 实现水相总质量诊断。
  • 实现水相总动量诊断。
  • 实现水相最大压力诊断。
  • 实现水相最小密度诊断。
  • 实现水相最大密度诊断。
  • 实现压力冲量占位诊断。
  • 增加 Tait EOS 标准压力测试。
  • 增加 Tait EOS 参考密度零压测试。
  • 增加 Tait EOS 非法参数测试。
  • 增加 water summary 诊断测试。

阶段 H:Water 连续性方程

  • 创建或完善 Water 密度计算入口。
  • 初始化 drho_dt 数组。
  • 基于邻域表遍历 water-water 粒子对。
  • 计算粒子相对速度。
  • 计算核函数梯度。
  • 累加连续性方程密度变化率。
  • 保持 summation density 不进入主流程。
  • 对非 water 粒子跳过密度贡献。
  • 对失效或 inactive 粒子按 status 跳过。
  • 增加双粒子压缩密度变化测试。
  • 增加双粒子拉伸密度变化测试。
  • 增加静止均匀粒子密度变化近零测试。
  • 增加非 water 粒子跳过测试。
  • 增加 drho_dt 有限性测试。

阶段 I:Water 人工黏性和力

  • 创建或完善 Water 人工黏性计算入口。
  • 实现 Monaghan 人工黏性开关条件。
  • 实现人工黏性平均声速计算。
  • 实现人工黏性平均密度计算。
  • 实现人工黏性 mu_ij 计算。
  • 实现人工黏性加速度贡献。
  • 对远离粒子返回零人工黏性。
  • 创建或完善 Water 压力力计算入口。
  • 实现 SPH 压力梯度加速度。
  • 累加 acc_pressure(3,npart)。
  • 累加 acc_viscosity(3,npart)。
  • 将 body force 加入总加速度。
  • 将外部耦合载荷占位加入总加速度。
  • 对非 water 粒子跳过水相力贡献。
  • 增加人工黏性方向测试。
  • 增加人工黏性有限性测试。
  • 增加人工黏性对称性测试。
  • 增加压力梯度双粒子测试。
  • 增加均匀压力净力近零测试。
  • 增加 body force 加速度测试。

阶段 J:Solver Water 集成

  • 在 build model 中构建 Water 运行时状态。
  • 在 build model 中构建邻域搜索状态。
  • 在显式步开始前校验 Water 参数。
  • 在显式步中必要时重建邻域。
  • 在显式步中根据 rho 更新 pressure。
  • 在显式步中计算 drho_dt。
  • 在显式步中计算水相压力加速度。
  • 在显式步中计算水相黏性加速度。
  • 在显式步中合成总加速度。
  • 在 Velocity-Verlet 中更新速度。
  • 在 Velocity-Verlet 中更新位置。
  • 在 Velocity-Verlet 中更新密度。
  • 在 Velocity-Verlet 中更新时间和步数。
  • 在显式步结束后更新 Water 诊断。
  • 在显式运行中按输出间隔写出结果。
  • 对负时间步保持明确错误。
  • 对零时间步保持明确错误。
  • 对未 build model 的显式步返回明确错误。
  • 增加单步 Water 推进测试。
  • 增加多步 Water 推进测试。
  • 增加 sph_run_explicit Water 闭环测试。

阶段 K:稳定时间步估计

  • 实现水相 CFL 声速约束估计。
  • 实现加速度约束估计。
  • 实现人工黏性约束估计。
  • 应用输入安全系数。
  • 保存 dt_cfl 诊断。
  • 保存 dt_accel 诊断。
  • 保存 dt_viscous 诊断。
  • 将三类约束最小值返回为 dtcrit。
  • 对无 water 粒子时返回明确策略。
  • 对非法 h 或声速返回明确错误。
  • 增加 CFL 约束测试。
  • 增加加速度约束测试。
  • 增加人工黏性约束测试。
  • 增加安全系数测试。

阶段 L:Output 和 Restart

  • 确认 CSV 输出包含 id 字段。
  • 确认 CSV 输出包含 phase 字段。
  • 确认 CSV 输出包含 status 字段。
  • 确认 CSV 输出包含 material 字段。
  • 确认 CSV 输出包含 section 字段。
  • 确认 CSV 输出包含坐标字段。
  • 确认 CSV 输出包含速度字段。
  • 确认 CSV 输出包含 rho 字段。
  • 确认 CSV 输出包含 pressure 字段。
  • 确认 CSV 输出包含 temperature 字段。
  • 确认 CSV 输出包含 h 字段。
  • 增加 Water summary 输出或诊断写出入口。
  • 输出 step 诊断。
  • 输出 time 诊断。
  • 输出 water mass 诊断。
  • 输出 water momentum 诊断。
  • 输出 max pressure 诊断。
  • 输出 min/max density 诊断。
  • 输出 dtcrit 诊断。
  • 扩展 restart 头部状态版本到 0.2。
  • restart 写入 Water EOS 参数。
  • restart 写入人工黏性参数。
  • restart 写入 body force 参数。
  • restart 写入密度状态。
  • restart 写入压力状态。
  • restart 写入 h 状态。
  • restart 写入速度、加速度和半步速度。
  • restart 写入邻域搜索控制参数。
  • restart 写入 Water 诊断状态。
  • restart 读入后重建邻域。
  • restart 读入后继续执行 Water 显式步。
  • 增加 0.2.0 output 测试。
  • 增加 0.2.0 restart 测试。

阶段 M:Fortran API

  • 实现 sph_rebuild_neighbors。
  • 实现 sph_get_neighbor_stats。
  • 实现 sph_get_water_summary。
  • 实现 sph_get_water_dt_limits。
  • 确认生命周期 API 兼容 0.1.1。
  • 确认 .inp 读取 API 兼容 0.1.1。
  • 确认 build model API 兼容 0.1.1。
  • 确认 stable dt API 兼容 0.1.1。
  • 确认 advance/run explicit API 兼容 0.1.1。
  • 确认 current time API 兼容 0.1.1。
  • 确认 particle count/state API 兼容 0.1.1。
  • 确认 output/restart API 兼容 0.1.1。
  • 确认 error query API 兼容 0.1.1。
  • 为新增 Fortran API 增加未初始化错误路径。
  • 为新增 Fortran API 增加空模型错误路径。
  • 为新增 Fortran API 增加正常路径测试。

阶段 N:C ABI、C++ 和 Python

  • 在 C 头文件中声明 sphlite_get_water_summary。
  • 在 C 头文件中声明 sphlite_get_water_dt_limits。
  • 在 C wrapper 中桥接 sphlite_get_water_summary。
  • 在 C wrapper 中桥接 sphlite_get_water_dt_limits。
  • 为 sphlite_get_water_summary 检查空指针。
  • 为 sphlite_get_water_dt_limits 检查空指针。
  • 确认 C 参数错误返回 -1。
  • 确认 Fortran 错误码原样返回 C 调用方。
  • 在 C++ wrapper 中包装 water summary。
  • 在 C++ wrapper 中包装 water dt limits。
  • 在 C++ 测试中覆盖 water summary。
  • 在 C++ 测试中覆盖 water dt limits。
  • 在 Python wrapper 中包装 water summary。
  • 在 Python wrapper 中包装 water dt limits。
  • 在 Python wrapper 中扩展 inspect 辅助函数。
  • 在 Python wrapper 中扩展 run 辅助函数。
  • 在 Python 测试中覆盖 water summary。
  • 在 Python 测试中覆盖 water dt limits。
  • 在 Python 测试中覆盖缺失 Water 参数错误。
  • 确认 C ABI、C++ 和 Python 不重新定义物理语义。

阶段 O:CLI

  • 保持 sphlite --version 可用。
  • 保持 sphlite model.inp inspect 模式可用。
  • 保持 sphlite model.inp --check 模式可用。
  • 保持 sphlite model.inp --run 模式可用。
  • 保持 sphlite model.inp --run --output output 可用。
  • CLI 输出 version 字段。
  • CLI 输出 input 字段。
  • CLI 输出 mode 字段。
  • CLI 输出 particles 字段。
  • CLI 输出 warnings 字段。
  • CLI 输出 time 字段。
  • CLI 输出 step 字段。
  • CLI 输出 status 字段。
  • CLI 输出 water_particles 字段。
  • CLI 输出 water_mass 字段。
  • CLI 输出 max_pressure 字段。
  • CLI 输出 dtcrit 字段。
  • CLI 错误时打印最近错误码。
  • CLI 错误时打印最近错误消息。
  • 确认 CLI 不绕过公共生命周期接口。
  • 增加 0.2.0 CLI inspect 测试。
  • 增加 0.2.0 CLI check 测试。
  • 增加 0.2.0 CLI run 测试。
  • 增加 0.2.0 CLI output 测试。
  • 增加 0.2.0 CLI 错误输入测试。

阶段 P:CouplingInterface 最小加固

  • 确认 Water 运行后 coupling particle count 可用。
  • 确认 Water 运行后 coupling particle 导出可用。
  • 确认 coupling particle 导出包含 pressure。
  • 确认 coupling particle 导出包含 phase。
  • 确认 coupling particle 导出包含 material。
  • 确认外部粒子力导入接口仍可用。
  • 将外部粒子力导入接入显式步外载占位。
  • 继续记录 coupling work 占位。
  • 继续记录 coupling momentum 占位。
  • 继续记录 coupling energy 占位。
  • 保持接触耦合类型字段。
  • 保持连续体耦合类型字段。
  • 确认接口命名不出现 FEMLite 内部结构。
  • 确认默认 gate 不运行真实 FEM-SPH 联合测试。
  • 扩展 coupling_interface 测试覆盖 Water 运行后状态。

阶段 Q:Pressure Wave Smoke

  • 确定 pressure wave smoke 的最小粒子布置。
  • 确定 pressure wave smoke 的初始压力扰动。
  • 确定 pressure wave smoke 的运行步数。
  • 确定 pressure wave smoke 的 checker 阈值。
  • 实现 pressure wave smoke 输入文件。
  • 实现 pressure wave smoke 运行脚本或测试程序。
  • 检查 pressure wave smoke 输出有限性。
  • 检查 pressure wave smoke 压力扰动传播方向。
  • 检查 pressure wave smoke 质量趋势。
  • 检查 pressure wave smoke 动量趋势。
  • 检查 pressure wave smoke 输出字段。
  • 确认 pressure wave smoke 不作为工程精度 benchmark。
  • 确认 pressure wave smoke 保持小规模。
  • 将 pressure wave smoke 纳入默认 gate。

阶段 R:Source Size 和测试门禁

  • 确认 source size 覆盖 Fortran 文件。
  • 确认 source size 覆盖 C 文件。
  • 确认 source size 覆盖 C++ 头文件。
  • 确认 source size 覆盖 Python 文件。
  • 为新增大文件登记必要例外。
  • 确认 stale exception 检查有效。
  • 运行 kernel 测试。
  • 运行 neighbor 测试。
  • 运行 water_eos 测试。
  • 运行 water_density 测试。
  • 运行 water_viscosity 测试。
  • 运行 water_force 测试。
  • 运行 solver_water 测试。
  • 运行 pressure_wave_smoke 测试。
  • 运行 0.1.1 既有接口测试。
  • 运行 source_size 测试。
  • 运行 git diff --check。

阶段 S:文档同步

  • 更新 README 当前版本为 0.2.0。
  • 更新 README 的 0.2.0 实际能力说明。
  • 记录 0.2.0 交付 Water 基础弱可压 SPH。
  • 记录 0.2.0 不交付 Gas 生产路径。
  • 记录 0.2.0 不交付 Explosive 生产路径。
  • 记录 0.2.0 不交付 Solid 生产路径。
  • 记录 0.2.0 不交付 Shell 生产路径。
  • 记录 0.2.0 不交付真实 FEM-SPH 联合运行。
  • 更新 docs/09_release_history.md 的 0.2.0 条目。
  • 更新 docs/11_benchmark_matrix.md 的 0.2.0 gate。
  • 确认 01-06 文档与 0.2.0 实际能力不冲突。
  • 确认文档使用 UTF-8 without BOM。
  • 确认文档不宣称已实现完整水下爆炸。
  • 确认文档不宣称已实现生产级多物理耦合。

阶段 T:0.2.0 验收

  • 完整配置 CMake。
  • 完整编译 sphlite_core。
  • 完整编译 sphlite_c。
  • 完整编译 sphlite。
  • 完整编译新增 Fortran 测试目标。
  • 完整编译新增 C/C++ 测试目标。
  • 运行 ctest -R "^(smoke|input|kernel|neighbor|water_eos|water_density|water_viscosity|water_force|solver_water|output|restart|c_api|cpp_api|python_debug|cli|pressure_wave_smoke)$"。
  • 运行 ctest -R "^source_size$"。
  • 运行 git diff --check。
  • 确认没有提交 build 目录。
  • 确认没有提交 Python 缓存。
  • 确认没有提交 CSV 临时结果。
  • 确认没有提交 VTK 临时结果。
  • 确认没有提交 restart 临时结果。
  • 确认没有残留旧模块命名。
  • 确认没有新增 FEMLite 源码依赖。
  • 确认没有新增几何生成能力。
  • 确认没有新增网格生成能力。
  • 记录 0.2.0 release gate 结果。