Files
SPHLite/docs/v2.1_development_plan.md
T

530 lines
21 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 v2.1 开发计划
文档状态:0.2.1 开发计划草案
目标软件版本:SPHLite 0.2.1
依据文档:
- `01_requirements_specification.md`
- `02_software_architecture_design.md`
- `03_detailed_design.md`
- `04_mathematical_model_and_algorithms.md`
- `05_interface_control_document.md`
- `06_test_and_verification_plan.md`
- `v2.0_development_plan.md`
## 1. 版本定位
SPHLite 0.2.1 是 0.2 系列的 Water 加固版本,定位为 0.2.0 基础水相弱可压 SPH 最小闭环之后的可靠性、可验证性和接口一致性增强。
0.2.0 已经打通以下最小计算链路:
```text
输入粒子状态 -> 构建邻域 -> 核函数 -> Tait EOS -> 连续性方程
-> 压力/人工黏性/外载 -> Velocity-Verlet -> 输出/restart/API/CLI/checker
```
0.2.1 不改变 0.2 系列的物理边界,不提前进入 `Gas`、`Explosive`、`Solid`、`Shell` 生产路径。该版本的核心目标是让 0.2.0 已有 Water 路径更稳、更可诊断、更适合后续 0.3 `Gas` 开发承接。
0.2.1 应重点回答以下问题:
- Water 输入错误是否足够早、足够清楚地暴露。
- Water 显式步是否能在更多小型 3D 排布下保持有限、可重复、可 restart。
- kernel、neighbor、dt、output、restart、API、CLI 是否形成稳定契约。
- CouplingInterface 是否足够中立,能承接后续外部 CouplingModule,但不引入 FEMLite 源码依赖。
- 默认 release gate 是否仍然小规模、快速、稳定。
## 2. 版本目标
0.2.1 应完成:
- 将软件版本更新为 `0.2.1`。
- 加固 0.2.0 Water 输入解析和错误诊断。
- 加固 `*SPHLITE EOS`、`*SPHLITE VISCOSITY`、`*SPHLITE PARTICLE CONTROL`、`*SPHLITE BODY FORCE` 的字段校验。
- 明确 unsupported-but-safe 输入项继续 warning,无法运行的缺失或非法参数继续 error。
- 加固 Tait EOS 在边界密度、低密度、负压或极端参数下的错误路径和有限性检查。
- 加固 Monaghan 人工黏性在接近、远离、零距离、非 Water 粒子和 inactive 粒子路径下的行为。
- 加固连续性方程和压力力计算的对称性、有限性和跳过规则。
- 加固 uniform cell/bin 邻域重建在小粒子数、稀疏粒子、重复坐标、不同 `h(i)` 和边界 cell 下的行为。
- 加固稳定时间步估计,明确 CFL、加速度和黏性约束的诊断输出。
- 加固 Velocity-Verlet 显式步错误路径,尤其是未 build、非法 dt、非法 Water 状态、restart 后继续推进。
- 加固 output 和 restart,使 0.2.1 Water 状态可恢复、可检查、可用于后续版本兼容策略。
- 加固 Fortran API、C ABI、C++ wrapper、Python `ctypes` 和 CLI 的 Water 诊断契约。
- 扩展 pressure wave smoke,使其更明确地检查方向、有限性、质量趋势、动量趋势和输出字段。
- 保持 source size、文档同步和 release gate 记录。
## 3. 明确不交付范围
0.2.1 不交付:
- 生产级水下接触爆炸模拟。
- Riemann-SPH、Godunov-SPH 或高阶强冲击格式。
- 真实 `Gas` EOS 计算、气体团簇、气泡脉动和气泡界面演化。
- `Explosive` 解析点火、programmed burn、反应进度和向 `Gas` 的源项注入。
- `Solid` 3D 结构应力更新、Johnson-Cook 材料和失效模型。
- `Shell` Mindlin-Reissner 板壳计算。
- 水-气、水-结构、气-结构的生产级相互作用。
- 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
- 与 FEMLite 的联合运行。
- 几何、网格或粒子生成能力。
- 大规模并行、GPU 后端和性能优化专项。
- 工程 benchmark 和长跑算例。
0.2.1 可以继续保留后续模块的目录、常量、占位状态和接口边界,但不得把占位能力描述为已实现物理算法。
## 4. 继承 0.2.0 的基线
0.2.1 以 0.2.0 发布状态为基线,默认继承:
- Fortran 95 核心库。
- C ABI、C++ 薄包装、Python `ctypes` 调试入口和 CLI。
- Abaqus `.inp` 明确子集解析。
- 统一集中型 `Database`。
- `Water` 基础弱可压 SPH 路径。
- Wendland C2、Wendland C4 和 cubic spline 核函数。
- uniform cell/bin 邻域搜索。
- Tait EOS。
- Monaghan 人工黏性。
- 连续性方程密度演化。
- Velocity-Verlet 显式推进。
- Water summary、dt limits、CSV output、restart 和 pressure wave smoke。
- CouplingInterface 中立数据导出、外部粒子力导入和诊断占位。
- 0.2.0 release gate。
0.2.1 不应重写 0.2.0 架构。除非测试证明存在实际问题,否则只做局部加固、接口补全和测试覆盖。
## 5. 输入解析加固范围
0.2.1 继续遵守:
- SPHLite 是求解器,不负责几何、网格或粒子生成。
- 输入采用 Abaqus `.inp` 明确子集。
- 能复用 Abaqus 关键词时不新增关键词。
- Abaqus 无法表达的专有能力使用 `*SPHLITE ...` 扩展关键词。
- set 只表示集合,不作为物理类型判断依据。
- material 决定物理材料类型和 EOS 参数。
- section 决定实体或板壳相关 section 属性。
- 单位系统由用户保持一致,SPHLite 不做内置单位换算。
0.2.1 建议加固以下输入路径:
- `*MATERIAL, TYPE=WATER` 大小写兼容。
- Water material 与 `*DENSITY` 的匹配关系。
- `*SECTION` 指向不存在 material 时的 error。
- `*SPHLITE EOS` 缺失 `TYPE`、`MATERIAL`、`RHO0`、`C0`、`GAMMA` 时的 error。
- `*SPHLITE EOS, TYPE=TAIT` 以外类型在 0.2.1 中应 error 或明确 warning 后不进入 Water 计算。
- `B` 未给定时继续由 `rho0*c0*c0/gamma` 推导。
- `B` 给定但非法时 error。
- `*SPHLITE VISCOSITY` 缺失 `TYPE`、`MATERIAL`、`ALPHA`、`BETA`、`ETA2` 时的 error。
- `*SPHLITE PARTICLE CONTROL` 中 `H`、`MASS`、`VOLUME` 的正值校验。
- `*SPHLITE BODY FORCE` 三维分量解析和非法字段 error。
- `*SPHLITE TIME CONTROL` 中 `DT`、`TIME`、`STEPS`、`SAFETY` 的正值和一致性校验。
- 未知但不影响运行的 `*SPHLITE ...` 子关键词 warning。
- 错误消息继续包含文件名、行号或足够定位的上下文。
## 6. Database 和运行时状态加固
0.2.1 不新增新的粒子对象模型,继续使用集中型数组数据库。
建议确认或加固:
- `particle_id_ext` 在重复输入、restart 读回和 API 查询中保持稳定。
- `particle_phase`、`particle_status`、`material_id`、`section_id` 在 build model 后一致。
- `x0`、`x`、`v`、`a`、`vhalf`、`mass`、`rho`、`volume`、`pressure`、`temperature`、`h` 在初始化、finalize、重复读取、restart 读回后状态一致。
- `drho_dt`、`acc_pressure`、`acc_viscosity`、`acc_body` 在每步计算前正确清零或保留应保留状态。
- Water 诊断量在 build、advance、run、restart read 后可重复计算。
- 非 Water 粒子默认跳过 Water 计算,但仍保持通用粒子状态可查询。
- inactive 或 failed 粒子不参与 Water 相互作用。
0.2.1 可以增加小型内部一致性检查,但不应引入大规模内存管理重构。
## 7. Kernel 加固范围
0.2.1 继续沿用:
- 默认 Wendland C2。
- 可选 Wendland C4。
- cubic spline 用于对比和回归测试。
- 每粒子独立 `h(i)`。
- 3D 归一化。
建议加固:
- `h <= 0` 明确 error。
- 未知 kernel type 明确 error。
- `r = 0` 时梯度有限并返回零向量。
- `r` 接近支持半径时值和梯度有限。
- 超出支持半径时 `W = 0` 且 `grad W = 0`。
- 对称粒子对梯度反对称。
- 不同 `h(i)` 结果有限。
- kernel 相关测试不变成长跑积分精度 benchmark。
## 8. Neighbor 加固范围
0.2.1 继续使用 uniform cell/bin,不引入树结构和并行优化。
建议加固:
- 空模型邻域构建。
- 单粒子邻域构建。
- 两粒子刚好在支持半径内外的边界判断。
- 重复坐标或极近坐标粒子的稳定处理。
- 负坐标粒子。
- 稀疏粒子导致大包围盒时的 cell 维度控制。
- 不同 `h(i)` 对搜索半径的影响。
- 粒子移动后重建邻域。
- 邻域容量不足时的明确 error。
- 邻域统计 API 的最大邻居数和平均邻居数。
0.2.1 默认 gate 只保留小规模邻域测试,不引入性能基准。
## 9. Water 算法加固范围
### 9.1 Tait EOS
建议加固:
- `rho = rho0` 时压力接近 `p0`。
- `rho > rho0` 时压力增加。
- `rho < rho0` 时压力策略明确。
- `rho <= 0` 时 error。
- `rho0 <= 0`、`c0 <= 0`、`gamma <= 0`、`B <= 0` 时 error。
- 声速或等效声速诊断保持正值。
- 压力结果有限。
0.2.1 不要求实现完整拉伸不稳定控制,但应在文档和测试中明确当前策略。
### 9.2 连续性方程
建议加固:
- 双粒子压缩时 `drho_dt` 符号正确。
- 双粒子拉伸时 `drho_dt` 符号正确。
- 静止均匀粒子组密度变化接近零。
- 非 Water 粒子跳过贡献。
- inactive 粒子跳过贡献。
- `drho_dt` 每步正确重置。
- 结果有限。
### 9.3 人工黏性
建议加固:
- 接近粒子产生黏性贡献。
- 远离粒子默认不产生压缩型人工黏性贡献。
- 零距离或极小距离保持有限。
- `alpha`、`beta`、`eta2` 非法时 error。
- 黏性加速度对称性或动量趋势检查。
- 非 Water 和 inactive 粒子跳过。
### 9.4 压力力和外载
建议加固:
- 双粒子压力力方向正确。
- 均匀压力或零压力的净力趋势合理。
- `acc_pressure`、`acc_viscosity`、`acc_body` 的合成顺序明确。
- `*SPHLITE BODY FORCE` 对速度方向有可验证影响。
- CouplingInterface 导入的粒子力能进入显式步外载占位。
- 非 Water 和 inactive 粒子跳过 Water 力。
## 10. Solver 和时间步加固范围
0.2.1 继续只支持显式动力学和 Velocity-Verlet,不增加 implicit、static 或 nonlinear static 接口。
建议加固:
- 未 initialize 调用显式步返回 state error。
- 未 build model 调用显式步返回 state error。
- `dt <= 0` 返回 argument error。
- Water 状态非法时 stable dt 返回明确 error。
- `sph_estimate_stable_dt` 同时保存并返回 CFL、加速度和黏性约束贡献。
- 安全系数 `SAFETY` 只在正值时生效。
- `sph_run_explicit` 在 `TIME`、`STEPS` 双约束下行为明确。
- 最后一小步不超过 `end_time`。
- 自动输出只在启用输出且满足间隔时发生。
- restart 读回后可继续显式步并保持时间、步号和诊断合理。
## 11. Output 和 Restart 加固范围
0.2.1 继续使用 CSV 作为默认 gate 输出,不要求新增 VTK 生产输出。
输出建议加固:
- 粒子 CSV 包含 id、phase、status、material、section、x、v、rho、pressure、temperature、h。
- summary CSV 包含 step、time、water mass、water momentum、max pressure、min/max density、dtcrit。
- 输出目录不存在或非法时 error。
- 手动 `sph_write_output` 不改变物理状态。
- CLI `--run --output` 使用实际 step/time 写出。
restart 建议加固:
- restart header 版本可识别。
- 写入并读回 current time、step、output control、safety factor。
- 写入并读回 Water EOS、viscosity、body force。
- 写入并读回粒子通用状态、rho、pressure、h、v、a、vhalf。
- 写入并读回 Water 诊断状态。
- 读回后重建邻域。
- 读回后继续执行 Water 显式步。
- 非法 restart 文件明确 error。
- 0.2.1 可以保持只兼容当前 restart 格式,但应在文档中记录格式版本策略。
## 12. Fortran API 范围
0.2.1 应保持 0.2.0 Fortran API 兼容。
必须继续可用:
- 生命周期。
- `.inp` 读取。
- build model。
- stable dt。
- advance/run explicit。
- current time。
- particle count/state。
- output/restart。
- error query。
- neighbor rebuild 和 neighbor stats。
- water summary。
- water dt limits。
建议加固:
- 每个新增或已有公开 API 的未初始化错误路径。
- 每个依赖模型的 API 的未 build 错误路径。
- 输出参数在错误返回前给出安全默认值。
- API 不暴露内部 allocatable 数组指针。
- Fortran API 仍作为物理语义来源。
## 13. C ABI、C++ 和 Python 范围
C ABI 必须保持 0.2.0 兼容。
建议加固:
- `sphlite_get_water_summary` 空指针返回 `-1`。
- `sphlite_get_water_dt_limits` 空指针返回 `-1`。
- Fortran 错误码原样返回 C 调用方。
- `sphlite_get_particle_state` 小容量和空指针错误路径。
- C wrapper 不重新定义物理语义。
- C++ wrapper 只做 RAII 和薄封装。
- Python `ctypes` 包装继续通过 C ABI,不直接访问 Fortran 内部符号。
- Python `inspect` 和 `run` 保持 Water summary、dt limits 和错误路径覆盖。
0.2.1 不要求提供完整 Python 包发布流程。
## 14. CLI 范围
0.2.1 CLI 继续支持:
```powershell
sphlite --version
sphlite model.inp
sphlite model.inp --check
sphlite model.inp --run
sphlite model.inp --run --output output
```
建议加固输出字段:
- `version`
- `input`
- `mode`
- `particles`
- `warnings`
- `time`
- `step`
- `water_particles`
- `water_mass`
- `max_pressure`
- `dtcrit`
- `status`
建议加固错误路径:
- 缺少输入文件。
- 输入文件不存在。
- `--run` 和 `--check` 同时给出。
- `--output` 缺少路径。
- Water 参数缺失。
- 输出目录非法。
CLI 内部必须继续调用公共生命周期 API,不得绕过 Fortran API 或 C ABI 的错误处理。
## 15. CouplingInterface 边界
0.2.1 不实现真实 FEM-SPH 耦合。
建议加固:
- Water 运行后 coupling particle count 可用。
- Water 运行后 coupling particle state 导出包含 id、position、velocity、phase、material、pressure。
- 外部粒子力导入后进入显式步外载占位。
- coupling work、momentum、energy 诊断继续可读。
- 接触耦合和连续体耦合类型字段继续保留。
- 接口命名不出现 FEMLite 内部数据结构。
- 默认 gate 不运行真实 FEM-SPH 联合测试。
如果 0.2.1 需要扩展 C ABI coupling 接口,应只采用中立命名,且不依赖外部 CouplingModule。
0.2.1 实施决策:本版本不暴露 CouplingInterface 的 C ABI。原因是外部耦合模块名称、区域匹配方式、facet/粒子载荷交换契约尚未冻结;过早公开 C ABI 会把临时占位语义固化为长期接口。0.2.1 仅保留 Fortran 模块级 gate,用于验证中立导出、外部粒子力导入和诊断占位。
## 16. 测试计划
0.2.1 默认 gate 建议包含:
- `smoke`:版本 0.2.1、生命周期、基础显式步和错误路径。
- `input`:Water 输入关键字、warning/error、section/material/set 语义。
- `kernel`:核函数边界、梯度、不同 `h(i)`。
- `neighbor`:uniform cell/bin、重复坐标、稀疏粒子、容量错误。
- `water_eos`:Tait EOS 正常、边界和非法参数。
- `water_density`:连续性方程压缩、拉伸、静止和跳过路径。
- `water_viscosity`:Monaghan 人工黏性接近、远离、零距离和非法参数。
- `water_force`:压力力、body force、外载占位和跳过路径。
- `solver_water`:单步、多步、stable dt、非法 dt、restart 后继续推进。
- `output`:粒子 CSV 和 summary CSV 字段。
- `restart`:0.2.1 Water 状态写入、读回和继续运行。
- `coupling_interface`:Water 运行后状态导出和外部粒子力导入。
- `c_api`:Water summary/dt limits、空指针和原有 C ABI 兼容。
- `cpp_api`:Water summary/dt limits 薄包装。
- `python_debug`:Water inspect/run、错误路径。
- `cli`:version、inspect、check、run、output、错误输入。
- `pressure_wave_smoke`:小型压力扰动方向、有限性、质量/动量趋势和输出字段。
- `source_size`:Fortran/C/C++/Python 文件大小和 stale exception。
非默认测试可以保留:
- 更大粒子数压力传播。
- 参数收敛研究。
- 更严格波速对比。
- 自由面探索算例。
- 长时间稳定性探索。
这些不进入默认 release gate。
## 17. 0.2.1 Release Gate
建议 release gate:
```powershell
cmake --build build-codex-unix --parallel
ctest --test-dir build-codex-unix -R "^(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)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
```
验收标准:
- 完整配置 CMake。
- 完整编译 `sphlite_core`、`sphlite_c`、`sphlite_c_shared`、`sphlite` 和测试目标。
- 默认 gate 全部通过。
- `source_size` 通过。
- `git diff --check` 通过。
- README、09 和 11 号文档记录 0.2.1 gate 结果。
- 文档不宣称已实现完整水下爆炸。
- 文档不宣称已实现 Gas/Explosive/Solid/Shell 生产路径。
- 文档不宣称已实现真实 FEM-SPH 联合运行。
- build 目录、CSV、VTK、restart 临时结果和 Python 缓存不进入提交。
- 文档使用 UTF-8 without BOM。
## 18. 开发阶段拆分
### 阶段 A:版本和基线检查
- 更新版本号到 0.2.1。
- 确认 0.2.0 release gate 仍通过。
- 确认当前 CMake、CTest 和 source size 门禁可用。
- 准备 0.2.1 专用测试输入文件。
### 阶段 B:输入解析加固
- 加固 Water material、density、section 和 set 映射。
- 加固 EOS、viscosity、particle control、body force 和 time control 参数错误路径。
- 补充输入错误消息测试。
- 补充 unknown keyword warning 测试。
### 阶段 C:Kernel 和 Neighbor 加固
- 增加 kernel 边界和非法参数测试。
- 增加 neighbor 重复坐标、稀疏粒子、边界半径和容量错误测试。
- 确认 neighbor stats API 结果稳定。
### 阶段 D:Water 算法加固
- 扩展 Tait EOS 边界测试。
- 扩展连续性方程测试。
- 扩展人工黏性测试。
- 扩展压力力和 body force 测试。
- 确认非 Water 和 inactive 粒子跳过规则。
### 阶段 E:Solver、Output 和 Restart
- 加固 stable dt 诊断。
- 加固非法 dt 和非法 Water 状态错误路径。
- 加固多步 run 和最后小步逻辑。
- 加固 CSV output 和 summary 字段检查。
- 加固 restart 读回后继续运行。
### 阶段 F:接口和 CLI
- 加固 Fortran API 错误路径。
- 加固 C ABI 空指针、小容量和错误码路径。
- 加固 C++ wrapper 测试。
- 加固 Python inspect/run 和错误路径。
- 加固 CLI 输出字段和错误输入路径。
### 阶段 G:CouplingInterface 最小加固
- 确认 Water 运行后导出状态包含 pressure、phase、material。
- 确认外部粒子力影响显式步。
- 确认 coupling 诊断继续记录。
- 确认默认 gate 不运行真实 FEM-SPH 联合测试。
- 记录 0.2.1 暂不暴露 CouplingInterface C ABI 的原因。
### 阶段 H:Pressure Wave Smoke 和 Gate
- 扩展 pressure wave smoke checker。
- 确认小规模、短时间、快速运行。
- 更新 README、09、11 号文档。
- 跑 0.2.1 release gate。
- 清理 todo 并记录验收结果。
## 19. 风险和控制
| 风险 | 控制 |
|---|---|
| 0.2.1 膨胀为 0.3 Gas 开发 | 只加固 Water,不实现 Gas EOS、气泡和气体团簇生产路径 |
| 过早引入强冲击算法 | Riemann-SPH 继续作为后续升级方向,不进入 0.2.1 默认 gate |
| 输入语法过度扩张 | 只补 Water 已有关键词的校验和错误路径 |
| pressure wave smoke 变成长跑 benchmark | 保持小粒子数、短时间、趋势检查 |
| source size 膨胀 | 继续使用 source size 门禁,必要时拆分模块而不是登记无意义例外 |
| C ABI 与 Fortran API 分叉 | Fortran API 仍为语义来源,C ABI 只做薄封装 |
| restart 格式不清晰 | 记录 restart state version 和 0.2.1 兼容策略 |
| 文档超前宣称能力 | README、09、11 和本计划均明确 0.2.1 不交付新物理模块 |
## 20. 后续版本衔接
0.2.1 完成后,后续可以选择:
- 若 Water 仍存在明显稳定性或接口问题,则继续开发 0.2.2。
- 若 Water 基础路径和 gate 足够稳定,则进入 0.3 `Gas`。
进入 0.3 前,0.2.1 应为 `Gas` 提供:
- 稳定的统一粒子数据库。
- 稳定的 phase/status/material/section 语义。
- 可复用的 neighbor 和 kernel 路径。
- 可复用的 output、restart、API、CLI 和 release gate 框架。
- 明确的 Water/Gas 独立计算模块边界。
0.2.1 不应提前实现 JWL、理想气体、Stiffened gas 或气泡诊断生产路径。
## 21. 待确认事项
- 0.2.1 是否需要引入 Water 拉伸压力限制,还是继续保留当前 Tait 负压策略并只加固测试说明。
- `*SPHLITE EOS` 非 `TYPE=TAIT` 时在 0.2.1 中应直接 error,还是 warning 后不进入 Water 计算。
- `*SPHLITE PARTICLE CONTROL` 是否需要支持逐粒子 `H/MASS/VOLUME`,还是继续只支持统一默认值。
- pressure wave smoke 是否需要增加第二个 3D 非共线粒子布置。
- restart 格式是否需要声明兼容 0.2.0,还是 0.2.1 只保证当前版本读写闭环。
- CouplingInterface 是否需要在 0.2.1 暴露 C ABI,还是继续停留在 Fortran 模块测试层。
- 0.2.1 是否需要新增 VTK 占位输出,还是继续只用 CSV 作为默认 gate 输出。