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

218 lines
9.0 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.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:版本和基线
- [x] 确认当前 git 状态并记录 0.3.0 开发起点。
- [x] 确认 `v0.2.2` 发布标签可作为 0.3.0 基线。
- [x] 将核心软件版本更新为 `0.3.0`。
- [x] 将 CMake 项目版本更新为 `0.3.0`。
- [x] 更新 Fortran smoke 测试中的版本期望。
- [x] 更新 C API 测试中的版本期望。
- [x] 更新 C++ API 测试中的版本期望。
- [x] 更新 Python debug 测试中的版本期望。
- [x] 更新 CLI `--version` 和 inspect 版本期望。
- [x] 在 README 中记录 0.3.0 Gas 开发定位。
## 阶段 B:Gas 输入测试数据
- [x] 创建最小 `TYPE=GAS` 理想气体输入文件。
- [x] 创建最小 `TYPE=GAS` JWL 输入文件。
- [x] 创建最小 `TYPE=GAS` Stiffened gas 输入文件。
- [x] 创建缺失 Gas `*DENSITY` 的错误输入文件。
- [x] 创建缺失 Gas `*SPHLITE EOS` 的错误输入文件。
- [x] 创建缺失 Gas EOS `TYPE` 的错误输入文件。
- [x] 创建缺失 Gas EOS `MATERIAL` 的错误输入文件。
- [x] 创建非法 Gas EOS 数值的错误输入文件。
- [x] 创建 Gas 未支持但可跳过关键词的 warning 输入文件。
- [x] 创建 Water 与 Gas 混合粒子的输入文件。
## 阶段 C:Gas 输入解析
- [x] 扩展 material 识别以支持 `TYPE=GAS`。
- [x] 保持 set 只作为集合而不参与 Gas 类型判断。
- [x] 解析 `*SPHLITE EOS, TYPE=IDEAL_GAS`。
- [x] 解析 `*SPHLITE EOS, TYPE=JWL`。
- [x] 解析 `*SPHLITE EOS, TYPE=STIFFENED_GAS`。
- [x] 校验 Gas EOS 必需字段缺失时报 error。
- [x] 校验 Gas EOS 非法数值时报 error。
- [x] 校验 Gas material 与 section 绑定关系。
- [x] 确认 Gas warning 不影响可运行输入。
- [x] 增加 `input_gas` 测试目标并接入 CTest。
## 阶段 D:Gas 模块状态
- [x] 初始化 Gas 模块生命周期状态。
- [x] 重置 Gas 模块时清空 EOS 和诊断状态。
- [x] 在数据库中确认 `SPH_PHASE_GAS` 常量与 C/Python 常量一致。
- [x] 建立 Gas material 名称和内部 id 记录。
- [x] 建立 Gas 默认 `h`、`mass` 和 `volume` 控制参数。
- [x] 建立 Gas 外部体力状态。
- [x] 建立 Gas 稳定时间步诊断状态。
- [x] 建立 Gas summary 诊断状态。
- [x] 建立 Gas bubble metrics 历史状态。
- [x] 确认 Water 状态不读取 Gas 专属变量。
## 阶段 E:理想气体 EOS
- [x] 实现理想气体 EOS 参数设置。
- [x] 校验理想气体 `gamma > 1`。
- [x] 校验理想气体 `rho > 0`。
- [x] 校验理想气体 `internal_energy >= 0`。
- [x] 计算理想气体压力。
- [x] 支持理想气体可选 `P0` 偏置。
- [x] 增加理想气体参考压力测试。
- [x] 增加理想气体压力单调性测试。
- [x] 增加理想气体非法参数测试。
- [x] 增加 `gas_eos_ideal` 测试目标并接入 CTest。
## 阶段 F:JWL EOS
- [x] 实现 JWL EOS 参数设置。
- [x] 校验 JWL `rho0 > 0`。
- [x] 校验 JWL `R1 > 0` 和 `R2 > 0`。
- [x] 校验 JWL `omega > 0`。
- [x] 校验 JWL `internal_energy >= 0`。
- [x] 按 `V = rho0 / rho` 计算相对体积。
- [x] 计算 JWL 压力。
- [x] 增加 JWL 有限性测试。
- [x] 增加 JWL 非法参数测试。
- [x] 增加 `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 的最终建议。