Files
CCLite/SPHLite/docs/v4.1_development_plan.md
2026-07-05 22:48:27 +08:00

19 KiB
Raw Permalink Blame History

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 稳定化闭环:

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 的多个点火记录:

*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 可拥有独立:

  • *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 建议新增每粒子反应质量基准:

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_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 的数组长度约定:

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 为:

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 耦合。