Files
SPHLite/docs/v1.1_development_plan.md
T
2026-07-02 19:50:44 +08:00

375 lines
15 KiB
Markdown
Raw 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.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`。