Files
SPHLite/todo.md
T
2026-07-02 23:53:17 +08:00

21 KiB
Raw Blame History

SPHLite TODO

当前目标版本:0.2.1

本文档依据 docs/v2.1_development_plan.md 拆分。0.2.1 是 Water 加固版本,目标是增强 0.2.0 已有水相弱可压 SPH 路径的可靠性、可验证性和接口一致性,不交付 Gas、Explosive、Solid、Shell 生产路径,不交付真实 FEM-SPH 联合运行,不新增几何、网格或粒子生成能力。

阶段 A:版本和基线检查

  • 将 sph_precision 中的软件版本更新为 0.2.1。
  • 将 CMake 项目版本更新为 0.2.1。
  • 更新 CLI --version 的版本期望。
  • 更新 Fortran smoke 测试中的版本期望。
  • 更新 C API 测试中的版本期望。
  • 更新 C++ API 测试中的版本期望。
  • 更新 Python debug 测试中的版本期望。
  • 确认 sphlite_core 仍以 Fortran 95 核心源文件为主。
  • 确认 sphlite_c 仍为 C ABI 薄封装库。
  • 确认 sphlite_c_shared 仍可构建。
  • 确认 sphlite CLI 仍通过公共接口调用求解器。
  • 确认不新增 geometry/ 目录。
  • 确认不新增 mesh/ 目录。
  • 确认不新增粒子生成器作为求解器功能。
  • 跑通 0.2.0 发布状态的默认 gate。
  • 跑通 source_size 门禁。
  • 跑通 git diff --check。
  • 记录 0.2.1 基线检查结果。

基线检查记录(2026-07-02):0.2.1 版本号迁移后,cmake --build build-codex-unix 通过;默认 ctest 18/18 通过;单独 source_size 通过;git diff --check 通过;未新增 geometry/、mesh/ 或粒子生成器目录。

阶段 B:0.2.1 输入测试数据

  • 创建 0.2.1 Water 最小合法输入文件。
  • 创建 Water material 大小写兼容测试输入文件。
  • 创建 Water material 缺少 *DENSITY 的错误输入文件。
  • 创建 *SECTION 指向不存在 material 的错误输入文件。
  • 创建缺失 *SPHLITE EOS, TYPE 的错误输入文件。
  • 创建缺失 *SPHLITE EOS, MATERIAL 的错误输入文件。
  • 创建缺失 *SPHLITE EOS, RHO0 的错误输入文件。
  • 创建缺失 *SPHLITE EOS, C0 的错误输入文件。
  • 创建缺失 *SPHLITE EOS, GAMMA 的错误输入文件。
  • 创建非法 *SPHLITE EOS, B 的错误输入文件。
  • 创建非 TYPE=TAIT 的 EOS 类型测试输入文件。
  • 创建缺失 *SPHLITE VISCOSITY 字段的错误输入文件。
  • 创建非法 *SPHLITE VISCOSITY 数值的错误输入文件。
  • 创建非法 *SPHLITE PARTICLE CONTROL 数值的错误输入文件。
  • 创建非法 *SPHLITE BODY FORCE 字段的错误输入文件。
  • 创建非法 *SPHLITE TIME CONTROL 数值的错误输入文件。
  • 创建未知但不影响运行的 *SPHLITE warning 输入文件。
  • 创建重复坐标 Water 粒子输入文件。
  • 创建稀疏 Water 粒子输入文件。
  • 创建非共线 3D pressure wave 输入文件。

阶段 C:输入解析加固

  • 加固 *MATERIAL, TYPE=WATER 大小写解析。
  • 加固 Water material 与 *DENSITY 的绑定校验。
  • 加固 *SECTION material 引用存在性校验。
  • 加固 set 只作为集合、不作为类型判断的测试。
  • 加固 *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 推导。
  • 明确非 TYPE=TAIT 的 EOS 处理策略。
  • 加固 *SPHLITE VISCOSITY 的 TYPE 字段校验。
  • 加固 *SPHLITE VISCOSITY 的 MATERIAL 字段校验。
  • 加固 *SPHLITE VISCOSITY 的 ALPHA 字段校验。
  • 加固 *SPHLITE VISCOSITY 的 BETA 字段校验。
  • 加固 *SPHLITE VISCOSITY 的 ETA2 字段校验。
  • 加固 *SPHLITE PARTICLE CONTROL 的 H 正值校验。
  • 加固 *SPHLITE PARTICLE CONTROL 的 MASS 正值校验。
  • 加固 *SPHLITE PARTICLE CONTROL 的 VOLUME 正值校验。
  • 加固 *SPHLITE BODY FORCE 三维分量解析。
  • 加固 *SPHLITE TIME CONTROL 的 DT 正值校验。
  • 加固 *SPHLITE TIME CONTROL 的 TIME 正值校验。
  • 加固 *SPHLITE TIME CONTROL 的 STEPS 正值校验。
  • 加固 *SPHLITE TIME CONTROL 的 SAFETY 正值校验。
  • 确认 unsupported-but-safe 关键词报 warning。
  • 确认无法运行的缺失关键词报 error。
  • 确认输入错误消息包含文件名。
  • 确认输入错误消息包含行号或定位上下文。

