16 KiB
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.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.0_development_plan.mddocs/09_release_history.mddocs/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 建议交付以下内容:
- 将软件版本更新为
0.3.1。 - 支持同一模型中存在多个
TYPE=GASmaterial,并为每个 Gas material 维护独立 EOS 类型和参数。 - 支持同一输入中同时存在空气类理想气体和爆轰产物类 JWL Gas material。
- 将 Gas 压力更新、dt 估计、summary 和 restart 改为 material/EOS 分派,避免单一全局 Gas EOS 限制。
- 建立 Gas 源项缓存占位,包括质量、动量和能量源项累计量。
- 建立 Gas 源项清零、累计和显式步应用的 Fortran 内部入口,但不实现 Explosive 反应。
- 将 Gas 源项状态写入 restart,并可读回后继续显式步。
- 扩展 Gas 诊断,补充质量、动量、密度范围、dt 分量和源项累计量的稳定查询路径。
- 保持 C ABI 兼容,新增接口只能追加,不能破坏 0.3.0 的
sphlite_get_gas_summary和sphlite_get_gas_bubble_metrics。 - 增强 Python 和 CLI 的 Gas inspect/run 输出检查。
- 复核
source_size例外,优先通过小规模拆分或辅助过程降低例外数量。 - 保持 0.3.0 默认 gate 全部通过,并新增 0.3.1 Gas 稳定化 gate。
- 更新 README、09 号发布记录和 11 号验收矩阵。
6. 非交付范围
0.3.1 不交付以下内容:
- 不实现 Explosive 的解析点火、爆轰传播或 programmed burn。
- 不实现 Explosive 粒子的真实反应进度
lambda。 - 不实现炸药粒子向 Gas phase 的生产级迁移。
- 不实现工程级水-气多相 Riemann 通量。
- 不实现复杂水-气界面重构、锐界面追踪或相变蒸发。
- 不实现生产级气泡多周期脉动 benchmark。
- 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。
- 不实现 Shell 的 Mindlin-Reissner 生产求解路径。
- 不实现真实 FEM-SPH 接触耦合或连续体耦合。
- 不暴露未冻结的 CouplingInterface C ABI。
- 不新增几何、网格或粒子生成能力。
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_particlesgas_massgas_volumegas_center_xgas_center_ygas_center_zgas_mean_pressuregas_max_pressuregas_equivalent_radiusgas_radius_rategas_dtcrit
建议新增或确认以下诊断:
gas_momentum_xgas_momentum_ygas_momentum_zgas_min_densitygas_max_densitygas_dt_cflgas_dt_accelgas_source_massgas_source_energygas_source_momentum_xgas_source_momentum_ygas_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_3restart。 - 若读取 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_summarysph_get_gas_source_summarysph_gas_clear_sourcessph_gas_add_source_by_particlesph_gas_apply_sources_explicit
12.2 C ABI
C ABI 继续保持追加式设计。0.3.1 不破坏:
sphlite_get_gas_summarysphlite_get_gas_bubble_metricssphlite_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.0STATE_0_3restart 的兼容路径。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:
smokeinputinput_gaskernelneighborwater_eoswater_densitywater_viscositywater_forcesolver_watergas_eos_idealgas_eos_jwlgas_eos_stiffenedgas_stategas_summarysolver_gasoutputgas_outputrestartgas_restartcoupling_interfacec_apicpp_apipython_debugclipressure_wave_smokesource_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,建议按以下阶段拆分:
- 0.3.1 版本号和 0.3.0 发布基线确认。
- 多 Gas material 输入文件和错误输入文件准备。
- Gas material/EOS 表数据结构。
- Gas EOS material 分派。
- Gas 状态初始化按 material 分派。
- Gas dt 和 sound speed 策略按 material 分派。
- Gas summary 和 extended summary。
- Gas 源项状态和内部入口。
- Gas 源项显式应用小步测试。
- Gas output 扩展字段。
- Gas restart 0.3.1 状态写入。
- 0.3.0 restart 兼容读入。
- Fortran API 和 C ABI 追加接口。
- C++ wrapper、Python ctypes 和 CLI 扩展。
- Source size 例外复核和必要拆分。
- Water、Gas 和 CouplingInterface 回归。
- README、09 和 11 号文档同步。
15. 验收标准
0.3.1 应满足以下验收标准:
- 软件版本为
0.3.1。 - 同一模型可包含多个 Gas material 和不同 EOS。
- Gas 压力、dt、summary 和 restart 按 material 正确分派。
- Gas 源项缓存可清零、累计、应用和诊断。
- Gas 源项不会误作用到 Water、Solid、Shell 或 inactive/failed 粒子。
- 0.3.0 Gas summary、bubble metrics、output、restart 和接口继续兼容。
- 0.3.0
STATE_0_3restart 可读入,并初始化 0.3.1 新状态默认值。 - Water 默认 gate 继续通过。
- 默认 gate、source size 和
git diff --check通过。 - 文档不宣称 0.3.1 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合能力。
- 不新增 FEMLite 直接依赖。
- 不修改 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:
- 0.3.1 多 Gas material/EOS 分派稳定。
- Gas 源项缓存、诊断、restart 和小型应用测试稳定。
- Gas 可接收质量、动量和能量源项而不破坏 Water/Gas gate。
- 默认 gate 可重复执行。
- 文档明确 Explosive 作用到 Gas 后形成 Bubble 的长期路线。