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

19 KiB
Raw Blame History

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 计算链路打通:

输入粒子状态 -> 构建邻域 -> 核函数 -> 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/ 目录。

建议重点完善:

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 作为唯一主时间推进格式。

建议单步流程:

校验模型和时间步
必要时重建邻域
根据 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 基础上增加或完善:

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 建议增加水相诊断查询:

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 用法:

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:

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 输出。