阶段 D:Database 状态一致性

  • 确认 particle_id_ext 在 build 后稳定。
  • 确认 particle_id_ext 在 restart 读回后稳定。
  • 确认 particle_phase 在 build 后一致。
  • 确认 particle_status 在 build 后一致。
  • 确认 material_id 在 build 后一致。
  • 确认 section_id 在 build 后一致。
  • 确认 x0(3,npart) 初始化路径一致。
  • 确认 x(3,npart) 初始化路径一致。
  • 确认 v(3,npart) 初始化路径一致。
  • 确认 a(3,npart) 初始化路径一致。
  • 确认 vhalf(3,npart) 初始化路径一致。
  • 确认 mass(npart) 初始化路径一致。
  • 确认 rho(npart) 初始化路径一致。
  • 确认 volume(npart) 初始化路径一致。
  • 确认 pressure(npart) 初始化路径一致。
  • 确认 temperature(npart) 初始化路径一致。
  • 确认 h(npart) 初始化路径一致。
  • 确认 drho_dt 每步计算前正确重置。
  • 确认 acc_pressure 每步计算前正确重置。
  • 确认 acc_viscosity 每步计算前正确重置。
  • 确认 acc_body 保留或重置策略明确。
  • 确认 Water 诊断在 build 后可重复计算。
  • 确认 Water 诊断在 advance 后可重复计算。
  • 确认 Water 诊断在 restart read 后可重复计算。
  • 确认非 Water 粒子仍可通过通用查询导出。
  • 确认 inactive 粒子不参与 Water 相互作用。
  • 确认重复 sph_initialize 后状态干净。
  • 确认重复读取模型前旧状态被释放。

阶段 E:Kernel 加固

  • 加固 Wendland C2 的 h <= 0 错误路径。
  • 加固 Wendland C4 的 h <= 0 错误路径。
  • 加固 cubic spline 的 h <= 0 错误路径。
  • 加固未知 kernel type 错误路径。
  • 加固 r = 0 时核函数值有限。
  • 加固 r = 0 时核函数梯度为零向量。
  • 加固接近支持半径时核函数值有限。
  • 加固接近支持半径时核函数梯度有限。
  • 加固超出支持半径时 W = 0。
  • 加固超出支持半径时 grad W = 0。
  • 加固对称粒子对梯度反对称。
  • 加固不同 h(i) 的核函数结果有限。
  • 确认默认 kernel 仍为 Wendland C2。
  • 确认 kernel 测试不变成长跑积分 benchmark。

阶段 F:Neighbor 加固

  • 加固空模型邻域构建。
  • 加固单粒子邻域构建。
  • 加固双粒子支持半径内判定。
  • 加固双粒子支持半径外判定。
  • 加固支持半径边界附近判定。
  • 加固重复坐标粒子的邻域构建。
  • 加固极近坐标粒子的邻域构建。
  • 加固负坐标粒子的邻域构建。
  • 加固稀疏粒子的包围盒计算。
  • 加固稀疏粒子的 cell 维度控制。
  • 加固不同 h(i) 对搜索半径的影响。
  • 加固粒子移动后邻域重建。
  • 加固邻域容量不足错误路径。
  • 加固 naive O(n^2) 对比辅助检查。
  • 加固 neighbor stats 最大邻居数。
  • 加固 neighbor stats 平均邻居数。
  • 确认 neighbor 测试保持小规模。

