Files
SPHLite/docs/v2.2_development_plan.md
T
2026-07-03 08:30:27 +08:00

10 KiB
Raw Blame History

SPHLite 0.2.2 开发计划

1. 文档定位

本文档用于规划 SPHLite 0.2.2 版本的开发范围。0.2.2 不作为新的物理功能主版本,而作为 0.2 水相能力完成后的补丁、稳定化与 0.3 Gas 开发前的交接版本。

0.2.2 的核心目标是:在不扩大软件功能边界的前提下,修正 0.2.1 可能遗留的问题,巩固已有 Water 求解路径,补齐验收与发布记录,并为 0.3.0 的 Gas 模块开发提供清晰入口。

2. 依据文件

本计划依据以下文档制定:

  • README.md
  • docs/01_project_overview.md
  • docs/02_software_architecture.md
  • docs/03_data_model.md
  • docs/04_numerical_algorithms.md
  • docs/05_interfaces_and_coupling.md
  • docs/06_testing_and_validation.md
  • docs/v2.0_development_plan.md
  • docs/v2.1_development_plan.md

3. 版本定位

3.1 与 0.2.1 的关系

0.2.1 已完成 0.2 阶段 Water 求解路径的主要加固工作,包括输入、数据库、邻域搜索、水相 EOS、密度连续性方程、人工黏性、压力力、显式时间推进、输出、重启动、API、CLI 与测试门禁。

0.2.2 应保持 0.2.1 的计算行为稳定,不主动引入新的物理模型或新的模块级架构。

3.2 与 0.3.0 的关系

0.3.0 应作为 Gas 模块的正式开发起点。0.2.2 只允许为 0.3.0 做接口、文档、测试命名和风险边界方面的准备,不应提前实现 Gas 生产求解路径。

若 0.2.1 发布后未发现需要修复的稳定性问题,0.2.2 可以作为预留版本,不强制实施完整开发,可直接进入 0.3.0。

4. 开发原则

4.1 保持模块边界

SPHLite 仍然只修改本文件夹内容,不修改 FEMLite 或其他外部模块。SPHLite 不直接依赖 FEMLite,后续耦合仍通过独立 CouplingModule 或其可能的新名称完成。

4.2 保持求解器定位

SPHLite 是求解器,不承担几何建模、网格生成或粒子生成职责。0.2.2 不新增内置建模器、网格器或粒子生成器。

4.3 保持语言和环境约束

核心代码继续遵守 Fortran 95 规范,支持环境与 FEMLite 保持一致。C、C++ 和 Python 接口保持轻量封装原则,不引入会破坏可移植性的外部依赖。

4.4 保持显式动力学路线

时间推进仍以显式动力学为唯一方式,采用 Velocity-Verlet 积分路线。0.2.2 不引入隐式求解器、不引入 Newmark 路线,也不恢复不需要的历史积分方案。

4.5 保持 Abaqus 子集策略

输入文件继续解析 SPHLite 支持的 Abaqus .inp 子集。能复用 Abaqus 关键词时不重新定义关键词;确需 SPHLite 扩展时使用清晰的 *SPHLITE 前缀。

5. 交付目标

0.2.2 建议交付以下内容:

  1. 0.2.1 Water 求解路径的稳定性复核。
  2. 输入解析、数据库、邻域搜索、Water、输出、重启动、API、CLI 的回归检查。
  3. 已知问题、警告策略和错误策略的整理。
  4. 发布说明和版本记录的补齐。
  5. 0.3.0 Gas 开发前的准备清单。
  6. 默认测试门禁和源码规模门禁的再确认。

6. 非交付范围

0.2.2 不应交付以下内容:

  1. 不实现 Gas 的正式生产求解路径。
  2. 不实现 JWL、理想气体或 Stiffened gas 的完整 Gas 模块。
  3. 不实现 Explosive 的点火爆炸生产算法。
  4. 不实现 Solid 的 Johnson-Cook 材料模型和失效模型。
  5. 不实现 Shell 的 Mindlin-Reissner 生产求解路径。
  6. 不实现 FEM-SPH 连续体耦合算例。
  7. 不把 CouplingModule 作为直接依赖。
  8. 不新增几何、网格或粒子生成能力。
  9. 不扩大 Abaqus 兼容范围到完整 Abaqus 输入。
  10. 不引入新的大型第三方依赖。

7. 建议工作包

7.1 基线复核

确认 0.2.1 当前代码状态、测试门禁和文档状态,建立 0.2.2 的开发基线。

建议检查内容:

  • 工作区是否干净。
  • 0.2.1 本地提交是否完整。
  • README、01-06 号文档和 0.2 系列开发计划是否互相一致。
  • 当前测试门禁是否仍可重复执行。

7.2 版本与发布记录整理

若决定实际发布 0.2.2,需要将版本号、发布记录和测试记录统一更新到 0.2.2。若 0.2.2 仅作为预留版本,则不应修改运行时版本号。

建议检查内容:

  • 版本号是否只在必要位置更新。
  • 发布说明是否说明 0.2.2 是补丁或稳定化版本。
  • 文档是否避免宣称未实现的 Gas、Explosive、Solid、Shell 或耦合能力。

7.3 Water 行为回归

复核 0.2.1 Water 求解路径,确保 0.2.2 不改变以下行为:

  • 密度采用连续性方程更新。
  • 默认 EOS 使用 Tait 模型。
  • Stiffened gas 仅作为后续或备选策略,不作为 0.2.2 新增生产能力。
  • rho < rho0 时保留负压,不进行压力截断。
  • 空化暂不作为 0.2.2 的实现内容。
  • 人工黏性和压力力的开关、参数和诊断行为保持稳定。

