Files
FemLite/docs/05_interface_control_document.md
T
2026-06-23 20:11:55 +08:00

730 lines
19 KiB
Markdown
Raw 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 Interface Control Document
文档状态:接口基线草稿
适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序
## 1. 文档目的
本文档定义 FEM 核心库对外暴露的调用接口、数组维度、编号规则、内存所有权、错误码、单位制和 SPH-FEM 耦合接口。
本文档是外部程序,特别是 SPH 程序,与 FemLite 进行联调时的接口合同。
## 2. 接口范围
第一版提供:
- Fortran95 原生接口。
- 显式瞬态动力学推进接口。
- Abaqus inp 模型读取接口。
- 外部 SPH 驱动接口。
- 节点力、facet 压力、facet 压力加剪切力接口。
- 节点运动学和单元平均结果查询接口。
- CSV 输出控制接口。
第二版提供:
- C ABI 包装层。
- Python 调试接口。
- 高斯点结果查询接口。
- VTK 和 restart 相关接口。
第三版提供:
- 线性静力求解接口。
- 非线性静力求解接口。
- 隐式 Newmark 动力学推进接口。
- 静力收敛历史查询接口。
- 节点反力查询接口。
- 接触状态、接触力和接触功查询接口。
## 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 驱动模式下,时间步长由外部程序传入。
第三版静力和隐式动力接口:
```fortran
subroutine fem_solve_static_linear(max_iter, tol, iter, res_norm, ierr)
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_solve_static_nonlinear(max_increment, max_iter, tol, &
iter, res_norm, ierr)
integer, intent(in) :: max_increment
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_advance_implicit_newmark(dt, max_iter, tol, iter, res_norm, ierr)
real(rk), intent(in) :: dt
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_run_implicit_newmark(max_iter, tol, iter_total, res_norm, ierr)
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter_total
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_advance_newmark_nonlinear(dt, max_iter, tol, iter, res_norm, ierr)
real(rk), intent(in) :: dt
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_run_newmark_nonlinear(max_iter, tol, iter_total, res_norm, ierr)
integer, intent(in) :: max_iter
real(rk), intent(in) :: tol
integer, intent(out) :: iter_total
real(rk), intent(out) :: res_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_set_rayleigh_damping(alpha_mass, beta_stiffness, ierr)
real(rk), intent(in) :: alpha_mass
real(rk), intent(in) :: beta_stiffness
integer, intent(out) :: ierr
end subroutine
```
说明:
- 静力接口不要求调用 `fem_compute_lumped_mass`。
- 隐式动力接口可复用质量矩阵、阻尼矩阵、CSR 矩阵和边界条件数据库。
- `fem_solve_static_linear` 与命令行 `--static-linear` 对应。
- `--implicit-linear` 保留为 `--static-linear` 的兼容别名。
- `fem_run_implicit_newmark` 使用输入文件中的时间控制运行到 `time_end`。
- `fem_run_newmark_nonlinear` 使用输入文件中的时间控制运行到 `time_end`,对应命令行 `--implicit-newmark-nonlinear`。
- `fem_set_rayleigh_damping` 设置 `C = alpha_mass M + beta_stiffness K`。
- 非线性 Newmark Fortran95 接口当前接入实体 J2 算法切线、壳膜内/弯曲/剪切 J2/J2_JC section tangent、trial/restore/commit、线搜索、可选步长缩减、Robin/MPC 切线、刚性平面 penalty contact 切线和面-面 contact pair 切线;C ABI 和 Python 调试接口跟随扩展。
## 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
```
说明:
- 第一版返回单元平均值。
- 高斯点查询作为第二版高级接口实现。
### 12.4 节点反力
第三版提供节点反力查询:
```fortran
subroutine fem_get_nodal_reactions(nnode_in, node_id, reaction, ierr)
integer, intent(in) :: nnode_in
integer, intent(in) :: node_id(nnode_in)
real(rk), intent(out) :: reaction(6,nnode_in)
integer, intent(out) :: ierr
end subroutine
```
说明:
- `reaction(1:3,:)` 为平动反力。
- `reaction(4:6,:)` 为转动反力或力矩。
- 实体单元未激活转动自由度时,对应分量返回 0。
### 12.5 静力收敛历史
第三版提供当前或最近一次静力/隐式求解收敛状态查询:
```fortran
subroutine fem_get_convergence_status(increment, iteration, residual_norm, &
correction_norm, converged, ierr)
integer, intent(out) :: increment
integer, intent(out) :: iteration
real(rk), intent(out) :: residual_norm
real(rk), intent(out) :: correction_norm
logical, intent(out) :: converged
integer, intent(out) :: ierr
end subroutine
```
### 12.6 接触状态
第三版提供接触结果查询接口:
```fortran
subroutine fem_get_contact_summary(active_count, work_step, work_total, &
max_penetration, force_norm, ierr)
integer, intent(out) :: active_count
real(rk), intent(out) :: work_step
real(rk), intent(out) :: work_total
real(rk), intent(out) :: max_penetration
real(rk), intent(out) :: force_norm
integer, intent(out) :: ierr
end subroutine
```
第三版当前 contact pair 采用 Fortran95 核心数据库接口配置:
```fortran
subroutine database_allocate_contact_pair(num_pairs, ierr)
integer, intent(in) :: num_pairs
integer, intent(out) :: ierr
end subroutine
```
配置数组包括:
- `contact_pair_slave(pair)`:slave 接触目标,可为 elset 名称、element id 字符串或 `ALL`。
- `contact_pair_master(pair)`:master 接触目标,可为 elset 名称、element id 字符串或 `ALL`。
- `contact_pair_penalty(pair)`:法向 penalty 刚度,必须大于 0。
- `contact_pair_damping(pair)`:法向阻尼,必须非负。
- `contact_pair_search(pair)`:搜索距离,0 表示只按 facet 等效半径过滤。
- `contact_pair_friction(pair)`:Coulomb 摩擦系数,必须非负;0 表示无摩擦。
当前 contact pair 支持投影裁剪面积积分、多 master facet 面积上限修正、Coulomb 摩擦、均匀空间网格候选搜索和 facet 空间 broad-phase 精筛。
接触统计包括:
- `contact_active_count`:最近一次接触力评估中的激活贡献数。
- `contact_work_step`:最近一次接触力评估的接触功估计。
- `contact_work_total`:累计接触功估计。
- `contact_max_penetration`:最近一次接触力评估的最大穿透量。
- `contact_force_norm`:最近一次接触力评估的接触力范数累加。
逐 contact pair 统计保存在 `contact_pair_active/work/max_penetration/force_norm` 数组中,并写入 `contact_step_xxxxx.csv`。
## 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 核心。
第三版包装层扩展:
- C ABI 暴露静力求解、反力查询和收敛状态查询。
- Python 调试接口支持运行静力算例并导出关键位移、反力和残差历史。