11 KiB
SPHLite v1.0 开发计划
文档状态:0.1.0 开发计划稿
目标软件版本:SPHLite 0.1.0
依据文档:
01_requirements_specification.md02_software_architecture_design.md03_detailed_design.md04_mathematical_model_and_algorithms.md05_interface_control_document.md06_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 测试优先级:
- Fortran 生命周期 smoke。
- 数据库分配、释放和粒子数量查询。
.inp最小输入解析。- unsupported keyword warning。
- 缺失关键数据 error。
- C ABI 生命周期和空指针错误。
- CLI inspect/run smoke。
- Python
ctypessmoke。 - 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。
- 实现
sphliteCLI 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 第一批
.inpsection 关键词名称。 - CTest 具体测试名和 label。
- source size 门禁阈值是否完全沿用 FEMLite。
- restart 占位文件格式是否从 0.1.0 开始版本化。
sphliteCLI inspect 输出字段格式。