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

451 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 输入形式:
```text
*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 应支持以下输入组合:
```text
*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 反应。建议最小状态为:
```fortran
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 时应避免破坏已有函数,可新增:
```c
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 为:
```powershell
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 的长期路线。