Files
SPHLite/docs/v4.0_development_plan.md
T
2026-07-03 11:50:07 +08:00

21 KiB
Raw Blame History

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.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.1_development_plan.md
  • docs/09_release_history.md
  • docs/10_development_roadmap.md
  • docs/11_benchmark_matrix.md

3. 版本定位

3.1 与 0.3.1 的关系

0.3.1 已完成 Gas 稳定化和 0.4.0 前置条件:

  • 多个 TYPE=GAS material 可各自绑定 EOS。
  • JWL、理想气体和 Stiffened gas 可按 material 分派。
  • Gas 具备质量、动量和能量源项缓存。
  • Gas 源项可清零、累计、应用和诊断。
  • Gas restart、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 建议交付以下内容:

  1. 将软件版本更新为 0.4.0。
  2. 新增 Explosive 模块骨架和生命周期 reset/build/advance/finalize 路径。
  3. 支持 TYPE=EXPLOSIVE material 和 explosive section 的输入识别。
  4. 支持炸药密度、爆速、单位质量能量、反应时间窗口和产物 Gas material 映射。
  5. 支持至少一个解析点火点,包括坐标和起爆时间。
  6. 按初始坐标计算炸药粒子的爆轰到达时间 td(i)。
  7. 保存并推进不可逆反应进度 lambda(i),范围为 0 <= lambda <= 1。
  8. 由反应进度增量生成质量、动量和能量释放量。
  9. 将释放量写入 0.3.1 已有的 Gas 源项缓存,并通过显式步应用到产物 Gas 状态。
  10. 支持炸药粒子不可逆转化为产物 Gas phase 的最小路径。
  11. 保留源项注入路径,用于炸药粒子不立即改变 phase 的测试和后续扩展。
  12. 输出 explosive summary,包括反应粒子数、平均反应进度、释放质量、释放能量和爆轰到达时间范围。
  13. 将 Explosive 状态写入 0.4.0 restart,并可读回继续显式步。
  14. 保持 C ABI 追加式兼容,新增 Explosive 查询接口不得破坏既有 Water/Gas 接口。
  15. 增强 Python 和 CLI,使其可以检查 explosive 输入、运行和 summary 字段。
  16. 新增 0.4.0 Explosive 默认 gate,并保持 0.3.1 默认 gate 全部通过。
  17. 更新 README、06、09 和 11 号文档中的 0.4.0 测试和验收记录。

6. 非交付范围

0.4.0 不交付以下内容:

  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 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_reset
  • sph_explosive_build
  • sph_explosive_compute_detonation_times
  • sph_explosive_advance
  • sph_get_explosive_summary
  • sph_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_particles
  • explosive_reacted_particles
  • explosive_lambda_min
  • explosive_lambda_max
  • explosive_lambda_mean
  • explosive_released_mass
  • explosive_released_energy
  • explosive_released_momentum_x
  • explosive_released_momentum_y
  • explosive_released_momentum_z
  • explosive_detonation_time_min
  • explosive_detonation_time_max

错误路径仍应向 stderr 输出 error_code 和 error_message。

13. 测试计划

13.1 新增 0.4.0 测试

建议新增以下测试:

  • input_explosive:TYPE=EXPLOSIVE material、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,建议按以下阶段拆分:

  1. 0.4.0 版本号和 0.3.1 发布基线确认。
  2. Explosive 输入样例和错误输入样例准备。
  3. PHASE_EXPLOSIVE、material type 和 section 校验加固。
  4. Explosive material/control 数据结构。
  5. Ignition point 数据结构和输入解析。
  6. Product Gas material 映射和校验。
  7. 爆轰到达时间计算。
  8. Programmed burn 反应进度推进。
  9. 质量、动量和能量释放量累计。
  10. Gas source 注入路径。
  11. Gas phase 转化路径。
  12. 显式求解器中的 Explosive 更新挂接。
  13. Explosive summary 和 output 字段。
  14. 0.4.0 restart 写入。
  15. 0.4.0 restart 读回和 0.3.1 兼容读入。
  16. Fortran API 和 C ABI 追加接口。
  17. C++ wrapper、Python ctypes 和 CLI 扩展。
  18. Source size 例外复核和必要拆分。
  19. Water、Gas、Explosive 和 CouplingInterface 回归。
  20. README、06、09 和 11 号文档同步。

15. 验收标准

0.4.0 应满足以下验收标准:

  1. 软件版本为 0.4.0。
  2. TYPE=EXPLOSIVE material 可通过 Abaqus 风格 .inp 子集读取。
  3. 点火点、爆速、反应能量、反应时间窗口和 product Gas material 可被校验。
  4. 爆轰到达时间按解析公式计算。
  5. 反应进度 lambda 单调、不可逆,且限制在 [0,1]。
  6. 反应增量可产生质量、动量和能量释放量。
  7. 释放量可进入 Gas 源项缓存或触发产物 Gas phase 转化。
  8. 产物 Gas 使用 Gas 模块 EOS 和 summary,不在 Explosive 中重复压力计算。
  9. 0.4.0 restart 可恢复 Explosive 反应状态并继续显式步。
  10. 0.3.1 restart 可兼容读入并初始化空 Explosive 状态。
  11. C ABI、C++ wrapper、Python ctypes 和 CLI 追加接口可用。
  12. Water/Gas 既有默认 gate 继续通过。
  13. 默认 gate、source size 和 git diff --check 通过。
  14. 文档不宣称 0.4.0 已实现 Solid、Shell、真实 FEM-SPH 耦合或工程级水下爆炸 benchmark。
  15. 不新增 FEMLite 直接依赖。
  16. 不修改 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:

  1. 0.4.0 Explosive 输入、点火、爆轰到达时间和反应进度稳定。
  2. Explosive 到 Gas 的质量、动量和能量释放路径稳定。
  3. Explosive/Gas restart 可重复读写并继续计算。
  4. Water/Gas/Explosive 默认 gate 可重复执行。
  5. 文档明确 0.4.0 尚未实现结构响应、破裂和真实 FEM-SPH 耦合。