阶段 G:Water EOS 加固

  • 加固 rho = rho0 时压力接近 p0。
  • 加固 rho > rho0 时压力单调增加。
  • 明确 rho < rho0 时负压策略。
  • 为当前负压策略增加测试。
  • 加固 rho <= 0 错误路径。
  • 加固 rho0 <= 0 错误路径。
  • 加固 c0 <= 0 错误路径。
  • 加固 gamma <= 0 错误路径。
  • 加固 B <= 0 错误路径。
  • 加固声速诊断保持正值。
  • 加固压力计算结果有限。
  • 加固 B 自动推导结果。
  • 加固显式给定 B 的结果。
  • 加固 Water summary 中最大压力诊断。
  • 在文档中记录 0.2.1 Tait EOS 当前策略。

阶段 H:连续性方程加固

  • 加固双粒子压缩时 drho_dt 符号。
  • 加固双粒子拉伸时 drho_dt 符号。
  • 加固静止均匀粒子组密度变化接近零。
  • 加固非 Water 粒子跳过密度贡献。
  • 加固 inactive 粒子跳过密度贡献。
  • 加固 failed 粒子跳过密度贡献。
  • 加固 drho_dt 每步重置。
  • 加固密度更新结果有限。
  • 加固低密度输入的错误路径。
  • 加固邻域为空时密度变化处理。
  • 确认 summation density 不进入主流程。
  • 保留 summation density 后续 checker 入口说明。

阶段 I:人工黏性加固

  • 加固接近粒子产生人工黏性贡献。
  • 加固远离粒子不产生压缩型人工黏性贡献。
  • 加固零距离粒子人工黏性有限。
  • 加固极小距离粒子人工黏性有限。
  • 加固 alpha < 0 错误路径。
  • 加固 beta < 0 错误路径。
  • 加固 eta2 <= 0 错误路径。
  • 加固人工黏性加速度方向。
  • 加固人工黏性加速度有限性。
  • 加固人工黏性动量趋势。
  • 加固非 Water 粒子跳过黏性贡献。
  • 加固 inactive 粒子跳过黏性贡献。
  • 加固 viscosity 参数读入后与计算一致。
  • 确认人工黏性测试保持小规模。

阶段 J:压力力和外载加固

  • 加固双粒子压力力方向。
  • 加固零压力时压力力接近零。
  • 加固均匀压力组净力趋势。
  • 加固压力力结果有限。
  • 加固 acc_pressure 合成前重置。
  • 加固 acc_viscosity 合成前重置。
  • 加固 acc_body 合成策略。
  • 加固 body force 对速度方向的影响。
  • 加固 body force 对加速度缓存的影响。
  • 加固外部粒子力进入显式步外载占位。
  • 加固非 Water 粒子跳过压力力。
  • 加固 inactive 粒子跳过压力力。
  • 加固 failed 粒子跳过压力力。
  • 确认总加速度合成顺序清晰。

阶段 K:Solver 和时间步加固

  • 加固未 initialize 时 sph_advance_explicit 错误路径。
  • 加固未 build model 时 sph_advance_explicit 错误路径。
  • 加固未 build model 时 sph_run_explicit 错误路径。
  • 加固负 dt 错误路径。
  • 加固零 dt 错误路径。
  • 加固非法 Water 状态下 stable dt 错误路径。
  • 加固 CFL 时间步约束诊断。
  • 加固加速度时间步约束诊断。
  • 加固黏性时间步约束诊断。
  • 加固 safety factor 正值生效路径。
  • 加固非法 safety factor 处理。
  • 加固 TIME 与 STEPS 双约束运行。
  • 加固最后小步不超过 end_time。
  • 加固单步 Water 推进。
  • 加固多步 Water 推进。
  • 加固 sph_run_explicit Water 闭环。
  • 加固自动输出间隔触发。
  • 加固未启用输出时不自动写文件。
  • 加固 restart 后继续显式步。
  • 加固当前时间和步号查询。

阶段 L:Output 加固

  • 确认粒子 CSV 包含 id 字段。
  • 确认粒子 CSV 包含 phase 字段。
  • 确认粒子 CSV 包含 status 字段。
  • 确认粒子 CSV 包含 material 字段。
  • 确认粒子 CSV 包含 section 字段。
  • 确认粒子 CSV 包含坐标字段。
  • 确认粒子 CSV 包含速度字段。
  • 确认粒子 CSV 包含 rho 字段。
  • 确认粒子 CSV 包含 pressure 字段。
  • 确认粒子 CSV 包含 temperature 字段。
  • 确认粒子 CSV 包含 h 字段。
  • 确认 summary CSV 包含 step 字段。
  • 确认 summary CSV 包含 time 字段。
  • 确认 summary CSV 包含 water mass 字段。
  • 确认 summary CSV 包含 water momentum 字段。
  • 确认 summary CSV 包含 max pressure 字段。
  • 确认 summary CSV 包含 min/max density 字段。
  • 确认 summary CSV 包含 dtcrit 字段。
  • 加固输出目录不存在时的处理。
  • 加固非法输出目录错误路径。
  • 确认手动 sph_write_output 不改变物理状态。
  • 确认 CLI --run --output 使用实际 step/time。

