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

581 lines
19 KiB
Markdown
Raw Permalink 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.0 开发计划
文档状态:0.2.0 开发计划稿
目标软件版本:SPHLite 0.2.0
依据文档:
- `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`
- `v1.0_development_plan.md`
- `v1.1_development_plan.md`
## 1. 版本定位
SPHLite 0.2.0 是第一个真实物理计算版本,定位为 `Water` 基础 SPH 最小闭环。该版本应在 0.1.1 已完成的工程骨架、输入元数据、粒子状态查询、C/C++/Python/CLI、output、restart 和 release gate 基础上,交付可测试的 3D 水相弱可压 SPH 计算路径。
0.2.0 的核心价值不是完成水下爆炸,而是把真实 SPH 计算链路打通:
```text
输入粒子状态 -> 构建邻域 -> 核函数 -> Tait EOS -> 连续性方程 -> 压力/黏性力 -> Velocity-Verlet -> 输出/restart/checker
```
0.2.0 不应扩展为 `Gas`、`Explosive`、`Solid`、`Shell` 或 FEM-SPH 联合运行版本。后续水下接触爆炸能力必须建立在本版本稳定的 `Water` 基础计算、邻域搜索和测试体系之上。
## 2. 版本目标
0.2.0 应完成:
- 将软件版本更新为 `0.2.0`。
- 建立 `Particle` 模块中的核函数和 uniform cell/bin 邻域搜索。
- 实现每粒子独立光滑长度 `h(i)` 的核函数计算路径。
- 实现 Wendland C2 默认核函数。
- 保留 Wendland C4 和 cubic spline 作为可选或回归测试核函数。
- 实现 Tait EOS 水相压力计算。
- 实现水相连续性方程,采用密度演化作为主流程。
- 实现 Monaghan 型人工黏性。
- 将水相压力梯度、人工黏性和外部体力贡献接入显式加速度计算。
- 使 Velocity-Verlet 从 0.1 系列的运动骨架升级为可调用水相力计算的真实推进流程。
- 实现水相稳定时间步估计,至少覆盖 CFL 声速约束、加速度约束和黏性约束。
- 完善 input/API/CLI/output/restart,使 0.2.0 水相状态可以读入、运行、输出和恢复。
- 建立 Water 单元测试、模块测试和小型 pressure wave smoke。
- 保持 C ABI、C++ wrapper 和 Python 调试入口与新增水相能力一致。
- 保持 release gate 快速、稳定、小规模。
## 3. 明确不交付范围
0.2.0 不交付:
- 生产级水下爆炸近场强冲击计算。
- Riemann-SPH、Godunov-SPH 或高阶强冲击格式。
- 真实 `Gas` EOS 计算、气体团簇和气泡脉动。
- `Explosive` 解析点火、programmed burn 和产物气体注入。
- `Solid` 3D 结构应力更新、Johnson-Cook 材料和失效。
- `Shell` Mindlin-Reissner 板壳计算。
- 水-气、水-结构、气-结构的生产级相互作用。
- 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
- 与 FEMLite 的联合运行。
- 几何、网格或粒子生成能力。
- 完整自由面重构、锐界面追踪、复杂边界条件库。
- 大规模并行、GPU 后端和性能优化专项。
- 工程 benchmark 和长跑算例。
0.2.0 可以为后续多物理能力保留接口和字段,但不得把占位能力描述为已实现物理算法。
## 4. 目录结构调整
0.2.0 沿用 0.1.1 目录结构,不新增 `geometry/` 或 `mesh/` 目录。
建议重点完善:
```text
src/
particle/
kernel
neighbor
material/
water material and EOS helpers
water/
density, pressure, viscosity, acceleration, diagnostics
solver/
explicit Velocity-Verlet force coupling
tests/
unit/
module/
interface/
data/
tools/
testing/
```
测试或示例所需的 `.inp` 文件可以手写或由 Python 辅助脚本生成,但这些脚本仍只属于测试/示例辅助工具,不属于求解器几何或粒子生成功能。
## 5. 数据库和运行时状态范围
0.2.0 继续采用集中型数据库。通用粒子状态仍由 `Database` 管理,`Water` 只维护水相计算所需参数、派生量、临时数组和诊断量。
0.2.0 应确认或完善以下通用状态:
- `particle_id_ext`
- `particle_phase`
- `particle_status`
- `material_id`
- `section_id`
- `x0(3,npart)`
- `x(3,npart)`
- `v(3,npart)`
- `a(3,npart)`
- `vhalf(3,npart)`
- `mass(npart)`
- `rho(npart)`
- `volume(npart)`
- `pressure(npart)`
- `internal_energy(npart)`
- `temperature(npart)`
- `h(npart)`
0.2.0 新增或完善的运行时状态建议包括:
- 每粒子的密度变化率 `drho_dt(npart)`。
- 每粒子的压力加速度贡献 `acc_pressure(3,npart)`。
- 每粒子的人工黏性加速度贡献 `acc_viscosity(3,npart)`。
- 每粒子的外部体力加速度贡献或等效力缓存。
- 邻域搜索 cell id、链表或压缩索引。
- 邻域对或邻域表。
- 每粒子邻居数量。
- 水相总质量、总动量、最大压力、压力冲量和时间步约束诊断。
邻域表应由 `Particle` 或邻域模块统一维护,水相模块按 phase、material、section 或 region 过滤相互作用。0.2.0 不建立多张互相独立的邻域表。
## 6. 输入解析范围
0.2.0 在 0.1.1 `.inp` 子集基础上增加水相计算所需参数解析。仍不追求完整 Abaqus 兼容,能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的 SPHLite 专有能力使用 `*SPHLITE ...` 扩展关键词。
建议输入能力:
- `*NODE`:继续读取 3D 粒子坐标。
- `*ELEMENT`:继续保存粒子或粒子集合连接占位,用于 set/section/material 映射。
- `*NSET` / `*ELSET`:继续作为集合,不作为物理类型判断依据。
- `*MATERIAL`:保存材料名称,并允许识别水材料类型。
- `*DENSITY`:优先复用 Abaqus 关键词读取参考密度。
- `*SECTION` 或等价 section 关键词:保存 section 与 material 引用。
- `*SPHLITE TIME CONTROL`:继续控制 `DT`、`TIME`、`STEPS` 和安全系数。
- `*SPHLITE OUTPUT`:继续控制输出目录和输出间隔。
- `*SPHLITE EOS`:建议作为 Tait EOS 参数入口。
- `*SPHLITE VISCOSITY`:建议作为 Monaghan 人工黏性参数入口。
- `*SPHLITE PARTICLE CONTROL`:建议作为 `h`、初始质量或体积等粒子数值参数入口。
- `*SPHLITE BODY FORCE`:可选,用于重力或小型验证算例体力。
建议 Tait EOS 字段:
- `TYPE=TAIT`
- `MATERIAL=<name>`
- `RHO0`
- `C0`
- `GAMMA`
- `P0`
- `B` 可选;若未给定,可由 `rho0*c0*c0/gamma` 计算。
建议 Monaghan 人工黏性字段:
- `TYPE=MONAGHAN`
- `MATERIAL=<name>`
- `ALPHA`
- `BETA`
- `ETA2`
0.2.0 应对缺失关键水相参数报 error,对不影响运行的未知关键词报 warning。输入错误消息应继续包含文件名和行号上下文。
## 7. 核函数范围
0.2.0 应建立 `Particle` 核函数模块,提供:
- `W(r,h)`。
- `grad W(r,h)`。
- 核函数支持半径。
- 3D 归一化系数。
- 核函数类型选择。
- 对非法 `h <= 0` 和非法核函数类型的错误路径。
默认核函数为 Wendland C2。Wendland C4 作为可选核函数,cubic spline 作为对比和回归测试核函数。
单元测试应覆盖:
- `r = 0` 处函数值有限。
- 超出支持半径时 `W = 0` 且梯度为零。
- 梯度方向与粒子连线方向一致。
- 对称粒子对的梯度反对称性。
- 不同 `h(i)` 下结果有限且符号正确。
0.2.0 不要求做完整三维积分归一性高精度 benchmark,但应保留后续 checker 入口。
## 8. 邻域搜索范围
0.2.0 邻域搜索采用 uniform cell/bin 方法,不引入树结构。
邻域搜索应支持:
- 根据当前坐标计算全局包围盒。
- 根据最大支持半径确定 cell 尺寸。
- 建立粒子到 cell 的映射。
- 遍历相邻 cell 生成邻域。
- 支持每粒子独立 `h(i)`。
- 对 phase、status 或 region 的过滤留给物理模块。
- 粒子移动后可重建邻域。
邻域测试应覆盖:
- 与朴素 `O(n^2)` 搜索结果一致。
- 不同 `h(i)` 的搜索半径。
- 空模型和单粒子模型。
- 粒子移动后重建。
- 边界 cell 和负坐标。
- 最大邻居数量或邻域表容量不足时的明确错误。
0.2.0 默认 gate 中邻域测试应保持小规模,不进入性能基准。
## 9. Water 模块范围
0.2.0 `Water` 模块应实现弱可压 SPH 最小闭环。
水相 EOS:
- 使用 Tait EOS。
- 压力由 `rho`、`rho0`、`c0`、`gamma`、`p0` 和可选 `B` 计算。
- 压力可允许为负值或设置拉伸限制,具体策略应在实现前写入测试说明。
水相密度:
- 主流程采用连续性方程。
- 不使用 summation density 作为主流程。
- 0.2.0 可保留 summation density 对比 checker 的后续入口,但不进入生产路径。
水相动量:
- 包含压力梯度项。
- 包含 Monaghan 型人工黏性项。
- 支持外部体力或体力占位。
- 默认只处理 water-water 相互作用。
- 对非 water phase 的粒子默认跳过,后续多相版本再引入水-气或水-结构相互作用。
水相诊断:
- 水相粒子数。
- 水相总质量。
- 水相总动量。
- 最大压力。
- 最小/最大密度。
- 压力冲量占位。
- CFL、加速度和黏性时间步约束贡献。
## 10. Solver 集成范围
0.2.0 继续使用 Velocity-Verlet 作为唯一主时间推进格式。
建议单步流程:
```text
校验模型和时间步
必要时重建邻域
根据 rho 计算 pressure
计算 drho_dt
计算水相压力和黏性加速度
加入体力或外部载荷占位
Velocity-Verlet 更新速度、位置、密度和时间
更新诊断
按间隔输出
```
稳定时间步估计应至少考虑:
- `dt_cfl = h / (c + |v|)` 类型的声速约束。
- 加速度约束。
- 人工黏性约束。
- 输入安全系数。
0.2.0 不引入隐式、静力、非线性静力或隐式-显式混合求解接口。
## 11. Output 和 Restart 范围
0.2.0 CSV 输出应在 0.1.1 字段基础上确保可检查水相计算结果:
- id
- phase
- status
- material
- section
- x
- v
- rho
- pressure
- temperature
- h
建议增加可选诊断输出或独立 summary:
- step
- time
- water mass
- water momentum
- max pressure
- min/max density
- dtcrit
restart 应保存 0.2.0 继续计算所需状态:
- 0.1 系列通用粒子状态。
- 当前时间、步数、输出控制。
- 速度、加速度和半步速度。
- 水相 EOS 和人工黏性参数。
- 密度、压力、内能、温度和 `h`。
- 邻域搜索控制参数。
- 水相诊断状态。
邻域表本身可以不写入 restart,读入 restart 后允许重建邻域,但控制参数必须可恢复。
## 12. Fortran API 范围
0.2.0 Fortran API 继续作为核心语义来源。建议在 0.1.1 API 基础上增加或完善:
```fortran
subroutine sph_rebuild_neighbors(ierr)
subroutine sph_get_neighbor_stats(max_neighbors, average_neighbors, ierr)
subroutine sph_get_water_summary(mass, momentum, max_pressure, min_density, max_density, ierr)
subroutine sph_get_water_dt_limits(dt_cfl, dt_accel, dt_viscous, ierr)
```
其中 `momentum` 为三维向量。若 0.2.0 实现阶段认为公开 neighbor API 过早,可先保留为 Fortran 模块测试入口,不进入 C ABI。
已有 API 必须继续可用:
- 生命周期。
- `.inp` 读取。
- build model。
- stable dt。
- advance/run explicit。
- current time。
- particle count/state。
- output/restart。
- error query。
所有新增可失败接口必须返回错误码,并写入最近错误消息。
## 13. C ABI、C++ 和 Python 范围
C ABI 应保持 0.1.1 已有接口兼容。0.2.0 建议增加水相诊断查询:
```c
int sphlite_get_water_summary(double *mass,
double *momentum,
double *max_pressure,
double *min_density,
double *max_density);
int sphlite_get_water_dt_limits(double *dt_cfl,
double *dt_accel,
double *dt_viscous);
```
数组约定:
- `momentum[0..2]` 为三维总动量。
C 参数错误仍返回 `-1`。Fortran 物理、输入或数据库错误仍返回 SPHLite 错误码。
C++ wrapper 仍保持薄包装定位:
- 包装新增水相 summary 和 dt limits。
- 不重新定义物理语义。
- 不作为核心实现语言。
Python `ctypes` 调试入口应扩展:
- 读取水相 summary。
- 读取 dt limits。
- 提供小型 run/checker 辅助函数。
- 保持缺失输入、缺失参数和错误路径测试。
Python 仍不是唯一入口,CLI 和 C ABI 必须完整可用。
## 14. CLI 范围
0.2.0 CLI 应保持 0.1.1 用法:
```powershell
sphlite model.inp
sphlite model.inp --check
sphlite model.inp --run
sphlite model.inp --run --output output
sphlite --version
```
建议增加或稳定以下 inspect/check 输出字段:
- `version`
- `input`
- `mode`
- `particles`
- `warnings`
- `time`
- `step`
- `status`
- `water_particles`
- `water_mass`
- `max_pressure`
- `dtcrit`
CLI 内部仍必须走公共生命周期 API,不绕过 Fortran API 或 C ABI。
## 15. CouplingInterface 边界
0.2.0 不实现外部耦合模块,也不依赖 FEMLite。CouplingInterface 维持 0.1.1 中立接口占位。
0.2.0 可做的最小加固:
- 确认水相运行后 coupling particle 导出仍可用。
- 确认外部粒子力导入可以进入显式步体力或外载占位。
- 继续记录耦合功、动量和能量诊断占位。
- 保持接触耦合和连续体耦合类型区分。
0.2.0 默认 gate 不包含真实 FEM-SPH 联合运行。
## 16. 测试计划
0.2.0 默认 gate 建议包含:
- `smoke`:版本 0.2.0、生命周期、显式步进和基础错误路径。
- `input`:Water material、Tait EOS、viscosity、particle control、warning/error。
- `kernel`:Wendland C2、Wendland C4、cubic spline 的基础性质。
- `neighbor`:uniform cell/bin 与朴素搜索一致。
- `water_eos`:Tait EOS 压力计算和非法参数错误。
- `water_density`:连续性方程密度变化率方向和量级。
- `water_viscosity`:Monaghan 人工黏性方向、有限性和对称性。
- `water_force`:压力梯度和黏性加速度 smoke。
- `solver_water`:Velocity-Verlet 与 Water 力计算闭环。
- `output`:CSV 字段包含 0.2.0 水相状态。
- `restart`:水相参数和状态写入、读回、继续最小显式步。
- `c_api`:新增水相诊断接口和原有 C ABI 兼容性。
- `cpp_api`:新增水相诊断薄包装 smoke。
- `python_debug`:水相 inspect/run/checker smoke。
- `cli`:0.2.0 inspect/check/run/version/error。
- `pressure_wave_smoke`:小型 3D 压力扰动传播 smoke。
- `source_size`:Fortran/C/C++/Python 文件大小和 stale exception。
0.2.0 的 `pressure_wave_smoke` 应只验证方向、有限性、守恒量趋势和输出字段,不作为工程精度 benchmark。
非默认测试可保留:
- 更大粒子数压力传播。
- 水柱或自由面示例。
- 参数收敛研究。
- 与解析波速的更严格对比。
这些不进入默认 release gate。
## 17. 0.2.0 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|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` 和新增测试目标。
- 默认 gate 全部通过。
- source size 通过。
- `git diff --check` 通过。
- README、09 和 11 号文档记录 0.2.0 gate 结果。
- 文档状态与实际能力一致,不宣称已实现水下爆炸完整能力。
- 输出目录、CSV、VTK、restart 和 Python 缓存不进入提交。
- 文档使用 UTF-8 without BOM。
## 18. 开发阶段拆分
### 阶段 A:版本和测试骨架
- 将软件版本更新为 0.2.0。
- 新增 `kernel`、`neighbor`、`water_eos` 等 CTest 目标占位。
- 准备最小 Water `.inp` 测试数据。
- 保持 0.1.1 gate 继续通过。
### 阶段 B:核函数模块
- 实现 Wendland C2。
- 实现 Wendland C4。
- 实现 cubic spline。
- 统一核函数类型选择。
- 增加核函数单元测试。
### 阶段 C:邻域搜索模块
- 实现 uniform cell/bin 数据结构。
- 实现邻域构建和重建。
- 支持每粒子独立 `h(i)`。
- 增加与朴素搜索对比测试。
### 阶段 D:Water 参数和 Tait EOS
- 扩展 input 解析水材料、Tait EOS 和粒子控制参数。
- 实现 Tait EOS。
- 增加非法参数错误路径。
- 增加 water summary 诊断占位。
### 阶段 E:连续性方程和人工黏性
- 实现 `drho_dt` 计算。
- 实现 Monaghan 人工黏性。
- 实现压力梯度加速度。
- 建立水相力计算主入口。
### 阶段 F:Solver、Output 和 Restart
- 将 Water 力计算接入 Velocity-Verlet。
- 实现稳定时间步估计。
- 扩展 CSV 输出字段和 summary。
- 扩展 restart 保存水相状态和控制参数。
- 增加继续运行测试。
### 阶段 G:接口和 CLI
- 增加 Fortran 水相诊断 API。
- 增加 C ABI 水相诊断 API。
- 扩展 C++ wrapper。
- 扩展 Python 调试入口。
- 扩展 CLI inspect/check/run 输出。
### 阶段 H:Pressure Wave Smoke 和 Gate
- 创建小型 3D pressure wave `.inp`。
- 实现 pressure wave checker。
- 更新 README、09 和 11 号文档。
- 更新 `todo.md`。
- 跑通 0.2.0 release gate。
## 19. 风险和控制
| 风险 | 控制 |
|---|---|
| 0.2.0 膨胀为完整水下爆炸版本 | 只交付 Water 基础弱可压 SPH,不做 Gas/Explosive/Solid/Shell 生产路径 |
| 邻域搜索过早复杂化 | 只做 uniform cell/bin,树结构和并行优化推迟 |
| 输入参数语法摇摆 | 先锁定 Tait EOS、viscosity 和 particle control 的最小字段 |
| 压力波 smoke 变成长跑 benchmark | 默认 gate 只保留小粒子数、短时间、趋势检查 |
| Tait EOS 单位混乱 | 继续沿用 Abaqus/FEMLite 风格,不做内置单位换算,示例中明确参数单位一致性 |
| 人工黏性导致数值不稳定 | 从小型对称测试和有限性测试开始,默认参数保守 |
| restart 状态缺失导致继续运行不一致 | 0.2.0 明确保存水相参数、密度、压力、速度、加速度和时间控制 |
| C ABI 与 Fortran API 分叉 | Fortran API 仍是语义来源,C ABI 只做薄包装 |
| 文档宣称超过实际能力 | README、09、11 和本计划均明确 0.2.0 不交付水下爆炸完整能力 |
## 20. 后续版本衔接
0.2.0 完成后,0.3 可集中进入 `Gas`:
- JWL EOS。
- 理想气体 EOS。
- Stiffened gas EOS。
- 气体总体积、中心、平均压力和最大压力。
- 等效气泡半径和半径变化率。
- 气体团簇统计。
0.2.0 应为 0.3 保留统一粒子数据库、phase 过滤、邻域搜索、输出、restart 和诊断接口,但不提前实现气体生产计算。
## 21. 待确认事项
- Tait EOS 第一版是否允许负压,或是否设置拉伸压力限制。
- `*SPHLITE EOS`、`*SPHLITE VISCOSITY` 和 `*SPHLITE PARTICLE CONTROL` 的最终字段名。
- 初始质量、体积和 `h` 是统一给定、逐粒子给定,还是由 section/material 默认值推导。
- Monaghan 人工黏性默认 `alpha`、`beta` 和 `eta2` 建议值。
- `pressure_wave_smoke` 的最小粒子布置和 checker 阈值。
- 水相 summary 是否进入 C ABI,还是先保留为 Fortran/Python 测试入口。
- 0.2.0 是否需要新增 VTK 输出占位,或继续只用 CSV 作为默认 gate 输出。