# 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 输出字段格式。