21 KiB
SPHLite v4.0 开发计划
文档状态:0.4.0 开发计划草案
目标软件版本:SPHLite 0.4.0
1. 文档定位
本文档用于规划 SPHLite 0.4.0 版本的开发范围。0.4.0 是 Explosive 版本线的起步版本,目标是在 0.3.1 已完成 Gas 多材料、EOS 分派、源项缓存、扩展诊断和 restart 兼容的基础上,建立炸药粒子的解析点火、爆轰到达时间、反应进度和向 Gas 释放质量、动量、能量的最小闭环。
0.4.0 应服务于船舶水下接触爆炸长期目标,但不应膨胀为完整水下爆炸工程 benchmark。第一版重点是把 Explosive 与 Gas 的模块边界、状态、输入、显式推进、restart、接口和测试 gate 建稳。
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/v3.1_development_plan.mddocs/09_release_history.mddocs/10_development_roadmap.mddocs/11_benchmark_matrix.md
3. 版本定位
3.1 与 0.3.1 的关系
0.3.1 已完成 Gas 稳定化和 0.4.0 前置条件:
- 多个
TYPE=GASmaterial 可各自绑定 EOS。 - JWL、理想气体和 Stiffened gas 可按 material 分派。
Gas具备质量、动量和能量源项缓存。Gas源项可清零、累计、应用和诊断。Gasrestart、CLI、Python、C ABI 和扩展 summary 已有稳定 gate。
0.4.0 应利用上述能力,不重新定义气体模块,也不把气泡作为独立一级模块。炸药反应产生的产物气体进入 Gas 后,再由 Gas 诊断气体体积、等效气泡半径、压力和中心迁移。
3.2 与 0.5.0 的关系
0.5.0 建议作为 Solid 起点。0.4.0 不实现 Johnson-Cook 结构材料、结构损伤、实体结构破裂或结构接触响应。若 0.4.0 需要检查爆炸载荷方向,可使用 Water/Gas/Explosive 小模型,不引入生产级结构响应。
3.3 0.4.0 核心目标
0.4.0 的核心目标是形成如下最小闭环:
Explosive material + ignition point
-> detonation arrival time
-> reaction progress lambda
-> mass/momentum/energy release
-> Gas source or Gas phase conversion
-> Gas pressure/update/output/restart diagnostics
4. 开发原则
4.1 保持模块边界
SPHLite 仍只修改本仓库内容,不修改 FEMLite 或其他外部模块。SPHLite 不直接依赖 FEMLite,也不直接依赖外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
Explosive 只负责点火、爆轰到达、反应进度和源项释放;Gas 负责产物气体 EOS、压力更新、气体统计和气泡诊断。
4.2 保持求解器定位
SPHLite 是求解器,不负责几何建模、网格生成或粒子生成。0.4.0 可以新增测试 .inp 文件和 Python checker,但这些只能作为测试和示例辅助,不作为求解器粒子生成能力宣传。
4.3 保持 Fortran 95 核心
核心实现继续使用 Fortran 95。C ABI、C++ wrapper 和 Python ctypes 仍作为薄接口层。0.4.0 不引入破坏 FEMLite 风格工具链兼容性的第三方运行时依赖。
4.4 保持显式动力学路线
时间推进继续只支持 Velocity-Verlet 显式动力学。0.4.0 不引入隐式求解、静力求解、Newmark 路线或隐式-显式混合接口。
4.5 保持 Abaqus 子集策略
输入文件继续解析 SPHLite 支持的 Abaqus .inp 明确子集。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的炸药点火、爆轰和反应控制使用 *SPHLITE ... 扩展关键词。
4.6 保持 Water/Gas 回归稳定
0.4.0 新增 Explosive 后,必须保持 0.2 Water 和 0.3 Gas 既有 gate 稳定。炸药反应不得改变未参与爆炸的 Water/Gas-only 算例结果。
5. 0.4.0 交付目标
0.4.0 建议交付以下内容:
- 将软件版本更新为
0.4.0。 - 新增
Explosive模块骨架和生命周期 reset/build/advance/finalize 路径。 - 支持
TYPE=EXPLOSIVEmaterial 和 explosive section 的输入识别。 - 支持炸药密度、爆速、单位质量能量、反应时间窗口和产物 Gas material 映射。
- 支持至少一个解析点火点,包括坐标和起爆时间。
- 按初始坐标计算炸药粒子的爆轰到达时间
td(i)。 - 保存并推进不可逆反应进度
lambda(i),范围为0 <= lambda <= 1。 - 由反应进度增量生成质量、动量和能量释放量。
- 将释放量写入 0.3.1 已有的
Gas源项缓存,并通过显式步应用到产物 Gas 状态。 - 支持炸药粒子不可逆转化为产物 Gas phase 的最小路径。
- 保留源项注入路径,用于炸药粒子不立即改变 phase 的测试和后续扩展。
- 输出 explosive summary,包括反应粒子数、平均反应进度、释放质量、释放能量和爆轰到达时间范围。
- 将
Explosive状态写入 0.4.0 restart,并可读回继续显式步。 - 保持 C ABI 追加式兼容,新增 Explosive 查询接口不得破坏既有 Water/Gas 接口。
- 增强 Python 和 CLI,使其可以检查 explosive 输入、运行和 summary 字段。
- 新增 0.4.0
Explosive默认 gate,并保持 0.3.1 默认 gate 全部通过。 - 更新 README、06、09 和 11 号文档中的 0.4.0 测试和验收记录。
6. 非交付范围
0.4.0 不交付以下内容:
- 不实现完整化学反应爆轰模型。
- 不实现球面经验载荷模型作为主模型。
- 不实现生产级近场水下爆炸强冲击 Riemann-SPH。
- 不实现复杂水-气界面重构、空化、相变蒸发或多气团合并/破碎算法。
- 不实现工程级多周期气泡脉动 benchmark。
- 不实现
SolidJohnson-Cook 材料、失效或破裂。 - 不实现
ShellMindlin-Reissner 生产求解路径。 - 不实现真实 FEM-SPH 接触耦合或连续体耦合。
- 不暴露未冻结的 CouplingInterface C ABI。
- 不新增几何、网格或粒子生成能力。
7. 输入范围
7.1 Explosive material 输入
0.4.0 建议使用 Abaqus 风格 material/section 识别炸药粒子:
*MATERIAL, NAME=TNT, TYPE=EXPLOSIVE
*DENSITY
rho0
*SECTION, ELSET=CHARGE_PARTICLES, MATERIAL=TNT
TYPE=EXPLOSIVE material 必须具备:
*DENSITY。- 至少一个 section 绑定,或明确没有 active 粒子时作为 warning/诊断处理。
- 对应的
*SPHLITE EXPLOSIVE控制记录。
7.2 Explosive 控制关键词
爆速、能量和产物 Gas material 无法用 Abaqus 通用关键词完整表达,建议使用扩展关键词:
*SPHLITE EXPLOSIVE, MATERIAL=TNT, TYPE=PROGRAMMED_BURN, DETONATION_VELOCITY=..., ENERGY=..., BURN_TIME=..., PRODUCT_MATERIAL=PRODUCTS, CONVERSION=PHASE
字段建议:
MATERIAL:炸药 material 名称。TYPE=PROGRAMMED_BURN:0.4.0 默认反应模型。DETONATION_VELOCITY:爆速,必须为正。ENERGY:单位质量释放能量,必须非负。BURN_TIME:反应时间窗口,必须非负;取 0 时表示到达后瞬时完成反应。PRODUCT_MATERIAL:产物 Gas material,必须为TYPE=GAS且具备 EOS。CONVERSION:PHASE或SOURCE。0.4.0 默认建议为PHASE。
7.3 点火输入
点火点建议使用扩展关键词:
*SPHLITE IGNITION, MATERIAL=TNT, X=..., Y=..., Z=..., TIME=...
0.4.0 release gate 至少覆盖单点点火。模块状态可预留多个点火记录;若实现多点点火,爆轰到达时间取所有点火点中的最小到达时间:
td(i) = min_k( t_ign(k) + |x0(i) - x_ign(k)| / D )
其中 x0(i) 使用炸药粒子初始坐标,D 使用该炸药 material 的爆速。
7.4 与 Gas 输入的关系
产物 Gas material 使用 0.3.1 已有 Gas 输入语义:
*MATERIAL, NAME=PRODUCTS, TYPE=GAS
*DENSITY
rho_products
*SPHLITE EOS, TYPE=JWL, MATERIAL=PRODUCTS, RHO0=..., A=..., B=..., R1=..., R2=..., OMEGA=..., E0=...
如果 PRODUCT_MATERIAL 缺失、不是 Gas material、或没有 EOS,必须报 error。
8. Explosive 状态设计
0.4.0 建议新增 Explosive 模块级状态:
integer :: explosive_material_count
integer, allocatable :: explosive_material_id(:)
integer, allocatable :: explosive_product_material_id(:)
real(rk), allocatable :: explosive_density0(:)
real(rk), allocatable :: explosive_detonation_velocity(:)
real(rk), allocatable :: explosive_energy_per_mass(:)
real(rk), allocatable :: explosive_burn_time(:)
integer, allocatable :: explosive_conversion_mode(:)
integer, allocatable :: explosive_ignition_status(:)
real(rk), allocatable :: explosive_detonation_time(:)
real(rk), allocatable :: explosive_reaction_progress(:)
real(rk), allocatable :: explosive_released_mass(:)
real(rk), allocatable :: explosive_released_energy(:)
real(rk), allocatable :: explosive_released_momentum(:,:)
数组形状建议:
explosive_detonation_time(npart)。explosive_reaction_progress(npart)。explosive_released_mass(npart)。explosive_released_energy(npart)。explosive_released_momentum(3,npart)。
reaction_progress 是不可逆状态,只能增加不能降低。已经完全反应的粒子应保持 lambda = 1,并通过 phase/status 或 summary 表达后续状态。
9. 反应和源项算法
9.1 爆轰到达时间
0.4.0 使用解析爆轰到达时间,不使用固定球面载荷模型。对每个 active explosive 粒子:
td(i) = t_ign + |x0(i) - x_ign| / D
多点火记录若进入实现,则取最小 td(i)。
9.2 反应进度
当当前时间达到 td(i) 后,按 programmed burn 更新反应进度:
lambda_target = clamp((t - td(i)) / burn_time, 0, 1)
delta_lambda = max(lambda_target - lambda_old, 0)
当 burn_time = 0 时,t >= td(i) 的粒子可在当前显式步内直接达到 lambda = 1。
9.3 释放量
反应增量建议按以下第一版近似产生源项:
dm = delta_lambda * m_explosive_initial
dE = dm * energy_per_mass
dp = dm * v_explosive
其中动量源项第一版默认继承炸药粒子当前速度;静止炸药测试中动量源项为零,便于守恒检查。后续如需 Chapman-Jouguet 速度或方向性冲量,应单独规划。
9.4 Gas phase 转化路径
CONVERSION=PHASE 是 0.4.0 推荐默认路径。粒子反应后不可逆进入 PHASE_GAS,material 改为 PRODUCT_MATERIAL,并由 Gas 的 EOS、压力更新和诊断接管。
0.4.0 可采用分阶段转化策略:
lambda = 0:保持PHASE_EXPLOSIVE。0 < lambda < 1:保持 explosive 状态,同时记录部分反应进度和已释放源项。lambda = 1:不可逆转为PHASE_GAS,material 改为 product Gas material。
如果实现更早的部分转化,也必须保证 restart 和 summary 能恢复同一状态。
9.5 Gas source 注入路径
CONVERSION=SOURCE 作为 0.4.0 的保留路径,用于炸药粒子不立即改变 phase、但向已有 Gas 粒子或目标 Gas region 注入质量、动量和能量。第一版若无法明确目标 Gas 粒子,应报 error,不得静默丢弃源项。
无论选择哪条路径,0.4.0 都应复用 Gas 的源项缓存和 summary,不在 Explosive 中复制 Gas EOS 或压力计算。
10. 显式求解器集成
0.4.0 建议在显式步中加入 Explosive 更新阶段:
estimate dt
Velocity-Verlet first half update
rebuild or reuse neighbor state
Water/Gas force and EOS update
Explosive detonation/reaction update
Gas source apply and pressure refresh
Velocity-Verlet second half update
output/restart diagnostics
具体顺序可按现有求解器结构微调,但必须满足:
Explosive反应使用当前步明确的时间点。- 源项应用后
Gas压力和 summary 是一致的。 - Water-only 和 Gas-only 算例不进入 Explosive 路径。
- 反应进度和 phase 改变可被 restart 恢复。
时间步估计建议增加反应约束:
dt_reaction = burn_time / n_reaction_substeps
当 burn_time = 0 时不新增该约束;当 burn_time > 0 时,dtcrit 应考虑反应进度变化的可控性。n_reaction_substeps 可先作为内部常量或输入控制项。
11. Restart 和兼容策略
0.4.0 restart 建议写入 STATE_0_4,并保存完整 Explosive 模块状态:
- Explosive material 表。
- product Gas material 映射。
- 点火记录。
- 每粒子爆轰到达时间。
- 每粒子反应进度。
- 每粒子已释放质量、动量和能量。
- phase 转化状态。
- Explosive summary 诊断。
- Gas 源项缓存和 0.3.1 Gas 状态。
兼容策略:
- 必须继续读取 0.3.1 restart。
- 读取 0.3.1 restart 时,若没有 Explosive 状态,应初始化为空 Explosive 状态。
- 若 0.3.1 restart 中存在 Gas 源项缓存,应按 0.3.1 兼容逻辑保留。
- 读回后必须能继续显式步,并重建邻域或运行时派生状态。
12. API、C ABI、C++、Python 和 CLI
12.1 Fortran API
建议新增或完善:
sph_explosive_resetsph_explosive_buildsph_explosive_compute_detonation_timessph_explosive_advancesph_get_explosive_summarysph_set_ignition_point
Fortran API 是核心语义来源,C ABI 只做薄包装。
12.2 C ABI
C ABI 继续保持追加式设计。可新增:
int sphlite_set_ignition_point(double x, double y, double z, double time);
int sphlite_get_explosive_summary(int *particle_count,
int *reacted_count,
double *lambda_range,
double *released_totals,
double *detonation_time_range);
建议字段含义:
lambda_range[0]:最小反应进度。lambda_range[1]:最大反应进度。lambda_range[2]:质量加权或粒子平均反应进度。released_totals[0]:累计释放质量。released_totals[1]:累计释放能量。released_totals[2..4]:累计释放动量。detonation_time_range[0]:最小爆轰到达时间。detonation_time_range[1]:最大爆轰到达时间。
C ABI 不暴露 Fortran 内部 allocatable 数组指针。
12.3 C++ wrapper
C++ wrapper 继续作为 C ABI 薄包装。新增 Explosive summary 结构体时,只表达 C ABI 返回数据,不重新定义反应模型。
12.4 Python ctypes
Python API 继续通过 C ABI 调用,用于:
- Explosive 输入 smoke。
- 点火点设置和 summary 读取。
- 反应进度 checker。
- CLI 输出 checker。
Python 不直接访问 Fortran 内部符号。
12.5 CLI
CLI inspect、check 和 run 模式应增加 Explosive 字段检查。建议输出或 summary CSV 包含:
explosive_particlesexplosive_reacted_particlesexplosive_lambda_minexplosive_lambda_maxexplosive_lambda_meanexplosive_released_massexplosive_released_energyexplosive_released_momentum_xexplosive_released_momentum_yexplosive_released_momentum_zexplosive_detonation_time_minexplosive_detonation_time_max
错误路径仍应向 stderr 输出 error_code 和 error_message。
13. 测试计划
13.1 新增 0.4.0 测试
建议新增以下测试:
input_explosive:TYPE=EXPLOSIVEmaterial、section、control 和 ignition 输入。input_explosive_errors:缺失密度、缺失 product Gas、非法爆速、非法 burn time、非法能量。explosive_detonation_time:按初始坐标和爆速计算td(i)。explosive_reaction_progress:programmed burn 下lambda单调增加并限制在[0,1]。explosive_release_source:反应进度增量产生质量、动量和能量源项。explosive_to_gas_phase:完全反应后 phase 不可逆转为 Gas。explosive_gas_coupling:产物 Gas material 使用 JWL EOS 并更新 Gas summary。explosive_summary:summary 字段和累计释放量一致。explosive_restart_040:0.4.0 restart 写入读回后继续显式步。explosive_restart_031_compat:读取 0.3.1 restart 并初始化空 Explosive 状态。explosive_c_api:C ABI 点火点和 summary 查询。explosive_python:Python ctypes 读取 Explosive summary。explosive_cli:CLI inspect/run 输出 Explosive 字段。explosive_source_size:新增模块和过程满足 source size gate。
13.2 既有回归测试
0.4.0 必须继续通过 0.3.1 默认 gate,包括 Water、Gas、restart、output、API、CLI、Python、CouplingInterface 占位和 source size。
13.3 建议 0.4.0 Release Gate
建议 0.4.0 默认 gate 为:
ctest --test-dir build-codex-unix --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
若新增测试命名较多,可额外单独运行:
ctest --test-dir build-codex-unix -R "^(input_explosive|input_explosive_errors|explosive_detonation_time|explosive_reaction_progress|explosive_release_source|explosive_to_gas_phase|explosive_gas_coupling|explosive_summary|explosive_restart_040|explosive_restart_031_compat|explosive_c_api|explosive_python|explosive_cli|explosive_source_size)$" --output-on-failure
14. 建议开发阶段
若后续根据本计划生成 todo.md,建议按以下阶段拆分:
- 0.4.0 版本号和 0.3.1 发布基线确认。
- Explosive 输入样例和错误输入样例准备。
PHASE_EXPLOSIVE、material type 和 section 校验加固。- Explosive material/control 数据结构。
- Ignition point 数据结构和输入解析。
- Product Gas material 映射和校验。
- 爆轰到达时间计算。
- Programmed burn 反应进度推进。
- 质量、动量和能量释放量累计。
- Gas source 注入路径。
- Gas phase 转化路径。
- 显式求解器中的 Explosive 更新挂接。
- Explosive summary 和 output 字段。
- 0.4.0 restart 写入。
- 0.4.0 restart 读回和 0.3.1 兼容读入。
- Fortran API 和 C ABI 追加接口。
- C++ wrapper、Python ctypes 和 CLI 扩展。
- Source size 例外复核和必要拆分。
- Water、Gas、Explosive 和 CouplingInterface 回归。
- README、06、09 和 11 号文档同步。
15. 验收标准
0.4.0 应满足以下验收标准:
- 软件版本为
0.4.0。 TYPE=EXPLOSIVEmaterial 可通过 Abaqus 风格.inp子集读取。- 点火点、爆速、反应能量、反应时间窗口和 product Gas material 可被校验。
- 爆轰到达时间按解析公式计算。
- 反应进度
lambda单调、不可逆,且限制在[0,1]。 - 反应增量可产生质量、动量和能量释放量。
- 释放量可进入
Gas源项缓存或触发产物 Gas phase 转化。 - 产物 Gas 使用
Gas模块 EOS 和 summary,不在Explosive中重复压力计算。 - 0.4.0 restart 可恢复 Explosive 反应状态并继续显式步。
- 0.3.1 restart 可兼容读入并初始化空 Explosive 状态。
- C ABI、C++ wrapper、Python ctypes 和 CLI 追加接口可用。
- Water/Gas 既有默认 gate 继续通过。
- 默认 gate、source size 和
git diff --check通过。 - 文档不宣称 0.4.0 已实现 Solid、Shell、真实 FEM-SPH 耦合或工程级水下爆炸 benchmark。
- 不新增 FEMLite 直接依赖。
- 不修改 SPHLite 文件夹之外的内容。
16. 风险与控制
| 风险 | 表现 | 控制方式 |
|---|---|---|
| 0.4.0 范围膨胀 | 试图同时实现工程级水下爆炸、结构破坏或耦合 | 只交付 Explosive 最小闭环和小型 gate |
| Explosive/Gas 边界混乱 | Explosive 重复实现 Gas EOS 或气泡诊断 | Explosive 只释放源项,Gas 负责 EOS 和气泡诊断 |
| phase 转化不一致 | 同一粒子在 restart 后 phase/material/lambda 不一致 | restart 保存 lambda、phase、product material 和已释放量 |
| 源项重复释放 | restart 或多步推进后重复计算同一反应增量 | 只按 delta_lambda 释放,并保存累计释放量 |
| 动量或能量量纲混乱 | 能量按总量和单位质量混用 | 输入字段明确 ENERGY 为单位质量能量,测试锁定累计值 |
| Water/Gas 回归漂移 | Explosive 路径影响非爆炸算例 | 对无 Explosive 输入直接跳过模块更新,默认 gate 全量回归 |
| C ABI 过早冻结内部结构 | 直接暴露 reaction array 或 material table | C ABI 只返回 summary 和测试所需稳定字段 |
| source size 债务扩大 | 新模块过程过长或例外过多 | 按 ignition、reaction、source、restart 拆分过程 |
17. 0.5.0 启动条件
满足以下条件后,可以启动 0.5.0 Solid:
- 0.4.0 Explosive 输入、点火、爆轰到达时间和反应进度稳定。
- Explosive 到 Gas 的质量、动量和能量释放路径稳定。
- Explosive/Gas restart 可重复读写并继续计算。
- Water/Gas/Explosive 默认 gate 可重复执行。
- 文档明确 0.4.0 尚未实现结构响应、破裂和真实 FEM-SPH 耦合。