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

16 KiB
Raw Permalink Blame History

SPHLite v3.1 开发计划

文档状态:0.3.1 开发计划草案

目标软件版本:SPHLite 0.3.1

1. 文档定位

本文档用于规划 SPHLite 0.3.1 版本的开发范围。0.3.1 是 0.3 Gas 版本线的稳定化和前置加固版本,目标是在 0.3.0 已发布的 Gas 最小闭环基础上,补强多 Gas material/EOS、Gas 源项占位、诊断一致性、restart 兼容性、接口覆盖和 release gate 可维护性。

0.3.1 不应演化为 0.4 Explosive。解析点火、爆轰到达时间、反应进度、炸药粒子 phase 转化和真实质量/动量/能量注入仍属于 0.4.0 或后续版本。

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

3. 版本定位

3.1 与 0.3.0 的关系

0.3.0 已完成 Gas 最小闭环,包括 Gas 输入、三类 EOS、状态初始化、单相显式推进、summary、bubble metrics、CSV output、restart、Fortran API、C ABI、C++ wrapper、Python ctypes、CLI 诊断字段和默认 gate。

0.3.1 应继承 0.3.0 的工程骨架和测试体系,并解决 0.3.0 中为快速闭环而保留的限制:

  • Gas EOS 状态更偏向单 Gas material。
  • Bubble metrics 仍是单气团近似。
  • Gas dt 估计和 sound speed 策略较保守。
  • Gas 诊断 API 暴露字段较少。
  • source_size 中已有必要例外,后续维护成本需要控制。
  • Explosive 到 Gas 的源项入口尚未形成模块级占位。

3.2 与 0.4.0 的关系

0.4.0 建议作为 Explosive 起点。0.3.1 应为 0.4.0 做准备,但不提前实现 Explosive 生产算法。0.3.1 可以交付:

  • Gas material 级 EOS 表。
  • Gas 源项缓存和清零/累计占位。
  • 从外部或后续 Explosive 模块向 Gas 施加源项的 Fortran 内部入口。
  • 能验证源项不会破坏 Water/Gas 既有 gate 的小型测试。

0.3.1 不交付:

  • 起爆点输入语义。
  • 爆轰传播。
  • programmed burn 反应进度。
  • Explosive 粒子向 Gas phase 的真实迁移。
  • 工程级气泡脉动 benchmark。

4. 开发原则

4.1 保持模块边界

SPHLite 仍只修改本仓库内容,不修改 FEMLite 或其他外部模块。SPHLite 不直接依赖 FEMLite,也不直接依赖外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。

4.2 保持求解器定位

SPHLite 仍是求解器,不负责几何建模、网格生成或粒子生成。0.3.1 可新增测试输入文件或测试辅助脚本,但不得将其宣传为求解器的粒子生成能力。

4.3 保持 Fortran 95 核心

核心实现继续使用 Fortran 95。C ABI、C++ wrapper 和 Python ctypes 仍作为薄接口层。0.3.1 不引入破坏可移植性的第三方运行时依赖。

4.4 保持显式动力学路线

时间推进仍只支持显式动力学,主积分格式为 Velocity-Verlet。不引入隐式求解器、静力求解器、Newmark 路线或隐式-显式混合求解接口。

4.5 保持 Abaqus 子集策略

输入文件继续解析 SPHLite 支持的 Abaqus .inp 明确子集。不追求完整 Abaqus 兼容。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的能力使用 *SPHLITE ... 扩展关键词。

4.6 保持 Water 与 Gas 独立

Water 和 Gas 共享集中型粒子数据库,但计算路径保持独立。0.3.1 新增 Gas 多材料、源项占位或诊断字段时,不得改变 Water 的 Tait EOS、连续性方程、Monaghan 人工黏性、负压保留和 pressure wave smoke 行为。

5. 0.3.1 交付目标

0.3.1 建议交付以下内容:

  1. 将软件版本更新为 0.3.1。
  2. 支持同一模型中存在多个 TYPE=GAS material,并为每个 Gas material 维护独立 EOS 类型和参数。
  3. 支持同一输入中同时存在空气类理想气体和爆轰产物类 JWL Gas material。
  4. 将 Gas 压力更新、dt 估计、summary 和 restart 改为 material/EOS 分派,避免单一全局 Gas EOS 限制。
  5. 建立 Gas 源项缓存占位,包括质量、动量和能量源项累计量。
  6. 建立 Gas 源项清零、累计和显式步应用的 Fortran 内部入口,但不实现 Explosive 反应。
  7. 将 Gas 源项状态写入 restart,并可读回后继续显式步。
  8. 扩展 Gas 诊断,补充质量、动量、密度范围、dt 分量和源项累计量的稳定查询路径。
  9. 保持 C ABI 兼容,新增接口只能追加,不能破坏 0.3.0 的 sphlite_get_gas_summary 和 sphlite_get_gas_bubble_metrics。
  10. 增强 Python 和 CLI 的 Gas inspect/run 输出检查。
  11. 复核 source_size 例外,优先通过小规模拆分或辅助过程降低例外数量。
  12. 保持 0.3.0 默认 gate 全部通过,并新增 0.3.1 Gas 稳定化 gate。
  13. 更新 README、09 号发布记录和 11 号验收矩阵。

