21 KiB
21 KiB
SPHLite TODO
当前目标版本:0.2.1
本文档依据 docs/v2.1_development_plan.md 拆分。0.2.1 是 Water 加固版本,目标是增强 0.2.0 已有水相弱可压 SPH 路径的可靠性、可验证性和接口一致性,不交付 Gas、Explosive、Solid、Shell 生产路径,不交付真实 FEM-SPH 联合运行,不新增几何、网格或粒子生成能力。
阶段 A:版本和基线检查
- 将
sph_precision中的软件版本更新为0.2.1。 - 将 CMake 项目版本更新为
0.2.1。 - 更新 CLI
--version的版本期望。 - 更新 Fortran smoke 测试中的版本期望。
- 更新 C API 测试中的版本期望。
- 更新 C++ API 测试中的版本期望。
- 更新 Python debug 测试中的版本期望。
- 确认
sphlite_core仍以 Fortran 95 核心源文件为主。 - 确认
sphlite_c仍为 C ABI 薄封装库。 - 确认
sphlite_c_shared仍可构建。 - 确认
sphliteCLI 仍通过公共接口调用求解器。 - 确认不新增
geometry/目录。 - 确认不新增
mesh/目录。 - 确认不新增粒子生成器作为求解器功能。
- 跑通 0.2.0 发布状态的默认 gate。
- 跑通
source_size门禁。 - 跑通
git diff --check。 - 记录 0.2.1 基线检查结果。
基线检查记录(2026-07-02):0.2.1 版本号迁移后,cmake --build build-codex-unix 通过;默认 ctest 18/18 通过;单独 source_size 通过;git diff --check 通过;未新增 geometry/、mesh/ 或粒子生成器目录。
阶段 B:0.2.1 输入测试数据
- 创建 0.2.1 Water 最小合法输入文件。
- 创建 Water material 大小写兼容测试输入文件。
- 创建 Water material 缺少
*DENSITY的错误输入文件。 - 创建
*SECTION指向不存在 material 的错误输入文件。 - 创建缺失
*SPHLITE EOS, TYPE的错误输入文件。 - 创建缺失
*SPHLITE EOS, MATERIAL的错误输入文件。 - 创建缺失
*SPHLITE EOS, RHO0的错误输入文件。 - 创建缺失
*SPHLITE EOS, C0的错误输入文件。 - 创建缺失
*SPHLITE EOS, GAMMA的错误输入文件。 - 创建非法
*SPHLITE EOS, B的错误输入文件。 - 创建非
TYPE=TAIT的 EOS 类型测试输入文件。 - 创建缺失
*SPHLITE VISCOSITY字段的错误输入文件。 - 创建非法
*SPHLITE VISCOSITY数值的错误输入文件。 - 创建非法
*SPHLITE PARTICLE CONTROL数值的错误输入文件。 - 创建非法
*SPHLITE BODY FORCE字段的错误输入文件。 - 创建非法
*SPHLITE TIME CONTROL数值的错误输入文件。 - 创建未知但不影响运行的
*SPHLITEwarning 输入文件。 - 创建重复坐标 Water 粒子输入文件。
- 创建稀疏 Water 粒子输入文件。
- 创建非共线 3D pressure wave 输入文件。
阶段 C:输入解析加固
- 加固
*MATERIAL, TYPE=WATER大小写解析。 - 加固 Water material 与
*DENSITY的绑定校验。 - 加固
*SECTIONmaterial 引用存在性校验。 - 加固 set 只作为集合、不作为类型判断的测试。
- 加固
*SPHLITE EOS的TYPE字段校验。 - 加固
*SPHLITE EOS的MATERIAL字段校验。 - 加固
*SPHLITE EOS的RHO0字段校验。 - 加固
*SPHLITE EOS的C0字段校验。 - 加固
*SPHLITE EOS的GAMMA字段校验。 - 加固
*SPHLITE EOS的可选P0字段解析。 - 加固
*SPHLITE EOS的可选B字段解析。 - 保持未给定
B时由rho0*c0*c0/gamma推导。 - 明确非
TYPE=TAIT的 EOS 处理策略。 - 加固
*SPHLITE VISCOSITY的TYPE字段校验。 - 加固
*SPHLITE VISCOSITY的MATERIAL字段校验。 - 加固
*SPHLITE VISCOSITY的ALPHA字段校验。 - 加固
*SPHLITE VISCOSITY的BETA字段校验。 - 加固
*SPHLITE VISCOSITY的ETA2字段校验。 - 加固
*SPHLITE PARTICLE CONTROL的H正值校验。 - 加固
*SPHLITE PARTICLE CONTROL的MASS正值校验。 - 加固
*SPHLITE PARTICLE CONTROL的VOLUME正值校验。 - 加固
*SPHLITE BODY FORCE三维分量解析。 - 加固
*SPHLITE TIME CONTROL的DT正值校验。 - 加固
*SPHLITE TIME CONTROL的TIME正值校验。 - 加固
*SPHLITE TIME CONTROL的STEPS正值校验。 - 加固
*SPHLITE TIME CONTROL的SAFETY正值校验。 - 确认 unsupported-but-safe 关键词报 warning。
- 确认无法运行的缺失关键词报 error。
- 确认输入错误消息包含文件名。
- 确认输入错误消息包含行号或定位上下文。
阶段 D:Database 状态一致性
- 确认
particle_id_ext在 build 后稳定。 - 确认
particle_id_ext在 restart 读回后稳定。 - 确认
particle_phase在 build 后一致。 - 确认
particle_status在 build 后一致。 - 确认
material_id在 build 后一致。 - 确认
section_id在 build 后一致。 - 确认
x0(3,npart)初始化路径一致。 - 确认
x(3,npart)初始化路径一致。 - 确认
v(3,npart)初始化路径一致。 - 确认
a(3,npart)初始化路径一致。 - 确认
vhalf(3,npart)初始化路径一致。 - 确认
mass(npart)初始化路径一致。 - 确认
rho(npart)初始化路径一致。 - 确认
volume(npart)初始化路径一致。 - 确认
pressure(npart)初始化路径一致。 - 确认
temperature(npart)初始化路径一致。 - 确认
h(npart)初始化路径一致。 - 确认
drho_dt每步计算前正确重置。 - 确认
acc_pressure每步计算前正确重置。 - 确认
acc_viscosity每步计算前正确重置。 - 确认
acc_body保留或重置策略明确。 - 确认 Water 诊断在 build 后可重复计算。
- 确认 Water 诊断在 advance 后可重复计算。
- 确认 Water 诊断在 restart read 后可重复计算。
- 确认非 Water 粒子仍可通过通用查询导出。
- 确认 inactive 粒子不参与 Water 相互作用。
- 确认重复
sph_initialize后状态干净。 - 确认重复读取模型前旧状态被释放。
阶段 E:Kernel 加固
- 加固 Wendland C2 的
h <= 0错误路径。 - 加固 Wendland C4 的
h <= 0错误路径。 - 加固 cubic spline 的
h <= 0错误路径。 - 加固未知 kernel type 错误路径。
- 加固
r = 0时核函数值有限。 - 加固
r = 0时核函数梯度为零向量。 - 加固接近支持半径时核函数值有限。
- 加固接近支持半径时核函数梯度有限。
- 加固超出支持半径时
W = 0。 - 加固超出支持半径时
grad W = 0。 - 加固对称粒子对梯度反对称。
- 加固不同
h(i)的核函数结果有限。 - 确认默认 kernel 仍为 Wendland C2。
- 确认 kernel 测试不变成长跑积分 benchmark。
阶段 F:Neighbor 加固
- 加固空模型邻域构建。
- 加固单粒子邻域构建。
- 加固双粒子支持半径内判定。
- 加固双粒子支持半径外判定。
- 加固支持半径边界附近判定。
- 加固重复坐标粒子的邻域构建。
- 加固极近坐标粒子的邻域构建。
- 加固负坐标粒子的邻域构建。
- 加固稀疏粒子的包围盒计算。
- 加固稀疏粒子的 cell 维度控制。
- 加固不同
h(i)对搜索半径的影响。 - 加固粒子移动后邻域重建。
- 加固邻域容量不足错误路径。
- 加固 naive
O(n^2)对比辅助检查。 - 加固 neighbor stats 最大邻居数。
- 加固 neighbor stats 平均邻居数。
- 确认 neighbor 测试保持小规模。
阶段 G:Water EOS 加固
- 加固
rho = rho0时压力接近p0。 - 加固
rho > rho0时压力单调增加。 - 明确
rho < rho0时负压策略。 - 为当前负压策略增加测试。
- 加固
rho <= 0错误路径。 - 加固
rho0 <= 0错误路径。 - 加固
c0 <= 0错误路径。 - 加固
gamma <= 0错误路径。 - 加固
B <= 0错误路径。 - 加固声速诊断保持正值。
- 加固压力计算结果有限。
- 加固
B自动推导结果。 - 加固显式给定
B的结果。 - 加固 Water summary 中最大压力诊断。
- 在文档中记录 0.2.1 Tait EOS 当前策略。
阶段 H:连续性方程加固
- 加固双粒子压缩时
drho_dt符号。 - 加固双粒子拉伸时
drho_dt符号。 - 加固静止均匀粒子组密度变化接近零。
- 加固非 Water 粒子跳过密度贡献。
- 加固 inactive 粒子跳过密度贡献。
- 加固 failed 粒子跳过密度贡献。
- 加固
drho_dt每步重置。 - 加固密度更新结果有限。
- 加固低密度输入的错误路径。
- 加固邻域为空时密度变化处理。
- 确认 summation density 不进入主流程。
- 保留 summation density 后续 checker 入口说明。
阶段 I:人工黏性加固
- 加固接近粒子产生人工黏性贡献。
- 加固远离粒子不产生压缩型人工黏性贡献。
- 加固零距离粒子人工黏性有限。
- 加固极小距离粒子人工黏性有限。
- 加固
alpha < 0错误路径。 - 加固
beta < 0错误路径。 - 加固
eta2 <= 0错误路径。 - 加固人工黏性加速度方向。
- 加固人工黏性加速度有限性。
- 加固人工黏性动量趋势。
- 加固非 Water 粒子跳过黏性贡献。
- 加固 inactive 粒子跳过黏性贡献。
- 加固 viscosity 参数读入后与计算一致。
- 确认人工黏性测试保持小规模。
阶段 J:压力力和外载加固
- 加固双粒子压力力方向。
- 加固零压力时压力力接近零。
- 加固均匀压力组净力趋势。
- 加固压力力结果有限。
- 加固
acc_pressure合成前重置。 - 加固
acc_viscosity合成前重置。 - 加固
acc_body合成策略。 - 加固 body force 对速度方向的影响。
- 加固 body force 对加速度缓存的影响。
- 加固外部粒子力进入显式步外载占位。
- 加固非 Water 粒子跳过压力力。
- 加固 inactive 粒子跳过压力力。
- 加固 failed 粒子跳过压力力。
- 确认总加速度合成顺序清晰。
阶段 K:Solver 和时间步加固
- 加固未 initialize 时
sph_advance_explicit错误路径。 - 加固未 build model 时
sph_advance_explicit错误路径。 - 加固未 build model 时
sph_run_explicit错误路径。 - 加固负
dt错误路径。 - 加固零
dt错误路径。 - 加固非法 Water 状态下 stable dt 错误路径。
- 加固 CFL 时间步约束诊断。
- 加固加速度时间步约束诊断。
- 加固黏性时间步约束诊断。
- 加固 safety factor 正值生效路径。
- 加固非法 safety factor 处理。
- 加固
TIME与STEPS双约束运行。 - 加固最后小步不超过
end_time。 - 加固单步 Water 推进。
- 加固多步 Water 推进。
- 加固
sph_run_explicitWater 闭环。 - 加固自动输出间隔触发。
- 加固未启用输出时不自动写文件。
- 加固 restart 后继续显式步。
- 加固当前时间和步号查询。
阶段 L:Output 加固
- 确认粒子 CSV 包含 id 字段。
- 确认粒子 CSV 包含 phase 字段。
- 确认粒子 CSV 包含 status 字段。
- 确认粒子 CSV 包含 material 字段。
- 确认粒子 CSV 包含 section 字段。
- 确认粒子 CSV 包含坐标字段。
- 确认粒子 CSV 包含速度字段。
- 确认粒子 CSV 包含 rho 字段。
- 确认粒子 CSV 包含 pressure 字段。
- 确认粒子 CSV 包含 temperature 字段。
- 确认粒子 CSV 包含 h 字段。
- 确认 summary CSV 包含 step 字段。
- 确认 summary CSV 包含 time 字段。
- 确认 summary CSV 包含 water mass 字段。
- 确认 summary CSV 包含 water momentum 字段。
- 确认 summary CSV 包含 max pressure 字段。
- 确认 summary CSV 包含 min/max density 字段。
- 确认 summary CSV 包含 dtcrit 字段。
- 加固输出目录不存在时的处理。
- 加固非法输出目录错误路径。
- 确认手动
sph_write_output不改变物理状态。 - 确认 CLI
--run --output使用实际 step/time。
阶段 M:Restart 加固
- 确认 restart header 可识别。
- 确认 restart state version 记录 0.2.1 策略。
- 确认 restart 写入 current time。
- 确认 restart 写入 current step。
- 确认 restart 写入 output control。
- 确认 restart 写入 safety factor。
- 确认 restart 写入 Water EOS 参数。
- 确认 restart 写入 viscosity 参数。
- 确认 restart 写入 body force 参数。
- 确认 restart 写入粒子通用状态。
- 确认 restart 写入 rho。
- 确认 restart 写入 pressure。
- 确认 restart 写入 h。
- 确认 restart 写入 v、a、vhalf。
- 确认 restart 写入 Water 诊断状态。
- 确认 restart 读回 current time。
- 确认 restart 读回 current step。
- 确认 restart 读回 Water 参数。
- 确认 restart 读回粒子状态。
- 确认 restart 读回后重建邻域。
- 确认 restart 读回后继续 Water 显式步。
- 加固非法 restart 文件错误路径。
阶段 N:Fortran API 加固
- 确认生命周期 API 兼容 0.2.0。
- 确认
.inp读取 API 兼容 0.2.0。 - 确认 build model API 兼容 0.2.0。
- 确认 stable dt API 兼容 0.2.0。
- 确认 advance/run explicit API 兼容 0.2.0。
- 确认 current time API 兼容 0.2.0。
- 确认 particle count/state API 兼容 0.2.0。
- 确认 output/restart API 兼容 0.2.0。
- 确认 error query API 兼容 0.2.0。
- 确认 neighbor rebuild API 兼容 0.2.0。
- 确认 neighbor stats API 兼容 0.2.0。
- 确认 water summary API 兼容 0.2.0。
- 确认 water dt limits API 兼容 0.2.0。
- 加固新增 API 未初始化错误路径。
- 加固新增 API 未 build 错误路径。
- 确认错误返回前输出参数为安全默认值。
- 确认 API 不暴露内部 allocatable 指针。
阶段 O:C ABI、C++ 和 Python 加固
- 确认 C ABI 头文件保持 0.2.0 兼容。
- 加固
sphlite_get_water_summary空指针错误路径。 - 加固
sphlite_get_water_dt_limits空指针错误路径。 - 加固
sphlite_get_particle_state空指针错误路径。 - 加固
sphlite_get_particle_state小容量错误路径。 - 确认 C 参数错误返回
-1。 - 确认 Fortran 错误码原样返回 C 调用方。
- 确认 C wrapper 不重新定义物理语义。
- 确认 C++ wrapper 只做薄封装。
- 加固 C++ water summary 测试。
- 加固 C++ water dt limits 测试。
- 加固 C++ 生命周期 RAII 测试。
- 确认 Python 通过 C ABI 调用。
- 加固 Python water summary 包装。
- 加固 Python water dt limits 包装。
- 加固 Python inspect 辅助函数。
- 加固 Python run 辅助函数。
- 加固 Python 缺失输入错误路径。
- 加固 Python 缺失 Water 参数错误路径。
- 确认 Python 不直接访问 Fortran 内部符号。
阶段 P:CLI 加固
- 保持
sphlite --version可用。 - 保持
sphlite model.inpinspect 模式可用。 - 保持
sphlite model.inp --check模式可用。 - 保持
sphlite model.inp --run模式可用。 - 保持
sphlite model.inp --run --output output可用。 - 确认 CLI 输出
version字段。 - 确认 CLI 输出
input字段。 - 确认 CLI 输出
mode字段。 - 确认 CLI 输出
particles字段。 - 确认 CLI 输出
warnings字段。 - 确认 CLI 输出
time字段。 - 确认 CLI 输出
step字段。 - 确认 CLI 输出
water_particles字段。 - 确认 CLI 输出
water_mass字段。 - 确认 CLI 输出
max_pressure字段。 - 确认 CLI 输出
dtcrit字段。 - 确认 CLI 输出
status字段。 - 加固缺少输入文件的错误路径。
- 加固输入文件不存在的错误路径。
- 加固
--run与--check同时给出的错误路径。 - 加固
--output缺少路径的错误路径。 - 加固 Water 参数缺失的错误路径。
- 加固输出目录非法的错误路径。
- 确认 CLI 不绕过公共生命周期接口。
阶段 Q:CouplingInterface 加固
- 确认 Water 运行后 coupling particle count 可用。
- 确认 Water 运行后 coupling particle state 导出可用。
- 确认 coupling particle 导出包含 id。
- 确认 coupling particle 导出包含 position。
- 确认 coupling particle 导出包含 velocity。
- 确认 coupling particle 导出包含 phase。
- 确认 coupling particle 导出包含 material。
- 确认 coupling particle 导出包含 pressure。
- 确认外部粒子力导入接口可用。
- 确认外部粒子力影响显式步。
- 确认 coupling work 诊断继续记录。
- 确认 coupling momentum 诊断继续记录。
- 确认 coupling energy 诊断继续记录。
- 保持接触耦合类型字段。
- 保持连续体耦合类型字段。
- 确认接口命名不出现 FEMLite 内部结构。
- 确认默认 gate 不运行真实 FEM-SPH 联合测试。
- 评估 0.2.1 是否暴露 C ABI coupling 接口。
- 若不暴露 C ABI coupling 接口,在文档中记录原因。
阶段 R:Pressure Wave Smoke 加固
- 保持已有 5 粒子 pressure wave smoke 可用。
- 评估是否增加非共线 3D 粒子布置。
- 若增加非共线布置,创建对应输入文件。
- 加固初始压力扰动设置。
- 加固运行步数检查。
- 加固 checker 阈值说明。
- 检查压力扰动传播方向。
- 检查输出有限性。
- 检查质量趋势。
- 检查动量趋势。
- 检查粒子 CSV 输出字段。
- 检查 summary CSV 输出字段。
- 确认 pressure wave smoke 不作为工程精度 benchmark。
- 确认 pressure wave smoke 保持小规模。
- 确认 pressure wave smoke 进入默认 gate。
阶段 S:Source Size 和默认 Gate
- 确认 source size 覆盖 Fortran 文件。
- 确认 source size 覆盖 C 文件。
- 确认 source size 覆盖 C++ 头文件。
- 确认 source size 覆盖 Python 文件。
- 为新增大文件登记必要例外。
- 确认 stale exception 检查有效。
- 运行
smoke测试。 - 运行
input测试。 - 运行
kernel测试。 - 运行
neighbor测试。 - 运行
water_eos测试。 - 运行
water_density测试。 - 运行
water_viscosity测试。 - 运行
water_force测试。 - 运行
solver_water测试。 - 运行
output测试。 - 运行
restart测试。 - 运行
coupling_interface测试。 - 运行
c_api测试。 - 运行
cpp_api测试。 - 运行
python_debug测试。 - 运行
cli测试。 - 运行
pressure_wave_smoke测试。 - 运行
source_size测试。 - 运行
git diff --check。
阶段 T:文档同步
- 更新 README 当前版本为 0.2.1。
- 更新 README 的 0.2.1 实际能力说明。
- 记录 0.2.1 交付 Water 加固能力。
- 记录 0.2.1 不交付 Gas 生产路径。
- 记录 0.2.1 不交付 Explosive 生产路径。
- 记录 0.2.1 不交付 Solid 生产路径。
- 记录 0.2.1 不交付 Shell 生产路径。
- 记录 0.2.1 不交付真实 FEM-SPH 联合运行。
- 更新
docs/09_release_history.md的 0.2.1 条目。 - 更新
docs/11_benchmark_matrix.md的 0.2.1 gate。 - 确认 01-06 文档与 0.2.1 实际能力不冲突。
- 确认文档使用 UTF-8 without BOM。
- 确认文档不宣称已实现完整水下爆炸。
- 确认文档不宣称已实现生产级多物理耦合。
- 记录 restart 格式版本策略。
- 记录非
TYPE=TAITEOS 的 0.2.1 处理策略。 - 记录 Water 拉伸压力策略。
- 记录 CouplingInterface C ABI 是否进入 0.2.1。
- 记录 VTK 是否进入 0.2.1。
阶段 U:0.2.1 验收
- 完整配置 CMake。
- 完整编译
sphlite_core。 - 完整编译
sphlite_c。 - 完整编译
sphlite_c_shared。 - 完整编译
sphlite。 - 完整编译新增 Fortran 测试目标。
- 完整编译新增 C/C++ 测试目标。
- 运行
ctest -R "^(smoke|input|kernel|neighbor|water_eos|water_density|water_viscosity|water_force|solver_water|output|restart|coupling_interface|c_api|cpp_api|python_debug|cli|pressure_wave_smoke)$"。 - 运行
ctest -R "^source_size$"。 - 运行
git diff --check。 - 确认没有提交 build 目录。
- 确认没有提交 Python 缓存。
- 确认没有提交 CSV 临时结果。
- 确认没有提交 VTK 临时结果。
- 确认没有提交 restart 临时结果。
- 确认没有残留旧模块命名。
- 确认没有新增 FEMLite 源码依赖。
- 确认没有新增几何生成能力。
- 确认没有新增网格生成能力。
- 确认没有新增粒子生成能力。
- 记录 0.2.1 release gate 结果。