Files
SPHLite/docs/v1.0_development_plan.md
T
2026-07-02 18:47:38 +08:00

11 KiB
Raw Blame History

SPHLite v1.0 开发计划

文档状态:0.1.0 开发计划稿

目标软件版本:SPHLite 0.1.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

1. 版本定位

SPHLite 0.1.0 是工程骨架版本,目标是先把软件框架搭起来,为后续 Water、Gas、Explosive、Solid、Shell 和 CouplingInterface 的物理实现提供稳定基础。

0.1.0 不追求完整 SPH 物理能力,不交付水下爆炸、气泡脉动、结构断裂或外部 FEM-SPH 联合计算。该版本的核心价值是建立可编译、可测试、可扩展、接口边界清晰的 Fortran 95 求解器框架。

2. 版本目标

0.1.0 应完成:

  • 与 FEMLite 一致风格的 CMake/CTest 工程骨架。
  • Fortran 95 核心库 sphlite_core。
  • C ABI 薄包装库 sphlite_c。
  • 命令行程序 sphlite。
  • 最小 Python ctypes 调试入口。
  • Fortran API 生命周期、错误码、日志和版本接口。
  • 集中型数据库的最小粒子状态。
  • Abaqus .inp 子集解析框架。
  • *SPHLITE ... 扩展关键词解析框架。
  • Velocity-Verlet 显式推进的最小骨架。
  • 输出、restart、CouplingInterface 的占位接口。
  • 0.1 release gate 和 source size 门禁。

3. 明确不交付范围

0.1.0 不交付:

  • 完整 Water 弱可压 SPH。
  • Gas EOS 的生产计算路径。
  • Explosive programmed burn 真实能量释放。
  • Solid Johnson-Cook 应力更新和失效。
  • Shell Mindlin-Reissner 板壳计算。
  • 真实水-气-结构相互作用。
  • 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
  • 与 FEMLite 的联合运行。
  • 几何、网格或粒子生成能力。
  • 工程 benchmark 和长跑算例。

0.1.0 可保留模块占位、接口占位和小型 smoke,但不得将占位写成已实现物理能力。

4. 目录结构

0.1.0 建议建立以下目录:

include/
  sphlite_c_api.h
src/
  core/
  input/
  database/
  particle/
  material/
  water/
  gas/
  explosive/
  solid/
  shell/
  coupling_interface/
  solver/
  output/
  interface/
  app/
Python/
tests/
  unit/
  module/
  interface/
  data/
tools/
  testing/
examples/
docs/

不设置 geometry/ 或 mesh/ 目录。Python 输入生成脚本只允许作为 tools/ 或 examples/ 的辅助工具存在,不作为求解器功能。

5. 构建目标

0.1.0 建议 CMake 目标:

目标 类型 内容
sphlite_core static library Fortran 95 核心模块
sphlite_c static library C ABI wrapper
sphlite executable 命令行程序
test_smoke executable Fortran 生命周期和数据库 smoke
test_input executable .inp 解析 smoke
test_c_api executable C ABI smoke

构建要求:

  • 使用 CMake。
  • 使用 CTest。
  • Fortran 标准遵守 Fortran 95。
  • 支持环境和 FEMLite 保持一致。
  • C ABI wrapper 使用 C。
  • Python 测试使用系统 Python3。

6. Fortran 核心模块

0.1.0 最小 Fortran 模块:

模块 初始职责
sph_precision 精度、版本号和基础常量
sph_error 错误码、最近错误消息、错误清理
sph_log 日志打开、关闭和基础消息
sph_control 时间控制、输出控制和默认参数
sph_database 集中粒子数据库和生命周期
sph_input_reader .inp 文件读取框架
sph_api_state 初始化状态
sph_api Fortran 公共 API
sph_solver_explicit Velocity-Verlet 最小步进框架
sph_output_csv 最小 CSV 输出占位
sph_restart restart 读写占位
sph_coupling_interface 中立耦合接口占位

物理模块 Water、Gas、Explosive、Solid、Shell 在 0.1.0 中可建立模块文件和空生命周期/诊断占位,但不实现生产物理算法。

7. 数据库最小状态

0.1.0 数据库至少支持:

integer :: npart
integer, allocatable :: particle_id_ext(:)
integer, allocatable :: particle_phase(:)
integer, allocatable :: particle_status(:)
integer, allocatable :: material_id(:)
integer, allocatable :: section_id(:)
real(rk), allocatable :: x0(:,:)
real(rk), allocatable :: x(:,:)
real(rk), allocatable :: v(:,:)
real(rk), allocatable :: a(:,:)
real(rk), allocatable :: vhalf(:,:)
real(rk), allocatable :: mass(:)
real(rk), allocatable :: rho(:)
real(rk), allocatable :: volume(:)
real(rk), allocatable :: pressure(:)
real(rk), allocatable :: internal_energy(:)
real(rk), allocatable :: temperature(:)
real(rk), allocatable :: h(:)

0.1.0 可先实现:

  • 分配和释放。
  • 默认初始化。
  • 粒子数量查询。
  • external id 保存。
  • phase/status/material/section 默认值。
  • x0(3,npart) 和 x(3,npart) 保存。

复杂物理状态可先预留字段,不要求完整填充。

8. 输入解析范围

0.1.0 支持 Abaqus .inp 子集解析框架。第一批建议解析:

  • *NODE
  • *ELEMENT
  • *NSET
  • *ELSET
  • *MATERIAL
  • *SECTION 或当前约定的 section 关键词
  • *SPHLITE ... 扩展关键词框架

0.1.0 不要求完整 Abaqus 兼容。未支持但不影响运行的关键词 warning 后跳过;缺失关键数据或导致无法运行的输入 error。

最小可运行 .inp 应能定义一组 3D 粒子节点、基本材料、section 和显式时间控制。

9. Fortran API 范围

0.1.0 Fortran API 至少包括:

subroutine sph_initialize(ierr)
subroutine sph_finalize(ierr)
subroutine sph_get_version(major, minor, patch, ierr)
subroutine sph_get_last_error(code, message, ierr)
subroutine sph_read_inp(filename, ierr)
subroutine sph_build_model(ierr)
subroutine sph_estimate_stable_dt(dtcrit, ierr)
subroutine sph_advance_explicit(dt, ierr)
subroutine sph_run_explicit(ierr)
subroutine sph_get_current_time(time, step, ierr)
subroutine sph_get_particle_count(count, ierr)

0.1.0 可以让 sph_advance_explicit 执行最小 Velocity-Verlet 骨架:更新时间、步数和基础运动状态,但不要求完整 Water/Gas/Solid/Shell 力学。

10. C ABI 范围

0.1.0 C ABI 至少包括:

int sphlite_initialize(void);
int sphlite_finalize(void);
int sphlite_get_version(int *major, int *minor, int *patch);
int sphlite_get_last_error(int *code, char *message, int message_capacity);
int sphlite_read_inp(const char *filename);
int sphlite_build_model(void);
int sphlite_estimate_stable_dt(double *dtcrit);
int sphlite_advance_explicit(double dt);
int sphlite_run_explicit(void);
int sphlite_get_current_time(double *time, int *step);
int sphlite_get_particle_count(int *count);

C 头文件应定义 phase 常量:

#define SPHLITE_PHASE_WATER 1
#define SPHLITE_PHASE_GAS 2
#define SPHLITE_PHASE_EXPLOSIVE 3
#define SPHLITE_PHASE_SOLID 4
#define SPHLITE_PHASE_SHELL 5
#define SPHLITE_PHASE_BOUNDARY 6
#define SPHLITE_PHASE_COUPLING 7
#define SPHLITE_PHASE_SOLID_FAILED 8
#define SPHLITE_PHASE_SHELL_FAILED 9

C 参数错误返回 -1。Fortran 物理、输入或数据库错误返回 SPHLite 错误码。

11. CLI 范围

0.1.0 命令行程序 sphlite 应支持最小用法:

sphlite model.inp --run

建议同时支持 inspect 模式:

sphlite model.inp

inspect 模式输出:

  • 版本号。
  • 粒子数量。
  • 当前时间和步数。
  • 输入是否成功。
  • 基础 warning/error 摘要。

CLI 语法风格应与 FEMLite 保持一致。

12. Python 范围

