399 lines
11 KiB
Markdown
399 lines
11 KiB
Markdown
|
|
# 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 输出字段格式。
|