阶段 M:Restart 加固

  • 确认 restart header 可识别。
  • 确认 restart state version 记录 0.2.1 策略。
  • 确认 restart 写入 current time。
  • 确认 restart 写入 current step。
  • 确认 restart 写入 output control。
  • 确认 restart 写入 safety factor。
  • 确认 restart 写入 Water EOS 参数。
  • 确认 restart 写入 viscosity 参数。
  • 确认 restart 写入 body force 参数。
  • 确认 restart 写入粒子通用状态。
  • 确认 restart 写入 rho。
  • 确认 restart 写入 pressure。
  • 确认 restart 写入 h。
  • 确认 restart 写入 v、a、vhalf。
  • 确认 restart 写入 Water 诊断状态。
  • 确认 restart 读回 current time。
  • 确认 restart 读回 current step。
  • 确认 restart 读回 Water 参数。
  • 确认 restart 读回粒子状态。
  • 确认 restart 读回后重建邻域。
  • 确认 restart 读回后继续 Water 显式步。
  • 加固非法 restart 文件错误路径。

阶段 N:Fortran API 加固

  • 确认生命周期 API 兼容 0.2.0。
  • 确认 .inp 读取 API 兼容 0.2.0。
  • 确认 build model API 兼容 0.2.0。
  • 确认 stable dt API 兼容 0.2.0。
  • 确认 advance/run explicit API 兼容 0.2.0。
  • 确认 current time API 兼容 0.2.0。
  • 确认 particle count/state API 兼容 0.2.0。
  • 确认 output/restart API 兼容 0.2.0。
  • 确认 error query API 兼容 0.2.0。
  • 确认 neighbor rebuild API 兼容 0.2.0。
  • 确认 neighbor stats API 兼容 0.2.0。
  • 确认 water summary API 兼容 0.2.0。
  • 确认 water dt limits API 兼容 0.2.0。
  • 加固新增 API 未初始化错误路径。
  • 加固新增 API 未 build 错误路径。
  • 确认错误返回前输出参数为安全默认值。
  • 确认 API 不暴露内部 allocatable 指针。

阶段 O:C ABI、C++ 和 Python 加固

  • 确认 C ABI 头文件保持 0.2.0 兼容。
  • 加固 sphlite_get_water_summary 空指针错误路径。
  • 加固 sphlite_get_water_dt_limits 空指针错误路径。
  • 加固 sphlite_get_particle_state 空指针错误路径。
  • 加固 sphlite_get_particle_state 小容量错误路径。
  • 确认 C 参数错误返回 -1。
  • 确认 Fortran 错误码原样返回 C 调用方。
  • 确认 C wrapper 不重新定义物理语义。
  • 确认 C++ wrapper 只做薄封装。
  • 加固 C++ water summary 测试。
  • 加固 C++ water dt limits 测试。
  • 加固 C++ 生命周期 RAII 测试。
  • 确认 Python 通过 C ABI 调用。
  • 加固 Python water summary 包装。
  • 加固 Python water dt limits 包装。
  • 加固 Python inspect 辅助函数。
  • 加固 Python run 辅助函数。
  • 加固 Python 缺失输入错误路径。
  • 加固 Python 缺失 Water 参数错误路径。
  • 确认 Python 不直接访问 Fortran 内部符号。

阶段 P: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 输出 water_particles 字段。
  • 确认 CLI 输出 water_mass 字段。
  • 确认 CLI 输出 max_pressure 字段。
  • 确认 CLI 输出 dtcrit 字段。
  • 确认 CLI 输出 status 字段。
  • 加固缺少输入文件的错误路径。
  • 加固输入文件不存在的错误路径。
  • 加固 --run 与 --check 同时给出的错误路径。
  • 加固 --output 缺少路径的错误路径。
  • 加固 Water 参数缺失的错误路径。
  • 加固输出目录非法的错误路径。
  • 确认 CLI 不绕过公共生命周期接口。