6. 非交付范围

0.3.1 不交付以下内容:

  1. 不实现 Explosive 的解析点火、爆轰传播或 programmed burn。
  2. 不实现 Explosive 粒子的真实反应进度 lambda。
  3. 不实现炸药粒子向 Gas phase 的生产级迁移。
  4. 不实现工程级水-气多相 Riemann 通量。
  5. 不实现复杂水-气界面重构、锐界面追踪或相变蒸发。
  6. 不实现生产级气泡多周期脉动 benchmark。
  7. 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。
  8. 不实现 Shell 的 Mindlin-Reissner 生产求解路径。
  9. 不实现真实 FEM-SPH 接触耦合或连续体耦合。
  10. 不暴露未冻结的 CouplingInterface C ABI。
  11. 不新增几何、网格或粒子生成能力。

7. 输入范围

7.1 继承 0.3.0 Gas 输入

0.3.1 继续支持 0.3.0 的 Gas 输入形式:

*MATERIAL, NAME=GAS_NAME, TYPE=GAS
*DENSITY
rho0
*SECTION, ELSET=GAS_PARTICLES, MATERIAL=GAS_NAME
*SPHLITE EOS, TYPE=IDEAL_GAS, MATERIAL=GAS_NAME, GAMMA=..., E0=..., P0=...
*SPHLITE EOS, TYPE=JWL, MATERIAL=GAS_NAME, RHO0=..., A=..., B=..., R1=..., R2=..., OMEGA=..., E0=...
*SPHLITE EOS, TYPE=STIFFENED_GAS, MATERIAL=GAS_NAME, RHO0=..., GAMMA=..., E0=..., PINF=...
*SPHLITE PARTICLE CONTROL, H=..., MASS=..., VOLUME=...
*SPHLITE BODY FORCE, X=..., Y=..., Z=...
*SPHLITE TIME CONTROL, DT=..., TIME=..., STEPS=..., SAFETY=...

7.2 多 Gas material 输入

0.3.1 应支持以下输入组合:

*MATERIAL, NAME=AIR, TYPE=GAS
*DENSITY
1.2
*SECTION, ELSET=AIR_PARTICLES, MATERIAL=AIR
*SPHLITE EOS, TYPE=IDEAL_GAS, MATERIAL=AIR, GAMMA=1.4, E0=...

*MATERIAL, NAME=PRODUCTS, TYPE=GAS
*DENSITY
1600.0
*SECTION, ELSET=PRODUCT_PARTICLES, MATERIAL=PRODUCTS
*SPHLITE EOS, TYPE=JWL, MATERIAL=PRODUCTS, RHO0=..., A=..., B=..., R1=..., R2=..., OMEGA=..., E0=...

每个 TYPE=GAS material 必须具备:

  • *DENSITY。
  • 对应 MATERIAL=... 的 *SPHLITE EOS。
  • 至少一个 section 绑定,或明确没有 active 粒子时作为 warning/诊断处理。

7.3 Gas 源项输入策略

0.3.1 不建议新增用户可见的 Explosive 源项输入语义。若需要为测试创建源项,可采用以下两种方式之一:

  • Fortran 模块级测试直接调用 Gas 源项内部入口。
  • 使用 *SPHLITE GAS SOURCE 作为测试性扩展关键词,但默认文档中标记为实验性,不作为 0.3.1 稳定用户接口。

若实现实验性关键词,应保证缺失或非法字段报 error,不影响运行的未来字段 warning 后跳过。

8. Gas 多材料状态

0.3.1 应将 Gas EOS 状态从单一全局记录扩展为 material 级记录。建议状态包括:

  • Gas material 数量。
  • Gas material 内部 id。
  • Gas material 名称。
  • 每个 Gas material 的 EOS 类型。
  • 每个 Gas material 的密度、内能、温度默认值。
  • 理想气体参数表。
  • JWL 参数表。
  • Stiffened gas 参数表。
  • 每个 Gas material 的默认 h、mass、volume 控制策略。
  • 每个 Gas material 的外部体力或共享外部体力策略。

压力更新时必须根据粒子的 material_id 查找对应 EOS,而不是使用单一全局 Gas EOS。若 Gas 粒子的 material 没有 EOS,应报 error。

9. Gas 源项占位

