Files
SPHLite/docs/02_software_architecture_design.md
T

152 lines
6.8 KiB
Markdown
Raw Normal View History

2026-07-02 18:47:38 +08:00
# 02 软件架构设计
文档状态:规划确认稿
## 1. 架构概览
SPHLite 采用与 FEMLite 一致的 Fortran 95 风格过程式模块架构。核心求解器使用 Fortran 编写并遵守 Fortran 95 规范;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、VTK、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` 厚度、法向/转角、积分点、损伤和撕裂状态。
- 耦合历史量、功、动量和能量诊断。
- 邻域搜索重建所需控制参数。
## 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 生成器的目录组织和示例规范。
- 外部耦合模块最终命名和配置文件边界。