阶段 Q:CouplingInterface 加固

  • 确认 Water 运行后 coupling particle count 可用。
  • 确认 Water 运行后 coupling particle state 导出可用。
  • 确认 coupling particle 导出包含 id。
  • 确认 coupling particle 导出包含 position。
  • 确认 coupling particle 导出包含 velocity。
  • 确认 coupling particle 导出包含 phase。
  • 确认 coupling particle 导出包含 material。
  • 确认 coupling particle 导出包含 pressure。
  • 确认外部粒子力导入接口可用。
  • 确认外部粒子力影响显式步。
  • 确认 coupling work 诊断继续记录。
  • 确认 coupling momentum 诊断继续记录。
  • 确认 coupling energy 诊断继续记录。
  • 保持接触耦合类型字段。
  • 保持连续体耦合类型字段。
  • 确认接口命名不出现 FEMLite 内部结构。
  • 确认默认 gate 不运行真实 FEM-SPH 联合测试。
  • 评估 0.2.1 是否暴露 C ABI coupling 接口。
  • 若不暴露 C ABI coupling 接口,在文档中记录原因。

阶段 R:Pressure Wave Smoke 加固

  • 保持已有 5 粒子 pressure wave smoke 可用。
  • 评估是否增加非共线 3D 粒子布置。
  • 若增加非共线布置,创建对应输入文件。
  • 加固初始压力扰动设置。
  • 加固运行步数检查。
  • 加固 checker 阈值说明。
  • 检查压力扰动传播方向。
  • 检查输出有限性。
  • 检查质量趋势。
  • 检查动量趋势。
  • 检查粒子 CSV 输出字段。
  • 检查 summary CSV 输出字段。
  • 确认 pressure wave smoke 不作为工程精度 benchmark。
  • 确认 pressure wave smoke 保持小规模。
  • 确认 pressure wave smoke 进入默认 gate。

阶段 S:Source Size 和默认 Gate

  • 确认 source size 覆盖 Fortran 文件。
  • 确认 source size 覆盖 C 文件。
  • 确认 source size 覆盖 C++ 头文件。
  • 确认 source size 覆盖 Python 文件。
  • 为新增大文件登记必要例外。
  • 确认 stale exception 检查有效。
  • 运行 smoke 测试。
  • 运行 input 测试。
  • 运行 kernel 测试。
  • 运行 neighbor 测试。
  • 运行 water_eos 测试。
  • 运行 water_density 测试。
  • 运行 water_viscosity 测试。
  • 运行 water_force 测试。
  • 运行 solver_water 测试。
  • 运行 output 测试。
  • 运行 restart 测试。
  • 运行 coupling_interface 测试。
  • 运行 c_api 测试。
  • 运行 cpp_api 测试。
  • 运行 python_debug 测试。
  • 运行 cli 测试。
  • 运行 pressure_wave_smoke 测试。
  • 运行 source_size 测试。
  • 运行 git diff --check。

阶段 T:文档同步

  • 更新 README 当前版本为 0.2.1。
  • 更新 README 的 0.2.1 实际能力说明。
  • 记录 0.2.1 交付 Water 加固能力。
  • 记录 0.2.1 不交付 Gas 生产路径。
  • 记录 0.2.1 不交付 Explosive 生产路径。
  • 记录 0.2.1 不交付 Solid 生产路径。
  • 记录 0.2.1 不交付 Shell 生产路径。
  • 记录 0.2.1 不交付真实 FEM-SPH 联合运行。
  • 更新 docs/09_release_history.md 的 0.2.1 条目。
  • 更新 docs/11_benchmark_matrix.md 的 0.2.1 gate。
  • 确认 01-06 文档与 0.2.1 实际能力不冲突。
  • 确认文档使用 UTF-8 without BOM。
  • 确认文档不宣称已实现完整水下爆炸。
  • 确认文档不宣称已实现生产级多物理耦合。
  • 记录 restart 格式版本策略。
  • 记录非 TYPE=TAIT EOS 的 0.2.1 处理策略。
  • 记录 Water 拉伸压力策略。
  • 记录 CouplingInterface C ABI 是否进入 0.2.1。
  • 记录 VTK 是否进入 0.2.1。

阶段 U:0.2.1 验收

  • 完整配置 CMake。
  • 完整编译 sphlite_core。
  • 完整编译 sphlite_c。
  • 完整编译 sphlite_c_shared。
  • 完整编译 sphlite。
  • 完整编译新增 Fortran 测试目标。
  • 完整编译新增 C/C++ 测试目标。
  • 运行 ctest -R "^(smoke|input|kernel|neighbor|water_eos|water_density|water_viscosity|water_force|solver_water|output|restart|coupling_interface|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.1 release gate 结果。