19 KiB
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.mddocs/01_requirements_specification.mddocs/02_software_architecture_design.mddocs/03_detailed_design.mddocs/04_mathematical_model_and_algorithms.mddocs/05_interface_control_document.mddocs/06_test_and_verification_plan.mddocs/v4.0_development_plan.mddocs/09_release_history.mddocs/11_benchmark_matrix.md
3. 版本定位
3.1 与 0.4.0 的关系
0.4.0 已完成 Explosive 起步闭环:
TYPE=EXPLOSIVEmaterial、explosive section 和 product Gas material 输入识别。*SPHLITE EXPLOSIVEprogrammed burn 控制。*SPHLITE IGNITION单点点火。- 解析爆轰到达时间。
- 反应进度
lambda、释放质量、释放动量和释放能量。 CONVERSION=SOURCE到 Gas 源项缓存。CONVERSION=PHASE到 product Gas phase。- Explosive summary、CSV 输出、
STATE_0_4restart、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 稳定化闭环:
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 建议交付以下内容:
- 将软件版本更新为
0.4.1。 - 保持 0.4.0 默认 gate 全部通过。
- 为 Explosive 新增初始反应质量基准状态,例如
explosive_initial_mass(:)或等价冻结状态。 - 确保释放质量按反应质量基准和
delta_lambda计算,而不是受后续 phase 转化或 Gas 源项应用影响。 - 完善多点点火记录,爆轰到达时间取所有匹配点火记录的最小值。
- 增加多点点火输入样例和独立 gate。
- 增加 Explosive material 多材料输入样例和 gate,验证不同炸药 material 拥有独立爆速、能量、burn time 和 product Gas 映射。
- 加固
CONVERSION=SOURCE的目标 Gas 粒子选择和诊断,至少按 product material 汇总目标。 - 加固
CONVERSION=PHASE后的 Gas summary、pressure、density 和 material 状态刷新。 - 增加 SOURCE 与 PHASE 两条路径的释放量一致性或可解释差异诊断。
- 增加 Explosive-Gas-Water 小型 smoke,验证爆炸产物 Gas 进入 Gas 诊断后不会破坏 Water/Gas 既有显式推进。
- 增加 release balance summary,包括释放质量、释放能量、释放动量、Gas 源项累计和 phase 转化数量。
- 在 CSV summary、CLI 和 Python 中暴露 0.4.1 新增诊断字段。
- 将 0.4.1 restart 状态版本更新为
STATE_0_4_1,保存新增反应质量基准和 release balance 相关状态。 - 保持
STATE_0_4restart 兼容读入,并为新增字段提供可重复默认值。 - 增加 restart 后继续推进不重复释放源项的专项测试。
- 保持 C ABI 追加式兼容,新增 summary 接口或扩展接口不得破坏 0.4.0 ABI。
- 复核 source size,保持
Explosive拆分后的文件和过程规模受控。 - 更新 README、06、09 和 11 号文档中的 0.4.1 测试和验收记录。
- 不新增 FEMLite 直接依赖,不修改 SPHLite 文件夹之外的内容。
6. 非交付范围
0.4.1 不交付以下内容:
- 不实现完整化学反应爆轰模型。
- 不实现球面经验载荷模型作为主模型。
- 不实现生产级近场水下爆炸强冲击 Riemann-SPH。
- 不实现复杂水-气界面重构、空化、相变蒸发或多气团合并/破碎。
- 不实现工程级多周期气泡脉动 benchmark。
- 不实现
SolidJohnson-Cook 材料、失效或破裂。 - 不实现
ShellMindlin-Reissner 生产求解路径。 - 不实现真实 FEM-SPH 接触耦合或连续体耦合。
- 不暴露未冻结的 CouplingInterface C ABI。
- 不新增几何、网格或粒子生成能力。
7. 输入范围
7.1 多点点火
0.4.1 应明确支持同一 Explosive material 的多个点火记录:
*SPHLITE IGNITION, MATERIAL=TNT, X=..., Y=..., Z=..., TIME=...
*SPHLITE IGNITION, MATERIAL=TNT, X=..., Y=..., Z=..., TIME=...
对每个 active explosive 粒子:
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 小样例:
*MATERIAL, NAME=TNT, TYPE=EXPLOSIVE
*MATERIAL, NAME=PBX, TYPE=EXPLOSIVE
每个 Explosive material 可拥有独立:
*DENSITYDETONATION_VELOCITYENERGYBURN_TIMEPRODUCT_MATERIALCONVERSION- 点火记录
不同 material 的爆轰到达时间、反应进度和释放量应彼此独立统计。product Gas material 可相同,也可不同;若不同,则 Gas material/EOS 分派继续由 Gas 模块负责。
7.3 释放量诊断字段
0.4.1 可以新增扩展 summary 字段,但不改变 0.4.0 已有字段含义。建议新增:
explosive_initial_massexplosive_remaining_massexplosive_converted_particlesexplosive_source_particlesexplosive_release_mass_errorexplosive_release_energy_errorexplosive_source_mass_totalexplosive_source_energy_total
如果新增字段过多,C ABI 可采用新增函数而不是修改 0.4.0 已有函数语义。
8. 状态设计
8.1 反应质量基准
0.4.1 建议新增每粒子反应质量基准:
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 可新增或派生:
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 应明确使用冻结反应质量:
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_balancesph_get_explosive_material_summarysph_explosive_get_tracked_countssph_explosive_get_source_balance
若实现阶段认为现有 sph_get_explosive_summary 足够,可保持原接口并只增加内部测试。但新增诊断字段若需要对外可见,应优先通过追加 API 实现。
10.2 C ABI
C ABI 应保持 0.4.0 兼容。建议新增独立函数,而不是改变现有 sphlite_get_explosive_summary 的数组长度约定:
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_massexplosive_remaining_massexplosive_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 为:
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,建议按以下阶段拆分:
- 0.4.1 版本号和 0.4.0 发布基线确认。
- 0.4.1 输入样例和错误输入样例准备。
- 多点点火输入和到达时间 gate。
- 多 Explosive material 输入和 product Gas 映射 gate。
explosive_initial_mass或等价反应质量基准状态。- SOURCE/PHASE 释放量统一按冻结质量计算。
- release balance summary 内部统计。
- SOURCE 目标 Gas material 分配加固。
- PHASE 转化后 Gas 状态刷新加固。
- Water/Gas/Explosive 混合 smoke。
- summary CSV 和粒子 CSV 字段扩展。
STATE_0_4_1restart 写入。STATE_0_4_1restart 读回。STATE_0_4和STATE_0_3_1兼容读入。- restart 后不重复释放专项测试。
- Fortran API 和 C ABI 追加接口。
- C++ wrapper、Python ctypes 和 CLI 扩展。
- source size 复核和必要拆分。
- 0.4.0 全量回归和 0.4.1 新增 gate。
- README、06、09 和 11 号文档同步。
14. 验收标准
0.4.1 应满足以下验收标准:
- 软件版本为
0.4.1。 - 0.4.0 release gate 继续通过。
- 多点点火的爆轰到达时间按最小到达时间计算。
- 多 Explosive material 可独立控制爆速、能量、burn time、product Gas 和 conversion mode。
- 释放质量基于冻结反应质量基准,不受 phase 转化或后续 Gas 源项应用影响。
lambda单调、不可逆,且限制在[0,1]。- SOURCE 路径只向匹配 product Gas material 的 active Gas 粒子注入源项。
- PHASE 路径完全反应后可刷新 Gas 状态和 summary。
- release balance summary 可解释累计释放质量、能量和动量。
- 0.4.1 restart 可恢复新增状态并继续显式步。
- 0.4.0 restart 可兼容读入,并初始化新增 0.4.1 状态。
- restart 后继续推进不重复释放源项。
- C ABI、C++ wrapper、Python ctypes 和 CLI 追加字段可用。
- Water/Gas/Explosive 混合 smoke 可重复通过。
- 默认 gate、0.4.1 专项 gate、source size 和
git diff --check通过。 - 文档不宣称 0.4.1 已实现 Solid、Shell、真实 FEM-SPH 耦合或工程级水下爆炸 benchmark。
- 不新增 FEMLite 直接依赖。
- 不修改 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:
- 0.4.1 多点点火、多材料和 release balance 稳定。
- SOURCE 和 PHASE 两条路径的质量、动量、能量诊断可重复。
- 0.4.1 restart 和 0.4.0 兼容 restart 可重复通过。
- Water/Gas/Explosive 混合 smoke 可重复通过。
- 0.4.1 文档明确尚未实现结构响应、破裂和真实 FEM-SPH 耦合。