# SPHLite v3.1 开发计划 文档状态:0.3.1 开发计划草案 目标软件版本:SPHLite 0.3.1 ## 1. 文档定位 本文档用于规划 SPHLite 0.3.1 版本的开发范围。0.3.1 是 0.3 `Gas` 版本线的稳定化和前置加固版本,目标是在 0.3.0 已发布的 Gas 最小闭环基础上,补强多 Gas material/EOS、Gas 源项占位、诊断一致性、restart 兼容性、接口覆盖和 release gate 可维护性。 0.3.1 不应演化为 0.4 `Explosive`。解析点火、爆轰到达时间、反应进度、炸药粒子 phase 转化和真实质量/动量/能量注入仍属于 0.4.0 或后续版本。 ## 2. 依据文件 本计划依据以下文件制定: - `README.md` - `docs/01_requirements_specification.md` - `docs/02_software_architecture_design.md` - `docs/03_detailed_design.md` - `docs/04_mathematical_model_and_algorithms.md` - `docs/05_interface_control_document.md` - `docs/06_test_and_verification_plan.md` - `docs/v3.0_development_plan.md` - `docs/09_release_history.md` - `docs/11_benchmark_matrix.md` ## 3. 版本定位 ### 3.1 与 0.3.0 的关系 0.3.0 已完成 Gas 最小闭环,包括 Gas 输入、三类 EOS、状态初始化、单相显式推进、summary、bubble metrics、CSV output、restart、Fortran API、C ABI、C++ wrapper、Python ctypes、CLI 诊断字段和默认 gate。 0.3.1 应继承 0.3.0 的工程骨架和测试体系,并解决 0.3.0 中为快速闭环而保留的限制: - Gas EOS 状态更偏向单 Gas material。 - Bubble metrics 仍是单气团近似。 - Gas dt 估计和 sound speed 策略较保守。 - Gas 诊断 API 暴露字段较少。 - `source_size` 中已有必要例外,后续维护成本需要控制。 - Explosive 到 Gas 的源项入口尚未形成模块级占位。 ### 3.2 与 0.4.0 的关系 0.4.0 建议作为 `Explosive` 起点。0.3.1 应为 0.4.0 做准备,但不提前实现 Explosive 生产算法。0.3.1 可以交付: - Gas material 级 EOS 表。 - Gas 源项缓存和清零/累计占位。 - 从外部或后续 Explosive 模块向 Gas 施加源项的 Fortran 内部入口。 - 能验证源项不会破坏 Water/Gas 既有 gate 的小型测试。 0.3.1 不交付: - 起爆点输入语义。 - 爆轰传播。 - programmed burn 反应进度。 - Explosive 粒子向 Gas phase 的真实迁移。 - 工程级气泡脉动 benchmark。 ## 4. 开发原则 ### 4.1 保持模块边界 SPHLite 仍只修改本仓库内容,不修改 FEMLite 或其他外部模块。SPHLite 不直接依赖 FEMLite,也不直接依赖外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。 ### 4.2 保持求解器定位 SPHLite 仍是求解器,不负责几何建模、网格生成或粒子生成。0.3.1 可新增测试输入文件或测试辅助脚本,但不得将其宣传为求解器的粒子生成能力。 ### 4.3 保持 Fortran 95 核心 核心实现继续使用 Fortran 95。C ABI、C++ wrapper 和 Python ctypes 仍作为薄接口层。0.3.1 不引入破坏可移植性的第三方运行时依赖。 ### 4.4 保持显式动力学路线 时间推进仍只支持显式动力学,主积分格式为 Velocity-Verlet。不引入隐式求解器、静力求解器、Newmark 路线或隐式-显式混合求解接口。 ### 4.5 保持 Abaqus 子集策略 输入文件继续解析 SPHLite 支持的 Abaqus `.inp` 明确子集。不追求完整 Abaqus 兼容。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的能力使用 `*SPHLITE ...` 扩展关键词。 ### 4.6 保持 Water 与 Gas 独立 Water 和 Gas 共享集中型粒子数据库,但计算路径保持独立。0.3.1 新增 Gas 多材料、源项占位或诊断字段时,不得改变 Water 的 Tait EOS、连续性方程、Monaghan 人工黏性、负压保留和 pressure wave smoke 行为。 ## 5. 0.3.1 交付目标 0.3.1 建议交付以下内容: 1. 将软件版本更新为 `0.3.1`。 2. 支持同一模型中存在多个 `TYPE=GAS` material,并为每个 Gas material 维护独立 EOS 类型和参数。 3. 支持同一输入中同时存在空气类理想气体和爆轰产物类 JWL Gas material。 4. 将 Gas 压力更新、dt 估计、summary 和 restart 改为 material/EOS 分派,避免单一全局 Gas EOS 限制。 5. 建立 Gas 源项缓存占位,包括质量、动量和能量源项累计量。 6. 建立 Gas 源项清零、累计和显式步应用的 Fortran 内部入口,但不实现 Explosive 反应。 7. 将 Gas 源项状态写入 restart,并可读回后继续显式步。 8. 扩展 Gas 诊断,补充质量、动量、密度范围、dt 分量和源项累计量的稳定查询路径。 9. 保持 C ABI 兼容,新增接口只能追加,不能破坏 0.3.0 的 `sphlite_get_gas_summary` 和 `sphlite_get_gas_bubble_metrics`。 10. 增强 Python 和 CLI 的 Gas inspect/run 输出检查。 11. 复核 `source_size` 例外,优先通过小规模拆分或辅助过程降低例外数量。 12. 保持 0.3.0 默认 gate 全部通过,并新增 0.3.1 Gas 稳定化 gate。 13. 更新 README、09 号发布记录和 11 号验收矩阵。 ## 6. 非交付范围 0.3.1 不交付以下内容: 1. 不实现 Explosive 的解析点火、爆轰传播或 programmed burn。 2. 不实现 Explosive 粒子的真实反应进度 `lambda`。 3. 不实现炸药粒子向 Gas phase 的生产级迁移。 4. 不实现工程级水-气多相 Riemann 通量。 5. 不实现复杂水-气界面重构、锐界面追踪或相变蒸发。 6. 不实现生产级气泡多周期脉动 benchmark。 7. 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。 8. 不实现 Shell 的 Mindlin-Reissner 生产求解路径。 9. 不实现真实 FEM-SPH 接触耦合或连续体耦合。 10. 不暴露未冻结的 CouplingInterface C ABI。 11. 不新增几何、网格或粒子生成能力。 ## 7. 输入范围 ### 7.1 继承 0.3.0 Gas 输入 0.3.1 继续支持 0.3.0 的 Gas 输入形式: ```text *MATERIAL, NAME=GAS_NAME, TYPE=GAS *DENSITY rho0 *SECTION, ELSET=GAS_PARTICLES, MATERIAL=GAS_NAME *SPHLITE EOS, TYPE=IDEAL_GAS, MATERIAL=GAS_NAME, GAMMA=..., E0=..., P0=... *SPHLITE EOS, TYPE=JWL, MATERIAL=GAS_NAME, RHO0=..., A=..., B=..., R1=..., R2=..., OMEGA=..., E0=... *SPHLITE EOS, TYPE=STIFFENED_GAS, MATERIAL=GAS_NAME, RHO0=..., GAMMA=..., E0=..., PINF=... *SPHLITE PARTICLE CONTROL, H=..., MASS=..., VOLUME=... *SPHLITE BODY FORCE, X=..., Y=..., Z=... *SPHLITE TIME CONTROL, DT=..., TIME=..., STEPS=..., SAFETY=... ``` ### 7.2 多 Gas material 输入 0.3.1 应支持以下输入组合: ```text *MATERIAL, NAME=AIR, TYPE=GAS *DENSITY 1.2 *SECTION, ELSET=AIR_PARTICLES, MATERIAL=AIR *SPHLITE EOS, TYPE=IDEAL_GAS, MATERIAL=AIR, GAMMA=1.4, E0=... *MATERIAL, NAME=PRODUCTS, TYPE=GAS *DENSITY 1600.0 *SECTION, ELSET=PRODUCT_PARTICLES, MATERIAL=PRODUCTS *SPHLITE EOS, TYPE=JWL, MATERIAL=PRODUCTS, RHO0=..., A=..., B=..., R1=..., R2=..., OMEGA=..., E0=... ``` 每个 `TYPE=GAS` material 必须具备: - `*DENSITY`。 - 对应 `MATERIAL=...` 的 `*SPHLITE EOS`。 - 至少一个 section 绑定,或明确没有 active 粒子时作为 warning/诊断处理。 ### 7.3 Gas 源项输入策略 0.3.1 不建议新增用户可见的 Explosive 源项输入语义。若需要为测试创建源项,可采用以下两种方式之一: - Fortran 模块级测试直接调用 Gas 源项内部入口。 - 使用 `*SPHLITE GAS SOURCE` 作为测试性扩展关键词,但默认文档中标记为实验性,不作为 0.3.1 稳定用户接口。 若实现实验性关键词,应保证缺失或非法字段报 error,不影响运行的未来字段 warning 后跳过。 ## 8. Gas 多材料状态 0.3.1 应将 Gas EOS 状态从单一全局记录扩展为 material 级记录。建议状态包括: - Gas material 数量。 - Gas material 内部 id。 - Gas material 名称。 - 每个 Gas material 的 EOS 类型。 - 每个 Gas material 的密度、内能、温度默认值。 - 理想气体参数表。 - JWL 参数表。 - Stiffened gas 参数表。 - 每个 Gas material 的默认 `h`、`mass`、`volume` 控制策略。 - 每个 Gas material 的外部体力或共享外部体力策略。 压力更新时必须根据粒子的 `material_id` 查找对应 EOS,而不是使用单一全局 Gas EOS。若 Gas 粒子的 material 没有 EOS,应报 error。 ## 9. Gas 源项占位 0.3.1 应为 0.4.0 `Explosive` 预留 Gas 源项状态,但不实现 Explosive 反应。建议最小状态为: ```fortran real(rk), allocatable :: gas_mass_source(:) real(rk), allocatable :: gas_energy_source(:) real(rk), allocatable :: gas_momentum_source(:,:) ``` 数组形状: - `gas_mass_source(npart)`。 - `gas_energy_source(npart)`。 - `gas_momentum_source(3,npart)`。 建议内部入口: - `sph_gas_clear_sources`。 - `sph_gas_add_source_by_particle`。 - `sph_gas_apply_sources_explicit`。 - `sph_gas_get_source_summary`。 源项应用第一版只要求小规模守恒检查: - 质量源项增加 Gas 粒子质量或等效诊断质量。 - 能量源项增加 Gas 粒子内能或等效能量状态。 - 动量源项改变 Gas 粒子速度或动量诊断。 - 非 Gas 粒子源项应报 error 或被明确拒绝。 具体能量到压力的物理转换仍以 Gas EOS 为准,不引入 Explosive 反应模型。 ## 10. Gas 诊断扩展 0.3.1 应保持 0.3.0 诊断字段: - `gas_particles` - `gas_mass` - `gas_volume` - `gas_center_x` - `gas_center_y` - `gas_center_z` - `gas_mean_pressure` - `gas_max_pressure` - `gas_equivalent_radius` - `gas_radius_rate` - `gas_dtcrit` 建议新增或确认以下诊断: - `gas_momentum_x` - `gas_momentum_y` - `gas_momentum_z` - `gas_min_density` - `gas_max_density` - `gas_dt_cfl` - `gas_dt_accel` - `gas_source_mass` - `gas_source_energy` - `gas_source_momentum_x` - `gas_source_momentum_y` - `gas_source_momentum_z` 新增 C ABI 时应避免破坏已有函数,可新增: ```c int sphlite_get_gas_extended_summary(double *mass, double *momentum, double *density_range, double *source_totals); ``` 若字段尚未冻结,可先通过 Fortran API、Python debug 和 CLI 输出覆盖,C ABI 只追加最稳定字段。 ## 11. Restart 和兼容策略 0.3.1 应更新 restart 状态策略: - 新写入状态建议为 `STATE_0_3_1` 或继续 `STATE_0_3` 并在文件内增加 Gas state revision。 - 必须能读取 0.3.0 的 `STATE_0_3` restart。 - 若读取 0.3.0 restart,缺失的多材料 EOS 表和源项状态应明确初始化为 0.3.1 默认值。 - 读回后必须重建邻域。 - 读回后必须能继续显式步。 restart 应保存: - Gas material/EOS 表。 - Gas 默认粒子控制状态。 - Gas 外部体力。 - Gas 源项缓存。 - Gas summary 诊断。 - bubble metrics 历史状态。 - Gas dt 诊断。 - 粒子通用状态中的 `pressure`、`internal_energy`、`temperature`、`rho`、`volume`、`h`、`mass`、`v` 和 `vhalf`。 ## 12. API、C ABI、C++、Python 和 CLI ### 12.1 Fortran API 建议新增或完善: - `sph_get_gas_extended_summary` - `sph_get_gas_source_summary` - `sph_gas_clear_sources` - `sph_gas_add_source_by_particle` - `sph_gas_apply_sources_explicit` ### 12.2 C ABI C ABI 继续保持追加式设计。0.3.1 不破坏: - `sphlite_get_gas_summary` - `sphlite_get_gas_bubble_metrics` - `sphlite_get_gas_dt_limits` 可新增稳定诊断接口,但不暴露 Fortran 内部数组指针。 ### 12.3 C++ wrapper C++ wrapper 继续作为 C ABI 薄包装。新增结构体只表达 C ABI 返回数据,不重新定义 Gas 物理语义。 ### 12.4 Python ctypes Python API 继续通过 C ABI 调用,用于: - 多 Gas material 输入 smoke。 - Gas source 调试。 - Gas extended summary 检查。 - CLI 输出 checker。 Python 不直接访问 Fortran 内部符号。 ### 12.5 CLI CLI inspect、check 和 run 模式应继续输出 0.3.0 Gas 字段。若 0.3.1 新增 extended 字段,应保证: - Water-only 输入输出字段仍稳定。 - Gas-only 输入输出字段可检查。 - Water/Gas 混合输入输出字段可检查。 - 错误路径仍向 stderr 输出 `error_code` 和 `error_message`。 ## 13. 测试计划 ### 13.1 新增 0.3.1 测试 建议新增以下测试: - `input_gas_multimaterial`:多个 Gas material、多个 section、多个 EOS。 - `gas_eos_dispatch`:按粒子 material 分派理想气体、JWL 和 Stiffened gas。 - `gas_source`:质量、动量、能量源项清零、累计和应用。 - `gas_source_errors`:非 Gas 粒子、非法粒子 id、非法源项数值。 - `gas_extended_summary`:质量、动量、密度范围、源项累计量。 - `gas_restart_031`:多 Gas material 和源项状态 restart。 - `gas_restart_030_compat`:读取 0.3.0 `STATE_0_3` restart 的兼容路径。 - `gas_cli_extended`:CLI inspect/run 的新增 Gas 字段。 - `gas_python_extended`:Python ctypes 的新增 Gas 字段。 - `gas_source_size_cleanup`:确认 source size 例外没有 stale 项。 ### 13.2 既有回归测试 0.3.1 必须继续通过 0.3.0 默认 gate: - `smoke` - `input` - `input_gas` - `kernel` - `neighbor` - `water_eos` - `water_density` - `water_viscosity` - `water_force` - `solver_water` - `gas_eos_ideal` - `gas_eos_jwl` - `gas_eos_stiffened` - `gas_state` - `gas_summary` - `solver_gas` - `output` - `gas_output` - `restart` - `gas_restart` - `coupling_interface` - `c_api` - `cpp_api` - `python_debug` - `cli` - `pressure_wave_smoke` - `source_size` ### 13.3 建议 0.3.1 Release Gate 建议 0.3.1 默认 gate 为: ```powershell ctest --test-dir build-codex-unix --output-on-failure ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure git diff --check ``` 若新增测试命名较多,也可使用明确正则列出 0.3.0 gate 与 0.3.1 新增 gate。实现完成后应同步更新 06、09、11 号文档。 ## 14. 建议开发阶段 若后续根据本计划生成 `todo.md`,建议按以下阶段拆分: 1. 0.3.1 版本号和 0.3.0 发布基线确认。 2. 多 Gas material 输入文件和错误输入文件准备。 3. Gas material/EOS 表数据结构。 4. Gas EOS material 分派。 5. Gas 状态初始化按 material 分派。 6. Gas dt 和 sound speed 策略按 material 分派。 7. Gas summary 和 extended summary。 8. Gas 源项状态和内部入口。 9. Gas 源项显式应用小步测试。 10. Gas output 扩展字段。 11. Gas restart 0.3.1 状态写入。 12. 0.3.0 restart 兼容读入。 13. Fortran API 和 C ABI 追加接口。 14. C++ wrapper、Python ctypes 和 CLI 扩展。 15. Source size 例外复核和必要拆分。 16. Water、Gas 和 CouplingInterface 回归。 17. README、09 和 11 号文档同步。 ## 15. 验收标准 0.3.1 应满足以下验收标准: 1. 软件版本为 `0.3.1`。 2. 同一模型可包含多个 Gas material 和不同 EOS。 3. Gas 压力、dt、summary 和 restart 按 material 正确分派。 4. Gas 源项缓存可清零、累计、应用和诊断。 5. Gas 源项不会误作用到 Water、Solid、Shell 或 inactive/failed 粒子。 6. 0.3.0 Gas summary、bubble metrics、output、restart 和接口继续兼容。 7. 0.3.0 `STATE_0_3` restart 可读入,并初始化 0.3.1 新状态默认值。 8. Water 默认 gate 继续通过。 9. 默认 gate、source size 和 `git diff --check` 通过。 10. 文档不宣称 0.3.1 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合能力。 11. 不新增 FEMLite 直接依赖。 12. 不修改 SPHLite 文件夹之外的内容。 ## 16. 风险与控制 | 风险 | 表现 | 控制方式 | | --- | --- | --- | | 0.3.1 范围膨胀 | 提前实现 Explosive 点火、爆轰或反应进度 | 只做 Gas 源项占位和小型守恒测试 | | 多 Gas EOS 分派错误 | 空气粒子使用 JWL 或产物气体使用理想气体参数 | 用混合 Gas material 输入和逐粒子压力测试锁定 | | restart 不兼容 | 0.3.0 restart 无法读入或新状态丢失 | 建立 `gas_restart_030_compat` 和 `gas_restart_031` | | Water 行为漂移 | Gas 源项或全局数组改动影响 Water 单相结果 | Water gate 与 Gas gate 一起运行 | | C ABI 过早暴露内部结构 | 多材料表或源项数组冻结过早 | C ABI 只追加稳定 summary,不暴露内部数组指针 | | source size 债务扩大 | 继续增加例外导致维护困难 | 优先拆分长过程,例外需有 stale 检查 | | Bubble 诊断被过度解释 | 单气团或多材料 smoke 被误认为工程 benchmark | 文档继续明确为小规模链路检查 | ## 17. 0.4.0 启动条件 满足以下条件后,可以启动 0.4.0 `Explosive`: 1. 0.3.1 多 Gas material/EOS 分派稳定。 2. Gas 源项缓存、诊断、restart 和小型应用测试稳定。 3. Gas 可接收质量、动量和能量源项而不破坏 Water/Gas gate。 4. 默认 gate 可重复执行。 5. 文档明确 Explosive 作用到 Gas 后形成 Bubble 的长期路线。