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

22 KiB
Raw Permalink Blame History

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 小型结构动力学闭环:

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 显式步提供的应变增量进入:

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_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 应保持追加式扩展。建议新增:

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 为:

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。