0.3.1 应为 0.4.0 Explosive 预留 Gas 源项状态,但不实现 Explosive 反应。建议最小状态为:

real(rk), allocatable :: gas_mass_source(:)
real(rk), allocatable :: gas_energy_source(:)
real(rk), allocatable :: gas_momentum_source(:,:)

数组形状:

  • gas_mass_source(npart)。
  • gas_energy_source(npart)。
  • gas_momentum_source(3,npart)。

建议内部入口:

  • sph_gas_clear_sources。
  • sph_gas_add_source_by_particle。
  • sph_gas_apply_sources_explicit。
  • sph_gas_get_source_summary。

源项应用第一版只要求小规模守恒检查:

  • 质量源项增加 Gas 粒子质量或等效诊断质量。
  • 能量源项增加 Gas 粒子内能或等效能量状态。
  • 动量源项改变 Gas 粒子速度或动量诊断。
  • 非 Gas 粒子源项应报 error 或被明确拒绝。

具体能量到压力的物理转换仍以 Gas EOS 为准,不引入 Explosive 反应模型。

10. Gas 诊断扩展

0.3.1 应保持 0.3.0 诊断字段:

  • gas_particles
  • gas_mass
  • gas_volume
  • gas_center_x
  • gas_center_y
  • gas_center_z
  • gas_mean_pressure
  • gas_max_pressure
  • gas_equivalent_radius
  • gas_radius_rate
  • gas_dtcrit

建议新增或确认以下诊断:

  • gas_momentum_x
  • gas_momentum_y
  • gas_momentum_z
  • gas_min_density
  • gas_max_density
  • gas_dt_cfl
  • gas_dt_accel
  • gas_source_mass
  • gas_source_energy
  • gas_source_momentum_x
  • gas_source_momentum_y
  • gas_source_momentum_z

新增 C ABI 时应避免破坏已有函数,可新增:

int sphlite_get_gas_extended_summary(double *mass,
                                     double *momentum,
                                     double *density_range,
                                     double *source_totals);

若字段尚未冻结,可先通过 Fortran API、Python debug 和 CLI 输出覆盖,C ABI 只追加最稳定字段。

11. Restart 和兼容策略

0.3.1 应更新 restart 状态策略:

  • 新写入状态建议为 STATE_0_3_1 或继续 STATE_0_3 并在文件内增加 Gas state revision。
  • 必须能读取 0.3.0 的 STATE_0_3 restart。
  • 若读取 0.3.0 restart,缺失的多材料 EOS 表和源项状态应明确初始化为 0.3.1 默认值。
  • 读回后必须重建邻域。
  • 读回后必须能继续显式步。

restart 应保存:

  • Gas material/EOS 表。
  • Gas 默认粒子控制状态。
  • Gas 外部体力。
  • Gas 源项缓存。
  • Gas summary 诊断。
  • bubble metrics 历史状态。
  • Gas dt 诊断。
  • 粒子通用状态中的 pressure、internal_energy、temperature、rho、volume、h、mass、v 和 vhalf。

12. API、C ABI、C++、Python 和 CLI

12.1 Fortran API

建议新增或完善:

  • sph_get_gas_extended_summary
  • sph_get_gas_source_summary
  • sph_gas_clear_sources
  • sph_gas_add_source_by_particle
  • sph_gas_apply_sources_explicit

12.2 C ABI

C ABI 继续保持追加式设计。0.3.1 不破坏:

  • sphlite_get_gas_summary
  • sphlite_get_gas_bubble_metrics
  • sphlite_get_gas_dt_limits

可新增稳定诊断接口,但不暴露 Fortran 内部数组指针。

12.3 C++ wrapper

C++ wrapper 继续作为 C ABI 薄包装。新增结构体只表达 C ABI 返回数据,不重新定义 Gas 物理语义。

12.4 Python ctypes

Python API 继续通过 C ABI 调用,用于:

  • 多 Gas material 输入 smoke。
  • Gas source 调试。
  • Gas extended summary 检查。
  • CLI 输出 checker。

Python 不直接访问 Fortran 内部符号。

12.5 CLI

CLI inspect、check 和 run 模式应继续输出 0.3.0 Gas 字段。若 0.3.1 新增 extended 字段,应保证:

  • Water-only 输入输出字段仍稳定。
  • Gas-only 输入输出字段可检查。
  • Water/Gas 混合输入输出字段可检查。
  • 错误路径仍向 stderr 输出 error_code 和 error_message。

13. 测试计划

13.1 新增 0.3.1 测试

