# 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。