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

15 KiB
Raw Permalink Blame History

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.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/v2.2_development_plan.md
  • docs/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 建议交付以下内容:

  1. 将软件版本更新为 0.3.0。
  2. 解析 TYPE=GAS material 和 Gas 相关 .inp 输入。
  3. 建立 Gas 粒子的 phase、材料、密度、压力、内能、温度、质量、体积和光滑长度初始化路径。
  4. 实现 Gas EOS 的最小闭环:理想气体、JWL 和 Stiffened gas。
  5. 实现 Gas 单相显式推进最小路径,包括压力更新、密度变化率、压力力或等价加速度贡献。
  6. 实现 Gas summary,包括气体质量、体积、中心、动量、平均压力、最大压力、密度范围和稳定时间步诊断。
  7. 实现气泡诊断入口,包括等效气泡半径、半径变化率和中心迁移指标。
  8. 将 Gas 状态写入 CSV 输出和 restart,并可读回后继续显式步。
  9. 扩展 Fortran API、C ABI、C++ wrapper、Python ctypes 和 CLI 的 Gas 诊断查询。
  10. 建立 Gas 默认 gate,同时保持 0.2.2 Water gate 全部通过。
  11. 更新 README、09 号发布记录和 11 号验收矩阵。

6. 非交付范围

0.3.0 不交付以下内容:

  1. 不实现 Explosive 的解析点火、爆轰传播或反应进度。
  2. 不实现 Explosive 向 Gas 的真实质量、动量和能量注入。
  3. 不实现生产级气泡多周期脉动 benchmark。
  4. 不实现复杂水-气界面重构、锐界面追踪、相变蒸发或多相 Riemann 通量。
  5. 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。
  6. 不实现 Shell 的 Mindlin-Reissner 生产求解路径。
  7. 不实现真实 FEM-SPH 接触耦合或连续体耦合。
  8. 不暴露未冻结的 CouplingInterface C ABI。
  9. 不新增几何、网格或粒子生成能力。
  10. 不把测试 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 + p0
  • gamma > 1
  • rho > 0
  • e >= 0

JWL 第一版建议采用相对体积形式:

  • V = rho0 / rho
  • p = A * exp(-R1 * V) + B * exp(-R2 * V) + omega * e / V
  • rho0 > 0
  • A、B、R1、R2、omega 和 E0 由输入给定并校验。

Stiffened gas 第一版建议采用内能形式,并在实现时锁定公式和字段命名。若实现过程中发现字段约定不足,应先补测试和文档,再进入默认 gate。

8. 数据库和 Gas 状态

Gas 应共享集中型数据库中的通用粒子状态:

  • particle_id_ext
  • particle_phase
  • particle_status
  • material_id
  • section_id
  • x0
  • x
  • v
  • a
  • vhalf
  • mass
  • rho
  • volume
  • pressure
  • internal_energy
  • temperature
  • h

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_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

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_summary
  • sph_get_gas_bubble_metrics
  • sph_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_particles
  • gas_volume
  • gas_mean_pressure
  • gas_max_pressure
  • gas_equivalent_radius
  • gas_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:

  • smoke
  • input
  • kernel
  • neighbor
  • water_eos
  • water_density
  • water_viscosity
  • water_force
  • solver_water
  • output
  • restart
  • coupling_interface
  • c_api
  • cpp_api
  • python_debug
  • cli
  • pressure_wave_smoke
  • source_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,建议按以下阶段拆分:

  1. 0.3.0 版本号和基线确认。
  2. Gas 输入测试数据准备。
  3. Gas 输入解析和校验。
  4. Gas 数据库状态和模块初始化。
  5. 理想气体 EOS。
  6. JWL EOS。
  7. Stiffened gas EOS。
  8. Gas 压力更新和 summary。
  9. Gas 气泡诊断。
  10. Gas 单相显式推进。
  11. Gas 输出。
  12. Gas restart。
  13. Fortran API 和 C ABI。
  14. C++ wrapper、Python ctypes 和 CLI。
  15. Water 回归和 CouplingInterface 边界复核。
  16. source size 和 release gate。
  17. README、09 和 11 号文档同步。

14. 验收标准

0.3.0 应满足以下验收标准:

  1. 软件版本为 0.3.0。
  2. Gas material 和 Gas EOS 输入可解析、可校验、错误路径清晰。
  3. 理想气体、JWL 和 Stiffened gas EOS 单元测试通过。
  4. Gas 粒子可完成最小显式推进,状态保持有限。
  5. Gas summary 和 bubble metrics 可通过 Fortran API、C ABI、Python 或 CLI 查询。
  6. Gas 输出 CSV 和 summary CSV 字段可检查。
  7. Gas restart 可写入、读回,并继续显式步。
  8. 0.2.2 Water 默认 gate 继续通过。
  9. 默认 gate 和 source size 门禁通过。
  10. 文档不宣称 0.3.0 已实现 Explosive、Solid、Shell 或真实 FEM-SPH 耦合能力。
  11. 不新增 FEMLite 直接依赖。
  12. 不修改 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:

  1. 0.3.0 Gas EOS、summary、bubble metrics、output 和 restart 稳定。
  2. Gas 与 Water 的共享数据库和独立计算路径明确。
  3. Gas 可接收后续 Explosive 质量、动量和能量源项的状态入口。
  4. 默认 gate 可重复执行。
  5. 文档明确 Explosive 作用到 Gas 后形成 Bubble 的长期路线。