# 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 输出。