Files
FemLite/docs/02_software_architecture_design.md
shenw 678d2006cc
FemLite CI / build-test (push) Has been cancelled
Document V4.8 solver and example coverage
2026-06-25 12:19:35 +08:00

505 lines
14 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.
# FEM Software Architecture Design
文档状态:架构基线草稿
适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序
## 1. 文档目的
本文档描述 FEM 软件的整体架构、交付形态、目录组织、模块划分、数据流、控制流、外部接口、错误处理和扩展策略。
本文档中的架构决策用于约束后续详细设计、算法设计、接口设计和代码实现。
## 2. 架构目标
软件架构应满足:
- 核心库与命令行程序分离
- 第一版优先支持显式瞬态动力学
- 第一版支持独立 FEM 程序运行和外部 SPH 驱动两种模式
- 第一版支持 Abaqus inp 输入
- 第一版支持 SPH-FEM 边界力交换接口
- Fortran95 过程式模块组织,不采用面向对象类型绑定
- 集中式数据库管理网格、材料、状态变量和全局向量
- 单元、材料、求解器、耦合和输出模块保持职责分离
- 第二版形成壳单元扩展、CSR、隐式线弹性、基础接触、VTK、restart 和外部接口的最小可用框架
- 第三版正式支持线性静力、非线性静力、壳单元静力、隐式非线性动力学和通用接触
## 3. 交付形态
第一版交付:
- 静态库:libFemLite
- 命令行程序:femlite
- 测试程序:单元测试、模块测试和集成测试可执行文件
- 示例算例:examples 目录中的 Abaqus inp 输入文件和参考输出
- 文档:docs 目录中的需求、架构、详细设计、算法、接口和测试文档
第二版或后续版本可扩展:
- 动态库
- C/C++/Python 包装层
- 更完整后处理工具链
- 外部求解器适配层
第三版交付应补充:
- 静力学命令行分析模式
- 静力学核心库接口
- 壳静力和非线性静力验证算例
- 静力学收敛历史、反力和 VTK/CSV 输出
## 4. 目录结构
建议目录结构:
```text
src/base 基础类型、常量、日志、错误码、控制参数
src/input Abaqus inp 读取与输入数据预处理
src/mesh 网格、集合、facet、自由度编号
src/material 材料模型与状态变量更新
src/element 实体单元、壳单元、形函数、积分规则
src/solver 显式求解器、静力求解器、隐式动力求解器、稀疏矩阵
src/boundary 边界条件、载荷、约束、接触
src/coupling FEM 外部耦合接口和 SPH 力映射
src/output 日志、CSV、VTK 预留、restart 预留
src/app femlite 命令行程序
tests 测试程序与测试数据
examples 示例 inp 文件与参考结果
docs 工程文档
```
目录职责边界:
- input 层只负责解析输入,不直接执行求解。
- material 层只负责本构更新,不直接访问全局网格。
- element 层负责单元级质量、内力、应力更新和稳定步长估计。
- solver 层负责时间推进和全局向量更新,不直接依赖 SPH 实现。
- coupling 层只负责数据交换和力映射,FEM 核心不依赖 SPH 程序。
- output 层统一处理日志、历史量和结果输出。
## 5. 总体分层
软件采用以下分层:
```text
Application Layer
femlite command line program
test programs
examples
Public API Layer
fem_initialize
fem_read_inp
fem_build_model
fem_advance_explicit
fem_get_boundary_facets
fem_apply_sph_forces
fem_finalize
Core FEM Layer
mesh database
dof numbering
material update
element routines
boundary and load routines
coupling force mapping
Solver Layer
explicit central difference solver
linear static solver
nonlinear static solver
implicit Newmark solver
CSR matrix layer
Input/Output Layer
Abaqus inp reader
log writer
CSV writer
VTK placeholder
restart placeholder
```
## 6. 数据库架构
软件采用集中式 fem_database 模块。
架构约定:
- 网格、材料、截面、集合、自由度、状态变量和全局向量由 fem_database 统一保存。
- 允许模块共享 fem_database 中的全局 allocatable 数组。
- 各模块通过明确的初始化、查询和更新子程序访问数据库。
- 不使用面向对象类型绑定。
- 材料例程不直接访问全局数据库。
- 单元例程可读取单元连接、坐标、材料编号和状态变量索引。
- 求解器例程负责全局向量清零、累计、边界条件施加和时间推进。
核心数据库类别:
- 节点坐标
- 单元连接关系
- 单元类型
- 节点集和单元集
- 材料参数
- 截面参数
- 自由度编号
- 位移、速度、加速度
- 集中质量
- 内力、外力、接触力、SPH 力
- 高斯点应力、应变、塑性应变和历史变量
- 单元删除标志
## 7. 自由度架构
每个节点预留 6 个自由度:
```text
1 UX
2 UY
3 UZ
4 RX
5 RY
6 RZ
```
自由度规则:
- 实体单元只激活 UX、UY、UZ。
- 壳单元激活 UX、UY、UZ、RX、RY、RZ。
- 未激活自由度编号为 0。
- 全局自由度编号由 mesh/dof 模块统一生成。
- Dirichlet 边界、节点力、输出和 SPH 接口均使用同一自由度约定。
- 后续 MPC、接触和壳-实体连接沿用同一自由度体系。
## 8. 大变形架构
第一版默认采用 Updated Lagrangian 架构。
基本约定:
- 当前构形用于计算单元几何、Jacobian、体积、面积和法向。
- 单元内力基于当前构形上的应力状态累计。
- 小应变 J2 和大应变 J2 通过材料更新选项切换。
- 大变形相关运动学量由单元模块计算并传递给材料模块。
- 材料模块只接收材料更新所需的局部变量和旧状态,返回新应力、状态变量和可选切线。
- 壳单元第一版可采用有限转动能力受限的 S4 实现,第二版再扩展更完整壳大变形框架。
## 9. 材料与状态变量架构
状态变量存储按 element + integration point 组织。
职责划分:
- fem_database 保存所有高斯点状态变量。
- element 模块负责从数据库取出旧状态并调用材料模块。
- material 模块负责应力更新和状态变量更新。
- element 模块负责把新状态写回数据库。
- solver 模块负责控制何时提交或回滚状态变量。
材料例程接口原则:
- 输入应包含材料编号、应变增量或变形度量、应变率、温度、时间步长和旧状态。
- 输出应包含新应力、新状态变量、失效标志和可选算法切线。
- 材料例程不得依赖全局节点、单元或求解器状态。
## 10. 单元调度架构
Fortran95 下直接使用 Abaqus 单元类型字符串作为内部主标识。
支持的单元类型字符串:
```text
C3D4
C3D8
S4
C3D10
C3D20
S3
S6
S8
```
调度原则:
- elem_type 使用固定长度字符串保存,例如 character(len=16)。
- INP 读取时将单元类型转换为大写并去除多余空格。
- element_driver 根据 elem_type 字符串调用具体单元例程。
- 具体单元例程只处理本单元的质量、内力、应力更新、稳定时间步和面载荷。
- 新增单元时扩展 elem_type 字符串识别和对应单元例程。
- 第一版必须实现 C3D4、C3D8、S4。
- 第二版应实现 C3D10、C3D20、S3、S6、S8。
- 后续如需性能优化,可增加内部缓存编码,但 Abaqus 字符串仍作为数据库主字段。
## 11. 核心数据流
独立程序模式数据流:
```text
Abaqus inp
-> inp reader
-> mesh/material/section/boundary database
-> dof numbering
-> facet construction
-> mass initialization
-> explicit time integration loop
-> element stress/internal force update
-> boundary and load update
-> output
```
外部 SPH 驱动模式数据流:
```text
external driver
-> fem_initialize
-> fem_read_inp / fem_build_model
-> fem_get_boundary_facets
-> external SPH force calculation
-> fem_apply_sph_forces
-> fem_advance_explicit(dt)
-> fem_get_boundary_facets
-> repeat
```
## 12. 求解控制流
第一版显式中心差分控制流:
```text
initialize model
compute lumped mass
initialize displacement, velocity and acceleration
for each time step:
clear force vectors
apply prescribed loads
receive SPH forces when running in coupling mode
compute element stress and internal force
apply boundary conditions
compute acceleration from lumped mass
update velocity
update displacement
update current configuration
delete failed elements when required
write output when required
end for
```
第二版隐式线弹性控制流:
```text
initialize model
build CSR sparsity
assemble linear elastic stiffness
assemble external load vector
apply Dirichlet and constraint equations
solve K u = f
recover strain and stress
write output
```
第四版起,静力和隐式路径不直接绑定单一线性求解器,而是经由
`fem_linear_solver_cg.f90` 中的分发层求解 CSR 系统。分发层读取
`fem_control` 中的 method/preconditioner 设置,当前内部支持 CG、
BiCGSTAB 和 GMRES,支持 none/Jacobi 预条件,并把最近一次 method、
preconditioner、迭代数、残差和状态码写回控制模块供 Fortran API、C ABI
和测试查询。外部 MUMPS/SuperLU/MKL Pardiso 等后端只作为后续适配层,
不得让隐式求解器直接依赖第三方库。
第三版非线性静力控制流:
```text
initialize model
build CSR sparsity
for each increment:
apply load factor and prescribed displacement increment
Newton iteration:
assemble internal force and external force
assemble residual R = F_ext - F_int
assemble tangent matrix
apply boundary and constraint equations
solve correction
optionally perform line search
update trial state
check convergence
if failed and allowed, restore state and cut back increment
commit state
write output
end for
```
第三版隐式 Newmark 动力学控制流:
```text
initialize model
build CSR sparsity
for each time increment:
Newmark predict displacement and velocity
Newton iteration:
assemble effective residual
assemble effective tangent K_eff
apply boundary, MPC and contact equations
solve correction
optionally perform line search
update trial displacement, velocity and acceleration
check convergence
if failed and allowed, restore kinematics/state and cut back step
commit state
write output
end for
```
求解控制权:
- 独立程序模式由 femlite 控制时间循环。
- 外部 SPH 驱动模式由外部驱动器控制时间步长和调用顺序。
- SPH 耦合时,solver 只接收 fsph 全局力向量。
- solver 不直接调用 SPH 程序或依赖 SPH 数据结构。
## 13. SPH-FEM 耦合架构
coupling 层职责:
- 构造和维护 FEM 边界 facet 列表。
- 导出 facet 坐标、速度、法向和面积。
- 接收压力、剪切力或等效节点力。
- 将外部耦合载荷映射为 FEM 全局 fsph 向量。
- 检查 coupling 接口参数合法性。
边界 facet 来源:
- 实体单元外表面
- 壳单元表面
- 指定 elset
耦合约束:
- FEM 核心不依赖具体 SPH 程序。
- coupling 层不执行 SPH 粒子计算。
- element 层不直接依赖 SPH。
- solver 层只使用已经映射好的 fsph。
- 每个时间步可执行一次双向交换。
- 时间步由 SPH 或外部耦合驱动器控制。
## 14. 输出架构
第一版输出:
- 日志文件:运行信息、warning、error、关键统计量
- CSV 历史量:时间、能量、最大位移、最大速度、外力功等
- CSV 场变量:节点位移、速度、加速度,单元应力、应变、塑性应变
第二版输出:
- VTK 结果文件
- restart 文件
第三版输出:
- 静力学收敛历史文件
- 节点反力输出
- 接触状态、接触力和接触功输出
- 隐式增量残差和迭代次数输出
第三版当前接触模块保留刚性平面接触,并新增基于边界 facet 的面-面 contact pair force/tangent 路径。0.3.1 已补充投影裁剪面积积分、多 master 面积上限修正、Coulomb 摩擦、均匀空间网格候选搜索、facet 空间 broad-phase 精筛,以及接触状态/接触功 CSV 与 API 输出。0.3.2 已补充投影交叠域 mortar 形函数积分、接触对级粘滑历史变量、stick/slip/累计滑移输出,以及可选 OpenMP 的 master facet BVH 宽相搜索。0.3.3 已补充 `*SURFACE, TYPE=ELEMENT` 输入子集、同名 surface `OP=ADD/NEW`、face label 筛选、壳 `SPOS`/`SNEG` 侧向语义和数据行式 `*CONTACT PAIR` 子集,并将接触状态、目标筛选、几何积分、搜索、摩擦、力、切线和输出拆分为独立模块。
输出控制:
- 输出频率由 fem_control 统一管理。
- 输出模块不参与求解状态更新。
- 第一版不建立复杂后处理数据库。
## 15. 错误处理与日志
错误处理原则:
- 所有核心接口返回 ierr。
- 日志模块记录 warning、error 和 fatal 信息。
- 不支持的 Abaqus keyword 作为 warning 后跳过。
- 关键数据缺失、非法材料参数、退化单元等错误应终止当前分析。
- 外部接口不得通过未捕获异常或直接停止进程隐藏错误来源。
错误码分组:
```text
0 success
1000 input errors
2000 mesh and dof errors
3000 material and state errors
4000 solver errors
5000 coupling errors
6000 output errors
9000 internal errors
```
日志至少记录:
- 输入文件名
- 识别和跳过的 keyword
- 节点数、单元数、自由度数
- 材料和截面数量
- 时间步设置
- 输出设置
- warning 和 error 位置
- 分析开始和结束状态
## 16. 扩展策略
添加新单元:
- 增加 elem_type 字符串识别
- 增加形函数和积分规则
- 增加质量、内力、应力更新和面载荷例程
- 增加单元测试和 patch test
添加新材料:
- 增加材料类型编码
- 增加材料参数解析
- 增加材料更新例程
- 增加单轴或多轴材料测试
添加新边界条件:
- 增加输入解析
- 增加数据库存储
- 增加载荷或约束施加例程
- 增加验证算例
添加新输入 keyword:
- 增加 keyword 识别
- 增加参数解析
- 增加错误诊断
- 增加输入回归测试
接入外部线性求解器:
- 通过 CSR 层提供矩阵和向量接口
- 隐式求解器不得直接绑定具体第三方库
- 外部库适配应单独放在 solver 或 external 子层
- 外部库不可用时必须保留内部 CG/BiCGSTAB/GMRES 路径,构建和 CTest 不应受影响
## 17. 构建与部署架构
构建系统:
- 使用 CMake。
- 默认编译器为 gfortran。
- 兼容 Intel Fortran。
- 支持 Windows 和 Linux。
构建目标:
- FemLite 静态库
- femlite 命令行程序
- 单元测试程序
- 模块测试程序
- 集成测试程序
第一版不要求:
- OpenMP
- MPI
- 动态库
- 外部求解器强依赖