Files
SPHLite/todo.md
T
2026-07-03 09:19:28 +08:00

9.0 KiB
Raw Blame History

SPHLite TODO

当前目标版本:0.3.0

本文档依据 docs/v3.0_development_plan.md 拆分。0.3.0 定位为 Gas 模块的第一个正式开发版本,目标是在 0.2.2 Water 稳定化基线之上建立 Gas 输入、状态、EOS、显式推进、诊断、输出、restart、接口和 release gate 的最小闭环。

所有事项均应限制在 SPHLite 文件夹内完成,不修改外部模块,不引入 FEMLite 直接依赖,不新增几何、网格或粒子生成能力。0.3.0 不实现 Explosive 生产算法、Solid 生产路径、Shell 生产路径或真实 FEM-SPH 联合运行。

执行约定:每完成 20 个待办事项,进行一次本地 git 提交,暂不推送远端。

阶段 A:版本和基线

  • 确认当前 git 状态并记录 0.3.0 开发起点。
  • 确认 v0.2.2 发布标签可作为 0.3.0 基线。
  • 将核心软件版本更新为 0.3.0。
  • 将 CMake 项目版本更新为 0.3.0。
  • 更新 Fortran smoke 测试中的版本期望。
  • 更新 C API 测试中的版本期望。
  • 更新 C++ API 测试中的版本期望。
  • 更新 Python debug 测试中的版本期望。
  • 更新 CLI --version 和 inspect 版本期望。
  • 在 README 中记录 0.3.0 Gas 开发定位。

阶段 B:Gas 输入测试数据

  • 创建最小 TYPE=GAS 理想气体输入文件。
  • 创建最小 TYPE=GAS JWL 输入文件。
  • 创建最小 TYPE=GAS Stiffened gas 输入文件。
  • 创建缺失 Gas *DENSITY 的错误输入文件。
  • 创建缺失 Gas *SPHLITE EOS 的错误输入文件。
  • 创建缺失 Gas EOS TYPE 的错误输入文件。
  • 创建缺失 Gas EOS MATERIAL 的错误输入文件。
  • 创建非法 Gas EOS 数值的错误输入文件。
  • 创建 Gas 未支持但可跳过关键词的 warning 输入文件。
  • 创建 Water 与 Gas 混合粒子的输入文件。

阶段 C:Gas 输入解析

  • 扩展 material 识别以支持 TYPE=GAS。
  • 保持 set 只作为集合而不参与 Gas 类型判断。
  • 解析 *SPHLITE EOS, TYPE=IDEAL_GAS。
  • 解析 *SPHLITE EOS, TYPE=JWL。
  • 解析 *SPHLITE EOS, TYPE=STIFFENED_GAS。
  • 校验 Gas EOS 必需字段缺失时报 error。
  • 校验 Gas EOS 非法数值时报 error。
  • 校验 Gas material 与 section 绑定关系。
  • 确认 Gas warning 不影响可运行输入。
  • 增加 input_gas 测试目标并接入 CTest。

阶段 D:Gas 模块状态

  • 初始化 Gas 模块生命周期状态。
  • 重置 Gas 模块时清空 EOS 和诊断状态。
  • 在数据库中确认 SPH_PHASE_GAS 常量与 C/Python 常量一致。
  • 建立 Gas material 名称和内部 id 记录。
  • 建立 Gas 默认 h、mass 和 volume 控制参数。
  • 建立 Gas 外部体力状态。
  • 建立 Gas 稳定时间步诊断状态。
  • 建立 Gas summary 诊断状态。
  • 建立 Gas bubble metrics 历史状态。
  • 确认 Water 状态不读取 Gas 专属变量。

阶段 E:理想气体 EOS

  • 实现理想气体 EOS 参数设置。
  • 校验理想气体 gamma > 1。
  • 校验理想气体 rho > 0。
  • 校验理想气体 internal_energy >= 0。
  • 计算理想气体压力。
  • 支持理想气体可选 P0 偏置。
  • 增加理想气体参考压力测试。
  • 增加理想气体压力单调性测试。
  • 增加理想气体非法参数测试。
  • 增加 gas_eos_ideal 测试目标并接入 CTest。

阶段 F:JWL EOS

  • 实现 JWL EOS 参数设置。
  • 校验 JWL rho0 > 0。
  • 校验 JWL R1 > 0 和 R2 > 0。
  • 校验 JWL omega > 0。
  • 校验 JWL internal_energy >= 0。
  • 按 V = rho0 / rho 计算相对体积。
  • 计算 JWL 压力。
  • 增加 JWL 有限性测试。
  • 增加 JWL 非法参数测试。
  • 增加 gas_eos_jwl 测试目标并接入 CTest。

阶段 G:Stiffened Gas EOS

  • 实现 Stiffened gas EOS 参数设置。
  • 锁定 Stiffened gas 的输入字段命名。
  • 校验 Stiffened gas gamma > 1。
  • 校验 Stiffened gas rho0 > 0。
  • 校验 Stiffened gas internal_energy >= 0。
  • 校验 Stiffened gas PINF 的允许范围。
  • 计算 Stiffened gas 压力。
  • 增加 Stiffened gas 有限性测试。
  • 增加 Stiffened gas 非法参数测试。
  • 增加 gas_eos_stiffened 测试目标并接入 CTest。