建议新增以下测试:

  • input_gas_multimaterial:多个 Gas material、多个 section、多个 EOS。
  • gas_eos_dispatch:按粒子 material 分派理想气体、JWL 和 Stiffened gas。
  • gas_source:质量、动量、能量源项清零、累计和应用。
  • gas_source_errors:非 Gas 粒子、非法粒子 id、非法源项数值。
  • gas_extended_summary:质量、动量、密度范围、源项累计量。
  • gas_restart_031:多 Gas material 和源项状态 restart。
  • gas_restart_030_compat:读取 0.3.0 STATE_0_3 restart 的兼容路径。
  • gas_cli_extended:CLI inspect/run 的新增 Gas 字段。
  • gas_python_extended:Python ctypes 的新增 Gas 字段。
  • gas_source_size_cleanup:确认 source size 例外没有 stale 项。

13.2 既有回归测试

0.3.1 必须继续通过 0.3.0 默认 gate:

  • smoke
  • input
  • input_gas
  • kernel
  • neighbor
  • water_eos
  • water_density
  • water_viscosity
  • water_force
  • solver_water
  • gas_eos_ideal
  • gas_eos_jwl
  • gas_eos_stiffened
  • gas_state
  • gas_summary
  • solver_gas
  • output
  • gas_output
  • restart
  • gas_restart
  • coupling_interface
  • c_api
  • cpp_api
  • python_debug
  • cli
  • pressure_wave_smoke
  • source_size

13.3 建议 0.3.1 Release Gate

建议 0.3.1 默认 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

若新增测试命名较多,也可使用明确正则列出 0.3.0 gate 与 0.3.1 新增 gate。实现完成后应同步更新 06、09、11 号文档。

14. 建议开发阶段

若后续根据本计划生成 todo.md,建议按以下阶段拆分:

  1. 0.3.1 版本号和 0.3.0 发布基线确认。
  2. 多 Gas material 输入文件和错误输入文件准备。
  3. Gas material/EOS 表数据结构。
  4. Gas EOS material 分派。
  5. Gas 状态初始化按 material 分派。
  6. Gas dt 和 sound speed 策略按 material 分派。
  7. Gas summary 和 extended summary。
  8. Gas 源项状态和内部入口。
  9. Gas 源项显式应用小步测试。
  10. Gas output 扩展字段。
  11. Gas restart 0.3.1 状态写入。
  12. 0.3.0 restart 兼容读入。
  13. Fortran API 和 C ABI 追加接口。
  14. C++ wrapper、Python ctypes 和 CLI 扩展。
  15. Source size 例外复核和必要拆分。
  16. Water、Gas 和 CouplingInterface 回归。
  17. README、09 和 11 号文档同步。

15. 验收标准

0.3.1 应满足以下验收标准:

  1. 软件版本为 0.3.1。
  2. 同一模型可包含多个 Gas material 和不同 EOS。
  3. Gas 压力、dt、summary 和 restart 按 material 正确分派。
  4. Gas 源项缓存可清零、累计、应用和诊断。
  5. Gas 源项不会误作用到 Water、Solid、Shell 或 inactive/failed 粒子。
  6. 0.3.0 Gas summary、bubble metrics、output、restart 和接口继续兼容。
  7. 0.3.0 STATE_0_3 restart 可读入,并初始化 0.3.1 新状态默认值。
  8. Water 默认 gate 继续通过。
  9. 默认 gate、source size 和 git diff --check 通过。
  10. 文档不宣称 0.3.1 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合能力。
  11. 不新增 FEMLite 直接依赖。
  12. 不修改 SPHLite 文件夹之外的内容。

16. 风险与控制

风险 表现 控制方式
0.3.1 范围膨胀 提前实现 Explosive 点火、爆轰或反应进度 只做 Gas 源项占位和小型守恒测试
多 Gas EOS 分派错误 空气粒子使用 JWL 或产物气体使用理想气体参数 用混合 Gas material 输入和逐粒子压力测试锁定
restart 不兼容 0.3.0 restart 无法读入或新状态丢失 建立 gas_restart_030_compat 和 gas_restart_031
Water 行为漂移 Gas 源项或全局数组改动影响 Water 单相结果 Water gate 与 Gas gate 一起运行
C ABI 过早暴露内部结构 多材料表或源项数组冻结过早 C ABI 只追加稳定 summary,不暴露内部数组指针
source size 债务扩大 继续增加例外导致维护困难 优先拆分长过程,例外需有 stale 检查
Bubble 诊断被过度解释 单气团或多材料 smoke 被误认为工程 benchmark 文档继续明确为小规模链路检查

17. 0.4.0 启动条件

满足以下条件后,可以启动 0.4.0 Explosive:

  1. 0.3.1 多 Gas material/EOS 分派稳定。
  2. Gas 源项缓存、诊断、restart 和小型应用测试稳定。
  3. Gas 可接收质量、动量和能量源项而不破坏 Water/Gas gate。
  4. 默认 gate 可重复执行。
  5. 文档明确 Explosive 作用到 Gas 后形成 Bubble 的长期路线。