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

248 lines
10 KiB
Markdown

# 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 已建立的默认测试门禁,并保留源码规模检查。
建议默认门禁:
```powershell
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、输出、重启动和测试展开。