阶段 H:Gas 状态初始化

  • 将 Gas material 对应粒子初始化为 SPH_PHASE_GAS。
  • 初始化 Gas 粒子 rho。
  • 初始化 Gas 粒子 pressure。
  • 初始化 Gas 粒子 internal_energy。
  • 初始化 Gas 粒子 temperature。
  • 初始化 Gas 粒子 mass。
  • 初始化 Gas 粒子 volume。
  • 初始化 Gas 粒子 h。
  • 确认非 Gas 粒子不被 Gas 初始化改写。
  • 增加 gas_state 测试目标并接入 CTest。

阶段 I:Gas Summary

  • 统计 active Gas 粒子数量。
  • 统计 Gas 总质量。
  • 统计 Gas 总体积。
  • 统计 Gas 动量。
  • 计算 Gas 体积加权中心。
  • 计算 Gas 平均压力。
  • 计算 Gas 最大压力。
  • 计算 Gas 密度范围。
  • 确认 inactive 或 failed 粒子不进入 Gas summary。
  • 增加 gas_summary 测试目标并接入 CTest。

阶段 J:Bubble 诊断

  • 按 Gas 总体积计算等效气泡半径。
  • 保存上一时间步等效气泡半径。
  • 计算等效气泡半径变化率。
  • 保存上一时间步 Gas 中心。
  • 计算 Gas 中心迁移量。
  • 处理无 Gas 粒子时的 bubble metrics 默认值。
  • 处理零体积 Gas 粒子时的错误路径。
  • 在文档中说明 0.3.0 bubble metrics 为单气团近似。
  • 增加 bubble metrics 单元测试。
  • 将 bubble metrics 纳入 gas_summary 或独立测试。

阶段 K:Gas 单相显式推进

  • 实现 Gas 压力更新入口。
  • 实现 Gas 密度变化率计算。
  • 实现 Gas 压力加速度计算。
  • 实现 Gas 人工黏性占位或明确跳过策略。
  • 合成 Gas 外部体力加速度。
  • 将 Gas 计算接入显式步进流程。
  • 确认 Gas 显式步不改变 Water 单相结果。
  • 实现 Gas 稳定时间步估计。
  • 增加 Gas 单步推进测试。
  • 增加 solver_gas 测试目标并接入 CTest。

阶段 L:Gas 输出

  • 保持粒子 CSV 通用字段兼容。
  • 在 summary CSV 写入 gas_particles。
  • 在 summary CSV 写入 gas_mass。
  • 在 summary CSV 写入 gas_volume。
  • 在 summary CSV 写入 Gas 中心三分量。
  • 在 summary CSV 写入 Gas 平均压力和最大压力。
  • 在 summary CSV 写入等效气泡半径。
  • 在 summary CSV 写入半径变化率。
  • 在 summary CSV 写入 gas_dtcrit。
  • 增加 gas_output 测试目标并接入 CTest。

阶段 M:Gas Restart

  • 更新 restart 状态版本策略。
  • 写入 Gas EOS 类型和参数。
  • 写入 Gas 默认粒子控制参数。
  • 写入 Gas 外部体力。
  • 写入 Gas summary 诊断状态。
  • 写入 bubble metrics 历史状态。
  • 写入 Gas 稳定时间步诊断。
  • 读回 Gas restart 后重建邻域。
  • 读回 Gas restart 后继续显式步。
  • 增加 gas_restart 测试目标并接入 CTest。

阶段 N:Fortran API 与 C ABI

  • 增加 Fortran sph_get_gas_summary。
  • 增加 Fortran sph_get_gas_bubble_metrics。
  • 增加 Fortran sph_get_gas_dt_limits。
  • 增加 C ABI sphlite_get_gas_summary。
  • 增加 C ABI sphlite_get_gas_bubble_metrics。
  • 增加 C ABI sphlite_get_gas_dt_limits。
  • 为 Gas C ABI 增加空指针错误测试。
  • 为 Gas C ABI 增加未初始化错误测试。
  • 为 Gas C ABI 增加未 build 错误测试。
  • 更新 C API 测试目标以覆盖 Gas 诊断。

阶段 O:C++、Python 和 CLI

  • 在 C++ wrapper 中增加 Gas summary 薄封装。
  • 在 C++ wrapper 中增加 bubble metrics 薄封装。
  • 在 C++ wrapper 测试中覆盖 Gas 诊断。
  • 在 Python ctypes 中增加 Gas summary 封装。
  • 在 Python ctypes 中增加 bubble metrics 封装。
  • 在 Python debug 测试中覆盖 Gas inspect。
  • 在 Python debug 测试中确认不访问 Fortran 内部符号。
  • 在 CLI inspect 输出中增加 Gas 诊断字段。
  • 在 CLI run 输出中增加 Gas 诊断字段。
  • 更新 CLI 测试以覆盖 Gas 输入和错误路径。

阶段 P:回归、文档和发布记录

  • 运行 0.2.2 Water 默认 gate 并确认全部通过。
  • 运行 0.3.0 新增 Gas gate 并确认全部通过。
  • 运行 source_size 门禁。
  • 运行 git diff --check。
  • 确认没有提交 build 目录或临时输出。
  • 更新 README 的 0.3.0 当前能力说明。
  • 更新 docs/09_release_history.md 的 0.3.0 条目。
  • 更新 docs/11_benchmark_matrix.md 的 0.3.0 gate。
  • 复核文档未宣称 0.3.0 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合。
  • 给出 0.3.0 是否发布以及是否进入 0.4.0 Explosive 的最终建议。