15 KiB
SPHLite v3.0 开发计划
文档状态:0.3.0 开发计划草案
目标软件版本:SPHLite 0.3.0
1. 文档定位
本文档用于规划 SPHLite 0.3.0 版本的开发范围。0.3.0 是 Gas 模块的第一个正式开发版本,目标是在 0.2.2 Water 稳定化基线之上,建立气体粒子的输入、状态、EOS、显式推进、诊断、输出、restart 和接口最小闭环。
0.3.0 不应演化为水下爆炸综合版本。爆炸点火、反应进度、向气体注入质量/能量、结构响应、板壳破裂和真实 FEM-SPH 联合运行仍属于后续版本。
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/v2.2_development_plan.mddocs/v3.0_gas_handoff.md
3. 版本定位
3.1 与 0.2.2 的关系
0.2.2 已完成 Water 阶段稳定化补丁,默认 gate、source size 和发布记录均已通过。0.3.0 应继承 0.2.2 的工程骨架、集中数据库、输入解析、邻域搜索、Velocity-Verlet 显式推进、CSV 输出、restart、C ABI、C++ wrapper、Python ctypes 和 CLI。
0.3.0 不应破坏 0.2.2 的 Water 行为。所有新增 Gas 能力必须与已有 Water gate 一起通过。
3.2 与 0.4 的关系
0.4 版本应作为 Explosive 模块开发起点。0.3.0 可以为 Explosive 到 Gas 的质量、动量和能量注入预留状态、接口和诊断字段,但不实现解析点火、爆轰传播、programmed burn 或炸药粒子反应。
4. 开发原则
4.1 保持模块边界
SPHLite 仍只修改本仓库内容,不修改 FEMLite 或其他外部模块。SPHLite 不直接依赖 FEMLite,也不直接依赖外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
4.2 保持求解器定位
SPHLite 是求解器,不负责几何建模、网格生成或粒子生成。0.3.0 的 Gas 输入文件可由测试或示例脚本生成,但生成器不作为求解器功能宣传或交付。
4.3 保持 Fortran 95 核心
核心实现继续使用 Fortran 95,C ABI、C++ wrapper 和 Python ctypes 仍作为薄接口层。0.3.0 不引入破坏可移植性的第三方运行时依赖。
4.4 保持显式动力学路线
时间推进仍只支持显式动力学,主积分格式为 Velocity-Verlet。0.3.0 不引入隐式求解器、静力求解器或 Newmark 路线。
4.5 保持 Abaqus 子集策略
输入文件继续解析 SPHLite 支持的 Abaqus .inp 明确子集。不追求完整 Abaqus 兼容。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的能力使用 *SPHLITE ... 扩展关键词。
4.6 保持 Water 与 Gas 独立
Water 和 Gas 共享集中型粒子数据库,但计算路径保持独立。Gas 新增状态、EOS、诊断和测试不得改变 Water 的 Tait EOS、连续性方程、人工黏性、负压保留和 pressure wave smoke 行为。
5. 0.3.0 交付目标
0.3.0 建议交付以下内容:
- 将软件版本更新为
0.3.0。 - 解析
TYPE=GASmaterial 和 Gas 相关.inp输入。 - 建立 Gas 粒子的 phase、材料、密度、压力、内能、温度、质量、体积和光滑长度初始化路径。
- 实现 Gas EOS 的最小闭环:理想气体、JWL 和 Stiffened gas。
- 实现 Gas 单相显式推进最小路径,包括压力更新、密度变化率、压力力或等价加速度贡献。
- 实现 Gas summary,包括气体质量、体积、中心、动量、平均压力、最大压力、密度范围和稳定时间步诊断。
- 实现气泡诊断入口,包括等效气泡半径、半径变化率和中心迁移指标。
- 将 Gas 状态写入 CSV 输出和 restart,并可读回后继续显式步。
- 扩展 Fortran API、C ABI、C++ wrapper、Python ctypes 和 CLI 的 Gas 诊断查询。
- 建立 Gas 默认 gate,同时保持 0.2.2 Water gate 全部通过。
- 更新 README、09 号发布记录和 11 号验收矩阵。
6. 非交付范围
0.3.0 不交付以下内容:
- 不实现 Explosive 的解析点火、爆轰传播或反应进度。
- 不实现 Explosive 向 Gas 的真实质量、动量和能量注入。
- 不实现生产级气泡多周期脉动 benchmark。
- 不实现复杂水-气界面重构、锐界面追踪、相变蒸发或多相 Riemann 通量。
- 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。
- 不实现 Shell 的 Mindlin-Reissner 生产求解路径。
- 不实现真实 FEM-SPH 接触耦合或连续体耦合。
- 不暴露未冻结的 CouplingInterface C ABI。
- 不新增几何、网格或粒子生成能力。
- 不把测试 smoke 宣称为工程精度 benchmark。
7. 输入范围
7.1 复用 Abaqus 关键词
0.3.0 应继续复用以下 Abaqus 风格关键词:
*NODE*ELEMENT*NSET*ELSET*MATERIAL*DENSITY*SECTION或已支持的 section 关键词
Gas 粒子类型通过 material 和 section 识别,set 仍只表示集合,不参与类型判断。
7.2 Gas 扩展关键词
建议 0.3.0 支持以下 *SPHLITE 扩展:
*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=...
若字段缺失导致 Gas 无法运行,应报 error。不影响运行的未支持字段可 warning 后跳过。
7.3 EOS 字段策略
理想气体第一版建议采用内能形式:
p = (gamma - 1) * rho * e + p0gamma > 1rho > 0e >= 0
JWL 第一版建议采用相对体积形式:
V = rho0 / rhop = A * exp(-R1 * V) + B * exp(-R2 * V) + omega * e / Vrho0 > 0A、B、R1、R2、omega和E0由输入给定并校验。
Stiffened gas 第一版建议采用内能形式,并在实现时锁定公式和字段命名。若实现过程中发现字段约定不足,应先补测试和文档,再进入默认 gate。
8. 数据库和 Gas 状态
Gas 应共享集中型数据库中的通用粒子状态:
particle_id_extparticle_phaseparticle_statusmaterial_idsection_idx0xvavhalfmassrhovolumepressureinternal_energytemperatureh
Gas 模块应维护以下模块状态:
- Gas material 名称和内部 id。
- Gas EOS 类型。
- 理想气体参数。
- JWL 参数。
- Stiffened gas 参数。
- Gas 默认粒子控制参数。
- Gas 外部体力。
- Gas 质量、动量、体积、中心和压力诊断。
- Gas 等效气泡半径、半径变化率和中心迁移诊断。
- Gas 稳定时间步约束。
0.3.0 可以先不实现气体团簇连通分量算法。若不实现,等效气泡半径按所有 active Gas 粒子总体积计算,并在文档中说明这是单气团近似。
9. Gas 数值路径
9.1 Gas 压力更新
Gas 压力由 EOS 和当前密度、内能或温度状态更新。第一版应保证:
- 非 Gas 粒子不被 Gas EOS 更新。
- inactive 或 failed 粒子不参与 Gas 计算。
- 非法密度、非法内能或非法 EOS 参数报 error。
- 压力计算结果必须有限。
9.2 Gas 密度与动量更新
0.3.0 应建立 Gas 单相显式推进最小路径:
- 使用已有邻域搜索和核函数。
- 使用 phase 过滤,只处理 active Gas 粒子。
- 密度变化率优先采用连续性方程路线。
- 压力力使用与 Gas EOS 一致的压力状态。
- 外部体力进入显式步加速度合成。
复杂水-气界面压力交换可以预留,但不作为 0.3.0 默认交付要求。若实现简单水-气相互作用,应进入独立 smoke,并不得破坏 Water 单相回归。
9.3 气泡诊断
0.3.0 的 Bubble 只作为 Gas 诊断,不作为独立模块。最小诊断包括:
- Gas 总体积。
- Gas 中心。
- Gas 平均压力。
- Gas 最大压力。
- 等效气泡半径。
- 等效半径变化率。
- 中心迁移距离或中心速度。
等效半径可先按球体体积公式计算:
R_eq = (3 * V_gas / (4 * pi))^(1/3)
半径变化率可由当前和上一输出/上一时间步的等效半径差分得到。restart 应保存计算半径变化率所需的历史量。
10. 输出和 Restart
10.1 输出
0.3.0 继续使用 CSV 和 summary CSV 作为默认 gate 输出。不要求新增 VTK 生产输出。
粒子 CSV 继续输出通用粒子字段。summary CSV 应新增或确认包含:
gas_particlesgas_massgas_volumegas_center_xgas_center_ygas_center_zgas_mean_pressuregas_max_pressuregas_equivalent_radiusgas_radius_rategas_dtcrit
10.2 Restart
restart 应保存 Gas 模块级状态,至少包括:
- Gas EOS 类型和参数。
- Gas 默认粒子控制参数。
- Gas 外部体力。
- Gas 诊断量。
- 等效气泡半径历史量。
- Gas 稳定时间步约束。
- 粒子通用状态中的 pressure、internal_energy、temperature、rho、volume 和 h。
0.3.0 可以继续沿用当前 restart 文本格式,但必须更新状态版本策略或在发布记录中说明 STATE_0_2 是否仍适用于 0.3.0。若新增 Gas 状态导致旧格式不可兼容,应明确报 error,不静默读取错误状态。
11. API、C ABI、C++、Python 和 CLI
11.1 Fortran API
建议新增或完善:
sph_get_gas_summarysph_get_gas_bubble_metricssph_get_gas_dt_limits
11.2 C ABI
建议实现 05 号文档中的 Gas 诊断接口:
int sphlite_get_gas_summary(double *volume,
double *center,
double *mean_pressure,
double *max_pressure);
int sphlite_get_gas_bubble_metrics(double *equivalent_radius,
double *radius_rate,
double *center);
如需补充质量、动量或 dt 诊断,优先新增保持中立语义的 sphlite_get_gas_dt_limits 或扩展 Fortran/Python 调试接口,避免破坏已有 C ABI。
11.3 C++ wrapper
C++ wrapper 继续作为 C ABI 薄包装,只增加轻量结构体和 RAII 使用示例,不重新定义 Gas 物理语义。
11.4 Python ctypes
Python API 继续通过 C ABI 调用,用于:
- Gas 输入 smoke。
- Gas EOS 检查。
- Gas summary 和 bubble metrics 读取。
- CLI 输出 checker。
Python 不直接访问 Fortran 内部符号。
11.5 CLI
CLI inspect、check 和 run 模式应增加 Gas 诊断字段。CLI 不应绕过公共生命周期接口。
建议 CLI 输出字段包括:
gas_particlesgas_volumegas_mean_pressuregas_max_pressuregas_equivalent_radiusgas_dtcrit
12. 测试计划
12.1 新增 Gas 测试
建议新增以下测试:
input_gas:Gas material、Gas EOS、缺失字段、warning/error。gas_eos_ideal:理想气体压力、非法参数和有限性。gas_eos_jwl:JWL 压力、相对体积、非法参数和有限性。gas_eos_stiffened:Stiffened gas 压力、非法参数和有限性。gas_state:Gas phase、状态初始化、非 Gas 跳过。gas_summary:质量、体积、中心、压力和等效半径。solver_gas:Gas 单相显式步、dt 诊断和状态有限性。gas_output:Gas summary CSV 字段。gas_restart:Gas restart 写入、读回和继续显式步。
12.2 既有回归测试
0.3.0 必须继续通过 0.2.2 默认 gate:
smokeinputkernelneighborwater_eoswater_densitywater_viscositywater_forcesolver_wateroutputrestartcoupling_interfacec_apicpp_apipython_debugclipressure_wave_smokesource_size
12.3 建议 0.3.0 Release Gate
建议 0.3.0 默认 gate 为:
ctest --test-dir build-codex-unix -R "^(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)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
若实际测试名称在实现中调整,应同步更新 06、09、11 号文档。
13. 建议开发阶段
若后续根据本计划生成 todo.md,建议按以下阶段拆分:
- 0.3.0 版本号和基线确认。
- Gas 输入测试数据准备。
- Gas 输入解析和校验。
- Gas 数据库状态和模块初始化。
- 理想气体 EOS。
- JWL EOS。
- Stiffened gas EOS。
- Gas 压力更新和 summary。
- Gas 气泡诊断。
- Gas 单相显式推进。
- Gas 输出。
- Gas restart。
- Fortran API 和 C ABI。
- C++ wrapper、Python ctypes 和 CLI。
- Water 回归和 CouplingInterface 边界复核。
- source size 和 release gate。
- README、09 和 11 号文档同步。
14. 验收标准
0.3.0 应满足以下验收标准:
- 软件版本为
0.3.0。 - Gas material 和 Gas EOS 输入可解析、可校验、错误路径清晰。
- 理想气体、JWL 和 Stiffened gas EOS 单元测试通过。
- Gas 粒子可完成最小显式推进,状态保持有限。
- Gas summary 和 bubble metrics 可通过 Fortran API、C ABI、Python 或 CLI 查询。
- Gas 输出 CSV 和 summary CSV 字段可检查。
- Gas restart 可写入、读回,并继续显式步。
- 0.2.2 Water 默认 gate 继续通过。
- 默认 gate 和 source size 门禁通过。
- 文档不宣称 0.3.0 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合能力。
- 不新增 FEMLite 直接依赖。
- 不修改 SPHLite 文件夹之外的内容。
15. 风险与控制
| 风险 | 表现 | 控制方式 |
|---|---|---|
| 0.3.0 范围膨胀 | 提前实现 Explosive、水气结构综合爆炸或 FEM-SPH 联合运行 | 将 0.3.0 限定为 Gas 最小闭环 |
| EOS 字段混乱 | JWL、理想气体和 Stiffened gas 参数命名不一致 | 先写输入测试和错误路径,再接入求解 |
| Water 行为漂移 | Gas 复用求解器时改变 Water 结果 | Water gate 与 Gas gate 一起运行 |
| restart 不完整 | Gas 历史诊断或 EOS 参数读回丢失 | Gas restart 测试覆盖写入、读回和继续步 |
| API 过早固化 | C ABI 暴露未稳定的 Gas 内部结构 | 只暴露 summary 和 bubble metrics 等稳定诊断 |
| 气泡诊断被误认为工程 benchmark | 等效半径小型 smoke 被过度解释 | 文档明确为单气团近似和小规模链路检查 |
| CouplingInterface 边界混乱 | 引入 FEMLite 内部结构或外部模块依赖 | 继续只保留中立接口概念 |
16. 0.4.0 启动条件
满足以下条件后,可以启动 0.4.0 Explosive:
- 0.3.0 Gas EOS、summary、bubble metrics、output 和 restart 稳定。
- Gas 与 Water 的共享数据库和独立计算路径明确。
- Gas 可接收后续 Explosive 质量、动量和能量源项的状态入口。
- 默认 gate 可重复执行。
- 文档明确 Explosive 作用到 Gas 后形成 Bubble 的长期路线。