# 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 - [ ] 实现理想气体 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 的最终建议。