0.1.0 Python 只提供最小调试入口:

  • 使用 ctypes 加载 C ABI。
  • 调用生命周期接口。
  • 读取 .inp。
  • 查询粒子数量。
  • 运行一个最小 smoke。

Python 生成器可放在 tools/ 或 examples/,用于生成测试 .inp,但不作为求解器几何或粒子生成功能宣传。

13. 测试计划

0.1.0 测试优先级:

  1. Fortran 生命周期 smoke。
  2. 数据库分配、释放和粒子数量查询。
  3. .inp 最小输入解析。
  4. unsupported keyword warning。
  5. 缺失关键数据 error。
  6. C ABI 生命周期和空指针错误。
  7. CLI inspect/run smoke。
  8. Python ctypes smoke。
  9. source size 门禁。

暂不进入 0.1.0 默认 gate:

  • Water 真实压力波 benchmark。
  • Gas EOS 生产路径。
  • Explosive 真实能量释放。
  • Solid/Shell 材料点。
  • CouplingInterface 联合外部模块测试。

14. 0.1.0 Release Gate

建议 release gate:

cmake --build build-codex-gcc --parallel
ctest --test-dir build-codex-gcc -R "^(smoke|input|c_api|python_debug)$" --output-on-failure
ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure
git diff --check

验收标准:

  • 完整编译通过。
  • smoke 通过。
  • input 通过。
  • c_api 通过。
  • python_debug 通过。
  • source_size 通过。
  • git diff --check 通过。
  • 文档状态与实际能力一致。

15. 开发阶段拆分

阶段 A:工程骨架

  • 建立目录结构。
  • 建立 CMakeLists。
  • 建立 Fortran 核心库。
  • 建立空 CLI。
  • 建立最小 CTest。

阶段 B:Core 和 Database

  • 实现 sph_precision。
  • 实现 sph_error。
  • 实现 sph_log。
  • 实现 sph_control。
  • 实现 sph_database 分配、释放和最小查询。

阶段 C:Input 和 API

  • 实现 .inp 读取框架。
  • 支持 *NODE 最小解析。
  • 支持基础 material/section 占位。
  • 实现 Fortran API 生命周期和输入接口。

阶段 D:C ABI 和 CLI

  • 生成 Fortran-C 名字修饰头。
  • 实现 include/sphlite_c_api.h。
  • 实现 C wrapper。
  • 实现 sphlite CLI inspect/run。

阶段 E:Solver、Output、Restart 占位

  • 实现 Velocity-Verlet 最小步进。
  • 实现稳定时间步占位。
  • 实现输出目录和输出间隔接口。
  • 实现 restart 占位接口。

阶段 F:测试和 Gate

  • 建立 Fortran smoke。
  • 建立 input smoke。
  • 建立 C ABI smoke。
  • 建立 Python debug smoke。
  • 建立 source size 检查。
  • 跑通 0.1.0 release gate。

16. 风险和控制

风险 控制
0.1.0 范围膨胀到物理算法 只实现框架和占位,物理能力推迟到后续版本
INP 解析目标过大 只支持明确子集,不追求完整 Abaqus 兼容
C ABI 与 Fortran API 分叉 C ABI 只做薄包装,Fortran API 是语义来源
CouplingInterface 过早绑定 FEMLite 接口命名保持中立,不出现 fem 依赖
restart 设计不足 0.1.0 先建立版本化占位和模块级状态清单
文件过大 从第一版启用 source size 门禁

17. 后续版本衔接

0.1.0 完成后,后续版本按以下方向推进:

  • 0.2:Water 基础 SPH、核函数、邻域搜索、Tait EOS、连续性方程。
  • 0.3:Gas EOS、气体统计和气泡诊断。
  • 0.4:Explosive 解析点火、爆轰传播和产物气体注入。
  • 0.5:Solid Johnson-Cook 材料与失效。
  • 0.6:Shell Mindlin-Reissner 板壳和失效。
  • 0.7 以后:水-气-结构局部爆炸、外部耦合接口和综合 benchmark。

18. 待确认事项

  • 0.1.0 第一批 .inp section 关键词名称。
  • CTest 具体测试名和 label。
  • source size 门禁阈值是否完全沿用 FEMLite。
  • restart 占位文件格式是否从 0.1.0 开始版本化。
  • sphlite CLI inspect 输出字段格式。