Files
SPHLite/docs/v5.1_development_plan.md
2026-07-03 16:54:45 +08:00

514 lines
22 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 v5.1 开发计划
文档状态:0.5.1 开发计划草案
目标软件版本:SPHLite 0.5.1
## 1. 文档定位
本文档用于规划 SPHLite 0.5.1 版本的开发范围。0.5.1 是 `Solid` 版本线的稳定化和结构算法加固版本,目标是在 0.5.0 已完成 3D 实体结构粒子输入、状态、本构、失效、显式推进、restart、接口和 gate 最小闭环的基础上,补强 Solid 参考构型、速度梯度、应变率、最小内力、能量诊断、restart 兼容和接口可观测性。
0.5.1 不作为 `Shell` 版本,也不作为真实水-气-结构工程爆炸响应版本。0.5.1 的重点是让 `Solid` 从材料点和体力驱动 smoke,推进到更清晰的结构 SPH 算法闭环,使后续 `Shell`、水-气-结构 smoke 和 FEM-SPH 耦合版本能够依赖更稳定的结构粒子力学状态。
## 2. 依据文件
本计划依据以下 01-06 号文档制定:
- `docs/01_requirements_specification.md`
- `docs/02_software_architecture_design.md`
- `docs/03_detailed_design.md`
- `docs/04_mathematical_model_and_algorithms.md`
- `docs/05_interface_control_document.md`
- `docs/06_test_and_verification_plan.md`
同时,0.5.1 以已发布的 0.5.0 Solid 起步闭环为开发基线。
## 3. 版本定位
### 3.1 与 0.5.0 的关系
0.5.0 已完成以下 Solid 最小闭环:
- `TYPE=SOLID` material 和 `*SOLID SECTION` 输入识别。
- Solid 密度、弹性、Johnson-Cook flow/failure 和 softening 参数读取。
- Solid 应力、应变、塑性应变、温度、damage、softening、内能、失效状态等状态数组。
- 弹性材料点、Johnson-Cook 材料点、失效 damage 累积和线性渐进软化。
- Solid-only 显式 smoke、结构波速稳定时间步、CSV 输出和 `STATE_0_5` restart。
- Solid summary、failure counts、Fortran API、C ABI、C++ wrapper、Python ctypes、CLI 字段和 Solid 专项 gate。
0.5.1 不重写 0.5.0 的材料输入和接口边界。0.5.1 应保持 0.5.0 全量 gate 稳定,并在此基础上增强 Solid 结构计算的可测性和可恢复性。
### 3.2 与 0.6.0 的关系
0.6.0 仍建议作为 `Shell` 版本线起点。0.5.1 不实现 Mindlin-Reissner 板壳生产路径,不实现厚度积分点、director、角速度、板壳撕裂或穿孔。0.5.1 可继续维护 `Shell` phase/status 和 section 占位,但不得宣称已实现板壳结构响应。
### 3.3 与耦合版本的关系
真实 FEM-SPH 接触耦合和连续体耦合仍属于后续 0.8/0.9。0.5.1 只维护 SPHLite 内部 `Solid` 粒子状态和中立 `CouplingInterface` 边界,不直接依赖 FEMLite,不修改 FEMLite,也不引入外部 CouplingModule 作为依赖。
### 3.4 0.5.1 核心目标
0.5.1 的核心目标是形成更可靠的 3D `Solid` 小型结构动力学闭环:
```text
0.5.0 Solid material/state/restart/API baseline
-> reference neighbor and correction quality checks
-> velocity gradient and strain-rate update
-> stress update driven by kinematics
-> stress/softening contribution to internal force
-> energy and momentum diagnostics
-> STATE_0_5_1 restart and STATE_0_5 compatibility
-> 0.5.0 full regression remains stable
```
## 4. 开发原则
### 4.1 保持 0.5 版本线边界
0.5.1 只加固 3D `Solid` 实体结构粒子能力,不进入 `Shell`、真实水-气-结构耦合、真实 FEM-SPH 耦合或工程级船舱破坏 benchmark。
### 4.2 保持求解器定位
SPHLite 仍是求解器,不负责几何建模、网格生成或粒子生成。新增 `.inp` 样例和 Python 脚本只能作为测试、示例或 checker 辅助工具,不作为求解器功能宣传。
### 4.3 保持 Fortran 95 和集中型数据管理
核心实现继续使用 Fortran 95。Solid 新状态应纳入集中数据库或 Solid 模块级状态管理,不采用面向对象粒子类设计。C ABI、C++ wrapper、Python ctypes 和 CLI 继续作为薄接口层。
### 4.4 保持显式动力学主流程
时间推进继续只支持 Velocity-Verlet 显式动力学。0.5.1 可增强 Solid 应变率、内力和能量路径,但不引入隐式求解、静力求解、非线性静力求解或隐式-显式混合接口。
### 4.5 小型可测优先
Solid 结构算法增强必须先通过小型、可重复测试验收。0.5.1 不追求复杂断裂路径、碎片云、焊缝失效、复杂接触或工程级舱段破坏。
### 4.6 不破坏既有接口
C ABI 必须追加式扩展。不得改变 0.5.0 已有函数的字段含义、数组长度约定或错误码语义。新增 Solid 粒子级状态查询应采用新函数和 caller-allocated buffer 风格。
## 5. 0.5.1 交付目标
0.5.1 建议交付以下内容:
1. 将软件版本更新为 `0.5.1`。
2. 保持 0.5.0 默认 gate 全部通过。
3. 加固 Solid material、section、phase/status 的输入校验和 warning/error 路径。
4. 建立或补强 Solid 参考邻域质量诊断,包括参考邻居数、退化邻域和修正矩阵状态。
5. 实现 Solid 修正矩阵的有限性、奇异性和条件质量检查。
6. 实现或补强 Solid 速度梯度计算入口。
7. 实现 Solid 应变率和应变增量更新入口。
8. 让弹性和 Johnson-Cook 材料点更新能够由 Solid 运动学增量驱动。
9. 实现最小 Solid 内力贡献路径,至少覆盖应力散度或等价对称力贡献。
10. 保证零应力、均匀平动和无 active Solid 粒子时不产生虚假内力。
11. 保证简单成对或对称粒子布置下内力动量残差受控。
12. 将 softening 作用到应力或内力贡献路径,并保持失效不可逆。
13. 加固 Solid 动能、内能、塑性功、damage、softening 和动量诊断。
14. 新增 Solid 最大应变率、最大加速度或内力残差等调试诊断。
15. 将 Solid 结构波速和加速度约束继续纳入全局 dt 估计,并覆盖 0.5.0 回归。
16. 将 restart 状态版本更新为 `STATE_0_5_1`,保存新增 Solid 持久状态和诊断。
17. 保持 `STATE_0_5` restart 兼容读入,并为新增状态提供安全默认值。
18. 保持 `STATE_0_4_1`、`STATE_0_4` 和更早可支持状态兼容读入。
19. 在 summary CSV 和粒子 CSV 中追加必要的 Solid 0.5.1 调试字段。
20. 新增 Solid 粒子级状态查询 Fortran API 和 C ABI。
21. 在 C++ wrapper、Python ctypes 和 CLI 中追加 Solid 0.5.1 诊断字段。
22. 新增 0.5.1 Solid 专项 CTest gate,并保持 source size 受控。
23. 更新 README、06、09 和 11 号文档中的 0.5.1 测试、验收和不交付范围。
24. 不新增 FEMLite 直接依赖,不修改 SPHLite 文件夹之外的内容。
## 6. 非交付范围
0.5.1 不交付以下内容:
1. 不实现 `Shell` Mindlin-Reissner 生产求解路径。
2. 不实现板壳厚度积分、director 更新、板壳撕裂或穿孔。
3. 不实现真实水-气-结构工程爆炸响应。
4. 不实现爆炸载荷作用下的船体破坏工程 benchmark。
5. 不实现真实 FEM-SPH 接触耦合或连续体耦合。
6. 不实现生产级断裂面追踪、裂纹扩展、碎片云或焊缝失效库。
7. 不实现复杂接触、碰撞、摩擦或碎片-流体相互作用。
8. 不实现热传导、熔化、相变或完整热-力耦合。
9. 不实现大规模并行、GPU 后端或性能优化版本。
10. 不新增几何、网格或粒子生成能力。
## 7. 输入和校验加固
### 7.1 Solid material 校验
0.5.1 应保持 0.5.0 已支持的 Solid 输入语法,并加固以下校验:
- Solid material 必须有正密度。
- 弹性模量必须为正值。
- 泊松比必须处于受控范围。
- Johnson-Cook flow 参数必须有限。
- 请求 failure 时 Johnson-Cook failure 参数必须完整且有限。
- softening 类型必须为已支持类型;不支持类型报 error。
- 未被 active Solid 粒子使用的 Solid material 可 warning,不阻断其他路径运行。
### 7.2 Solid section 校验
`*SOLID SECTION` 继续作为 3D 实体结构 section 入口。0.5.1 应确认:
- section 指向的 material 必须存在。
- Solid section 指向非 Solid material 时应报 error。
- 缺少 Solid section 且存在 active Solid 粒子时应报 error 或给出明确默认策略。
- set 仍只表示集合,不作为 Solid 类型判断依据。
### 7.3 初始条件和受控小算例
0.5.1 的 Solid 小算例可继续使用已有 `*SPHLITE BODY FORCE`、初始速度和时间控制。若需要固定粒子或简化约束,应优先使用现有 status/phase/control 路径,不新增复杂边界条件库。
## 8. 参考构型和梯度修正
### 8.1 参考邻域
Solid 结构计算应以参考构型为主。0.5.1 建议保存或诊断:
- 每个 active Solid 粒子的参考邻居数。
- 参考邻域权重和参考体积。
- 参考邻域是否退化。
- 与非 Solid 粒子的过滤规则。
参考邻域不足时,0.5.1 可先 warning 或报受控 error。默认 gate 应覆盖退化邻域和正常邻域两类路径。
### 8.2 修正矩阵
0.5.1 建议将 `solid_correction_matrix(3,3,npart)` 从占位推进到可诊断状态:
- 构建参考梯度矩阵。
- 判断矩阵有限性。
- 判断行列式是否接近退化。
- 保存或统计修正质量指标。
- 对不可逆矩阵采用受控 fallback,不静默给出错误内力。
若 0.5.1 仍不交付完整工程 TL-SPH 修正,应在文档和测试中明确其小型 smoke 范围。
### 8.3 变形梯度
0.5.1 建议补强 `solid_deformation_gradient(3,3,npart)`:
- 初始状态为单位阵。
- 显式步中由速度梯度或位移梯度更新。
- 受控小变形测试下与解析预期一致。
- restart 后可恢复。
## 9. 运动学、本构和失效耦合
### 9.1 速度梯度和应变率
0.5.1 建议新增或补强以下计算:
- `Solid` 速度梯度 `L = grad(v)`。
- 小应变率或等价对称部分 `D = 0.5 * (L + L^T)`。
- 旋转部分或 Jaumann 率后续预留。
- 等效塑性应变率的安全计算。
第一版测试应覆盖:
- 均匀平动下速度梯度为零。
- 简单拉伸速度场下应变率方向和量级正确。
- 非 Solid 粒子不污染 Solid 速度梯度。
### 9.2 本构更新入口
0.5.1 应让材料点更新不再只依赖人工构造增量,而能从 Solid 显式步提供的应变增量进入:
```text
velocity gradient
-> strain-rate / strain increment
-> elastic trial stress
-> Johnson-Cook flow correction
-> Johnson-Cook damage update
-> progressive softening
-> stress used by internal force
```
等温退化仍可作为 gate 默认路径,但温度和等效温升状态必须继续保存。
### 9.3 失效不可逆
0.5.1 应继续确认:
- damage 单调不减。
- softening 单调不增。
- `PHASE_SOLID_FAILED` 不可逆。
- 失效不删除粒子,不改变质量。
- restart 后失效和 softening 状态不被重置。
## 10. Solid 内力和能量诊断
### 10.1 最小内力路径
0.5.1 建议实现最小 Solid 内力贡献路径。第一版目标不是工程级断裂,而是形成可测的应力到加速度链路:
- 零应力时 Solid 内力为零。
- 均匀平动不产生内力。
- 简单双粒子或对称粒子布置下内力成对平衡。
- softening 可降低失效粒子的内力贡献。
- 无 active Solid 粒子时跳过 Solid 内力路径。
### 10.2 动量和能量诊断
0.5.1 应加固 Solid 诊断:
- Solid 总质量。
- Solid 总动量。
- Solid 动能。
- Solid 内能。
- 塑性功或等价内能增量。
- 最大 von Mises 应力。
- 最大应变率。
- 最大 Solid 加速度。
- damage 和 softening 范围。
- 内力动量残差或等价平衡诊断。
### 10.3 与 Water/Gas/Explosive 的隔离
Solid 内力和诊断增强不得改变 Water-only、Gas-only、Explosive-Gas-Water 既有算例结果。0.5.1 必须保留 0.5.0 完整回归。
## 11. 稳定时间步
0.5.1 继续使用 Velocity-Verlet 显式推进。Solid dt 约束建议包括:
```text
dt_solid_wave = cfl * h / (c_solid + |v|)
dt_solid_acc = cfl_acc * sqrt(h / (|a_solid| + eps))
dt_solid = min(dt_solid_wave, dt_solid_acc)
```
其中加速度约束可作为 0.5.1 的新增诊断或受控选项。默认 gate 应验证:
- 无 active Solid 时不影响全局 dt。
- 有 active Solid 时 dt 有限且为正。
- 内力或体力增大时加速度约束可收紧。
- restart 后 dt 诊断一致。
## 12. 输出和 Restart
### 12.1 CSV 输出
0.5.1 建议在 summary CSV 中追加或确认以下字段:
- `solid_max_strain_rate`
- `solid_max_acceleration`
- `solid_internal_force_residual`
- `solid_reference_neighbor_min`
- `solid_correction_det_min`
- `solid_correction_status`
粒子 CSV 可追加:
- `solid_strain_rate_eq`
- `solid_acceleration_norm`
- `solid_reference_neighbor_count`
- `solid_correction_status`
如果字段过多,0.5.1 可优先将完整粒子级调试状态放入 API 和 module tests,CSV 只保留 release gate 最有价值的字段。
### 12.2 Restart
0.5.1 建议写入 `STATE_0_5_1`。必须保存或可恢复:
- 0.5.0 已有粒子通用状态。
- Velocity-Verlet 所需 `v`、`a` 和 `vhalf`。
- Water、Gas、Explosive 既有模块状态。
- Solid material 表。
- Solid per-particle 应力、应变、塑性、温度、damage、softening、内能、失效状态。
- Solid 参考构型、修正矩阵、变形梯度和新增诊断状态。
- 时间步诊断和输出计数。
兼容读入:
- `STATE_0_5_1`:完整读回。
- `STATE_0_5`:读回 0.5.0 Solid 状态,并初始化 0.5.1 新状态。
- `STATE_0_4_1` 及更早可支持状态:初始化空 Solid 状态。
restart 后继续显式步不得重复初始化 Solid 应力、塑性应变、damage、softening、变形梯度或失效状态。
## 13. API、C ABI、C++、Python 和 CLI
### 13.1 Fortran API
0.5.1 建议新增或补强:
- `sph_get_solid_state`
- `sph_get_solid_diagnostics`
- `sph_get_solid_reference_quality`
若粒子级 state 查询过大,Fortran API 可拆分为计数查询、summary 查询和 caller-allocated buffer 查询。
### 13.2 C ABI
C ABI 应保持追加式扩展。建议新增:
```c
int sphlite_get_solid_particle_state(int max_particles,
int *particle_id_ext,
int *phase,
int *failure_status,
double *stress,
double *strain,
double *plastic_strain,
double *damage,
double *softening,
double *strain_rate,
int *count);
```
数组展开顺序建议:
- `stress[component + 6 * particle]`
- `strain[component + 6 * particle]`
- `strain_rate[component + 6 * particle]`
空指针、非正容量、未初始化状态和小容量必须走既有错误路径。
### 13.3 C++ wrapper 和 Python ctypes
C++ 和 Python 继续做 C ABI 薄包装,不重新定义 Solid 物理语义。Python checker 应覆盖:
- Solid state 查询。
- Solid 小模型 run 后应力、damage、softening 和 strain-rate 字段。
- 0.5.1 restart 读回后的 Solid state 一致性。
- 0.5.0 restart 兼容读入后的安全默认值。
### 13.4 CLI
CLI inspect/run 可追加:
- `solid_max_strain_rate`
- `solid_max_acceleration`
- `solid_internal_force_residual`
- `solid_correction_status`
- `solid_reference_neighbor_min`
CLI 测试应覆盖:
- Solid 0.5.1 输入 inspect。
- Solid-only 小模型 run。
- Solid restart 读回 inspect 或 run。
- Solid 错误输入。
## 14. 测试计划
### 14.1 新增 0.5.1 测试
建议新增以下测试:
- `solid_051_input_validation`:Solid material/section 校验、warning/error 路径。
- `solid_reference_neighbor`:参考邻域计数、退化邻域和非 Solid 过滤。
- `solid_correction_matrix`:修正矩阵有限性、退化检测和安全 fallback。
- `solid_velocity_gradient`:均匀平动、单轴拉伸速度场和非 Solid 过滤。
- `solid_strain_increment`:应变率到应变增量的受控更新。
- `solid_internal_force_pair`:成对粒子内力方向和动量平衡。
- `solid_uniform_stress_balance`:对称布置下均匀应力残差受控。
- `solid_softening_force`:softening 对内力或应力贡献的折减。
- `solid_energy_diagnostics`:动能、内能、塑性功或等价能量诊断。
- `solid_dt_acceleration`:Solid 加速度约束和全局 dt 贡献。
- `solid_restart_051`:`STATE_0_5_1` 写入读回并继续显式步。
- `solid_restart_050_compat`:`STATE_0_5` 兼容读入并初始化 0.5.1 新状态。
- `solid_state_api`:Fortran API 和 C ABI 的 Solid 粒子级状态查询。
- `solid_python_051`:Python ctypes 的 Solid 0.5.1 诊断。
- `solid_cli_051`:CLI 的 Solid 0.5.1 inspect/run/restart 字段。
- `solid_051_source_size`:Solid 0.5.1 source size 和 stale exception 检查。
### 14.2 既有回归测试
0.5.1 必须继续通过 0.5.0 完整 gate,包括:
- Water gate。
- Gas gate。
- Explosive 0.4.0 gate。
- Explosive 0.4.1 gate。
- Solid 0.5.0 gate。
- output/restart gate。
- C API/C++/Python/CLI gate。
- source size gate。
### 14.3 建议 0.5.1 Release Gate
建议 0.5.1 默认 gate 为:
```powershell
cmake --build build-codex-unix --parallel
ctest --test-dir build-codex-unix --output-on-failure
ctest --test-dir build-codex-unix -R "^(input_solid_material|input_solid_errors|solid_state_build|solid_elastic_material|solid_johnson_cook_flow|solid_johnson_cook_failure|solid_progressive_softening|solid_gradient_correction|solid_stable_dt|solid_explicit_smoke|solid_output|solid_restart_050|solid_restart_041_compat|solid_c_api|solid_python|solid_cli|solid_source_size)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^(solid_051_input_validation|solid_reference_neighbor|solid_correction_matrix|solid_velocity_gradient|solid_strain_increment|solid_internal_force_pair|solid_uniform_stress_balance|solid_softening_force|solid_energy_diagnostics|solid_dt_acceleration|solid_restart_051|solid_restart_050_compat|solid_state_api|solid_python_051|solid_cli_051|solid_051_source_size)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
```
## 15. 建议开发阶段
若后续根据本计划生成 `todo.md`,建议按以下阶段拆分:
1. 0.5.1 版本号、0.5.0 发布基线和文档范围确认。
2. Solid 0.5.1 输入样例、错误输入样例和小型结构 smoke 样例准备。
3. Solid material/section 校验加固。
4. 参考邻域计数、过滤和退化诊断。
5. 修正矩阵构建、有限性检查和 fallback。
6. 变形梯度初始化、更新和 restart 默认值。
7. 速度梯度和应变率计算。
8. 应变增量驱动的弹性材料点更新。
9. 应变增量驱动的 Johnson-Cook flow/failure 更新。
10. softening 对应力或内力贡献的作用路径。
11. 最小 Solid 内力贡献和成对平衡测试。
12. Solid 能量、动量、应变率、加速度和内力残差诊断。
13. Solid dt 加速度约束或新增 dt 诊断。
14. summary CSV 和粒子 CSV 字段扩展。
15. `STATE_0_5_1` restart 写入。
16. `STATE_0_5_1` restart 读回。
17. `STATE_0_5` 和更早 restart 兼容读入。
18. Fortran API 和 C ABI 的 Solid 粒子级状态查询。
19. C++ wrapper、Python ctypes 和 CLI 扩展。
20. source size 复核和必要拆分。
21. 0.5.0 全量回归和 0.5.1 新增 gate。
22. README、06、09 和 11 号文档同步。
## 16. 验收标准
0.5.1 应满足以下验收标准:
1. 软件版本为 `0.5.1`。
2. 0.5.0 release gate 继续通过。
3. Solid material 和 Solid section 校验路径清晰。
4. 参考邻域和修正矩阵诊断可用。
5. 速度梯度和应变率在受控小算例中与预期一致。
6. Solid 应力更新可由显式步运动学增量驱动。
7. 最小 Solid 内力路径可运行,并通过零应力、均匀平动和成对平衡测试。
8. softening 可影响应力或内力贡献,失效仍不可逆且不删除粒子。
9. Solid 能量、动量、最大应变率、最大加速度和 damage/softening 诊断可用。
10. Solid dt 约束有限为正,并可进入全局 dt 估计。
11. `STATE_0_5_1` restart 可恢复 Solid 0.5.1 状态并继续显式步。
12. `STATE_0_5` restart 可兼容读入,并初始化新增状态。
13. Solid 粒子级状态 Fortran API、C ABI、C++ wrapper、Python ctypes 和 CLI 字段可用。
14. 默认 gate、0.5.0 Solid gate、0.5.1 Solid gate、source size 和 `git diff --check` 通过。
15. 文档不宣称 0.5.1 已实现 Shell、真实水-气-结构爆炸响应、真实 FEM-SPH 耦合或工程级结构破坏 benchmark。
16. 不新增 FEMLite 直接依赖。
17. 不修改 SPHLite 文件夹之外的内容。
## 17. 风险与控制
| 风险 | 表现 | 控制方式 |
| --- | --- | --- |
| 0.5.1 范围膨胀 | 试图进入 Shell、水-气-结构工程爆炸或 FEM-SPH 耦合 | 限定为 Solid 结构算法小型闭环 |
| TL-SPH 内力实现不稳 | 小模型中出现非物理加速度或动量漂移 | 先做零应力、均匀平动、成对平衡和对称布置测试 |
| 修正矩阵退化 | 粒子布局不良导致奇异矩阵和非有限结果 | 明确退化检测、warning/error 和 fallback |
| 本构和运动学耦合错误 | 应变率方向或量级错误,导致应力更新失真 | 使用解析速度场和材料点退化测试锁定语义 |
| 失效处理破坏质量守恒 | 删除粒子或改变质量导致诊断跳变 | 失效只改变 phase/status/softening,不删除粒子 |
| Solid 更新影响既有算例 | 无 Solid 输入时仍进入 Solid 内力路径 | 无 active Solid 时直接跳过,并保持 0.5.0 全量回归 |
| API 兼容破坏 | 修改已有 Solid summary 字段或数组约定 | 新增粒子级状态 API,不改变 0.5.0 接口含义 |
| restart 不完整 | 读回后修正矩阵、变形梯度或失效状态丢失 | `STATE_0_5_1` 保存完整 Solid 0.5.1 持久状态 |
| source size 债务扩大 | Solid 内力、梯度和 restart 堆入单个大文件 | 按 reference、kinematics、force、restart、api 拆分 |
## 18. 0.6.0 启动条件
满足以下条件后,可以启动 0.6.0 `Shell`:
1. 0.5.1 Solid 参考构型、速度梯度、应变率和最小内力 gate 稳定。
2. Solid failure/softening 对动力学贡献路径可重复通过。
3. Solid output、restart、API、CLI 和 Python 诊断稳定。
4. 0.5.0 Water/Gas/Explosive/Solid gate 仍可重复通过。
5. 0.5.1 文档明确尚未实现 Shell、真实 FEM-SPH 耦合和工程级水下爆炸结构破坏 benchmark。