Files
FemLite/docs/05_interface_control_document.md
T
shenw 2b7962eb96
FemLite CI / build-test (push) Has been cancelled
Release FemLite 0.5.3
2026-07-01 18:39:18 +08:00

1483 lines
59 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 动力学推进接口。
- 静力收敛历史查询接口。
- 节点反力查询接口。
- 接触状态、接触力和接触功查询接口。
第四版扩展:
- node-based surface、analytical rigid plane surface 和 contact property 查询/输入子集。
- contact pair active-set、gap residual 和 augmented penalty 诊断接口。
- contact pair 搜索统计接口,用于 V4.4 搜索/并行性能验收。
- 线性求解器设置和最近一次线性求解统计接口,用于 V4.6 内部求解路径切换验收。
- 壳 drilling/S3 剪切锁定控制和稳定性统计接口,用于 V4.7 壳基准验收。
## 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` 负责形成显式动力学所需集中质量。
### 8.1 Mohr-Coulomb 材料输入子集
第五版当前支持 Abaqus 风格材料块中的 `*MOHR COULOMB` 子集。该关键字必须位于
`*MATERIAL` 块内,且材料仍需通过 `*ELASTIC` 提供弹性模量和泊松比。数据行格式为:
```inp
*MOHR COULOMB
friction_angle_deg, cohesion, dilation_angle_deg, tensile_strength
residual_friction_angle_deg, residual_cohesion, residual_dilation_angle_deg, reduction_factor
```
约定:
- 角度以 degree 输入,内部转换为 radian。
- `friction_angle_deg` 必须在 `(0, 90)` 内。
- `cohesion`、`tensile_strength` 和 `residual_cohesion` 必须非负。
- `dilation_angle_deg` 必须在 `[0, friction_angle_deg]` 内。
- `reduction_factor < 1` 按 1 处理;大于 1 时用于强度折减材料参数。
- 残余摩擦角、残余黏聚力和残余膨胀角作为折减下限。
解析后数据库字段包括 `mat_mc_phi`、`mat_mc_cohesion`、`mat_mc_dilation`、
`mat_mc_tension`、`mat_mc_res_phi`、`mat_mc_res_cohesion`、
`mat_mc_res_dilation` 和 `mat_mc_reduction`。材料模型名称写入
`mat_plastic_model='MOHR_COULOMB'`,由材料分发层进入 Mohr-Coulomb 更新和切线路径。
### 8.2 非线性 continuation 方法选择
第五版 0.5.2 开始支持 FemLite 扩展关键字:
```inp
*NONLINEAR CONTINUATION, METHOD=value, TARGET_NEWTON=n, GROWTH=g, SHRINK=s,
TRUST_RADIUS=r, TRUST_MIN_RADIUS=rmin, TRUST_MAX_RADIUS=rmax,
TRUST_GROWTH=tg, TRUST_SHRINK=ts, TRUST_ACCEPT_RATIO=ra, TRUST_GOOD_RATIO=rg,
ARC_LENGTH=dl, ARC_LOAD_SCALE=s_lambda,
MC_MIN_SUBSTEPS=nmin, MC_MAX_SUBSTEPS=nmax, MC_TARGET_STRAIN=eps,
MC_YIELD_TOL=tol, MC_PLASTIC_LIMIT=dpmax, SHELL_GEOMETRIC=LINEAR|FINITE_STRAIN
```
该关键字为 header-only 控制项,不需要数据行。若省略该关键字,
`nonlinear_continuation_method` 默认取 `1`。`METHOD` 可使用数字或符号名:
| 数字 | 符号名 | 当前接口含义 |
|---:|---|---|
| 1 | `TWO_STAGE_LOAD_STRENGTH` | 默认路线;先收敛完整外载,再固定外载推进强度折减因子。 |
| 2 | `ADAPTIVE_TARGET_NEWTON` | 目标 Newton 迭代数自适应步长控制。 |
| 3 | `TRUST_REGION_DAMPED_NEWTON` | trust-region / damping Newton 控制。 |
| 4 | `ARC_LENGTH_OR_DISPLACEMENT_CONTROL` | 载荷型问题使用 Riks/arc-length 增广方程;非零 prescribed-displacement 问题使用直接位移控制 accepted-path 记录;两类控制量均不存在时报错。 |
| 5 | `MC_SUBSTEPPING_SEMISMOOTH` | Mohr-Coulomb substepping / semismooth 活动集路线。 |
解析器同时接受常用短名或连字符形式,例如 `LOAD_STRENGTH`、
`TARGET_NEWTON`、`TRUST_REGION`、`ARC_LENGTH`、`DISPLACEMENT_CONTROL` 和
`SUBSTEPPING_SEMISMOOTH`。非法数字或未知名称在输入读取阶段报错,且不修改已存在的
`nonlinear_continuation_method`。
可选控制项:
| 参数 | 适用方法 | 合法范围 | 含义 |
|---|---|---|---|
| `TARGET_NEWTON` 或 `TARGET` | 2 | 正整数 | 目标 Newton 迭代数。 |
| `GROWTH` 或 `GROWTH_FACTOR` | 2 | `> 1` | 低迭代接受步后的下一步增长倍率。 |
| `SHRINK` 或 `SHRINK_FACTOR` | 2 | `(0, 1)` | 高迭代、cutback 或失败后的下一步收缩倍率。 |
| `TRUST_RADIUS` 或 `RADIUS` | 3 | `>= 0` | 初始/current trust radius;0 表示由首个修正自动初始化。 |
| `TRUST_MIN_RADIUS` 或 `MIN_RADIUS` | 3 | `> 0` | trust radius 下限。 |
| `TRUST_MAX_RADIUS` 或 `MAX_RADIUS` | 3 | `0` 或 `>= TRUST_MIN_RADIUS` | trust radius 上限;0 表示不显式封顶。 |
| `TRUST_GROWTH` 或 `TRUST_GROWTH_FACTOR` | 3 | `> 1` | 高质量残差下降后的半径增长倍率。 |
| `TRUST_SHRINK` 或 `TRUST_SHRINK_FACTOR` | 3 | `(0, 1)` | 阻尼、拒绝或低质量下降后的半径收缩倍率。 |
| `TRUST_ACCEPT_RATIO` 或 `MERIT_ACCEPT_RATIO` | 3 | `[0, 1)` | 小于该 residual merit 下降率时收缩半径。 |
| `TRUST_GOOD_RATIO` 或 `MERIT_GOOD_RATIO` | 3 | `(0, 1]` 且 `>= TRUST_ACCEPT_RATIO` | 达到该下降率且无阻尼/拒绝时增长半径。 |
| `ARC_LENGTH` 或 `ARC_RADIUS` | 4 | `>= 0` | Riks 球面约束半径;`0` 表示使用当前静力增量长度。 |
| `ARC_LOAD_SCALE`、`RIKS_LOAD_SCALE` 或 `LOAD_SCALE` | 4 | `> 0` | `load_factor` 在弧长约束中的缩放,默认 `1`。 |
| `MC_MIN_SUBSTEPS` 或 `MIN_SUBSTEPS` | 5 | 正整数 | Mohr-Coulomb 局部积分最小子步数,默认 `1`。 |
| `MC_MAX_SUBSTEPS` 或 `MAX_SUBSTEPS` | 5 | 正整数且 `>= MC_MIN_SUBSTEPS` | Mohr-Coulomb 局部积分最大子步数,默认 `64`。 |
| `MC_TARGET_STRAIN` 或 `TARGET_STRAIN` | 5 | `> 0` | 按最大应变增量选择子步数的目标应变尺度,默认 `2.5e-3`。 |
| `MC_YIELD_TOL`、`MC_YIELD_TOLERANCE` 或 `YIELD_TOL` | 5 | `>= 0` | 子步返回后正屈服残差触发 limited 状态的容差,默认 `1.0e-7`。 |
| `MC_PLASTIC_LIMIT` 或 `PLASTIC_LIMIT` | 5 | `> 0` | 单子步塑性增量触发 limited 状态的上限,默认 `5.0e-2`。 |
| `SHELL_GEOMETRIC` | S4 nonlinear shell | `LINEAR` 或 `FINITE_STRAIN` | `LINEAR` 保持现有线性壳路径;`FINITE_STRAIN` 请求 V5.11 Abaqus-style finite-membrane-strain S4 生产路线,S3/S6/S8 请求必须清晰报 unsupported。 |
所有非法控制值在输入读取阶段报错,且不修改此前有效的 continuation 控制状态。
旧布尔写法 `SHELL_GEOMETRIC=YES/NO` 以及旧名称 `GEOMETRIC_SHELL`、
`COROTATIONAL_SHELL`、`S4_COROTATIONAL` 已从稳定接口中移除;当前解析层仅将其作为
输入错误拒绝,不提供兼容求解路径。
当前已完成生产输入接口、默认值、非法值校验和诊断记录。方法 1 已在
strengthReduction nonlinear chain/cloud 工作流中接入两阶段 load-strength
continuation,并通过 `static_ramp_load` 让第二阶段在固定外载下使用伪时间推进材料
强度折减因子;方法 2 已接入生产目标 Newton 步长控制;方法 3 已接入生产
trust-region damped Newton 控制;方法 4 已接入载荷型 Riks/arc-length 增广方程、
直接位移控制 accepted increment 路径记录、无控制量时的显式 solver error、
Fortran API 查询和
`continuation_path.csv` 输出;方法 5 已接入生产
Mohr-Coulomb 材料点子步和活动集诊断,并在 strengthReduction nonlinear
chain/cloud/progress 输出中汇总结构级 MC 子步和分支状态。0.75 m
临界失稳 cloud 长跑移入后续研究验证,不作为 V5 接口交付项。方法 4
的真实非单调结构路径和方法 5 的材料点/结构级诊断按
`docs/v5_development_plan.md` 的 NC-4 至 NC-5 记录。
当 `METHOD=MC_SUBSTEPPING_SEMISMOOTH` 时,材料点状态变量额外约定:
```text
statev(27) accepted substeps
statev(28) requested substeps
statev(29) driver status, 0 OK and 1 limited
statev(30) branch mask, elastic=1, shear=2, tension=4, mixed=8
statev(31) max positive yield residual
statev(32) max plastic increment
```
strengthReduction nonlinear chain/cloud/progress CSV 的 continuation 诊断字段包括:
```text
continuation_method,target_dt,actual_dt,next_dt,adapt_adjust,
trust_radius,next_trust_radius,damping,merit_ratio,trust_rejections,trust_adjust,
mc_points,mc_updated_points,mc_substeps,mc_requested_substeps,mc_limited_points,
mc_branch_mask,mc_max_yield,mc_max_plastic_step
```
summary CSV 还记录 `target_newton`、`growth_factor`、`shrink_factor`、
`trust_radius`、`trust_min_radius`、`trust_max_radius`、`trust_growth_factor`、
`trust_shrink_factor`、`trust_accept_ratio`、`trust_good_ratio`、`last_trust_radius`、
`next_trust_radius`、`last_damping`、`last_merit_ratio`、
`last_trust_rejections`、`last_trust_adjust`、`mc_min_substeps`、
`mc_max_substeps`、`mc_target_strain`、`mc_yield_tol`、`mc_plastic_limit`
以及同名结构级 MC 聚合字段。`mc_branch_mask` 为积分点分支 bit OR 结果:
elastic=1、shear=2、tension=4、mixed=8。
当 `METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL` 且存在 accepted path 数据时,标准
CSV 输出目录中会新增 `continuation_path.csv`,字段为:
```text
step,time,control_parameter,control_dof_count,
prescribed_l2,prescribed_max,actual_l2,actual_max,
constraint_residual_linf,constraint_residual_l2,
control_reaction_sum,control_reaction_generalized,control_work,
iterations,residual_norm,relative_residual,correction_norm,
status_code,failure_code
```
其中 prescribed/actual 位移使用求解时实际施加的
`load_factor * amplitude(t) * boundary_value` 口径;直接位移路径的 control
parameter 等于 accepted increment 的伪时间;载荷型 Riks 路径中该字段为求解得到的
`load_factor`。V5.11 稳定接口是 `SHELL_GEOMETRIC=FINITE_STRAIN`,对应
finite-membrane-strain S4 formulation、有限转动 director、MITC/ANS assumed
strain、section material coupling 和生产切线。旧 S4 诊断路线的生产 dispatch、输入别名和
专用测试入口已从稳定路径移除;S4 `FINITE_STRAIN` 请求进入生产路径,S3/S6/S8 请求
必须显式报 unsupported,而不是回退到线性壳或旧诊断算法。方法 4 后续扩展真实非单调
结构验收时应保持 `continuation_path.csv` 字段向后兼容。
### 8.3 Benchmark 工具输入子集
`tools/benchmarks` 下的程序是验收编排工具,不属于 `fem_read_inp` 的通用
Abaqus 子集。它们可以读取小型专用输入以驱动核心模块验证,但不得把专用
keyword 宣称为主求解器接口。
主 `femlite --buckling` Euler 柱屈曲路径和兼容包装
`euler_column_buckling_benchmark` 当前读取如下专用块:
```inp
*BUCKLING COLUMN
E, I, L, element_count, effective_length_factor
```
字段含义:
- `E`:弹性模量。
- `I`:梁截面二次矩。
- `L`:柱长。
- `element_count`:Euler-Bernoulli 梁单元数量,当前要求不少于 2。
- `effective_length_factor`:Euler 解析临界载荷中的有效长度系数。
主程序通过 `fem_buckling_column` 装配梁弯曲刚度,调用生产
`geom_beam2d_column_stiffness` 和 `buckling_dense_solve`,输出
`buckling_summary.csv` 与 `buckling_mode_1.csv`。该块是已接入主程序的
Euler 柱专用生产入口;它不等同于完整 Abaqus 风格通用 `*BUCKLING` step。
静力预载 step 联动、壳/实体几何刚度装配、循环扇区约束和模态 VTK 输出仍属于
V5.5 后续工程接口。`tools/benchmarks/euler_column_buckling_benchmark` 只保留为
调用同一生产模块的兼容薄包装,不应再维护独立屈曲算法。
`corrugated_shell_buckling_benchmark` 当前读取如下专用块:
```inp
*CORRUGATED SHELL BUCKLING
sectors, selected_wave, output_mode_count, bottom_radius, top_radius, height, thickness
young, poisson, stiffness_coupling_ratio, geometric_coupling_ratio, corrugation_factor
```
字段含义:
- `sectors`:周期扇区数。
- `selected_wave`:要与全模型特征值比较的循环波数。
- `output_mode_count`:写入 modal CSV 的低阶模态数量。
- `bottom_radius`、`top_radius`、`height`、`thickness`:参考波纹锥壳尺度。
- `young`、`poisson`:材料弹性参数。
- `stiffness_coupling_ratio`、`geometric_coupling_ratio`:周期相邻扇区刚度和几何刚度耦合比例。
- `corrugation_factor`:波纹增强因子,用于形成紧凑 benchmark 的基础弯曲刚度。
该工具输出 `corrugated_buckling_summary.csv`、`corrugated_buckling_waves.csv`、
`corrugated_buckling_modes.csv` 和 `corrugated_buckling_profile.csv`。它用于
验证内部屈曲求解、循环波数一致性和 modal CSV 输出,不代表主求解器已经支持
完整 Abaqus 风格屈曲 step。
`roll_forming_kinematics_benchmark` 当前读取如下专用块:
```inp
*ROLLER KINEMATICS
radius, normal_force, mu, feed_rate, down_rate, angular_speed, reference_speed, duration, samples
```
字段含义:
- `radius`:刚体辊半径。
- `normal_force`:用于牵引和压力指标的参考法向力。
- `mu`:摩擦系数。
- `feed_rate`、`down_rate`:进给和下压速度。
- `angular_speed`:绕辊轴角速度。
- `reference_speed`:正则化牵引中的滑移速度尺度;0 表示经典 Coulomb 幅值。
- `duration`、`samples`:输出历史采样时间和采样数。
该工具输出 `roller_kinematics_history.csv` 和
`roller_kinematics_summary.csv`,用于验证角速度进入接触相对切向速度、正则化
牵引、摩擦能、压力和扭矩指标。它不是主 `femlite` 输入语法的一部分。
`roll_forming_springback_benchmark` 当前读取如下专用块:
```inp
*ROLL FORMING SPRINGBACK
thickness, half_width, strips, layers, length, radius, feed_total, down_total,
angular_speed, normal_force, mu, reference_speed, duration, E, nu, yield,
hardening, target_curvature, samples
```
字段含义:
- `thickness`、`half_width`、`strips`、`layers`:紧凑多层工件截面离散。
- `length`:用于残余位移和回弹位移指标的跨距。
- `radius`、`feed_total`、`down_total`、`angular_speed`、`normal_force`、`mu`、
`reference_speed`、`duration` 和 `samples`:滚压运动学、牵引和历史采样参数。
- `E`、`nu`、`yield` 和 `hardening`:J2 小应变材料点参数。
- `target_curvature`:成形目标曲率。
该工具输出 `springback_history.csv`、`springback_summary.csv` 和
`plastic_zone.csv`,用于验证塑性功、塑性区、成形力、卸载残余弯矩、残余位移
和 springback ratio。它同样不是主 `femlite` 输入语法的一部分。
`ball_adhesion_cohesive_benchmark` 当前读取如下专用块:
```inp
*BALL ADHESION COHESIVE
ball_radius, contact_radius, rings, samples, duration, max_indentation,
max_opening, normal_stiffness, tangent_stiffness, normal_strength,
tangent_strength, fracture_energy_i, fracture_energy_ii, mode_mix_eta,
compression_factor, slip_ratio
```
字段含义:
- `ball_radius`、`contact_radius`:球半径和 compact 粘附区半径。
- `rings`、`samples`:同心环数量和 force-displacement 采样点数。
- `max_indentation`、`max_opening`:压入和拉脱位移幅值。
- `normal/tangent_stiffness`、`normal/tangent_strength`、`fracture_energy_i/ii`、
`mode_mix_eta` 和 `compression_factor`:传给 `cohesive_params_init` 的
traction-separation 参数。
- `slip_ratio`:拉脱阶段切向滑移与正开口的比例。
该工具输出 `adhesion_history.csv`、`adhesion_summary.csv` 和
`decohesion_profile.csv`,用于验证 force-displacement hysteresis、peak pull-off
force、cohesive energy、damage 和 decohesion area。它同样不是主 `femlite`
输入语法的一部分。
## 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` 的兼容别名。
- 命令行 `--allow-cutback`、`--max-newton n` 和 `--newton-tol value` 分别写入
`allow_step_cutback`、`max_newton_iter` 和 `newton_tol_force`,用于非线性
静力与非线性 Newmark 入口。
- `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
subroutine fem_get_convergence_metrics(relative_residual_norm, &
contact_gap_norm, combined_norm, ierr)
real(rk), intent(out) :: relative_residual_norm
real(rk), intent(out) :: contact_gap_norm
real(rk), intent(out) :: combined_norm
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_convergence_diagnostics(cutback_count, last_dt, &
last_accepted_time, status_code, &
failure_code, ierr)
integer, intent(out) :: cutback_count
real(rk), intent(out) :: last_dt
real(rk), intent(out) :: last_accepted_time
integer, intent(out) :: status_code
integer, intent(out) :: failure_code
integer, intent(out) :: ierr
end subroutine
```
说明:
- `increment` 为最近一次静力/隐式求解尝试的实际步号或增量号。
- `iteration` 为该增量内最近一次 Newton 迭代号;求解尚未开始时为 0。
- `residual_norm` 为最近一次力残差范数。
- `correction_norm` 为最近一次位移修正范数;线性路径或尚未形成修正时为 0。
对 `METHOD=TRUST_REGION_DAMPED_NEWTON`,该值为 trust radius 和 damping 处理后
实际应用的修正范数。
- `converged` 表示最近一次记录的增量是否已满足收敛准则。
- `relative_residual_norm` 为力残差相对参考外力范数的比值。
- `contact_gap_norm` 为最近一次接触力评估中的最大 contact gap residual。
- `combined_norm` 为相对力残差、位移修正范数和 contact gap residual 的最大值,用于统一诊断多准则收敛状态。
- `cutback_count` 为最近一次静力/非线性 Newmark 运行累计触发的步长缩减次数。
- `last_dt` 为最近一次记录的静力增量长度或 Newmark 时间步长。
- `last_accepted_time` 为最近一次已提交成功的求解时间;失败并回滚时保持为最后有效时间。
- `status_code` 使用 `CONVERGENCE_STATUS_IDLE=0`、`ITERATING=1`、`CONVERGED=2`、`CUTBACK=3`、`FAILED=-1`。
- `failure_code` 使用 `CONV_FAIL_NONE=0`、`CONV_FAIL_NONCONVERGENCE=1`、`CONV_FAIL_CUTBACK_LIMIT=2`、`CONV_FAIL_STOPPED=3`。
- V4.5 起,非线性静力 Newton 迭代、静力 cutback 失败路径、非线性 Newmark cutback 运行和接触力评估会更新该状态;contact gap/mortar residual 当前作为 diagnostics 进入多准则统计,硬收敛判据仍以力残差为主。
第五版 0.5.2 追加 continuation path 查询:
```fortran
subroutine fem_get_continuation_path_count(count, ierr)
integer, intent(out) :: count
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_continuation_path_row(index, step, time, control_parameter, &
control_dof_count, prescribed_l2, prescribed_max, actual_l2, actual_max, &
residual_linf, residual_l2, reaction_sum, reaction_generalized, work, &
iteration, residual_norm, relative_residual, correction_norm, status_code, &
failure_code, ierr)
integer, intent(in) :: index
integer, intent(out) :: step, control_dof_count, iteration
integer, intent(out) :: status_code, failure_code, ierr
real(rk), intent(out) :: time, control_parameter
real(rk), intent(out) :: prescribed_l2, prescribed_max, actual_l2, actual_max
real(rk), intent(out) :: residual_linf, residual_l2
real(rk), intent(out) :: reaction_sum, reaction_generalized, work
real(rk), intent(out) :: residual_norm, relative_residual, correction_norm
end subroutine
```
`index` 从 1 开始;越界返回输入错误。当前该 API 覆盖 `METHOD=4` 的直接
prescribed-displacement accepted path 和载荷型 Riks path;后续非单调结构验收应复用同一查询接口。
### 12.6 线性求解器控制
V4.6 提供内部线性求解器配置和最近一次求解统计查询:
```fortran
subroutine fem_set_linear_solver(method, preconditioner, ierr)
integer, intent(in) :: method
integer, intent(in) :: preconditioner
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_linear_solver_settings(method, preconditioner, ierr)
integer, intent(out) :: method
integer, intent(out) :: preconditioner
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_linear_solver_stats(method, preconditioner, iteration, &
residual_norm, status_code, ierr)
integer, intent(out) :: method
integer, intent(out) :: preconditioner
integer, intent(out) :: iteration
real(rk), intent(out) :: residual_norm
integer, intent(out) :: status_code
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_linsol_diagnostics(matrix_class, initial_residual, &
final_residual, relative_residual, &
status_code, ierr)
integer, intent(out) :: matrix_class
real(rk), intent(out) :: initial_residual
real(rk), intent(out) :: final_residual
real(rk), intent(out) :: relative_residual
integer, intent(out) :: status_code
integer, intent(out) :: ierr
end subroutine
```
说明:
- `method` 使用 `LSOLVER_CG=1`、`LSOLVER_BICGSTAB=2`、
`LSOLVER_GMRES=3`、`LSOLVER_DENSE=4`。
- `preconditioner` 使用 `LPRECOND_NONE=0`、`LPRECOND_JACOBI=1`、
`LPRECOND_GAUSS_SEIDEL=2`、`LPRECOND_ILU0=3`;`LSOLVER_DENSE`
忽略预条件器并记录实际配置值。
- `status_code` 使用 `LS_STATUS_IDLE=0`、`LS_STATUS_CONVERGED=1`、`LS_STATUS_FAILED=-1`。
- CG 主要面向对称正定系统;BiCGSTAB 和 GMRES 可用于非对称 CSR 小系统;
DENSE 是内部 dense pivoting fallback,用于小中型回归矩阵或非线性修正诊断,
不是第三方 sparse-direct 后端。
- `matrix_class` 使用 `FEMLITE_CSR_CLASS_GENERAL=1`、`STRUCT_SYM=2`、
`SYMMETRIC=3`、`SPD_CAND=4`。分发层在调用内部 Krylov 求解器前
分析 CSR 图案、对角项和数值对称性,并记录初始残差、最终残差和最终相对残差。
- 非上述 method 值为非法配置;旧外部求解器 method 数值也必须返回错误,并保持当前
method/preconditioner 设置不变。
- 静力、隐式 Newmark 和非线性 Newton 修正方程均通过同一分发层求解。
### 12.7 壳稳定控制
V4.7 提供壳单元稳定参数设置和最近一次壳刚度装配统计查询:
```fortran
subroutine fem_set_shell_stabilization(drilling_factor, s3_shear_factor, &
s3_shear_min_scale, ierr)
real(rk), intent(in) :: drilling_factor
real(rk), intent(in) :: s3_shear_factor
real(rk), intent(in) :: s3_shear_min_scale
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_shell_stabilization(drilling_factor, s3_shear_factor, &
s3_shear_min_scale, ierr)
real(rk), intent(out) :: drilling_factor
real(rk), intent(out) :: s3_shear_factor
real(rk), intent(out) :: s3_shear_min_scale
integer, intent(out) :: ierr
end subroutine
subroutine fem_get_shell_stability_stats(sample_count, last_element, &
last_drilling_stiffness, &
last_shear_scale, min_shear_scale, &
max_drilling_stiffness, ierr)
integer, intent(out) :: sample_count
integer, intent(out) :: last_element
real(rk), intent(out) :: last_drilling_stiffness
real(rk), intent(out) :: last_shear_scale
real(rk), intent(out) :: min_shear_scale
real(rk), intent(out) :: max_drilling_stiffness
integer, intent(out) :: ierr
end subroutine
```
C ABI 对应函数为:
```c
int femlite_set_shell_stabilization(double drilling_factor,
double s3_shear_factor,
double s3_shear_min_scale);
int femlite_get_shell_stabilization(double *drilling_factor,
double *s3_shear_factor,
double *s3_shear_min_scale);
int femlite_get_shell_stability_stats(int *sample_count, int *last_element,
double *last_drilling_stiffness,
double *last_shear_scale,
double *min_shear_scale,
double *max_drilling_stiffness);
```
说明:
- 默认值为 `drilling_factor=1.0e-4`、`s3_shear_factor=0.0625`、`s3_shear_min_scale=1.0e-4`。
- `drilling_factor` 取值范围为 `[0,1]`,`s3_shear_factor >= 0`,`s3_shear_min_scale` 取值范围为 `(0,1]`。
- 统计量在 `control_set_defaults` 时清零;每次壳单元刚度装配后记录最近样本,并累计最小 S3 剪切折减和最大 drilling 刚度。
### 12.8 接触状态
第三版提供接触结果查询接口:
```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` 段,则读入时清空当前接触历史。
V5.7 cohesive 生产模块当前提供 Fortran 内部接口,尚未新增 C ABI 包装:
```fortran
subroutine cohesive_params_init(kn, kt, tn0, tt0, gi, gii, eta, &
comp_factor, params, ierr)
subroutine cohesive_trial_update(params, opening, slip, old_damage, &
old_max_eff, traction_n, traction_t, &
tangent_n, tangent_t, new_damage, &
new_max_eff, dissipated, status, ierr)
subroutine cohesive_state_store_trial(pair, selem, sface, melem, mface, &
point_id, damage, max_opening, &
max_effective, energy_delta, status, &
ierr)
subroutine cohesive_state_write(unit_id, ios)
subroutine cohesive_state_read(unit_id, count_in, ierr)
subroutine cohesive_metrics_add(state, status, damage, opening, effective, &
area, cohesive_energy, elastic_energy, ierr)
```
`cohesive_trial_update` 的状态码为 `OPEN=0`、`BONDED=1`、`DAMAGING=2`、
`FAILED=3`、`COMPRESS=4`。`energy_delta` 必须为非负耗散增量;state 层会将
damage、最大开口、最大有效分离和能量做不可逆累计。独立 cohesive state
restart 段的文本头为 `COHESIVE_STATE count`,随后逐槽写出 pair/slave/master
索引、point id、status、damage、maximum opening、maximum effective separation、
energy 和 trial energy。主 `femlite` restart 文件尚未接入 cohesive state 段;
当前 V5.7 单点验收通过模块级 write/read 验证 restart 语义。
V5.8 颗粒生产模块当前提供 Fortran 内部接口,尚未新增 C ABI 包装:
```fortran
subroutine particle_add(ext_id, position, velocity, radius, mass, slot, ierr)
subroutine particle_kinetic_energy(energy, ierr)
subroutine particle_momentum(momentum, total_mass, ierr)
subroutine particle_contact_init(kn, cn, kt, mu, kwall, cwall, params, ierr)
subroutine pstep_advance(ctrl, params, walls, nwall, diag, ierr)
subroutine pstep_diag_values(diag, dt, mass_before, mass_after, &
momentum_before, momentum_after, &
kinetic_before, kinetic_after, &
dissipated_energy, max_overlap, ierr)
subroutine pfacet_step_cloud(nparticle, slots, nfacet, max_nodes, &
facet_nnode, coords, velocities, params, &
node_loads, stats, ierr)
subroutine pfacet_step_summary(stats, particle_count, contact_count, &
max_overlap, total_energy, total_power, &
force_norm, ierr)
subroutine particle_fem_apply_all(params, clear_particle_forces, stats, ierr)
subroutine particle_fem_stats_summary(stats, particle_count, contact_count, &
max_overlap, total_energy, total_power, &
force_norm, ierr)
subroutine particle_fem_stats_force_norms(stats, particle_force_norm, &
node_force_norm, ierr)
subroutine pfacet_force_balance(nnode, node_forces, particle_force, &
residual, ierr)
```
`pstep_diag_values` 使用 `particle_step_diag%dissipated_power * dt` 输出单步
`dissipated_energy`;质量、动量和动能分别来自 step 前后状态。facet coupling
路径的总质量、动量和动能通过 `particle_momentum` 与 `particle_kinetic_energy`
查询,节点载荷平衡通过 `pfacet_force_balance` 查询。`test_particle_acceptance`
覆盖这些 Fortran 输出路径。`particle_fem_apply_all` 从当前 FEM 边界 facet
收集坐标/速度,计算所有激活颗粒的 facet 接触,按节点写回 `fsph`,并返回
contact count、最大重叠、能量、耗散功率和力范数统计。
V5.8 dynamic grain container benchmark 工具命令行:
```text
dynamic_grain_container_benchmark INPUT.inp OUTPUT_DIR
```
`INPUT.inp` 使用 benchmark 专用控制块:
```inp
*DYNAMIC GRAIN CONTAINER
structure_file, steps, dt, gx, gy, gz, damping, search_gap, probe_node
*PARTICLE CONTACT
kn, cn, kt, mu, kwall, cwall
*PARTICLES
id, x, y, z, vx, vy, vz, radius, mass
```
工具输出 `grain_container_history.csv` 和 `grain_container_summary.csv`。该
benchmark 输入格式服务于 `examples/` 验收,不是主 `femlite` 应用程序的通用 INP
keyword。
第三版当前 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`。
- `TYPE=NODE` contact pair slave 当前只支持 analytical master;`TYPE=NODE` slave 对一般 element master 会在模型 build 阶段报错,避免被误认为完整 node-to-facet mortar 支持。
- `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 候选缓存使用和溢出统计。
- C ABI 暴露 `femlite_get_convergence_status`,其中 `converged` 使用 `int` 返回 0/1。
- C ABI 暴露 `femlite_get_convergence_metrics`,返回相对力残差、contact gap residual 和 combined norm。
- C ABI 暴露 `femlite_get_convergence_diagnostics`,返回 cutback 次数、最后步长、最后有效时间、收敛状态码和失败原因码。
- C ABI 暴露 `femlite_set_linear_solver`、`femlite_get_linear_solver_settings`、
`femlite_get_linear_solver_stats` 和 `femlite_get_linear_solver_diagnostics`,
返回/设置值与 Fortran API 常量一致。
- 上述函数只追加新符号,不改变 `femlite_get_contact_summary` 的签名和含义。
## 18. 0.5.3 Diagnostic Interface Addendum
Fortran diagnostic API:
- `fem_get_residual_breakdown(total_residual, force_residual,
contact_residual, constraint_residual, arc_residual,
material_fail_count, ierr)` returns the latest nonlinear residual
decomposition. Missing categories are returned as zero, preserving older
scalar residual queries.
CSV/output schema:
- `continuation_path.csv` appends `residual_total`, `residual_force`,
`residual_contact`, `residual_constraint`, `residual_arc` and
`material_failure_count` before `reason_id` and `reason_name`.
- Contact CSV/report output may include stable state counts, mean/L2 gap,
maximum penetration, failed projection count, active-set flip count,
slip increment/residual, friction residual, multiplier residual,
augmentation factor/update diagnostics and augmented multiplier values.
Restart schema:
- Restart files with version 4 may include optional
`CONTACT_PAIR_DIAGNOSTICS` rows after `CONTACT_MULTIPLIER`.
- Readers still accept older restart versions and old files ending directly at
`END`; version 4 is required only to round-trip the new accepted-increment
contact diagnostic fields.
Boundary:
- 0.5.3 documents audit and diagnostic interfaces. It does not claim complete
industrial AL/mortar consistent tangent support.