562 lines
13 KiB
Markdown
562 lines
13 KiB
Markdown
# FEM Interface Control Document
|
|
|
|
文档状态:接口基线草稿
|
|
|
|
适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序
|
|
|
|
## 1. 文档目的
|
|
|
|
本文档定义 FEM 核心库对外暴露的调用接口、数组维度、编号规则、内存所有权、错误码、单位制和 SPH-FEM 耦合接口。
|
|
|
|
本文档是外部程序,特别是 SPH 程序,与 FemLite 进行联调时的接口合同。
|
|
|
|
## 2. 接口范围
|
|
|
|
第一版提供:
|
|
|
|
- Fortran95 原生接口。
|
|
- 显式瞬态动力学推进接口。
|
|
- Abaqus inp 模型读取接口。
|
|
- 外部 SPH 驱动接口。
|
|
- 节点力、facet 压力、facet 压力加剪切力接口。
|
|
- 节点运动学和单元平均结果查询接口。
|
|
- CSV 输出控制接口。
|
|
|
|
第二版提供:
|
|
|
|
- C ABI 包装层。
|
|
- Python 调试接口。
|
|
- 高斯点结果查询接口。
|
|
- VTK 和 restart 相关接口。
|
|
|
|
## 3. 接口设计原则
|
|
|
|
接口设计遵循:
|
|
|
|
- 第一版只承诺 Fortran95 原生接口。
|
|
- 不依赖 Fortran 2003 `iso_c_binding`。
|
|
- 不依赖面向对象类型绑定。
|
|
- 调用者不直接访问 FEM 内部数据库。
|
|
- 外部数组采用调用者分配。
|
|
- 查询类接口采用两步查询模式。
|
|
- 所有核心接口通过 ierr 返回错误状态。
|
|
- warning 只写入日志,不作为 ierr 返回。
|
|
- FEM 不做单位转换,调用者必须保证单位一致。
|
|
|
|
## 4. 编号与维度约定
|
|
|
|
### 4.1 编号约定
|
|
|
|
外部接口默认使用 Abaqus 原始编号:
|
|
|
|
- node_id 为 Abaqus 输入文件中的节点编号。
|
|
- elem_id 为 Abaqus 输入文件中的单元编号。
|
|
- facet_id 为 FEM 构造并导出的稳定 facet 编号。
|
|
|
|
内部可维护连续编号,并提供原始编号和内部编号之间的查询接口。
|
|
|
|
建议接口:
|
|
|
|
```fortran
|
|
subroutine fem_get_internal_node_id(node_id_ext, node_id_int, ierr)
|
|
subroutine fem_get_internal_elem_id(elem_id_ext, elem_id_int, ierr)
|
|
subroutine fem_get_external_node_id(node_id_int, node_id_ext, ierr)
|
|
subroutine fem_get_external_elem_id(elem_id_int, elem_id_ext, ierr)
|
|
```
|
|
|
|
### 4.2 自由度约定
|
|
|
|
自由度编号:
|
|
|
|
```text
|
|
1 UX
|
|
2 UY
|
|
3 UZ
|
|
4 RX
|
|
5 RY
|
|
6 RZ
|
|
```
|
|
|
|
节点力接口:
|
|
|
|
- `force(3,nnode)` 只作用于平动自由度 UX、UY、UZ。
|
|
- 通用自由度接口使用 `node_id + dof + value`。
|
|
|
|
### 4.3 数组维度约定
|
|
|
|
接口数组采用 Fortran 列主序友好的维度:
|
|
|
|
```fortran
|
|
coord(3,nnode)
|
|
velocity(3,nnode)
|
|
acceleration(3,nnode)
|
|
normal(3,nfacet)
|
|
force(3,nnode)
|
|
shear(3,nfacet)
|
|
conn(max_face_nodes,nfacet)
|
|
x(3,max_face_nodes,nfacet)
|
|
vnod(3,max_face_nodes,nfacet)
|
|
```
|
|
|
|
所有数组下标从 1 开始。
|
|
|
|
## 5. 字符串约定
|
|
|
|
文件名:
|
|
|
|
```fortran
|
|
character(len=*), intent(in) :: filename
|
|
```
|
|
|
|
内部固定长度:
|
|
|
|
```text
|
|
NAME_LEN = 80
|
|
ELEM_TYPE_LEN = 16
|
|
```
|
|
|
|
对外返回名称时,由调用者提供固定长度字符数组。
|
|
|
|
## 6. 内存所有权
|
|
|
|
第一版采用调用者分配数组的模式。
|
|
|
|
查询类接口采用两步流程:
|
|
|
|
```text
|
|
1. 调用 fem_get_xxx_size 查询数量和最大维度
|
|
2. 调用者 allocate 所需数组
|
|
3. 调用 fem_get_xxx_data 填充数组
|
|
```
|
|
|
|
FEM 内部不返回由库内 allocate 的外部数组指针。
|
|
|
|
## 7. 库生命周期接口
|
|
|
|
标准生命周期:
|
|
|
|
```fortran
|
|
subroutine fem_initialize(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_finalize(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
调用规则:
|
|
|
|
- `fem_initialize` 必须在其他接口之前调用。
|
|
- `fem_finalize` 负责释放 FEM 内部内存。
|
|
- 多次重复初始化和释放应返回明确错误或在日志中记录状态。
|
|
|
|
## 8. 模型输入与构建接口
|
|
|
|
```fortran
|
|
subroutine fem_read_inp(filename, ierr)
|
|
character(len=*), intent(in) :: filename
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_build_model(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_compute_lumped_mass(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
推荐调用顺序:
|
|
|
|
```text
|
|
fem_initialize
|
|
fem_read_inp
|
|
fem_build_model
|
|
fem_compute_lumped_mass
|
|
```
|
|
|
|
说明:
|
|
|
|
- `fem_read_inp` 只负责读取和解析输入。
|
|
- `fem_build_model` 负责内部编号、自由度、facet 和状态变量数据库构建。
|
|
- `fem_compute_lumped_mass` 负责形成显式动力学所需集中质量。
|
|
|
|
## 9. 求解控制接口
|
|
|
|
```fortran
|
|
subroutine fem_estimate_stable_dt(dtcrit, ierr)
|
|
real(rk), intent(out) :: dtcrit
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_advance_explicit(dt, ierr)
|
|
real(rk), intent(in) :: dt
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_get_current_time(time, step, ierr)
|
|
real(rk), intent(out) :: time
|
|
integer, intent(out) :: step
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
独立程序模式:
|
|
|
|
- `femlite` 读取 inp 后控制时间循环。
|
|
- 输出由 `femlite` 按控制参数调用。
|
|
|
|
外部 SPH 驱动模式:
|
|
|
|
```text
|
|
fem_get_boundary_facets
|
|
external SPH calculation
|
|
fem_clear_sph_forces
|
|
fem_apply_sph_xxx
|
|
fem_advance_explicit(dt)
|
|
```
|
|
|
|
在 SPH 驱动模式下,时间步长由外部程序传入。
|
|
|
|
## 10. 载荷接口
|
|
|
|
### 10.1 外力清零
|
|
|
|
```fortran
|
|
subroutine fem_clear_external_forces(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_clear_sph_forces(ierr)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
SPH 耦合规则:
|
|
|
|
- 外部程序每个时间步显式调用 `fem_clear_sph_forces`。
|
|
- 然后调用 SPH 载荷施加接口。
|
|
- 最后调用 `fem_advance_explicit(dt)`。
|
|
- `fem_advance_explicit` 不应自动清除刚传入的 `fsph`。
|
|
|
|
### 10.2 节点力
|
|
|
|
```fortran
|
|
subroutine fem_apply_nodal_force(nnode_in, node_id, force, ierr)
|
|
integer, intent(in) :: nnode_in
|
|
integer, intent(in) :: node_id(nnode_in)
|
|
real(rk), intent(in) :: force(3,nnode_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- `node_id` 使用 Abaqus 原始节点编号。
|
|
- `force` 使用全局坐标。
|
|
- 只作用于平动自由度。
|
|
|
|
### 10.3 通用自由度载荷
|
|
|
|
```fortran
|
|
subroutine fem_apply_dof_force(nitem, node_id, dof, value, ierr)
|
|
integer, intent(in) :: nitem
|
|
integer, intent(in) :: node_id(nitem)
|
|
integer, intent(in) :: dof(nitem)
|
|
real(rk), intent(in) :: value(nitem)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- `dof` 采用 1 到 6 的自由度编号。
|
|
- 非激活自由度应返回错误。
|
|
|
|
## 11. SPH-FEM 耦合接口
|
|
|
|
### 11.1 facet 数量查询
|
|
|
|
```fortran
|
|
subroutine fem_get_boundary_facet_count(nfacet, max_face_nodes, ierr)
|
|
integer, intent(out) :: nfacet
|
|
integer, intent(out) :: max_face_nodes
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
### 11.2 facet 数据查询
|
|
|
|
```fortran
|
|
subroutine fem_get_boundary_facets(nfacet_in, max_face_nodes_in, &
|
|
facet_id, elem_id, face_id, facet_nnode, &
|
|
facet_conn, x, vnod, normal, area, ierr)
|
|
integer, intent(in) :: nfacet_in
|
|
integer, intent(in) :: max_face_nodes_in
|
|
integer, intent(out) :: facet_id(nfacet_in)
|
|
integer, intent(out) :: elem_id(nfacet_in)
|
|
integer, intent(out) :: face_id(nfacet_in)
|
|
integer, intent(out) :: facet_nnode(nfacet_in)
|
|
integer, intent(out) :: facet_conn(max_face_nodes_in,nfacet_in)
|
|
real(rk), intent(out) :: x(3,max_face_nodes_in,nfacet_in)
|
|
real(rk), intent(out) :: vnod(3,max_face_nodes_in,nfacet_in)
|
|
real(rk), intent(out) :: normal(3,nfacet_in)
|
|
real(rk), intent(out) :: area(nfacet_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- `elem_id` 使用 Abaqus 原始单元编号。
|
|
- `facet_conn` 使用 Abaqus 原始节点编号。
|
|
- `normal` 为固体外法向。
|
|
- 删除单元对应 facet 不应作为有效 facet 导出。
|
|
- 外部程序接受 `x(3,max_face_nodes,nfacet)` 和 `vnod(3,max_face_nodes,nfacet)` 三维数组。
|
|
|
|
### 11.3 SPH 节点力输入
|
|
|
|
```fortran
|
|
subroutine fem_apply_sph_nodal_forces(nnode_in, node_id, force, ierr)
|
|
integer, intent(in) :: nnode_in
|
|
integer, intent(in) :: node_id(nnode_in)
|
|
real(rk), intent(in) :: force(3,nnode_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
### 11.4 SPH facet 压力输入
|
|
|
|
```fortran
|
|
subroutine fem_apply_sph_facet_pressure(nfacet_in, facet_id, pressure, ierr)
|
|
integer, intent(in) :: nfacet_in
|
|
integer, intent(in) :: facet_id(nfacet_in)
|
|
real(rk), intent(in) :: pressure(nfacet_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
压力约定:
|
|
|
|
```text
|
|
p > 0 means compression
|
|
t = -p n
|
|
```
|
|
|
|
### 11.5 SPH facet 压力与剪切输入
|
|
|
|
```fortran
|
|
subroutine fem_apply_sph_facet_tractions(nfacet_in, facet_id, pressure, shear, ierr)
|
|
integer, intent(in) :: nfacet_in
|
|
integer, intent(in) :: facet_id(nfacet_in)
|
|
real(rk), intent(in) :: pressure(nfacet_in)
|
|
real(rk), intent(in) :: shear(3,nfacet_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
剪切约定:
|
|
|
|
- `shear(3,nfacet)` 为全局坐标下的剪切牵引向量。
|
|
- FEM 将 `-p n + shear` 映射为 facet 等效节点力。
|
|
|
|
## 12. 结果查询接口
|
|
|
|
### 12.1 节点运动学
|
|
|
|
```fortran
|
|
subroutine fem_get_nodal_kinematics(nnode_in, node_id, uout, vout, aout, ierr)
|
|
integer, intent(in) :: nnode_in
|
|
integer, intent(in) :: node_id(nnode_in)
|
|
real(rk), intent(out) :: uout(3,nnode_in)
|
|
real(rk), intent(out) :: vout(3,nnode_in)
|
|
real(rk), intent(out) :: aout(3,nnode_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- 第一版只返回平动位移、速度、加速度。
|
|
- 壳节点转角查询可在第二版扩展。
|
|
|
|
### 12.2 单元状态
|
|
|
|
```fortran
|
|
subroutine fem_get_element_status(nelem_in, elem_id, status, ierr)
|
|
integer, intent(in) :: nelem_in
|
|
integer, intent(in) :: elem_id(nelem_in)
|
|
integer, intent(out) :: status(nelem_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
状态约定:
|
|
|
|
```text
|
|
0 active
|
|
1 deleted
|
|
2 inactive by input
|
|
```
|
|
|
|
### 12.3 单元平均结果
|
|
|
|
```fortran
|
|
subroutine fem_get_element_average_state(nelem_in, elem_id, stress, strain, &
|
|
plastic_strain, eqps, damage, ierr)
|
|
integer, intent(in) :: nelem_in
|
|
integer, intent(in) :: elem_id(nelem_in)
|
|
real(rk), intent(out) :: stress(6,nelem_in)
|
|
real(rk), intent(out) :: strain(6,nelem_in)
|
|
real(rk), intent(out) :: plastic_strain(6,nelem_in)
|
|
real(rk), intent(out) :: eqps(nelem_in)
|
|
real(rk), intent(out) :: damage(nelem_in)
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- 第一版返回单元平均值。
|
|
- 高斯点查询作为第二版高级接口实现。
|
|
|
|
## 13. 输出控制接口
|
|
|
|
```fortran
|
|
subroutine fem_set_output_directory(path, ierr)
|
|
character(len=*), intent(in) :: path
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_set_output_interval(interval, ierr)
|
|
integer, intent(in) :: interval
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
|
|
subroutine fem_write_output(step, time, ierr)
|
|
integer, intent(in) :: step
|
|
real(rk), intent(in) :: time
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
说明:
|
|
|
|
- 第一版输出 CSV 和日志。
|
|
- 第二版扩展 VTK 和 restart。
|
|
- 外部程序可关闭自动输出并显式调用 `fem_write_output`。
|
|
|
|
## 14. 版本与错误查询接口
|
|
|
|
### 14.1 版本查询
|
|
|
|
```fortran
|
|
subroutine fem_get_version(major, minor, patch, ierr)
|
|
integer, intent(out) :: major
|
|
integer, intent(out) :: minor
|
|
integer, intent(out) :: patch
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
### 14.2 错误查询
|
|
|
|
```fortran
|
|
subroutine fem_get_last_error(code, message, ierr)
|
|
integer, intent(out) :: code
|
|
character(len=*), intent(out) :: message
|
|
integer, intent(out) :: ierr
|
|
end subroutine
|
|
```
|
|
|
|
错误返回规则:
|
|
|
|
- `ierr = 0` 表示成功。
|
|
- `ierr > 0` 表示错误。
|
|
- warning 只写日志,不作为 ierr 返回。
|
|
- 发生错误后,`fem_get_last_error` 可返回最近一次错误码和错误信息。
|
|
|
|
错误码分组:
|
|
|
|
```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
|
|
```
|
|
|
|
## 15. 单位制约定
|
|
|
|
FemLite 不进行单位转换。
|
|
|
|
调用者必须保证以下数据采用一致单位制:
|
|
|
|
- Abaqus inp 几何尺寸
|
|
- 材料密度
|
|
- 弹性和塑性参数
|
|
- 时间步长
|
|
- 节点力
|
|
- 压力
|
|
- 剪切牵引
|
|
- SPH 传入数据
|
|
- 输出解释
|
|
|
|
日志中应记录单位制不检查的提示。
|
|
|
|
## 16. 第一版典型调用流程
|
|
|
|
### 16.1 独立 FEM 程序流程
|
|
|
|
```text
|
|
fem_initialize
|
|
fem_read_inp
|
|
fem_build_model
|
|
fem_compute_lumped_mass
|
|
loop:
|
|
fem_estimate_stable_dt
|
|
fem_advance_explicit
|
|
fem_write_output
|
|
fem_finalize
|
|
```
|
|
|
|
### 16.2 SPH 驱动流程
|
|
|
|
```text
|
|
fem_initialize
|
|
fem_read_inp
|
|
fem_build_model
|
|
fem_compute_lumped_mass
|
|
loop:
|
|
fem_get_boundary_facet_count
|
|
allocate external arrays if needed
|
|
fem_get_boundary_facets
|
|
SPH computes pressure, shear or nodal force
|
|
fem_clear_sph_forces
|
|
fem_apply_sph_facet_pressure / fem_apply_sph_facet_tractions / fem_apply_sph_nodal_forces
|
|
fem_advance_explicit(dt)
|
|
fem_get_nodal_kinematics if needed
|
|
fem_finalize
|
|
```
|
|
|
|
## 17. C/C++/Python 包装层规划
|
|
|
|
第二版提供:
|
|
|
|
- C ABI 包装层。
|
|
- Python 调试接口。
|
|
- 面向 C/C++ 的扁平化数组接口。
|
|
|
|
包装层原则:
|
|
|
|
- 不改变 Fortran95 原生接口的物理含义。
|
|
- 不改变压力、剪切、编号和单位制约定。
|
|
- 对三维数组接口提供扁平化视图。
|
|
- 包装层单独测试,不污染 FEM 核心。
|
|
|