22 KiB
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.mddocs/02_software_architecture_design.mddocs/03_detailed_design.mddocs/04_mathematical_model_and_algorithms.mddocs/05_interface_control_document.mddocs/06_test_and_verification_plan.md
同时,0.5.1 以已发布的 0.5.0 Solid 起步闭环为开发基线。
3. 版本定位
3.1 与 0.5.0 的关系
0.5.0 已完成以下 Solid 最小闭环:
TYPE=SOLIDmaterial 和*SOLID SECTION输入识别。- Solid 密度、弹性、Johnson-Cook flow/failure 和 softening 参数读取。
- Solid 应力、应变、塑性应变、温度、damage、softening、内能、失效状态等状态数组。
- 弹性材料点、Johnson-Cook 材料点、失效 damage 累积和线性渐进软化。
- Solid-only 显式 smoke、结构波速稳定时间步、CSV 输出和
STATE_0_5restart。 - 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 小型结构动力学闭环:
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 建议交付以下内容:
- 将软件版本更新为
0.5.1。 - 保持 0.5.0 默认 gate 全部通过。
- 加固 Solid material、section、phase/status 的输入校验和 warning/error 路径。
- 建立或补强 Solid 参考邻域质量诊断,包括参考邻居数、退化邻域和修正矩阵状态。
- 实现 Solid 修正矩阵的有限性、奇异性和条件质量检查。
- 实现或补强 Solid 速度梯度计算入口。
- 实现 Solid 应变率和应变增量更新入口。
- 让弹性和 Johnson-Cook 材料点更新能够由 Solid 运动学增量驱动。
- 实现最小 Solid 内力贡献路径,至少覆盖应力散度或等价对称力贡献。
- 保证零应力、均匀平动和无 active Solid 粒子时不产生虚假内力。
- 保证简单成对或对称粒子布置下内力动量残差受控。
- 将 softening 作用到应力或内力贡献路径,并保持失效不可逆。
- 加固 Solid 动能、内能、塑性功、damage、softening 和动量诊断。
- 新增 Solid 最大应变率、最大加速度或内力残差等调试诊断。
- 将 Solid 结构波速和加速度约束继续纳入全局 dt 估计,并覆盖 0.5.0 回归。
- 将 restart 状态版本更新为
STATE_0_5_1,保存新增 Solid 持久状态和诊断。 - 保持
STATE_0_5restart 兼容读入,并为新增状态提供安全默认值。 - 保持
STATE_0_4_1、STATE_0_4和更早可支持状态兼容读入。 - 在 summary CSV 和粒子 CSV 中追加必要的 Solid 0.5.1 调试字段。
- 新增 Solid 粒子级状态查询 Fortran API 和 C ABI。
- 在 C++ wrapper、Python ctypes 和 CLI 中追加 Solid 0.5.1 诊断字段。
- 新增 0.5.1 Solid 专项 CTest gate,并保持 source size 受控。
- 更新 README、06、09 和 11 号文档中的 0.5.1 测试、验收和不交付范围。
- 不新增 FEMLite 直接依赖,不修改 SPHLite 文件夹之外的内容。
6. 非交付范围
0.5.1 不交付以下内容:
- 不实现
ShellMindlin-Reissner 生产求解路径。 - 不实现板壳厚度积分、director 更新、板壳撕裂或穿孔。
- 不实现真实水-气-结构工程爆炸响应。
- 不实现爆炸载荷作用下的船体破坏工程 benchmark。
- 不实现真实 FEM-SPH 接触耦合或连续体耦合。
- 不实现生产级断裂面追踪、裂纹扩展、碎片云或焊缝失效库。
- 不实现复杂接触、碰撞、摩擦或碎片-流体相互作用。
- 不实现热传导、熔化、相变或完整热-力耦合。
- 不实现大规模并行、GPU 后端或性能优化版本。
- 不新增几何、网格或粒子生成能力。
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 显式步提供的应变增量进入:
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 约束建议包括:
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_ratesolid_max_accelerationsolid_internal_force_residualsolid_reference_neighbor_minsolid_correction_det_minsolid_correction_status
粒子 CSV 可追加:
solid_strain_rate_eqsolid_acceleration_normsolid_reference_neighbor_countsolid_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_statesph_get_solid_diagnosticssph_get_solid_reference_quality
若粒子级 state 查询过大,Fortran API 可拆分为计数查询、summary 查询和 caller-allocated buffer 查询。
13.2 C ABI
C ABI 应保持追加式扩展。建议新增:
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_ratesolid_max_accelerationsolid_internal_force_residualsolid_correction_statussolid_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 为:
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,建议按以下阶段拆分:
- 0.5.1 版本号、0.5.0 发布基线和文档范围确认。
- Solid 0.5.1 输入样例、错误输入样例和小型结构 smoke 样例准备。
- Solid material/section 校验加固。
- 参考邻域计数、过滤和退化诊断。
- 修正矩阵构建、有限性检查和 fallback。
- 变形梯度初始化、更新和 restart 默认值。
- 速度梯度和应变率计算。
- 应变增量驱动的弹性材料点更新。
- 应变增量驱动的 Johnson-Cook flow/failure 更新。
- softening 对应力或内力贡献的作用路径。
- 最小 Solid 内力贡献和成对平衡测试。
- Solid 能量、动量、应变率、加速度和内力残差诊断。
- Solid dt 加速度约束或新增 dt 诊断。
- summary CSV 和粒子 CSV 字段扩展。
STATE_0_5_1restart 写入。STATE_0_5_1restart 读回。STATE_0_5和更早 restart 兼容读入。- Fortran API 和 C ABI 的 Solid 粒子级状态查询。
- C++ wrapper、Python ctypes 和 CLI 扩展。
- source size 复核和必要拆分。
- 0.5.0 全量回归和 0.5.1 新增 gate。
- README、06、09 和 11 号文档同步。
16. 验收标准
0.5.1 应满足以下验收标准:
- 软件版本为
0.5.1。 - 0.5.0 release gate 继续通过。
- Solid material 和 Solid section 校验路径清晰。
- 参考邻域和修正矩阵诊断可用。
- 速度梯度和应变率在受控小算例中与预期一致。
- Solid 应力更新可由显式步运动学增量驱动。
- 最小 Solid 内力路径可运行,并通过零应力、均匀平动和成对平衡测试。
- softening 可影响应力或内力贡献,失效仍不可逆且不删除粒子。
- Solid 能量、动量、最大应变率、最大加速度和 damage/softening 诊断可用。
- Solid dt 约束有限为正,并可进入全局 dt 估计。
STATE_0_5_1restart 可恢复 Solid 0.5.1 状态并继续显式步。STATE_0_5restart 可兼容读入,并初始化新增状态。- Solid 粒子级状态 Fortran API、C ABI、C++ wrapper、Python ctypes 和 CLI 字段可用。
- 默认 gate、0.5.0 Solid gate、0.5.1 Solid gate、source size 和
git diff --check通过。 - 文档不宣称 0.5.1 已实现 Shell、真实水-气-结构爆炸响应、真实 FEM-SPH 耦合或工程级结构破坏 benchmark。
- 不新增 FEMLite 直接依赖。
- 不修改 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:
- 0.5.1 Solid 参考构型、速度梯度、应变率和最小内力 gate 稳定。
- Solid failure/softening 对动力学贡献路径可重复通过。
- Solid output、restart、API、CLI 和 Python 诊断稳定。
- 0.5.0 Water/Gas/Explosive/Solid gate 仍可重复通过。
- 0.5.1 文档明确尚未实现 Shell、真实 FEM-SPH 耦合和工程级水下爆炸结构破坏 benchmark。