Prepare SPHLite 0.2.0 development baseline

This commit is contained in:
Codex
2026-07-02 19:50:44 +08:00
parent ad31c2d5cc
commit ed1f5a5ab2
36 changed files with 3122 additions and 267 deletions
+27 -3
View File
@@ -1,16 +1,17 @@
# 09 版本历史与验收记录
文档状态:0.1.0 开发中
文档状态:0.1.1 本地验收通过
## 1. 当前状态
SPHLite 当前正在搭建 0.1.0 工程骨架版本。该版本只交付可编译、可测试、可扩展的求解器框架,不交付生产级物理算法。
SPHLite 当前完成 0.1.1 框架加固版本的本地验收。该版本只交付可编译、可测试、可扩展的求解器框架和接口闭合,不交付生产级物理算法。
## 2. 规划版本线
| 版本线 | 目标 |
|---|---|
| 0.1.0 | 工程骨架、生命周期、错误码、C ABI、CLI、Python 调试入口和测试框架 |
| 0.1.1 | 输入元数据、粒子状态查询、C++ wrapper、CLI/output/restart/CouplingInterface gate 加固 |
| 0.2 | 粒子状态、核函数、邻域搜索和基础 `Water` |
| 0.3 | `Gas`、基础 EOS、气体统计和气泡诊断 |
| 0.4 | `Explosive`、解析点火、爆轰传播和产物气体注入 |
@@ -47,7 +48,30 @@ cmake --build build-codex-unix --parallel
- 已通过 `.gitignore` 排除 build 目录、CSV/VTK/restart 临时结果和 Python 缓存。
- 文档已明确 0.1.0 不交付生产级 Water、Gas、Explosive、Solid、Shell 物理算法。
说明:当前目录已初始化本地 git 仓库,并设置远端 `origin` 为 `http://123.57.213.67:3062/shen/SPHLite.git`,尚未执行提交或推送。
说明:0.1.0 已提交并推送到远端,标签为 `v0.1.0`。
### 0.1.1 本地验收记录
记录日期:2026-07-02
本地构建目录:`build-codex-unix`
构建配置:
```powershell
cmake -S . -B build-codex-unix -G "Unix Makefiles" -DCMAKE_C_COMPILER=C:/gcc-16.1.0-64/bin/gcc.exe -DCMAKE_CXX_COMPILER=C:/gcc-16.1.0-64/bin/g++.exe -DCMAKE_Fortran_COMPILER=C:/gcc-16.1.0-64/bin/gfortran.exe -DCMAKE_MAKE_PROGRAM=C:/gcc-16.1.0-64/bin/make.exe
cmake --build build-codex-unix --parallel
```
验收结果:
- `sphlite_core`、`sphlite_c`、`sphlite` 和 `test_cpp_api` 完整编译通过。
- `ctest --test-dir build-codex-unix --output-on-failure` 通过,10/10。
- `source_size` 通过。
- `git diff --check` 通过。
- CLI `--version`、inspect、`--check`、`--run` 和错误输入路径通过。
- output、restart 和 CouplingInterface 占位测试通过。
- 文档已明确 0.1.1 不交付生产级 Water、Gas、Explosive、Solid、Shell 物理算法。
后续每个版本应记录:
+25 -2
View File
@@ -1,10 +1,10 @@
# 11 Benchmark 与验收矩阵
文档状态:0.1.0 gate 草案
文档状态:0.1.1 gate 记录
## 1. 当前状态
0.1.0 不交付工程 benchmark,只建立 release gate 和 source size 门禁。后续物理 benchmark 矩阵保留为长期规划。
0.1.1 不交付工程 benchmark,只建立并加固 release gate 和 source size 门禁。后续物理 benchmark 矩阵保留为长期规划。
## 2. 0.1.0 Release Gate
@@ -24,6 +24,29 @@
|---|---|---|
| 2026-07-02 | `build-codex-unix` | `smoke`、`input`、`c_api`、`python_debug`、`source_size` 和 `git diff --check` 均通过 |
## 2.1 0.1.1 Release Gate
| 测试名 | 类型 | 验收点 |
|---|---|---|
| `smoke` | Fortran smoke | 版本 0.1.1、生命周期、数据库、常量、显式步进错误路径 |
| `input` | Fortran input | 元数据占位、set 不作为类型判断、warning/error 路径 |
| `c_api` | C ABI | 空指针、非正容量、粒子状态、output、restart |
| `cpp_api` | C++ wrapper | RAII 生命周期、读入、构建、粒子状态 |
| `python_debug` | Python `ctypes` | 常量、粒子状态、output、restart、错误路径 |
| `cli` | CLI | `--version`、inspect、`--check`、`--run`、错误输入 |
| `restart` | Fortran restart | 写入、读回、继续最小显式步 |
| `output` | Fortran output | CSV 字段和输出路径控制 |
| `coupling_interface` | Fortran coupling | 中立导出/导入占位和诊断字段 |
| `source_size` | 工具门禁 | Fortran/C/C++/Python 文件大小和 stale exception |
0.1.1 不验收 Water、Gas、Explosive、Solid、Shell 的生产级物理结果,也不验收真实 FEM-SPH 联合运行。
本地验收记录:
| 日期 | 构建目录 | 结果 |
|---|---|---|
| 2026-07-02 | `build-codex-unix` | 0.1.1 gate 10/10 通过,`git diff --check` 通过 |
## 3. 基础数值矩阵
| 领域 | 测试或 benchmark | 验收点 |
+374
View File
@@ -0,0 +1,374 @@
# SPHLite v1.1 开发计划
文档状态:0.1.1 开发计划稿
目标软件版本:SPHLite 0.1.1
依据文档:
- `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`
- `v1.0_development_plan.md`
## 1. 版本定位
SPHLite 0.1.1 是 0.1 系列的框架加固版本。0.1.0 已完成工程骨架、最小数据库、最小 `.inp` 解析、显式步进骨架、C ABI、CLI、Python 调试入口和 release gate。0.1.1 的目标是在不进入生产级物理算法的前提下,把输入、数据库、接口、restart、输出和测试闭环进一步整理到可支撑 0.2 `Water` 开发的状态。
0.1.1 不定位为 `Water` 物理版本,也不交付气泡、爆炸、结构断裂或外部 FEM-SPH 联合计算。该版本应减少后续物理模块开发时需要反复修改的基础接口和数据契约。
## 2. 版本目标
0.1.1 应完成:
- 锁定 0.1 系列 phase/status 常量,并确保 Fortran、C、C++ 和 Python 一致。
- 完善 `.inp` 子集解析的模型元数据保存,包括 material、section、set 和基础 `*SPHLITE ...` 控制项。
- 增加粒子状态查询 API,采用 dimension query + caller-allocated buffer 风格。
- 完善 C ABI,使 05 号文档中 0.1 阶段需要的输出、restart、粒子查询和基础错误路径具备占位实现。
- 完善 Python 调试入口,使其能读取粒子状态、执行 inspect/run smoke,并覆盖错误路径。
- 完善 CLI 的 inspect/check/run 行为,输出字段稳定、错误消息明确。
- 使 restart 占位格式更接近模块级状态清单,至少覆盖 0.1 已有全部通用状态。
- 使 CSV 输出占位可由 API/CLI 驱动,并避免输出产物进入仓库。
- 增加 C++ wrapper smoke 测试,但不把 C++ 作为核心实现语言。
- 增加 CouplingInterface 的中立接口测试占位,确认命名中不出现 FEMLite 内部依赖。
- 保持 0.1 release gate 快速、稳定,并扩展到 0.1.1 新增接口。
## 3. 明确不交付范围
0.1.1 不交付:
- 完整 Water 弱可压 SPH。
- 核函数、邻域搜索和 Tait EOS 的生产计算路径。
- Gas EOS 生产计算。
- Explosive programmed burn 真实质量/动量/能量注入。
- Solid Johnson-Cook 应力更新、损伤和失效。
- Shell Mindlin-Reissner 板壳计算。
- 水-气-结构真实相互作用。
- 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
- 与 FEMLite 的联合运行。
- 几何、网格或粒子生成能力。
- 工程 benchmark 和长跑算例。
0.1.1 可以新增数据字段、接口占位、解析占位和测试占位,但不得将这些占位描述为已实现生产级物理能力。
## 4. 目录结构调整
0.1.1 沿用 0.1.0 目录结构,不新增 `geometry/` 或 `mesh/` 目录。
建议保留并完善:
```text
include/
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/
```
测试或示例所需的 `.inp` 生成脚本只允许放入 `tools/` 或 `examples/`,并明确标注为辅助工具,不作为求解器几何或粒子生成能力。
## 5. 数据库加固范围
0.1.1 数据库应继续采用集中型数据管理模式。建议新增或完善以下能力:
- 明确 phase/status 常量整数值,并在 Fortran/C/Python 中保持一致。
- 保存输入 material 的名称、类型、内部 id 和外部名称映射占位。
- 保存 section 的名称、类型、材料引用、厚度/积分点占位和内部 id。
- 保存 set 名称、成员 id 和 set 类型占位,明确 set 不参与物理类型判断。
- 保存 region/coupling region 占位数据,用于后续输出和耦合。
- 提供粒子状态查询例程,输出 id、phase、status、material、section、位置、速度、加速度、密度、压力、内能、温度和 `h`。
- 保证 `sph_finalize`、重复 `sph_initialize` 和重复读入模型时数据库状态一致释放。
0.1.1 不要求完整材料参数库,也不要求 material/section 驱动真实物理计算。
## 6. 输入解析范围
0.1.1 在 0.1.0 的基础上加固 Abaqus `.inp` 明确子集:
- `*NODE`:继续支持 3D 坐标解析,增加错误行号或上下文消息。
- `*ELEMENT`:保存 element id、element type 和节点连接占位。
- `*NSET`:保存 set 名称和节点集合占位。
- `*ELSET`:保存 set 名称和 element 集合占位。
- `*MATERIAL`:保存 material 名称和后续材料卡片入口占位。
- `*SECTION` 或 Abaqus 等价 section 关键词:保存 section 和 material 引用占位。
- `*SPHLITE TIME CONTROL`:解析 `DT`、`TIME`、`STEPS` 和安全系数占位。
- `*SPHLITE OUTPUT`:解析输出目录和输出间隔占位。
- `*SPHLITE COUPLING REGION`:解析 SPHLite 侧 coupling region 名称和集合引用占位。
未知关键词处理原则保持不变:不影响程序运行的未支持关键词 warning 后跳过;缺失关键数据或导致无法运行的输入 error。
0.1.1 应新增输入测试,覆盖大小写混合、空行、注释、逗号字段空白、未知关键词 warning、缺失 material/section/time control error 和 set 不作为类型判断依据。
## 7. Fortran API 范围
0.1.1 Fortran API 在 0.1.0 基础上建议扩展:
```fortran
subroutine sph_get_particle_state_capacity(count, ndim, ierr)
subroutine sph_get_particle_state(max_particles, particle_id_ext, phase, status, &
material_id, section_id, x, v, a, rho, pressure, &
internal_energy, temperature, h, count, ierr)
subroutine sph_set_output_directory(directory, ierr)
subroutine sph_set_output_interval(interval, ierr)
subroutine sph_write_output(step, time, ierr)
subroutine sph_write_restart(filename, ierr)
subroutine sph_read_restart(filename, ierr)
subroutine sph_get_input_warning_count(count, ierr)
```
Fortran API 仍是语义来源。所有可失败接口必须返回错误码,并通过最近错误消息说明原因。
## 8. C ABI 范围
0.1.1 C ABI 应覆盖 05 号接口文档中 0.1 阶段需要闭合的接口:
```c
int sphlite_set_output_directory(const char *path);
int sphlite_set_output_interval(int interval);
int sphlite_write_output(int step, double time);
int sphlite_write_restart(const char *filename);
int sphlite_read_restart(const char *filename);
int sphlite_get_particle_state(int max_particles,
int *particle_id_ext,
int *phase,
int *status,
int *material_id,
int *section_id,
double *x,
double *v,
double *a,
double *rho,
double *pressure,
double *internal_energy,
double *temperature,
double *h,
int *count);
```
C ABI 参数错误仍返回 `-1`。Fortran 物理、输入或数据库错误仍返回 SPHLite 错误码。多维数组按 Fortran 顺序展开到 C 缓冲区,即 `value[dim + 3 * particle]`。
0.1.1 可为 Gas、Explosive 和 CouplingInterface 诊断接口建立占位声明,但默认测试只验证占位接口的错误处理、容量检查和中立命名,不验证真实物理数值。
## 9. C++ 和 Python 范围
C++ wrapper 在 0.1.1 中保持薄包装定位:
- 不重新定义物理语义。
- 提供 RAII 生命周期辅助。
- 包装版本、读入、构建、运行、粒子数量和粒子状态查询。
- 增加一个最小 C++ smoke 测试。
Python `ctypes` 调试入口应扩展:
- 包装输出目录、输出间隔、restart 读写占位。
- 包装粒子状态查询。
- 提供 inspect/run 辅助函数。
- 增加错误路径测试,如空路径、缺失文件、缺失关键输入。
Python 仍不作为唯一入口,CLI 和 C ABI 必须完整可用。
## 10. CLI 范围
0.1.1 CLI 建议支持:
```powershell
sphlite model.inp
sphlite model.inp --check
sphlite model.inp --run
sphlite model.inp --run --output output
sphlite --version
```
CLI inspect/check 输出字段建议稳定为:
- `version`
- `input`
- `mode`
- `particles`
- `warnings`
- `time`
- `step`
- `status`
CLI 错误时应打印最近错误码和错误消息。CLI 内部必须走公共生命周期 API,不绕过 Fortran API 或 C ABI 的状态管理。
## 11. Solver、Output 和 Restart 范围
0.1.1 继续使用 Velocity-Verlet 作为唯一主时间推进格式。求解器仍不引入隐式、静力或非线性静力接口。
求解器加固内容:
- 稳定时间步估计保留占位,但应返回输入控制中的默认时间步。
- `sph_advance_explicit` 对负时间步、零时间步和未初始化状态给出明确错误。
- `sph_run_explicit` 对 `end_time`、`max_steps` 和浮点截断进行更稳定的边界处理。
输出加固内容:
- CSV 输出包含 id、phase、status、material、section、坐标、速度、密度、压力和温度。
- 输出目录和输出间隔可由 input/API/CLI 设置。
- 输出文件命名规则稳定,测试产物写入 build 或临时目录,不提交仓库。
restart 加固内容:
- restart 头部包含格式名、软件版本和状态版本。
- restart 保存当前 0.1 系列已有通用粒子状态、时间、步数和输出控制。
- restart read 后能够继续执行最小显式步。
- restart 格式仍为 0.1 占位格式,不承诺长期二进制兼容。
## 12. CouplingInterface 范围
0.1.1 不实现外部耦合模块,也不依赖 FEMLite。CouplingInterface 只做中立接口加固:
- coupling region 名称和内部 id 占位。
- coupling particle count 查询。
- coupling particle 状态导出占位。
- coupling facet count 和 facet 导出占位。
- 外部粒子力、面力或体力导入占位。
- 耦合功、动量交换、能量交换诊断占位。
- 接触耦合和连续体耦合类型字段占位。
接口、文件名和变量名中不得出现 FEMLite 内部数据结构依赖,也不得把连续体耦合简化成接触耦合。
## 13. 测试计划
0.1.1 默认 gate 建议包含:
- `smoke`:生命周期、数据库、显式步进。
- `input`:`.inp` 子集、warning/error、material/section/set 占位。
- `c_api`:生命周期、空指针、非正容量、小缓冲区、粒子状态查询。
- `cpp_api`:C++ wrapper 最小生命周期和粒子数量 smoke。
- `python_debug`:Python `ctypes` 读入、查询、run 和错误路径。
- `cli`:inspect、check、run、version 和错误输入。
- `restart`:写入、读回、继续最小显式步。
- `output`:CSV 输出字段和输出路径控制。
- `coupling_interface`:中立导出/导入占位和错误路径。
- `source_size`:Fortran/C/C++/Python 文件大小和 stale exception。
0.1.1 默认 gate 仍不包含 Water/Gas/Explosive/Solid/Shell 的真实物理 benchmark。
## 14. 0.1.1 Release Gate
建议 release gate:
```powershell
cmake --build build-codex-unix --parallel
ctest --test-dir build-codex-unix -R "^(smoke|input|c_api|cpp_api|python_debug|cli|restart|output|coupling_interface)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
```
验收标准:
- 完整配置 CMake。
- 完整编译 `sphlite_core`、`sphlite_c` 和 `sphlite`。
- 新增接口测试全部通过。
- source size 通过。
- `git diff --check` 通过。
- README、09 和 11 号文档记录 0.1.1 gate 结果。
- 文档状态与实际能力一致,不宣称已实现生产级物理算法。
## 15. 开发阶段拆分
### 阶段 A:版本和常量加固
- 将软件版本更新为 0.1.1。
- 锁定 phase/status 常量。
- 同步 Fortran、C、C++ 和 Python 常量。
- 增加常量一致性测试。
### 阶段 B:数据库和输入元数据
- 增加 material/section/set/region 占位数据结构。
- 增加 `.inp` 对 material、section、set 和 `*SPHLITE ...` 控制项的保存。
- 增加输入 warning/error 上下文。
- 增加输入解析测试数据。
### 阶段 C:粒子查询和接口闭合
- 实现 Fortran 粒子状态查询。
- 实现 C ABI 粒子状态查询。
- 扩展 C++ wrapper。
- 扩展 Python wrapper。
- 增加 C/C++/Python 查询测试。
### 阶段 D:CLI、Output 和 Restart
- 完善 CLI inspect/check/run/version。
- 完善 CSV 输出字段。
- 完善 output directory 和 interval 控制。
- 加固 restart 头、写入、读回和继续步进。
- 增加 CLI/output/restart 测试。
### 阶段 E:CouplingInterface 占位测试
- 完善 coupling region 占位状态。
- 增加 coupling particle/facet 导出和载荷导入错误路径测试。
- 增加耦合功、动量和能量诊断占位检查。
- 确认接口命名中立。
### 阶段 F:文档和 Gate
- 更新 README 当前版本。
- 更新 `docs/09_release_history.md`。
- 更新 `docs/11_benchmark_matrix.md`。
- 更新 `todo.md` 或新增 0.1.1 TODO。
- 跑通 0.1.1 release gate。
## 16. 风险和控制
| 风险 | 控制 |
|---|---|
| 0.1.1 膨胀到 0.2 Water 物理 | 只做接口、数据、输出和测试加固,不实现真实 SPH 相互作用 |
| `.inp` 解析过早追求完整 Abaqus 兼容 | 只支持明确子集,保存占位元数据,不做完整关键字覆盖 |
| C ABI 和 Fortran API 语义分叉 | Fortran API 仍是语义来源,C ABI 只做薄包装 |
| restart 格式过早固化 | 0.1.1 标注为 0.1 占位格式,只保证当前最小状态可恢复 |
| CouplingInterface 绑定外部模块 | 只使用中立命名和 SPHLite 侧 region,不出现 FEMLite 内部结构 |
| CLI 输出不稳定影响测试 | 固定 inspect/check 字段,测试按字段名检查 |
| source size 例外膨胀 | 必要例外登记,stale exception 必须失败 |
## 17. 后续版本衔接
0.1.1 完成后,0.2 可集中进入 `Water` 基础 SPH:
- 核函数模块。
- uniform cell/bin 邻域搜索。
- Tait EOS。
- 连续性方程。
- Monaghan 人工黏性。
- 小型压力传播 smoke。
0.1.1 不应把上述内容实现成生产路径,但应保证数据库、输入、查询、输出和测试基础足以承接这些工作。
## 18. 待确认事项
- 0.1.1 是否需要把 `cpp_api` 纳入默认 release gate。
- `*SPHLITE OUTPUT` 和 `*SPHLITE COUPLING REGION` 的第一版字段名。
- restart 0.1 占位格式是否继续使用文本格式。
- CLI `--check` 与 inspect 模式的输出差异。
- source size 是否把 C++ 头文件和 Python 文件纳入同一门禁。
- 0.1.1 是否需要单独创建 `todo_0.1.1.md`,还是继续维护根目录 `todo.md`。
+580
View File
@@ -0,0 +1,580 @@
# SPHLite v2.0 开发计划
文档状态:0.2.0 开发计划稿
目标软件版本:SPHLite 0.2.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`
- `v1.0_development_plan.md`
- `v1.1_development_plan.md`
## 1. 版本定位
SPHLite 0.2.0 是第一个真实物理计算版本,定位为 `Water` 基础 SPH 最小闭环。该版本应在 0.1.1 已完成的工程骨架、输入元数据、粒子状态查询、C/C++/Python/CLI、output、restart 和 release gate 基础上,交付可测试的 3D 水相弱可压 SPH 计算路径。
0.2.0 的核心价值不是完成水下爆炸,而是把真实 SPH 计算链路打通:
```text
输入粒子状态 -> 构建邻域 -> 核函数 -> Tait EOS -> 连续性方程 -> 压力/黏性力 -> Velocity-Verlet -> 输出/restart/checker
```
0.2.0 不应扩展为 `Gas`、`Explosive`、`Solid`、`Shell` 或 FEM-SPH 联合运行版本。后续水下接触爆炸能力必须建立在本版本稳定的 `Water` 基础计算、邻域搜索和测试体系之上。
## 2. 版本目标
0.2.0 应完成:
- 将软件版本更新为 `0.2.0`。
- 建立 `Particle` 模块中的核函数和 uniform cell/bin 邻域搜索。
- 实现每粒子独立光滑长度 `h(i)` 的核函数计算路径。
- 实现 Wendland C2 默认核函数。
- 保留 Wendland C4 和 cubic spline 作为可选或回归测试核函数。
- 实现 Tait EOS 水相压力计算。
- 实现水相连续性方程,采用密度演化作为主流程。
- 实现 Monaghan 型人工黏性。
- 将水相压力梯度、人工黏性和外部体力贡献接入显式加速度计算。
- 使 Velocity-Verlet 从 0.1 系列的运动骨架升级为可调用水相力计算的真实推进流程。
- 实现水相稳定时间步估计,至少覆盖 CFL 声速约束、加速度约束和黏性约束。
- 完善 input/API/CLI/output/restart,使 0.2.0 水相状态可以读入、运行、输出和恢复。
- 建立 Water 单元测试、模块测试和小型 pressure wave smoke。
- 保持 C ABI、C++ wrapper 和 Python 调试入口与新增水相能力一致。
- 保持 release gate 快速、稳定、小规模。
## 3. 明确不交付范围
0.2.0 不交付:
- 生产级水下爆炸近场强冲击计算。
- Riemann-SPH、Godunov-SPH 或高阶强冲击格式。
- 真实 `Gas` EOS 计算、气体团簇和气泡脉动。
- `Explosive` 解析点火、programmed burn 和产物气体注入。
- `Solid` 3D 结构应力更新、Johnson-Cook 材料和失效。
- `Shell` Mindlin-Reissner 板壳计算。
- 水-气、水-结构、气-结构的生产级相互作用。
- 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。
- 与 FEMLite 的联合运行。
- 几何、网格或粒子生成能力。
- 完整自由面重构、锐界面追踪、复杂边界条件库。
- 大规模并行、GPU 后端和性能优化专项。
- 工程 benchmark 和长跑算例。
0.2.0 可以为后续多物理能力保留接口和字段,但不得把占位能力描述为已实现物理算法。
## 4. 目录结构调整
0.2.0 沿用 0.1.1 目录结构,不新增 `geometry/` 或 `mesh/` 目录。
建议重点完善:
```text
src/
particle/
kernel
neighbor
material/
water material and EOS helpers
water/
density, pressure, viscosity, acceleration, diagnostics
solver/
explicit Velocity-Verlet force coupling
tests/
unit/
module/
interface/
data/
tools/
testing/
```
测试或示例所需的 `.inp` 文件可以手写或由 Python 辅助脚本生成,但这些脚本仍只属于测试/示例辅助工具,不属于求解器几何或粒子生成功能。
## 5. 数据库和运行时状态范围
0.2.0 继续采用集中型数据库。通用粒子状态仍由 `Database` 管理,`Water` 只维护水相计算所需参数、派生量、临时数组和诊断量。
0.2.0 应确认或完善以下通用状态:
- `particle_id_ext`
- `particle_phase`
- `particle_status`
- `material_id`
- `section_id`
- `x0(3,npart)`
- `x(3,npart)`
- `v(3,npart)`
- `a(3,npart)`
- `vhalf(3,npart)`
- `mass(npart)`
- `rho(npart)`
- `volume(npart)`
- `pressure(npart)`
- `internal_energy(npart)`
- `temperature(npart)`
- `h(npart)`
0.2.0 新增或完善的运行时状态建议包括:
- 每粒子的密度变化率 `drho_dt(npart)`。
- 每粒子的压力加速度贡献 `acc_pressure(3,npart)`。
- 每粒子的人工黏性加速度贡献 `acc_viscosity(3,npart)`。
- 每粒子的外部体力加速度贡献或等效力缓存。
- 邻域搜索 cell id、链表或压缩索引。
- 邻域对或邻域表。
- 每粒子邻居数量。
- 水相总质量、总动量、最大压力、压力冲量和时间步约束诊断。
邻域表应由 `Particle` 或邻域模块统一维护,水相模块按 phase、material、section 或 region 过滤相互作用。0.2.0 不建立多张互相独立的邻域表。
## 6. 输入解析范围
0.2.0 在 0.1.1 `.inp` 子集基础上增加水相计算所需参数解析。仍不追求完整 Abaqus 兼容,能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的 SPHLite 专有能力使用 `*SPHLITE ...` 扩展关键词。
建议输入能力:
- `*NODE`:继续读取 3D 粒子坐标。
- `*ELEMENT`:继续保存粒子或粒子集合连接占位,用于 set/section/material 映射。
- `*NSET` / `*ELSET`:继续作为集合,不作为物理类型判断依据。
- `*MATERIAL`:保存材料名称,并允许识别水材料类型。
- `*DENSITY`:优先复用 Abaqus 关键词读取参考密度。
- `*SECTION` 或等价 section 关键词:保存 section 与 material 引用。
- `*SPHLITE TIME CONTROL`:继续控制 `DT`、`TIME`、`STEPS` 和安全系数。
- `*SPHLITE OUTPUT`:继续控制输出目录和输出间隔。
- `*SPHLITE EOS`:建议作为 Tait EOS 参数入口。
- `*SPHLITE VISCOSITY`:建议作为 Monaghan 人工黏性参数入口。
- `*SPHLITE PARTICLE CONTROL`:建议作为 `h`、初始质量或体积等粒子数值参数入口。
- `*SPHLITE BODY FORCE`:可选,用于重力或小型验证算例体力。
建议 Tait EOS 字段:
- `TYPE=TAIT`
- `MATERIAL=<name>`
- `RHO0`
- `C0`
- `GAMMA`
- `P0`
- `B` 可选;若未给定,可由 `rho0*c0*c0/gamma` 计算。
建议 Monaghan 人工黏性字段:
- `TYPE=MONAGHAN`
- `MATERIAL=<name>`
- `ALPHA`
- `BETA`
- `ETA2`
0.2.0 应对缺失关键水相参数报 error,对不影响运行的未知关键词报 warning。输入错误消息应继续包含文件名和行号上下文。
## 7. 核函数范围
0.2.0 应建立 `Particle` 核函数模块,提供:
- `W(r,h)`。
- `grad W(r,h)`。
- 核函数支持半径。
- 3D 归一化系数。
- 核函数类型选择。
- 对非法 `h <= 0` 和非法核函数类型的错误路径。
默认核函数为 Wendland C2。Wendland C4 作为可选核函数,cubic spline 作为对比和回归测试核函数。
单元测试应覆盖:
- `r = 0` 处函数值有限。
- 超出支持半径时 `W = 0` 且梯度为零。
- 梯度方向与粒子连线方向一致。
- 对称粒子对的梯度反对称性。
- 不同 `h(i)` 下结果有限且符号正确。
0.2.0 不要求做完整三维积分归一性高精度 benchmark,但应保留后续 checker 入口。
## 8. 邻域搜索范围
0.2.0 邻域搜索采用 uniform cell/bin 方法,不引入树结构。
邻域搜索应支持:
- 根据当前坐标计算全局包围盒。
- 根据最大支持半径确定 cell 尺寸。
- 建立粒子到 cell 的映射。
- 遍历相邻 cell 生成邻域。
- 支持每粒子独立 `h(i)`。
- 对 phase、status 或 region 的过滤留给物理模块。
- 粒子移动后可重建邻域。
邻域测试应覆盖:
- 与朴素 `O(n^2)` 搜索结果一致。
- 不同 `h(i)` 的搜索半径。
- 空模型和单粒子模型。
- 粒子移动后重建。
- 边界 cell 和负坐标。
- 最大邻居数量或邻域表容量不足时的明确错误。
0.2.0 默认 gate 中邻域测试应保持小规模,不进入性能基准。
## 9. Water 模块范围
0.2.0 `Water` 模块应实现弱可压 SPH 最小闭环。
水相 EOS:
- 使用 Tait EOS。
- 压力由 `rho`、`rho0`、`c0`、`gamma`、`p0` 和可选 `B` 计算。
- 压力可允许为负值或设置拉伸限制,具体策略应在实现前写入测试说明。
水相密度:
- 主流程采用连续性方程。
- 不使用 summation density 作为主流程。
- 0.2.0 可保留 summation density 对比 checker 的后续入口,但不进入生产路径。
水相动量:
- 包含压力梯度项。
- 包含 Monaghan 型人工黏性项。
- 支持外部体力或体力占位。
- 默认只处理 water-water 相互作用。
- 对非 water phase 的粒子默认跳过,后续多相版本再引入水-气或水-结构相互作用。
水相诊断:
- 水相粒子数。
- 水相总质量。
- 水相总动量。
- 最大压力。
- 最小/最大密度。
- 压力冲量占位。
- CFL、加速度和黏性时间步约束贡献。
## 10. Solver 集成范围
0.2.0 继续使用 Velocity-Verlet 作为唯一主时间推进格式。
建议单步流程:
```text
校验模型和时间步
必要时重建邻域
根据 rho 计算 pressure
计算 drho_dt
计算水相压力和黏性加速度
加入体力或外部载荷占位
Velocity-Verlet 更新速度、位置、密度和时间
更新诊断
按间隔输出
```
稳定时间步估计应至少考虑:
- `dt_cfl = h / (c + |v|)` 类型的声速约束。
- 加速度约束。
- 人工黏性约束。
- 输入安全系数。
0.2.0 不引入隐式、静力、非线性静力或隐式-显式混合求解接口。
## 11. Output 和 Restart 范围
0.2.0 CSV 输出应在 0.1.1 字段基础上确保可检查水相计算结果:
- id
- phase
- status
- material
- section
- x
- v
- rho
- pressure
- temperature
- h
建议增加可选诊断输出或独立 summary:
- step
- time
- water mass
- water momentum
- max pressure
- min/max density
- dtcrit
restart 应保存 0.2.0 继续计算所需状态:
- 0.1 系列通用粒子状态。
- 当前时间、步数、输出控制。
- 速度、加速度和半步速度。
- 水相 EOS 和人工黏性参数。
- 密度、压力、内能、温度和 `h`。
- 邻域搜索控制参数。
- 水相诊断状态。
邻域表本身可以不写入 restart,读入 restart 后允许重建邻域,但控制参数必须可恢复。
## 12. Fortran API 范围
0.2.0 Fortran API 继续作为核心语义来源。建议在 0.1.1 API 基础上增加或完善:
```fortran
subroutine sph_rebuild_neighbors(ierr)
subroutine sph_get_neighbor_stats(max_neighbors, average_neighbors, ierr)
subroutine sph_get_water_summary(mass, momentum, max_pressure, min_density, max_density, ierr)
subroutine sph_get_water_dt_limits(dt_cfl, dt_accel, dt_viscous, ierr)
```
其中 `momentum` 为三维向量。若 0.2.0 实现阶段认为公开 neighbor API 过早,可先保留为 Fortran 模块测试入口,不进入 C ABI。
已有 API 必须继续可用:
- 生命周期。
- `.inp` 读取。
- build model。
- stable dt。
- advance/run explicit。
- current time。
- particle count/state。
- output/restart。
- error query。
所有新增可失败接口必须返回错误码,并写入最近错误消息。
## 13. C ABI、C++ 和 Python 范围
C ABI 应保持 0.1.1 已有接口兼容。0.2.0 建议增加水相诊断查询:
```c
int sphlite_get_water_summary(double *mass,
double *momentum,
double *max_pressure,
double *min_density,
double *max_density);
int sphlite_get_water_dt_limits(double *dt_cfl,
double *dt_accel,
double *dt_viscous);
```
数组约定:
- `momentum[0..2]` 为三维总动量。
C 参数错误仍返回 `-1`。Fortran 物理、输入或数据库错误仍返回 SPHLite 错误码。
C++ wrapper 仍保持薄包装定位:
- 包装新增水相 summary 和 dt limits。
- 不重新定义物理语义。
- 不作为核心实现语言。
Python `ctypes` 调试入口应扩展:
- 读取水相 summary。
- 读取 dt limits。
- 提供小型 run/checker 辅助函数。
- 保持缺失输入、缺失参数和错误路径测试。
Python 仍不是唯一入口,CLI 和 C ABI 必须完整可用。
## 14. CLI 范围
0.2.0 CLI 应保持 0.1.1 用法:
```powershell
sphlite model.inp
sphlite model.inp --check
sphlite model.inp --run
sphlite model.inp --run --output output
sphlite --version
```
建议增加或稳定以下 inspect/check 输出字段:
- `version`
- `input`
- `mode`
- `particles`
- `warnings`
- `time`
- `step`
- `status`
- `water_particles`
- `water_mass`
- `max_pressure`
- `dtcrit`
CLI 内部仍必须走公共生命周期 API,不绕过 Fortran API 或 C ABI。
## 15. CouplingInterface 边界
0.2.0 不实现外部耦合模块,也不依赖 FEMLite。CouplingInterface 维持 0.1.1 中立接口占位。
0.2.0 可做的最小加固:
- 确认水相运行后 coupling particle 导出仍可用。
- 确认外部粒子力导入可以进入显式步体力或外载占位。
- 继续记录耦合功、动量和能量诊断占位。
- 保持接触耦合和连续体耦合类型区分。
0.2.0 默认 gate 不包含真实 FEM-SPH 联合运行。
## 16. 测试计划
0.2.0 默认 gate 建议包含:
- `smoke`:版本 0.2.0、生命周期、显式步进和基础错误路径。
- `input`:Water material、Tait EOS、viscosity、particle control、warning/error。
- `kernel`:Wendland C2、Wendland C4、cubic spline 的基础性质。
- `neighbor`:uniform cell/bin 与朴素搜索一致。
- `water_eos`:Tait EOS 压力计算和非法参数错误。
- `water_density`:连续性方程密度变化率方向和量级。
- `water_viscosity`:Monaghan 人工黏性方向、有限性和对称性。
- `water_force`:压力梯度和黏性加速度 smoke。
- `solver_water`:Velocity-Verlet 与 Water 力计算闭环。
- `output`:CSV 字段包含 0.2.0 水相状态。
- `restart`:水相参数和状态写入、读回、继续最小显式步。
- `c_api`:新增水相诊断接口和原有 C ABI 兼容性。
- `cpp_api`:新增水相诊断薄包装 smoke。
- `python_debug`:水相 inspect/run/checker smoke。
- `cli`:0.2.0 inspect/check/run/version/error。
- `pressure_wave_smoke`:小型 3D 压力扰动传播 smoke。
- `source_size`:Fortran/C/C++/Python 文件大小和 stale exception。
0.2.0 的 `pressure_wave_smoke` 应只验证方向、有限性、守恒量趋势和输出字段,不作为工程精度 benchmark。
非默认测试可保留:
- 更大粒子数压力传播。
- 水柱或自由面示例。
- 参数收敛研究。
- 与解析波速的更严格对比。
这些不进入默认 release gate。
## 17. 0.2.0 Release Gate
建议 release gate:
```powershell
cmake --build build-codex-unix --parallel
ctest --test-dir build-codex-unix -R "^(smoke|input|kernel|neighbor|water_eos|water_density|water_viscosity|water_force|solver_water|output|restart|c_api|cpp_api|python_debug|cli|pressure_wave_smoke)$" --output-on-failure
ctest --test-dir build-codex-unix -R "^source_size$" --output-on-failure
git diff --check
```
验收标准:
- 完整配置 CMake。
- 完整编译 `sphlite_core`、`sphlite_c`、`sphlite` 和新增测试目标。
- 默认 gate 全部通过。
- source size 通过。
- `git diff --check` 通过。
- README、09 和 11 号文档记录 0.2.0 gate 结果。
- 文档状态与实际能力一致,不宣称已实现水下爆炸完整能力。
- 输出目录、CSV、VTK、restart 和 Python 缓存不进入提交。
- 文档使用 UTF-8 without BOM。
## 18. 开发阶段拆分
### 阶段 A:版本和测试骨架
- 将软件版本更新为 0.2.0。
- 新增 `kernel`、`neighbor`、`water_eos` 等 CTest 目标占位。
- 准备最小 Water `.inp` 测试数据。
- 保持 0.1.1 gate 继续通过。
### 阶段 B:核函数模块
- 实现 Wendland C2。
- 实现 Wendland C4。
- 实现 cubic spline。
- 统一核函数类型选择。
- 增加核函数单元测试。
### 阶段 C:邻域搜索模块
- 实现 uniform cell/bin 数据结构。
- 实现邻域构建和重建。
- 支持每粒子独立 `h(i)`。
- 增加与朴素搜索对比测试。
### 阶段 D:Water 参数和 Tait EOS
- 扩展 input 解析水材料、Tait EOS 和粒子控制参数。
- 实现 Tait EOS。
- 增加非法参数错误路径。
- 增加 water summary 诊断占位。
### 阶段 E:连续性方程和人工黏性
- 实现 `drho_dt` 计算。
- 实现 Monaghan 人工黏性。
- 实现压力梯度加速度。
- 建立水相力计算主入口。
### 阶段 F:Solver、Output 和 Restart
- 将 Water 力计算接入 Velocity-Verlet。
- 实现稳定时间步估计。
- 扩展 CSV 输出字段和 summary。
- 扩展 restart 保存水相状态和控制参数。
- 增加继续运行测试。
### 阶段 G:接口和 CLI
- 增加 Fortran 水相诊断 API。
- 增加 C ABI 水相诊断 API。
- 扩展 C++ wrapper。
- 扩展 Python 调试入口。
- 扩展 CLI inspect/check/run 输出。
### 阶段 H:Pressure Wave Smoke 和 Gate
- 创建小型 3D pressure wave `.inp`。
- 实现 pressure wave checker。
- 更新 README、09 和 11 号文档。
- 更新 `todo.md`。
- 跑通 0.2.0 release gate。
## 19. 风险和控制
| 风险 | 控制 |
|---|---|
| 0.2.0 膨胀为完整水下爆炸版本 | 只交付 Water 基础弱可压 SPH,不做 Gas/Explosive/Solid/Shell 生产路径 |
| 邻域搜索过早复杂化 | 只做 uniform cell/bin,树结构和并行优化推迟 |
| 输入参数语法摇摆 | 先锁定 Tait EOS、viscosity 和 particle control 的最小字段 |
| 压力波 smoke 变成长跑 benchmark | 默认 gate 只保留小粒子数、短时间、趋势检查 |
| Tait EOS 单位混乱 | 继续沿用 Abaqus/FEMLite 风格,不做内置单位换算,示例中明确参数单位一致性 |
| 人工黏性导致数值不稳定 | 从小型对称测试和有限性测试开始,默认参数保守 |
| restart 状态缺失导致继续运行不一致 | 0.2.0 明确保存水相参数、密度、压力、速度、加速度和时间控制 |
| C ABI 与 Fortran API 分叉 | Fortran API 仍是语义来源,C ABI 只做薄包装 |
| 文档宣称超过实际能力 | README、09、11 和本计划均明确 0.2.0 不交付水下爆炸完整能力 |
## 20. 后续版本衔接
0.2.0 完成后,0.3 可集中进入 `Gas`:
- JWL EOS。
- 理想气体 EOS。
- Stiffened gas EOS。
- 气体总体积、中心、平均压力和最大压力。
- 等效气泡半径和半径变化率。
- 气体团簇统计。
0.2.0 应为 0.3 保留统一粒子数据库、phase 过滤、邻域搜索、输出、restart 和诊断接口,但不提前实现气体生产计算。
## 21. 待确认事项
- Tait EOS 第一版是否允许负压,或是否设置拉伸压力限制。
- `*SPHLITE EOS`、`*SPHLITE VISCOSITY` 和 `*SPHLITE PARTICLE CONTROL` 的最终字段名。
- 初始质量、体积和 `h` 是统一给定、逐粒子给定,还是由 section/material 默认值推导。
- Monaghan 人工黏性默认 `alpha`、`beta` 和 `eta2` 建议值。
- `pressure_wave_smoke` 的最小粒子布置和 checker 阈值。
- 水相 summary 是否进入 C ABI,还是先保留为 Fortran/Python 测试入口。
- 0.2.0 是否需要新增 VTK 输出占位,或继续只用 CSV 作为默认 gate 输出。