Files
SPHLite/docs/v1.0_development_plan.md
T

399 lines
11 KiB
Markdown
Raw Normal View History

2026-07-02 18:47:38 +08:00
# 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 建议建立以下目录:
```text
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 数据库至少支持:
```fortran
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 至少包括:
```fortran
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 至少包括:
```c
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 常量:
```c
#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` 应支持最小用法:
```powershell
sphlite model.inp --run
```
建议同时支持 inspect 模式:
```powershell
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:
```powershell
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 输出字段格式。