Files
SPHLite/docs/02_software_architecture_design.md
2026-07-05 21:41:34 +08:00

154 lines
7.4 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.
# 02 软件架构设计
文档状态:规划确认稿
## 1. 架构概览
SPHLite 算法核心采用与 FEMLite 一致的 Fortran 95 风格过程式模块架构。`sphlite_core` 内的求解器、粒子/单元语义、材料、物理模块、数据库、输入解析、显式求解器和 Fortran API 继续遵守 Fortran 95 规范;worker、CLI、IPC 等外围集成层及其测试/工具性 Fortran 代码可放宽到 Fortran 2018。C API/ABI、C++ 薄包装和 Python API 作为接口层提供,不作为核心求解实现语言。
推荐的数据流:
```text
输入层 -> 数据库 -> 粒子/材料/物理模块 -> 显式求解器 -> 输出/API
```
SPHLite 是求解器,不负责几何、网格或粒子生成。测试和示例可以使用 Python 脚本生成 Abaqus 风格 `.inp` 输入文件,但这些脚本属于测试/示例辅助工具,不作为求解器功能。
SPHLite 的支持环境、构建方式和工具链要求应与 FEMLite 保持一致。
## 2. 主要模块
| 模块 | 职责 |
|---|---|
| `Core` | 精度、错误、日志、生命周期、控制参数 |
| `Input` | Abaqus `.inp` 子集解析和 `*SPHLITE ...` 扩展关键词解析 |
| `Database` | 集中管理粒子、集合、材料、section、phase、时间状态和模块状态 |
| `Particle` | 粒子状态、粒子族、邻域搜索、核函数 |
| `Material` | 水、气体、炸药、金属、壳材料和损伤参数 |
| `Water` | 水体、压力、人工黏性、冲击波和自由界面 |
| `Gas` | 气体 EOS、气体粒子、气体团簇和气泡诊断 |
| `Explosive` | 起爆、爆轰到达时间、反应进度和能量释放 |
| `Solid` | 3D 固体结构、应力更新、塑性、损伤、断裂 |
| `Shell` | 板壳粒子、厚度、法向/转角、膜弯剪和撕裂 |
| `CouplingInterface` | 面向外部耦合模块的中立数据交换接口和耦合诊断 |
| `Solver` | Velocity-Verlet 显式时间推进、子循环、稳定时间步估计 |
| `Output` | CSV、summary CSV、VTU、PVD、restart、诊断和 benchmark 指标 |
| `Interface` | Fortran API、C ABI、C++ 薄包装、Python API、CLI |
## 3. 模块边界
- `Explosive` 只负责炸药反应和能量释放,不直接实现气泡脉动。
- `Gas` 负责气体相状态、EOS、气体界面和气泡诊断。
- `Water` 负责水相运动和水中压力传播。
- `Solid` 和 `Shell` 分别处理实体结构粒子和板壳结构粒子,不互相伪装。
- `CouplingInterface` 只定义中立耦合数据、边界导出、载荷导入和诊断统计,不依赖 FEMLite,也不依赖外部耦合模块内部实现。
- 外部耦合模块暂称 `CouplingModule`,后续可能命名为 `CoupleLite`、`CoupledLite` 或 `CouplingLite`。该模块不属于 SPHLite 内部依赖。
## 4. 输入与模型识别
SPHLite 应解析 Abaqus `.inp` 文件的明确子集,不追求完整 Abaqus 兼容。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的 SPHLite 专有能力统一使用 `*SPHLITE ...` 扩展关键词。
输入识别原则:
- 水、气、炸药和实体结构均作为 3D 实体粒子处理。
- 板壳结构为 2D 几何,通过 section 识别板壳属性。
- 水、气、炸药、实体结构和板壳结构通过 material 识别物理类型和本构/EOS 参数。
- set 只表示集合,可包含同种或不同种类的粒子,不能作为类型判断依据。
- 不影响程序运行的未支持关键词应 warning 后跳过。
- 关键词缺失或不支持导致程序无法运行时应报 error。
- 单位系统与 FEMLite/Abaqus 风格一致,程序不做内置单位换算,用户负责保持单位一致。
## 5. 数据库与粒子状态
SPHLite 采用集中型数据库。所有粒子的通用状态由 `Database` 统一管理,包括 id、phase、material、section、位置、速度、加速度、质量、密度、压力、体积和时间状态。
水和气有本质区别,计算模块保持独立;但水粒子和气粒子共享同一套粒子通用数据结构。`Water` 和 `Gas` 只维护各自计算所需的派生状态、EOS 状态、诊断量和临时工作数组。
phase 允许在计算中改变,例如炸药粒子可逐步转化为气体 phase。`Explosive` 同时预留两种路线:
- 同一粒子从 explosive phase 迁移到 gas phase。
- 炸药粒子保留自身状态,并向 `Gas` 注入质量、动量和能量源项。
## 6. 时间推进
SPHLite 只支持显式动力学时间推进。求解器采用 Velocity-Verlet 作为唯一主时间积分格式。
架构中不保留隐式求解、静力求解、非线性静力求解或隐式-显式混合求解接口。后续如需引入子循环,也应服务于显式动力学主流程。
## 7. 外部耦合边界
SPHLite 不直接与 FEMLite 耦合,也不引用 FEMLite 模块作为依赖。SPHLite 只通过中立耦合数据契约与外部耦合模块交换数据。外部耦合模块再负责与 FEMLite 或其他求解器通信。
SPHLite 侧应提供:
- 导出 SPH 侧耦合区域的粒子状态、边界面、法向、面积、速度和材料/phase 信息。
- 导入外部耦合模块提供的节点力、面力、体力、位移/速度约束或连续体界面交换量。
- 记录耦合功、动量交换、能量交换和错误诊断。
- 区分接触耦合和连续体耦合,不将连续体耦合简化为接触。
SPHLite 输入文件只定义 SPHLite 侧 coupling region 和交换变量。外部求解器侧区域由外部耦合模块或其配置文件匹配。
## 8. Restart 和输出
restart 应按完整模块级别设计,能够恢复显式动力学继续计算所需的全部状态。第一版至少应在格式上预留:
- 粒子通用状态。
- 时间控制、步数、输出计数和 Velocity-Verlet 所需的当前/历史加速度或半步状态。
- 水相状态和气体状态。
- 炸药反应进度、爆轰到达状态和源项累计量。
- `Solid` 应力、塑性、损伤和失效状态。
- `Shell` 厚度、法向/转角、积分点、损伤和撕裂状态。
- 耦合历史量、功、动量和能量诊断。
- 邻域搜索重建所需控制参数。
输出层当前采用文本 CSV 与 VTK XML 并行策略:粒子结果写入 CSV 和 VTU,时间序列管理文件写入 PVD,summary CSV 保存标量诊断。worker 预研阶段新增的 log、particle report 和 force report 属于 CCLite adapter 诊断,不替代求解输出。
## 9. 构建产物和接口层
SPHLite 建议采用与 FEMLite 类似的产物分层:
- `sphlite_core`:Fortran 核心库。
- `sphlite_c`:C ABI 薄包装库。
- `sphlite`:命令行程序。
- C++ wrapper:薄包装 C ABI。
- Python API:优先使用 `ctypes` 包装 C ABI。
命令行程序作为一等入口,语法风格应与 FEMLite 保持一致,例如读取 `.inp` 文件并执行显式动力学分析。
## 10. 建议目录结构
```text
include/
sphlite_c_api.h
src/
core/
input/
database/
particle/
material/
water/
gas/
explosive/
solid/
shell/
coupling_interface/
solver/
output/
interface/
Python/
tests/
examples/
tools/
docs/
```
不设置 `geometry/` 或 `mesh/` 目录。SPHLite 不承担几何建模、网格生成或粒子生成职责。
## 11. 待讨论问题
- Abaqus 子集的第一批关键词清单。
- `*SPHLITE ...` 扩展关键词的详细语法。
- Velocity-Verlet restart 中半步速度和加速度的保存约定。
- Python inp 生成器的目录组织和示例规范。
- 外部耦合模块最终命名和配置文件边界。