# 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 动力学推进接口。 - 静力收敛历史查询接口。 - 节点反力查询接口。 - 接触状态、接触力和接触功查询接口。 第四版扩展: - node-based surface、analytical rigid plane surface 和 contact property 查询/输入子集。 - contact pair active-set、gap residual 和 augmented penalty 诊断接口。 - contact pair 搜索统计接口,用于 V4.4 搜索/并行性能验收。 ## 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 ``` 第四版追加接触诊断查询接口,不改变旧 summary 接口: ```fortran subroutine fem_get_contact_diagnostics(active_pair_count, & activated_pair_count, & maintained_pair_count, & released_pair_count, & max_gap_residual, max_aug_lambda, ierr) integer, intent(out) :: active_pair_count integer, intent(out) :: activated_pair_count integer, intent(out) :: maintained_pair_count integer, intent(out) :: released_pair_count real(rk), intent(out) :: max_gap_residual real(rk), intent(out) :: max_aug_lambda integer, intent(out) :: ierr end subroutine ``` - `active_pair_count`:最近一次接触力评估中至少有一个激活贡献的 contact pair 数。 - `activated_pair_count`:本次由 open 切换为 active 的 pair 数。 - `maintained_pair_count`:本次保持 active 的 pair 数。 - `released_pair_count`:本次由 active 切换为 open 的 pair 数。 - `max_gap_residual`:逐 pair gap 残差最大值,当前定义为最近一次力评估中的最大穿透量。 - `max_aug_lambda`:逐 pair augmented penalty 法向乘子最大值。 第四版 V4.3 起步追加摩擦输出查询接口: ```fortran subroutine fem_get_contact_friction(work_step, work_total, & max_accumulated_slip, ierr) real(rk), intent(out) :: work_step real(rk), intent(out) :: work_total real(rk), intent(out) :: max_accumulated_slip integer, intent(out) :: ierr end subroutine ``` - `work_step`:最近一次接触评估中的正摩擦耗散功估计。 - `work_total`:累计正摩擦耗散功估计。 - `max_accumulated_slip`:逐 contact pair 累计滑移最大值。 V4.3 进一步追加 mortar 积分点级历史统计接口: ```fortran subroutine fem_get_contact_hist_stats(slot_count, max_slot_slip, & max_slot_work, max_tangent_force, ierr) integer, intent(out) :: slot_count real(rk), intent(out) :: max_slot_slip real(rk), intent(out) :: max_slot_work real(rk), intent(out) :: max_tangent_force integer, intent(out) :: ierr end subroutine ``` - `slot_count`:当前模型内已创建的 mortar 积分点摩擦历史槽数量。 - `max_slot_slip`:单个历史槽的最大累计滑移。 - `max_slot_work`:单个历史槽的最大累计摩擦功。 - `max_tangent_force`:单个历史槽中历史切向力模长最大值。 - 当前历史槽键为 `pair + slave element/face + master element/face + point_id`,其中 `point_id` 是该 slave/master facet overlap 内的 mortar 积分点序号。 V4.4 起步追加 contact pair 搜索统计接口: ```fortran subroutine fem_get_contact_search_stats(facet_count, master_count, & broad_count, active_count, & bvh_node_count, ierr) integer, intent(out) :: facet_count integer, intent(out) :: master_count integer, intent(out) :: broad_count integer, intent(out) :: active_count integer, intent(out) :: bvh_node_count integer, intent(out) :: ierr end subroutine ``` - `facet_count`:最近一次接触力评估中累计处理的 boundary facet 数;多 contact pair 时按 pair 评估次数累计。 - `master_count`:最近一次接触力评估中累计识别的 master facet 数。 - `broad_count`:搜索第一遍候选评估次数;全搜索、uniform grid 和 BVH 路径均记录。 - `active_count`:候选评估中判定为接触激活的次数。 - `bvh_node_count`:最近一次接触力评估累计构建的 BVH 节点数;非 BVH 路径为 0。 V4.4 追加接触性能计时接口,时间单位为秒,口径为 Fortran `cpu_time`: ```fortran subroutine fem_get_contact_perf_stats(search_time, force_time, & tangent_time, ierr) real(rk), intent(out) :: search_time real(rk), intent(out) :: force_time real(rk), intent(out) :: tangent_time integer, intent(out) :: ierr end subroutine ``` - `search_time`:最近一次接触状态周期内 contact pair 搜索准备和第一遍候选评估累计 CPU 时间。 - `force_time`:最近一次 `contact_apply_plane_forces` 总 CPU 时间。 - `tangent_time`:最近一次接触切线装配累计 CPU 时间;若未调用切线装配则为 0。 V4.4 追加 BVH 局部候选缓存统计接口: ```fortran subroutine fem_get_contact_cache_stats(used_count, overflow_count, ierr) integer, intent(out) :: used_count integer, intent(out) :: overflow_count integer, intent(out) :: ierr end subroutine ``` - `used_count`:最近一次接触力评估中使用 BVH active 候选缓存施力的 slave facet 数。 - `overflow_count`:active 候选数超过固定缓存容量并回退到旧 BVH 遍历施力路径的 slave facet 数。 Restart 说明: - restart 文件格式从 V4.3 起写出为 `FEMLITE_RESTART 2`。 - v2 在 DOF、单元状态和高斯点状态之后追加 `CONTACT_HISTORY` 段,用于保存 mortar 积分点摩擦历史槽。 - 读入端兼容旧的 v1 文件;若旧文件没有 `CONTACT_HISTORY` 段,则读入时清空当前接触历史。 第三版当前 contact pair 支持两种配置方式: 1. INP 文件中的 FemLite 子集: ```inp *CONTACT PAIR, SLAVE=slave_target, MASTER=master_target, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION=value, FRICTION_REGULARIZATION=value, AUGMENT=value ``` - header 式写法中,`SLAVE`、`MASTER` 和 `PENALTY` 为必填参数。 - `DAMPING`、`SEARCH`、`FRICTION`、`FRICTION_REGULARIZATION` 和 `AUGMENT` 为可选参数,未给出时默认为 0。 - `SLAVE` 和 `MASTER` 可为 surface 名称、elset 名称、element id 字符串或 `ALL`。 - 解析器接受大小写混用、参数等号两侧空格以及单/双引号包裹的名称。 也支持 Abaqus 常见的数据行式 contact pair 子集: ```inp *SURFACE, NAME=slave_surface, TYPE=ELEMENT slave_elset_or_element, face_label *SURFACE, NAME=master_surface, TYPE=ELEMENT master_elset_or_element, face_label *CONTACT PAIR, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION=value, FRICTION_REGULARIZATION=value slave_surface, master_surface ``` - `*SURFACE` 当前支持 `TYPE=ELEMENT`、`TYPE=NODE` 和 analytical rigid `PLANE` 子集;`TYPE` 可省略,缺省为 `ELEMENT`。 - `OP` 可省略或写为 `ADD` / `NEW`:省略时按 `ADD` 处理;同名 surface 的 `ADD` 会追加数据行,`NEW` 会清除该 surface 已有数据行后重新定义。 - surface 可包含多条数据行;每行第一个字段可为 elset 名称或 element id,二者可在同一 surface 中混用。 - 第二字段 `face_label` 可省略;省略、`ALL` 或 `EXTERIOR` 表示该 target 的所有候选 facet 均可匹配。 - 当前支持 `S1`、`S2` 等面号标签,以及 `F1`、`FACE1` 等等价写法;壳单元支持 `SPOS`/`SNEG` 匹配其当前单一 shell facet。 - `SPOS`/`SNEG` 已参与接触计算语义:master surface 的 `SNEG` 会翻转有效接触法向;slave surface 若显式给出 `SPOS`/`SNEG`,候选接触只接受该侧法向朝向 master facet 的组合。 - 更完整的 Abaqus surface 变体、曲线/球/柱 analytical surface 和更复杂的数据行变体仍列入后续版本。 - 数据行式 `*CONTACT PAIR` 的 header 中仍要求 `PENALTY`,slave/master 从下一行读取。 2. Fortran95 核心数据库接口: ```fortran subroutine database_allocate_surfaces(num_surfaces, num_items, ierr) integer, intent(in) :: num_surfaces integer, intent(in) :: num_items integer, intent(out) :: ierr end subroutine subroutine database_allocate_contact_pair(num_pairs, ierr) integer, intent(in) :: num_pairs integer, intent(out) :: ierr end subroutine ``` 配置数组包括: - `surface_name(surface)`:surface 名称。 - `surface_start(surface)`、`surface_count(surface)`:surface 数据行在 item 表中的起始位置和数量;当同名 surface 经过 `OP=ADD` 非连续追加时,`surface_count` 表示有效 item 数量。 - `surface_owner(item)`:surface item 所属 surface 编号;为 0 表示该 item 已被 `OP=NEW` 覆盖失效。 - `surface_target(item)`:surface 数据行的 elset 名称或 element id 字符串。 - `surface_face(item)`:surface 数据行的 face label,用于实际接触候选 facet 筛选。 - `contact_pair_slave(pair)`:slave 接触目标,可为 surface 名称、elset 名称、element id 字符串或 `ALL`。 - `contact_pair_master(pair)`:master 接触目标,可为 surface 名称、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_friction_reg(pair)`:摩擦正则化滑移尺度,必须非负;0 表示经典 Coulomb 截断。 - `contact_pair_aug_factor(pair)`:augmented penalty 更新系数,必须非负;0 表示仅使用 penalty。 当前 contact pair 支持投影裁剪 mortar 形函数积分、多 master facet 面积上限修正、Coulomb 粘滑历史、均匀空间网格候选搜索、OpenMP BVH 宽相搜索和 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_pair_status/activation_count/release_count/gap_residual/aug_lambda`、`contact_pair_stick_count/slip_count/slip/tangent_force`、`contact_pair_friction_work/fric_work_total` 数组中,并写入 `contact_XXXXXXXX.csv`。V4.4 起,contact CSV 的 `SUMMARY` 行写出 `search_facets/search_masters/search_candidates/search_active/search_bvh_nodes` 全局搜索统计、`search_cache_used/search_cache_overflow` 缓存统计,以及 `search_cpu_time/contact_force_cpu_time/contact_tangent_cpu_time` 计时统计;逐 `PAIR` 行通过内部 Fortran 查询 `contact_get_pair_stats` 写出对应接触对的搜索、缓存和计时统计。当前 C ABI 只暴露全局 search/perf/cache 统计,pair 级查询先作为 Fortran 内部接口和 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 调试接口支持运行静力算例并导出关键位移、反力和残差历史。 第四版包装层扩展: - C ABI 追加 `femlite_get_contact_diagnostics`,返回 active pair 数、activated/maintained/released pair 数、最大 gap residual 和最大 augmented penalty 乘子。 - C ABI 追加 `femlite_get_contact_friction_summary`,返回摩擦 step/total 功和最大累计滑移。 - C ABI 追加 `femlite_get_contact_history_stats`,返回 mortar 积分点摩擦历史槽数量、单槽最大累计滑移、单槽最大累计摩擦功和单槽最大切向力模长。 - C ABI 追加 `femlite_get_contact_search_stats`,返回 contact pair 搜索 facet/master/candidate/active/BVH 节点统计。 - C ABI 追加 `femlite_get_contact_perf_stats`,返回 contact search/force/tangent CPU 时间统计。 - C ABI 追加 `femlite_get_contact_cache_stats`,返回 BVH 候选缓存使用和溢出统计。 - 上述函数只追加新符号,不改变 `femlite_get_contact_summary` 的签名和含义。