Files
CCLite/SPHLite/docs/v1.0_development_plan.md
2026-07-05 22:48:27 +08:00

399 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 输出字段格式。