# SPHLite v4.1 开发计划 文档状态:0.4.1 开发计划草案 目标软件版本:SPHLite 0.4.1 ## 1. 文档定位 本文档用于规划 SPHLite 0.4.1 版本的开发范围。0.4.1 是 0.4 `Explosive` 版本线的稳定化和加固版本,目标是在 0.4.0 已完成解析点火、爆轰到达时间、programmed burn、Gas 源项注入、phase 转化、restart 和接口 gate 的基础上,提升 Explosive-Gas-Water 链路的一致性、可诊断性和回归覆盖。 0.4.1 不作为 0.5 `Solid` 的启动版本。0.4.1 的重点是把 0.4.0 的最小闭环变成更稳的数值和接口基线,使后续 `Solid`、`Shell` 和耦合版本可以依赖 Explosive/Gas 的质量、动量、能量和 restart 行为。 ## 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/v4.0_development_plan.md` - `docs/09_release_history.md` - `docs/11_benchmark_matrix.md` ## 3. 版本定位 ### 3.1 与 0.4.0 的关系 0.4.0 已完成 `Explosive` 起步闭环: - `TYPE=EXPLOSIVE` material、explosive section 和 product Gas material 输入识别。 - `*SPHLITE EXPLOSIVE` programmed burn 控制。 - `*SPHLITE IGNITION` 单点点火。 - 解析爆轰到达时间。 - 反应进度 `lambda`、释放质量、释放动量和释放能量。 - `CONVERSION=SOURCE` 到 Gas 源项缓存。 - `CONVERSION=PHASE` 到 product Gas phase。 - Explosive summary、CSV 输出、`STATE_0_4` restart、C ABI、C++ wrapper、Python ctypes 和 CLI 字段。 - Explosive 专项 gate 和完整 release gate。 0.4.1 不重写 0.4.0 路线,而是围绕以下薄弱点加固: - 多点点火记录和最小到达时间行为需要独立 gate。 - 释放质量应基于炸药初始质量或明确冻结的反应基准,避免 phase 转化或源项应用后重复或漂移。 - SOURCE 和 PHASE 两条路径的质量、动量、能量诊断应可比较。 - Water/Gas/Explosive 混合小算例应进入默认回归,避免 Explosive 加入后破坏 Water/Gas 既有路径。 - restart 后继续推进不得重复释放源项。 - output、CLI 和 Python 应能区分 active explosive 粒子、已转化 Gas 粒子和历史 tracked explosive 粒子。 ### 3.2 与 0.5.0 的关系 0.5.0 仍建议作为 `Solid` 版本线起点。0.4.1 不实现 Johnson-Cook 材料、结构损伤、结构断裂或结构接触响应。0.4.1 可以为后续结构版本准备爆炸载荷和 Gas 压力诊断,但不能宣称已实现结构响应。 ### 3.3 0.4.1 核心目标 0.4.1 的核心目标是形成更可验证的 Explosive-Gas-Water 稳定化闭环: ```text multiple ignition records -> deterministic detonation arrival min -> initial-mass-based reaction release -> SOURCE/PHASE conservation diagnostics -> Gas pressure and Water/Gas smoke response -> restart continue without repeated release -> API/CLI/Python/output consistency ``` ## 4. 开发原则 ### 4.1 保持 0.4 版本线边界 0.4.1 只加固 `Explosive`、`Gas`、`Water` 交界处的最小链路,不进入 `Solid`、`Shell` 或真实 FEM-SPH 耦合。所有开发仍限定在 SPHLite 仓库内,不修改 FEMLite 或外部 CouplingModule。 ### 4.2 不引入几何或粒子生成能力 SPHLite 仍是求解器,不负责几何建模、网格生成或粒子生成。新增 `.inp` 样例和 Python checker 仅作为测试辅助,不作为求解器功能。 ### 4.3 保持 Fortran 95 和追加式接口 核心实现继续使用 Fortran 95。C ABI、C++ wrapper、Python ctypes 和 CLI 只做追加式扩展,不破坏 0.4.0 已有接口和测试。 ### 4.4 保持显式动力学主流程 时间推进继续只支持 Velocity-Verlet 显式动力学。0.4.1 可以加固反应时间步约束和显式步内更新顺序,但不引入隐式求解、静力求解或混合求解接口。 ### 4.5 优先保证可诊断性 0.4.1 的物理模型仍是起步阶段。相比扩大模型复杂度,本版本优先保证质量、动量、能量、phase 转化、源项应用和 restart 的可诊断、可回归和可解释。 ## 5. 0.4.1 交付目标 0.4.1 建议交付以下内容: 1. 将软件版本更新为 `0.4.1`。 2. 保持 0.4.0 默认 gate 全部通过。 3. 为 Explosive 新增初始反应质量基准状态,例如 `explosive_initial_mass(:)` 或等价冻结状态。 4. 确保释放质量按反应质量基准和 `delta_lambda` 计算,而不是受后续 phase 转化或 Gas 源项应用影响。 5. 完善多点点火记录,爆轰到达时间取所有匹配点火记录的最小值。 6. 增加多点点火输入样例和独立 gate。 7. 增加 Explosive material 多材料输入样例和 gate,验证不同炸药 material 拥有独立爆速、能量、burn time 和 product Gas 映射。 8. 加固 `CONVERSION=SOURCE` 的目标 Gas 粒子选择和诊断,至少按 product material 汇总目标。 9. 加固 `CONVERSION=PHASE` 后的 Gas summary、pressure、density 和 material 状态刷新。 10. 增加 SOURCE 与 PHASE 两条路径的释放量一致性或可解释差异诊断。 11. 增加 Explosive-Gas-Water 小型 smoke,验证爆炸产物 Gas 进入 Gas 诊断后不会破坏 Water/Gas 既有显式推进。 12. 增加 release balance summary,包括释放质量、释放能量、释放动量、Gas 源项累计和 phase 转化数量。 13. 在 CSV summary、CLI 和 Python 中暴露 0.4.1 新增诊断字段。 14. 将 0.4.1 restart 状态版本更新为 `STATE_0_4_1`,保存新增反应质量基准和 release balance 相关状态。 15. 保持 `STATE_0_4` restart 兼容读入,并为新增字段提供可重复默认值。 16. 增加 restart 后继续推进不重复释放源项的专项测试。 17. 保持 C ABI 追加式兼容,新增 summary 接口或扩展接口不得破坏 0.4.0 ABI。 18. 复核 source size,保持 `Explosive` 拆分后的文件和过程规模受控。 19. 更新 README、06、09 和 11 号文档中的 0.4.1 测试和验收记录。 20. 不新增 FEMLite 直接依赖,不修改 SPHLite 文件夹之外的内容。 ## 6. 非交付范围 0.4.1 不交付以下内容: 1. 不实现完整化学反应爆轰模型。 2. 不实现球面经验载荷模型作为主模型。 3. 不实现生产级近场水下爆炸强冲击 Riemann-SPH。 4. 不实现复杂水-气界面重构、空化、相变蒸发或多气团合并/破碎。 5. 不实现工程级多周期气泡脉动 benchmark。 6. 不实现 `Solid` Johnson-Cook 材料、失效或破裂。 7. 不实现 `Shell` Mindlin-Reissner 生产求解路径。 8. 不实现真实 FEM-SPH 接触耦合或连续体耦合。 9. 不暴露未冻结的 CouplingInterface C ABI。 10. 不新增几何、网格或粒子生成能力。 ## 7. 输入范围 ### 7.1 多点点火 0.4.1 应明确支持同一 Explosive material 的多个点火记录: ```text *SPHLITE IGNITION, MATERIAL=TNT, X=..., Y=..., Z=..., TIME=... *SPHLITE IGNITION, MATERIAL=TNT, X=..., Y=..., Z=..., TIME=... ``` 对每个 active explosive 粒子: ```text td(i) = min_k( t_ign(k) + |x0(i) - x_ign(k)| / D_material ) ``` 验收重点: - 多点点火顺序不影响最终 `td(i)`。 - 只使用与粒子 material 匹配的点火记录。 - 缺少匹配点火记录时仍为 error。 - 点火坐标非有限值、时间为负值仍为 error。 ### 7.2 多炸药 material 0.4.1 应增加一个多炸药 material 小样例: ```text *MATERIAL, NAME=TNT, TYPE=EXPLOSIVE *MATERIAL, NAME=PBX, TYPE=EXPLOSIVE ``` 每个 Explosive material 可拥有独立: - `*DENSITY` - `DETONATION_VELOCITY` - `ENERGY` - `BURN_TIME` - `PRODUCT_MATERIAL` - `CONVERSION` - 点火记录 不同 material 的爆轰到达时间、反应进度和释放量应彼此独立统计。product Gas material 可相同,也可不同;若不同,则 Gas material/EOS 分派继续由 `Gas` 模块负责。 ### 7.3 释放量诊断字段 0.4.1 可以新增扩展 summary 字段,但不改变 0.4.0 已有字段含义。建议新增: - `explosive_initial_mass` - `explosive_remaining_mass` - `explosive_converted_particles` - `explosive_source_particles` - `explosive_release_mass_error` - `explosive_release_energy_error` - `explosive_source_mass_total` - `explosive_source_energy_total` 如果新增字段过多,C ABI 可采用新增函数而不是修改 0.4.0 已有函数语义。 ## 8. 状态设计 ### 8.1 反应质量基准 0.4.1 建议新增每粒子反应质量基准: ```fortran real(rk), allocatable :: explosive_initial_mass(:) ``` 语义: - 在 `sph_explosive_build` 阶段从 `mass(i)` 冻结。 - SOURCE 和 PHASE 路径均使用该值计算 `dm = delta_lambda * explosive_initial_mass(i)`。 - restart 必须保存该值。 - 从 `STATE_0_4` 读入时,如缺失该字段,应以当前粒子质量作为兼容默认值,但不得导致已反应粒子重复释放。 ### 8.2 转化和源项计数 0.4.1 可新增或派生: ```fortran integer :: explosive_converted_count integer :: explosive_source_particle_count real(rk) :: explosive_release_balance(5) ``` 其中 `explosive_release_balance` 可用于记录质量、能量和三向动量的总释放量或误差量。若不新增存储数组,也应能通过现有 per-particle 状态可靠计算。 ### 8.3 Restart 状态版本 0.4.1 restart 建议写入 `STATE_0_4_1`。新增状态包括: - 反应质量基准。 - SOURCE/PHASE 诊断计数或可恢复状态。 - release balance 诊断所需累计量。 兼容读入: - `STATE_0_4_1`:完整读回。 - `STATE_0_4`:初始化新增状态,保持已释放量和 `lambda` 不重复释放。 - `STATE_0_3_1`:初始化空 Explosive 状态。 ## 9. 算法加固 ### 9.1 反应释放公式 0.4.1 应明确使用冻结反应质量: ```text dm = delta_lambda * m0_explosive(i) dE = dm * energy_per_mass(material) dp = dm * v_explosive(i) ``` 其中 `m0_explosive(i)` 为 build 或 restart 恢复的反应质量基准。该公式避免 phase 转化后 `mass(i)` 被 Gas 源项或后续模型改变时影响反应释放量。 ### 9.2 SOURCE 路径目标分配 SOURCE 路径第一版继续采用 product Gas material 作为目标选择依据。0.4.1 应加固: - 无 active product Gas target 时 error。 - 目标粒子数、总源项、每粒子源项在 summary 中可诊断。 - 多 product Gas material 时只向匹配 material 的 Gas 粒子注入。 - 源项应用后 Gas summary 和 source summary 保持一致。 ### 9.3 PHASE 路径状态刷新 PHASE 路径中,完全反应粒子转为 product Gas 后应确保: - `particle_phase = PHASE_GAS`。 - `material_id = product_material_id`。 - `rho`、`volume`、`internal_energy` 与 product Gas 初始状态和 EOS 约定一致。 - Gas pressure 和 summary 在同一步内刷新。 - 原 Explosive 历史状态仍可被 summary 和 restart 追踪。 ### 9.4 Water/Gas/Explosive 小型链路 0.4.1 应新增小型混合算例,至少包括: - 若干 Water 粒子。 - 若干 Gas product 粒子或 phase 转化后的 Gas 粒子。 - 若干 Explosive 粒子。 该 smoke 不作为工程精度 benchmark,只检查: - 显式步可推进。 - Water summary 仍有限。 - Gas summary 产生正体积和有限压力。 - Explosive release summary 非负且可重复。 - output/restart 可覆盖混合 phase。 ## 10. API、C ABI、C++、Python 和 CLI ### 10.1 Fortran API 建议新增或完善: - `sph_get_explosive_release_balance` - `sph_get_explosive_material_summary` - `sph_explosive_get_tracked_counts` - `sph_explosive_get_source_balance` 若实现阶段认为现有 `sph_get_explosive_summary` 足够,可保持原接口并只增加内部测试。但新增诊断字段若需要对外可见,应优先通过追加 API 实现。 ### 10.2 C ABI C ABI 应保持 0.4.0 兼容。建议新增独立函数,而不是改变现有 `sphlite_get_explosive_summary` 的数组长度约定: ```c int sphlite_get_explosive_release_balance(double *mass_values, double *energy_values, double *momentum_values); ``` 建议语义: - `mass_values[0]`:初始炸药质量。 - `mass_values[1]`:累计释放质量。 - `mass_values[2]`:剩余可反应质量。 - `energy_values[0]`:累计释放能量。 - `energy_values[1]`:Gas source 累计能量或等价转化能量。 - `momentum_values[0..2]`:累计释放动量。 具体字段可在实现时进一步收敛,但必须在测试中锁定。 ### 10.3 C++ wrapper 和 Python ctypes C++ 和 Python 继续做薄包装,不引入独立物理语义。Python checker 应覆盖: - 多点点火 inspect/run。 - release balance 字段。 - restart 后继续 run 的 summary 不重复释放。 ### 10.4 CLI CLI inspect/run 应继续输出 0.4.0 字段,并追加 0.4.1 字段。错误路径仍输出 `error_code` 和 `error_message`。CLI 测试应覆盖: - 多点点火输入。 - 多 material 输入。 - SOURCE 路径。 - PHASE 路径。 - restart 读回后的 run 或 inspect。 ## 11. 输出和 Restart ### 11.1 CSV 输出 0.4.1 建议在 summary CSV 中追加 release balance 字段。粒子 CSV 可追加: - `explosive_initial_mass` - `explosive_remaining_mass` - `explosive_conversion_flag` 如果粒子 CSV 字段变多,应同步更新 output 测试,确保 header 稳定。 ### 11.2 Restart 0.4.1 restart 必须验证: - `STATE_0_4_1` 写入和读回。 - `STATE_0_4` 兼容读入。 - `STATE_0_3_1` 兼容读入并初始化空 Explosive 状态。 - 读回后继续显式步不重复释放质量、动量和能量。 - 读回后多点点火、material table、product mapping 和 release balance 保持一致。 ## 12. 测试计划 ### 12.1 新增 0.4.1 测试 建议新增以下测试: - `input_explosive_multi_ignition`:多点点火输入、顺序无关和最小到达时间。 - `input_explosive_multimaterial`:多个 Explosive material、多个 product Gas material 和独立控制参数。 - `explosive_initial_mass_release`:释放量基于冻结初始质量。 - `explosive_release_balance`:释放质量、能量、动量和剩余质量一致。 - `explosive_source_targeting`:SOURCE 只注入匹配 product Gas material。 - `explosive_phase_refresh`:PHASE 转化后 Gas 状态和 summary 刷新。 - `explosive_restart_041`:`STATE_0_4_1` 写入读回并继续显式步。 - `explosive_restart_040_compat`:`STATE_0_4` 兼容读入并初始化新增字段。 - `explosive_restart_no_double_release`:restart 后继续推进不重复释放。 - `explosive_water_gas_smoke`:Water/Gas/Explosive 混合小算例显式推进。 - `explosive_release_c_api`:C ABI release balance 查询。 - `explosive_release_python`:Python ctypes release balance 查询。 - `explosive_release_cli`:CLI 输出 release balance 字段。 - `explosive_041_source_size`:0.4.1 新增拆分和 source size gate。 ### 12.2 既有回归测试 0.4.1 必须继续通过 0.4.0 完整 gate,包括: - Water gate。 - Gas gate。 - Explosive 0.4.0 gate。 - output/restart gate。 - C API/C++/Python/CLI gate。 - source size gate。 ### 12.3 建议 0.4.1 Release Gate 建议 0.4.1 默认 gate 为: ```powershell cmake --build build-codex-unix --parallel ctest --test-dir build-codex-unix --output-on-failure ctest --test-dir build-codex-unix -R "^(input_explosive_multi_ignition|input_explosive_multimaterial|explosive_initial_mass_release|explosive_release_balance|explosive_source_targeting|explosive_phase_refresh|explosive_restart_041|explosive_restart_040_compat|explosive_restart_no_double_release|explosive_water_gas_smoke|explosive_release_c_api|explosive_release_python|explosive_release_cli|explosive_041_source_size)$" --output-on-failure ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure git diff --check ``` ## 13. 建议开发阶段 若后续根据本计划生成 `todo.md`,建议按以下阶段拆分: 1. 0.4.1 版本号和 0.4.0 发布基线确认。 2. 0.4.1 输入样例和错误输入样例准备。 3. 多点点火输入和到达时间 gate。 4. 多 Explosive material 输入和 product Gas 映射 gate。 5. `explosive_initial_mass` 或等价反应质量基准状态。 6. SOURCE/PHASE 释放量统一按冻结质量计算。 7. release balance summary 内部统计。 8. SOURCE 目标 Gas material 分配加固。 9. PHASE 转化后 Gas 状态刷新加固。 10. Water/Gas/Explosive 混合 smoke。 11. summary CSV 和粒子 CSV 字段扩展。 12. `STATE_0_4_1` restart 写入。 13. `STATE_0_4_1` restart 读回。 14. `STATE_0_4` 和 `STATE_0_3_1` 兼容读入。 15. restart 后不重复释放专项测试。 16. Fortran API 和 C ABI 追加接口。 17. C++ wrapper、Python ctypes 和 CLI 扩展。 18. source size 复核和必要拆分。 19. 0.4.0 全量回归和 0.4.1 新增 gate。 20. README、06、09 和 11 号文档同步。 ## 14. 验收标准 0.4.1 应满足以下验收标准: 1. 软件版本为 `0.4.1`。 2. 0.4.0 release gate 继续通过。 3. 多点点火的爆轰到达时间按最小到达时间计算。 4. 多 Explosive material 可独立控制爆速、能量、burn time、product Gas 和 conversion mode。 5. 释放质量基于冻结反应质量基准,不受 phase 转化或后续 Gas 源项应用影响。 6. `lambda` 单调、不可逆,且限制在 `[0,1]`。 7. SOURCE 路径只向匹配 product Gas material 的 active Gas 粒子注入源项。 8. PHASE 路径完全反应后可刷新 Gas 状态和 summary。 9. release balance summary 可解释累计释放质量、能量和动量。 10. 0.4.1 restart 可恢复新增状态并继续显式步。 11. 0.4.0 restart 可兼容读入,并初始化新增 0.4.1 状态。 12. restart 后继续推进不重复释放源项。 13. C ABI、C++ wrapper、Python ctypes 和 CLI 追加字段可用。 14. Water/Gas/Explosive 混合 smoke 可重复通过。 15. 默认 gate、0.4.1 专项 gate、source size 和 `git diff --check` 通过。 16. 文档不宣称 0.4.1 已实现 Solid、Shell、真实 FEM-SPH 耦合或工程级水下爆炸 benchmark。 17. 不新增 FEMLite 直接依赖。 18. 不修改 SPHLite 文件夹之外的内容。 ## 15. 风险与控制 | 风险 | 表现 | 控制方式 | | --- | --- | --- | | 0.4.1 范围膨胀 | 提前实现 Solid、Shell 或工程爆炸 benchmark | 限定为 Explosive 稳定化和混合 smoke | | 多点点火行为不确定 | 输入顺序影响到达时间 | 测试锁定最小到达时间和顺序无关 | | 释放量重复计算 | restart 或 phase 转化后重复释放质量/能量 | 使用 `delta_lambda` 和冻结初始质量,新增 no-double-release gate | | SOURCE 目标不清晰 | 源项注入到错误 Gas material | 按 product material 过滤,并测试多 Gas material | | PHASE 转化状态不一致 | 转化后 material、rho、volume、pressure 不匹配 | 转化后刷新 Gas 状态和 summary,并测试 restart | | API 兼容破坏 | 修改 0.4.0 summary 数组长度或字段含义 | 新增 API,不改变旧接口语义 | | output 字段膨胀 | CSV header 频繁变化 | 新增字段必须有 output 测试锁定 | | source size 债务扩大 | Explosive 稳定化代码堆回主文件 | 保持 state/helper/reaction/restart 拆分 | ## 16. 0.5.0 启动条件 满足以下条件后,可以启动 0.5.0 `Solid`: 1. 0.4.1 多点点火、多材料和 release balance 稳定。 2. SOURCE 和 PHASE 两条路径的质量、动量、能量诊断可重复。 3. 0.4.1 restart 和 0.4.0 兼容 restart 可重复通过。 4. Water/Gas/Explosive 混合 smoke 可重复通过。 5. 0.4.1 文档明确尚未实现结构响应、破裂和真实 FEM-SPH 耦合。