7.4 输入解析回归

确认 0.2.1 支持的 Abaqus 子集仍保持兼容,错误和警告策略不发生漂移。

建议检查内容:

  • 不影响程序运行的问题报 warning。
  • 缺失必要关键词导致无法运行时报 error。
  • *SPHLITE 扩展关键词边界清晰。
  • 不新增与 Abaqus 关键词冲突的 SPHLite 关键词。

7.5 数据库与相变边界复核

继续采用集中型数据管理模式,粒子数据统一管理。Water、Gas、Explosive、Solid 和 Shell 共享基础粒子数据,但计算路径保持独立。

0.2.2 只复核既有 phase 机制,不新增复杂相变模型。若发现 phase 改变相关问题,应以修复状态一致性为目标,不扩大到新物理。

7.6 重启动完整性复核

重启动继续按模块级完整重启动的方向维护。0.2.2 应重点确认当前版本写出的 restart 数据能够恢复 Water 求解状态。

建议检查内容:

  • 坐标、速度、密度、质量、相标识和材料标识保存完整。
  • Water 相关状态变量保存完整。
  • 时间步、步数和输出计数恢复一致。
  • 不在 0.2.2 引入复杂跨版本迁移机制。

7.7 API 兼容性复核

C ABI、C++ 封装和 Python ctypes 接口应保持 0.2.1 兼容。0.2.2 只允许修复错误,不主动调整公开接口名称、参数顺序或返回约定。

建议检查内容:

  • C ABI 可被 C++ 和 Python 稳定调用。
  • C++ 继续作为轻量 RAII 封装。
  • Python 继续作为轻量 ctypes 封装。
  • CLI 行为不因内部整理发生不兼容变化。

7.8 CouplingInterface 中立性复核

SPHLite 继续保留中立耦合接口概念,但不直接依赖 FEMLite。0.2.2 可复核文档和接口命名,确保后续 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite 等外部名称变化不会影响 SPHLite 内部边界。

0.2.2 不实现真实 FEM-SPH 耦合算法,不把 FEMLite 数据结构引入 SPHLite。

7.9 测试门禁复核

0.2.2 应继续使用 0.2.1 已建立的默认测试门禁,并保留源码规模检查。

建议默认门禁:

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

若当前环境不能运行完整测试,应在发布记录中明确说明原因和剩余风险。

7.10 0.3.0 Gas 交接准备

为 0.3.0 准备但不实现以下内容:

  • Gas 输入关键词草案。
  • Gas 状态变量清单。
  • Gas EOS 测试命名建议。
  • Water 与 Gas 共享粒子数据但独立计算路径的边界说明。
  • Explosive 作用到 Gas 后形成 Bubble 的长期路线说明。
  • 0.3.0 首批最小可验收算例建议。

8. 建议待办阶段

若后续需要根据本计划生成 todo.md,建议采用以下阶段:

  1. 基线与版本状态复核。
  2. 文档一致性与发布记录整理。
  3. 输入解析回归检查。
  4. 数据库和 phase 状态回归检查。
  5. Water EOS、密度、黏性、压力力回归检查。
  6. 显式时间推进与输出回归检查。
  7. 重启动完整性回归检查。
  8. C、C++、Python 和 CLI 接口兼容性检查。
  9. CouplingInterface 中立性检查。
  10. 0.3.0 Gas 交接清单整理。
  11. 默认门禁和源码规模门禁执行。
  12. 0.2.2 发布决策记录。

9. 验收标准

0.2.2 若实际实施,应满足以下验收标准:

  1. 0.2.1 已支持的 Water 测试全部通过。
  2. 输入解析错误和 warning 行为符合 02 号文档要求。
  3. 重启动测试可恢复 Water 求解关键状态。
  4. C、C++、Python 和 CLI 基础测试通过。
  5. 默认门禁和源码规模门禁通过。
  6. 文档没有宣称尚未实现的 Gas、Explosive、Solid、Shell 或耦合能力。
  7. 不新增 FEMLite 直接依赖。
  8. 不修改 SPHLite 文件夹之外的内容。

10. 风险与控制

风险 表现 控制方式
0.2.2 范围膨胀 提前实现 Gas 或其他新模块 将 0.2.2 限定为补丁和稳定化版本
文档过度承诺 README 或开发计划宣称未实现能力 发布前进行文档一致性复核
Water 行为漂移 小修复改变 0.2.1 数值路径 通过 Water 回归测试和 pressure wave smoke 测试约束
API 不兼容 C/C++/Python 调用方式变化 0.2.2 不主动调整公开接口
耦合边界混乱 引入 FEMLite 直接依赖 只保留中立 CouplingInterface 概念
发布记录不清 无法判断 0.2.2 是否应发布 记录 0.2.2 是实际补丁还是预留版本

11. 发布建议

建议将 0.2.2 作为可选版本处理:

  1. 若 0.2.1 发现明确缺陷,则实施 0.2.2,修复后发布。
  2. 若 0.2.1 稳定且无必须修复事项,则保留本计划作为预案,直接启动 0.3.0。
  3. 若 0.2.2 仅包含文档整理,不改变代码行为,应在发布记录中明确说明其性质。

12. 0.3.0 启动条件

满足以下条件后,可以启动 0.3.0:

  1. 0.2.1 或 0.2.2 的 Water 基线稳定。
  2. 默认测试门禁可重复执行。
  3. 文档确认 0.3.0 的主要目标是 Gas 模块。
  4. Gas 与 Water 的共享数据和独立计算边界已经明确。
  5. 0.3.0 的首批待办事项能够围绕 Gas 输入、状态、EOS、输出、重启动和测试展开。