Files
FemLite/docs/07_user_manual.md
T
shenw 175531e24d
FemLite CI / build-test (push) Has been cancelled
Release 0.6.0
2026-07-01 20:44:15 +08:00

617 lines
33 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.
# FemLite 0.5.x 用户手册
日期:2026-06-26
## 1. 适用范围
本文档面向 FemLite 0.5.x 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。
FemLite 0.5.x 是船舶接触爆炸结构响应 FEM 软件的第五版开发线,当前支持:
- 三维实体和壳单元结构分析。
- 显式瞬态动力学。
- 线性静力学和非线性静力学。
- 隐式 Newmark 和非线性 Newmark-Newton 主流程。
- 各向同性线弹性、J2 弹塑性、Johnson-Cook 相关材料路径。
- Mohr-Coulomb 材料点更新、张拉截断、分支诊断、材料 driver 和强度折减参数折减基础。
- 小规模线性屈曲支撑模块、内部 dense 特征值求解和 Euler 柱解析 benchmark。
- Abaqus inp 输入子集。
- element/node/analytical surface 子集、contact property 子集、刚性平面接触和面-面 contact pair 阶段能力。
- contact pair active set、gap residual 和 augmented penalty 诊断输出。
- 静力/隐式求解的收敛状态和 cutback 诊断查询接口。
- 线性求解器可在内部 CG、BiCGSTAB、GMRES 和 dense pivoting fallback 间切换,并提供预条件和迭代/残差统计查询;核心模块不依赖第三方或外部稀疏求解器。
- CSV、VTK、restart 和 contact CSV 输出。
- Fortran95 原生接口、C ABI 子集和 Python 调试脚本。
0.5.x 当前开发态不等价于完整 Abaqus 兼容求解器,也不等价于全部 V5 高保真 benchmark 已完成的最终版。
## 2. 目录概览
常用目录:
```text
src/ Fortran95 核心源码和 C ABI 包装
include/ C ABI 头文件
Python/ Python 调试辅助脚本
docs/ 需求、设计、接口、测试和验收文档
examples/ 示例算例和生成脚本
tests/ 单元、模块、接口、示例 smoke 和性能测试
```
主要可执行目标:
- `femlite`:命令行分析程序。
- `test_*`:各类本地测试程序。
- `perf_p1`:P1 性能测试程序。
主要库目标:
- `femlite_core`:Fortran95 静态核心库。
- `femlite_c`:C ABI 静态库。
## 3. 环境准备
推荐环境:
- Windows:GCC 16.1.0 或 Intel oneAPI ifx 2026.0 + MSVC。
- Linux/WSL:Ubuntu + gfortran 13.3。
- 构建系统:CMake 3.20 或更高版本。
- 可选:Python 3,用于示例生成和 Python 调试测试。
- 可选:Gmsh Python API,用于部分示例重新生成网格。
本项目默认以 WSL Ubuntu + gfortran 13.3 + CMake 作为主要开发环境,同时保留 Windows GCC 和 Intel ifx 兼容性检查。
## 4. 编译
### 4.1 Windows GCC
在仓库根目录运行:
```powershell
cmake -S . -B build-win-gcc-16 -G "MinGW Makefiles" -DCMAKE_Fortran_COMPILER=C:\gcc-16.1.0-64\bin\gfortran.exe -DCMAKE_C_COMPILER=C:\gcc-16.1.0-64\bin\gcc.exe
cmake --build build-win-gcc-16
```
可执行程序通常位于:
```text
build-win-gcc-16\femlite.exe
```
### 4.2 WSL gfortran
在 Windows PowerShell 中可调用 WSL:
```powershell
wsl bash -lc "cd /mnt/d/Codex/FemLite && cmake -S . -B build-wsl"
wsl bash -lc "cd /mnt/d/Codex/FemLite && cmake --build build-wsl"
```
### 4.3 Intel oneAPI ifx
Intel oneAPI 在 Windows 上安装后,可通过 oneAPI 和 MSVC 环境脚本配置编译环境,再运行 CMake 构建。0.3.3 发布基线已通过 Windows Intel oneAPI ifx 2026.0 + MSVC cl 19.44 构建与 CTest;0.4.x 发布前建议按同一流程复测。
## 5. 命令行用法
基本形式:
```powershell
build-win-gcc-16\femlite.exe input.inp [analysis-mode] [options]
```
如果只给出 `input.inp`,程序会读取输入文件、构建模型并打印模型摘要,不执行分析。
分析模式只能选择一个:
| 参数 | 含义 |
|---|---|
| `--run` | 显式瞬态动力学 |
| `--static-linear` | 线性静力学 |
| `--implicit-linear` | `--static-linear` 的兼容别名 |
| `--static-nonlinear` | 非线性静力学 |
| `--implicit-newmark` | 隐式 Newmark 线性动力学 |
| `--implicit-newmark-nonlinear` | 非线性 Newmark-Newton 动力学 |
| `--buckling` | Euler 柱专用线性屈曲分析,读取 `*BUCKLING COLUMN` |
通用选项:
| 参数 | 含义 |
|---|---|
| `--output-dir path` | 设置结果输出目录 |
| `--output-interval n` | 设置输出间隔;0 表示不输出步结果 |
| `--allow-cutback` | 允许非线性静力/非线性 Newmark 在不收敛时自动缩步 |
| `--max-newton n` | 设置非线性 Newton 最大迭代次数 |
| `--newton-tol value` | 设置非线性力残差收敛容差 |
示例:
```powershell
build-win-gcc-16\femlite.exe examples\scordelis_lo_roof\scordelis_lo_s4_static.inp --output-dir examples\scordelis_lo_roof\results\s4_static --static-linear
```
```powershell
build-win-gcc-16\femlite.exe examples\rigid_sphere_impact_plate\rigid_sphere_impact_plate_s4.inp --output-dir examples\rigid_sphere_impact_plate\results\s4 --output-interval 50 --run
```
```powershell
build-win-gcc-16\femlite.exe examples\euler_column_buckling\euler_column_buckling.inp --buckling --output-dir examples\euler_column_buckling\results\auto_run
```
## 6. 输入文件
FemLite 使用 Abaqus inp 风格输入文件的子集。0.4.8 常用支持项包括:
- `*NODE`
- `*ELEMENT`
- `*NSET`
- `*ELSET`
- `*MATERIAL`
- `*DENSITY`
- `*ELASTIC`
- `*PLASTIC`
- `*MOHR COULOMB`
- `*SOLID SECTION`
- `*SHELL SECTION`
- `*BOUNDARY`
- `*CLOAD`
- `*DLOAD`
- `*AMPLITUDE`
- `*STEP`
- `*DYNAMIC`
- `*STATIC`
- `*NONLINEAR CONTINUATION`
- `*SURFACE`
- `*SURFACE INTERACTION`
- `*CONTACT PROPERTY`
- `*FRICTION`
- `*CONTACT PAIR`
- `GENERATE`
不支持的 keyword 默认 warning 后跳过;关键数据缺失、非法材料参数、非法单元类型等会报错终止。
## 7. 单元与材料
当前常用单元:
| 类别 | 单元 |
|---|---|
| 实体线性 | C3D4、C3D8 |
| 实体二次 | C3D10、C3D20 |
| 壳单元 | S3、S4、S6、S8 |
材料:
- 各向同性线弹性:`*DENSITY` 和 `*ELASTIC`。
- J2 von Mises 弹塑性:`*PLASTIC`。
- Johnson-Cook 流动应力、应变率和损伤相关路径为阶段能力,具体格式见设计和示例输入。
- Mohr-Coulomb:`*MOHR COULOMB`,当前材料点路径支持摩擦角、黏聚力、膨胀角、张拉强度、残余参数和强度折减系数。
密度是动力学分析的必需材料参数。
Mohr-Coulomb 输入示例:
```inp
*MATERIAL, NAME=SOIL
*DENSITY
1800.0
*ELASTIC
2.0E7, 0.30
*MOHR COULOMB
30.0, 10000.0, 5.0, 2000.0
20.0, 4000.0, 1.0, 1.5
```
第一行依次为摩擦角 degree、黏聚力、膨胀角 degree 和张拉强度;第二行依次为
残余摩擦角 degree、残余黏聚力、残余膨胀角 degree 和强度折减系数。材料点输出中
`statev(11)` 记录当前分支,`statev(12:13)` 记录最终剪切/张拉屈服值,
`statev(22)` 记录最近一次塑性增量。若选择方法 5,`statev(27:32)` 还记录
Mohr-Coulomb 子步数、请求子步数、driver 状态、分支 mask、最大屈服残差和最大
塑性增量。结构级强度折减 benchmark 已在
`examples/strengthReduction` 中按 PDF 参考路线接入,通用非线性自动 trial
重求解仍作为后续增强。
非线性 continuation 方法选择:
```inp
*STEP
*NONLINEAR CONTINUATION, METHOD=TWO_STAGE_LOAD_STRENGTH
*STATIC
0.01, 1.0, 1.0e-5, 0.05
*END STEP
```
如果省略 `*NONLINEAR CONTINUATION`,默认使用 `METHOD=1`,即
`TWO_STAGE_LOAD_STRENGTH`。当前 `METHOD=1..5` 和对应符号名已可由 INP 解析并写入
非线性诊断;方法 1 已用于 strengthReduction 非线性 chain/cloud 的两阶段路线:
先在强度因子 `F=1.0` 下收敛完整外载,再固定外载并推进材料强度折减因子。方法
2 `ADAPTIVE_TARGET_NEWTON` 已可用 `TARGET_NEWTON`、`GROWTH` 和 `SHRINK` 控制
静力 continuation 步长;方法 3 `TRUST_REGION_DAMPED_NEWTON` 已可用
`TRUST_RADIUS`、`TRUST_MIN_RADIUS`、`TRUST_MAX_RADIUS`、`TRUST_GROWTH`、
`TRUST_SHRINK`、`TRUST_ACCEPT_RATIO` 和 `TRUST_GOOD_RATIO` 限制 Newton 修正、
执行 residual-merit damping 并输出 trust 诊断。方法 4
`ARC_LENGTH_OR_DISPLACEMENT_CONTROL` 对载荷型问题使用 Riks/arc-length 增广方程,
把全局 `load_factor` 作为未知量;如果输入含非零 prescribed displacement,
则使用直接位移控制 accepted path。若两类控制量都不存在,求解会返回错误,
不会退回普通 Newton path 记录。两条有效路径都会在每个收敛增量输出控制参数、
位移、约束残差、反力和收敛状态。方法 5
`MC_SUBSTEPPING_SEMISMOOTH` 当前会在 Mohr-Coulomb 材料点启用局部子步和活动集
诊断,并在 strengthReduction 可选诊断输出中汇总结构级 substep 信息。
完整 0.75 m 临界失稳 cloud 的 longrun 效果证明属于后续研究验证,
不作为 V5 使用验收项。
方法 2 示例:
```inp
*NONLINEAR CONTINUATION, METHOD=ADAPTIVE_TARGET_NEWTON, TARGET_NEWTON=6, GROWTH=1.5, SHRINK=0.5
```
方法 3 示例:
```inp
*NONLINEAR CONTINUATION, METHOD=TRUST_REGION_DAMPED_NEWTON, TRUST_RADIUS=0.1, TRUST_MIN_RADIUS=1.0e-6, TRUST_MAX_RADIUS=1.0, TRUST_GROWTH=1.5, TRUST_SHRINK=0.5
```
方法 4 示例:
```inp
*NONLINEAR CONTINUATION, METHOD=ARC_LENGTH_OR_DISPLACEMENT_CONTROL, ARC_LENGTH=0.05, ARC_LOAD_SCALE=1.0
```
For direct prescribed-displacement paths, adaptive path spacing is the default
continuation route. `DISP_ADAPTIVE=NO` on the same `*NONLINEAR CONTINUATION`
line, or CLI `--disp-path-adaptive off`, can be used to recover the older fixed
time-grid sampling. The adaptive route also limits the next displacement step
when the accepted generalized reaction changes sharply, so post-peak branches
are sampled before cutback is forced to recover from an over-large step.
When the input keeps the historical `TARGET_NEWTON=6` default, the direct
displacement path uses a relaxed internal target of 12 accepted Newton
iterations before shrinking; explicit `TARGET_NEWTON` values remain honored.
The CLI option `--linear-precond none|jacobi|gs|ilu0` can override the internal
linear preconditioner for diagnostic runs. The default remains Jacobi.
For nonlinear line-search diagnostics, `--line-search-min-alpha value`,
`--line-search-reduction value`, and `--line-search-accept-ratio value` override
the Newton damping floor, backtracking reduction, and residual merit acceptance
ratio for the current run only.
For cutback diagnostics, `--max-cutback count` and `--cutback-factor value`
override the retry count and shrink factor for the current run; the factor must
be greater than 0 and less than 1.
For trust-region diagnostics, `--trust-radius value`, `--trust-min-radius
value`, and `--trust-max-radius value` can enable the existing damped Newton
correction limiter for direct prescribed-displacement ARC_DISP paths when a
positive trust radius is provided. The default remains off for ARC_DISP.
当输出目录启用且有 accepted path 数据时,会生成 `continuation_path.csv`;库调用者
也可使用 `fem_get_continuation_path_count` 和 `fem_get_continuation_path_row`
查询同一数据。V5.11 正式壳几何非线性配置为
`SHELL_GEOMETRIC=FINITE_STRAIN`,当前支持 S4 finite-membrane-strain、有限转动
director、MITC/ANS assumed strain、section material coupling 和生产切线。稳定配置只接受
`SHELL_GEOMETRIC=LINEAR` 或 `SHELL_GEOMETRIC=FINITE_STRAIN`;旧布尔写法和旧
shell 几何名称已移除,输入中出现时会报错。S3/S6/S8 请求 `FINITE_STRAIN` 时会报
unsupported。
`ARC_LENGTH`/`ARC_RADIUS` 指定弧长半径;
省略时使用当前静力增量长度。`ARC_LOAD_SCALE` 指定载荷因子在弧长约束中的缩放,
默认 1。当前保留的可复用基础设施包括 section/resultant 状态、弹性多层 ABD/H
section 矩阵、内部非对称修正求解链和壳压力 follower tangent;它们仍不能作为完整
Shell-4/8/16 后屈曲验收依据。
方法 5 示例:
```inp
*NONLINEAR CONTINUATION, METHOD=MC_SUBSTEPPING_SEMISMOOTH, MC_MIN_SUBSTEPS=2, MC_MAX_SUBSTEPS=64, MC_TARGET_STRAIN=1.0e-3, MC_YIELD_TOL=1.0e-7, MC_PLASTIC_LIMIT=5.0e-2
```
方法 5 只改变 Mohr-Coulomb 局部材料积分路径;若算例没有 `MOHR_COULOMB` 材料,
这些 MC 控制项不会改变弹性或 J2 材料更新。
## 8. 边界、载荷与接触
常用边界和载荷:
- `*BOUNDARY`:节点或集合自由度约束。
- `*CLOAD`:集中节点力。
- `*DLOAD`:分布载荷子集;`target, P, pressure` 用于壳面压力,
`target, GRAV, magnitude, gx, gy, gz` 用于实体重力/体力加速度。
- `*AMPLITUDE`:时间或增量相关幅值。
contact pair 支持两种输入方式。
header 式:
```inp
*CONTACT PAIR, SLAVE=slave_target, MASTER=master_target, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION=value, FRICTION_REGULARIZATION=value, AUGMENT=value
```
contact property 继承式:
```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
*SURFACE INTERACTION, NAME=normal_contact, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION_REGULARIZATION=value, AUGMENT=value
*FRICTION
mu
*CONTACT PAIR, INTERACTION=normal_contact
slave_surface, master_surface
```
说明:
- `PENALTY` 可在 contact pair 或 contact property 中给出,最终值必须大于 0。
- `DAMPING`、`SEARCH`、`FRICTION`、`FRICTION_REGULARIZATION`、`AUGMENT` 可选,默认 0。
- `FRICTION_REGULARIZATION` 是接触对级摩擦正则化滑移尺度;0 表示经典 Coulomb 截断。
- `SLAVE` 和 `MASTER` 可为 surface 名称、elset 名称、element id 字符串或 `ALL`。
- `*SURFACE` 当前支持 `TYPE=ELEMENT`、`TYPE=NODE` 和 `TYPE=ANALYTICAL` 刚性平面子集。
- 面-面 contact pair 当前仍以 element surface facet 路径为主;node surface 和 analytical plane 主要用于节点目标/刚性平面接触子集。V5 明确拒绝 `TYPE=NODE` slave 对一般 element master 的 contact pair;该路径留到后续版本转换为 facet 约束或完整 mortar 节点约束后再支持。
- analytical plane 数据行为 `PLANE, nx, ny, nz, offset`。
- face label 支持省略、`ALL`、`EXTERIOR`、`S1`、`F1`、`FACE1` 等形式。
- 壳单元支持 `SPOS`/`SNEG` 当前单一 shell facet 语义。
## 9. 输出文件
默认输出文件包括:
| 文件 | 内容 |
|---|---|
| `history.csv` | 时间步、能量或求解历史 |
| `nodes_XXXXXXXX.csv` | 节点位移、速度、加速度等 |
| `elements_XXXXXXXX.csv` | 单元应力、应变、塑性变量等 |
| `reactions_XXXXXXXX.csv` | 节点反力 |
| `result_XXXXXXXX.vtk` | Legacy ASCII VTK 后处理文件 |
| `contact_XXXXXXXX.csv` | 接触 summary 和逐 contact pair 统计 |
| `restart_*.frs` | restart 文件 |
`contact_XXXXXXXX.csv` 当前字段包含:
```text
kind,pair_id,active_count,max_penetration,force_norm,work_estimate,cumulative_work,stick_count,slip_count,accumulated_slip,friction_work,friction_work_total,friction_regularization,ftx,fty,ftz,status,activation_count,release_count,gap_residual,aug_factor,aug_lambda,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
```
`search_*` 字段在 `SUMMARY` 行给出最近一次 contact pair 力评估的全局搜索统计、BVH 候选缓存使用情况和 `cpu_time` 口径秒数;逐 `PAIR` 行给出对应接触对的搜索、缓存和计时统计。`cpu_time` 是轻量趋势诊断,小算例中可能显示为 0。
Fortran95 API 可通过 `fem_get_convergence_status` 查询最近一次求解的增量、迭代、残差、位移修正范数和收敛标志;在 trust-region damped Newton 中,位移修正范数是半径限制和 damping 后实际应用的范数。通过 `fem_get_convergence_metrics` 可查询相对残差、contact gap residual 和 combined norm,通过 `fem_get_convergence_diagnostics` 查询 cutback 次数、最后步长、最后有效时间、状态码和失败原因码。`fem_set_linear_solver` 可选择 `CG`、`BiCGSTAB`、`GMRES`、`DENSE` 与 `none/Jacobi/Gauss-Seidel/ILU0` 预条件,`fem_get_linear_solver_stats` 查询最近一次线性求解迭代数、残差和状态,`fem_get_linsol_diagnostics` 查询 CSR 矩阵分类、初始残差、最终残差和最终相对残差;其他 method 值会返回错误且不会改变当前设置。非线性 Newton 修正若在配置的 CG 路径遇到非正定切线,可在内部 GMRES、BiCGSTAB 和 dense pivoting fallback 间自动重试,并在返回前恢复用户配置的求解器设置。V4.7 起,`fem_set_shell_stabilization` 可设置壳 drilling 系数、S3 剪切锁定折减系数和最小折减比例,默认分别为 `1.0e-4`、`0.0625`、`1.0e-4`;`fem_get_shell_stability_stats` 可查询最近壳刚度装配诊断。C ABI 提供同名 `femlite_get_*`/`femlite_set_*` 包装,`converged` 使用 0/1 整数返回。
建议把大型结果输出到 `examples/.../results/...` 或独立 `output/` 目录。仓库 `.gitignore` 默认忽略大规模结果文件。
## 10. 示例算例
当前示例包括:
| 目录 | 说明 |
|---|---|
| `examples/uniaxialTension3D` | 3D 圆柱单轴拉伸,tet/hex |
| `examples/tension2D` | 板壳拉伸,tri/quad |
| `examples/ScordelisLo` | Scordelis-Lo 屋面壳体基准 |
| `examples/scordelis_lo_roof` | V4.7 Scordelis-Lo S3/S4 独立基准目录 |
| `examples/Kirsch` | Kirsch 带孔板静力基准 |
| `examples/shell_patch_test` | 壳单元 patch test |
| `examples/clamped_square_plate_pressure_pulse` | 固支方板压力脉冲 |
| `examples/rigid_sphere_impact_plate` | 刚球冲击板壳接触算例 |
| `examples/elliptic_membrane` | NAFEMS LE1 椭圆膜缩减静力案例 |
| `examples/membrane_uniaxial_stretching` | 文档参数派生的膜单轴拉伸静力案例 |
| `examples/shell_solid_connection` | 共享节点壳-实体接口静力案例 |
| `examples/strengthReduction` | Mohr-Coulomb 坡体强度折减 benchmark |
| `examples/euler_column_buckling` | Euler pinned-pinned column 主程序线性屈曲解析 benchmark |
| `examples/golfBallImpact` | 高尔夫冲击文档派生的壳接触动力缩减案例 |
| `examples/node_analytical_plane_contact` | node surface 到 analytical plane 的接触 smoke |
| `examples/block_on_arch` | 文档派生的浅拱-解析刚体面接触 smoke |
| `examples/cylinder_roller_contact` | 滚子-基础法向接触代表性 smoke |
| `examples/sliding_wedge` | 倾斜楔块摩擦滑移接触 smoke |
| `examples/membrane_airbag_inflation` | 膜气囊压力载荷 S4 动力/静力回归入口 |
| `examples/spherical_cap_with_central_point_load` | 球冠中心载荷位移控制壳 benchmark;默认检查 Shell-16 小应变样本,附带全 S4 finite-strain target deck;V5.11 用于验证有限应变 S4 生产路径、translational-rim 口径、continuation path 诊断和 post-peak load drop,完整 PDF 全曲线匹配留到后续版本 |
| `examples/two_arches` | 基于 `models.sme.two_arches.pdf` 几何的双拱壳-壳接触 geometry/contact smoke;当前默认验收参考几何、30/75 壳网格、1.2 mm 上拱中点位移和 active contact;另提供 optional `run_two_arches_reference_point.py` 单个位移参考工况入口,输出 `two_arches_reference_point.csv`;V5 不提供 COMSOL 参数化扫描 |
| `examples/blasting_rock` | 花岗岩块爆破脉冲显式动力 smoke |
| `examples/nonlinear_harmonic` | 薄膜谐波压力响应显式动力 smoke |
| `examples/failure_prediction_in_a_layered_shell` | 四层共享节点壳拉伸回归入口 |
| `examples/pinched_hemispherical_shell` | pinched hemisphere S4 壳动力 smoke |
| `examples/stress_dependent_elasticity` | 应力相关弹性悬臂梁纯弯矩 benchmark |
| `examples/roll_forming` | 滚压摩擦 smoke、roller kinematics benchmark 和 springback benchmark |
| `examples/falling_objects` | 多物体显式接触与刚性箱底代表性 smoke |
| `examples/ball_adhesion_decohesion` | 球-膜接触压入 smoke 和 compact cohesive 粘附/脱粘 benchmark |
| `examples/buckling_corrugated_shell` | 波纹锥壳紧凑循环线性屈曲 benchmark |
| `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | 柔性容器压力-地面接触 smoke 和 V5.8 真实粒子-柔性容器耦合 benchmark |
| `examples/thick_plate` | NAFEMS LE10 厚板压力静力回归入口 |
| `examples/contact_rigid_plane_indentation` | 刚性平面压入接触算例 |
| `examples/contact_two_blocks_compression` | 非匹配两实体块 mortar 压缩接触 benchmark |
| `examples/shell_rigid_plane_contact` | S4 壳-刚性平面接触算例 |
| `examples/contact_block_sliding` | 非匹配两实体块大滑移 mortar-friction benchmark |
| `examples/shell_shell_contact` | S4-to-S4 shell-shell 接触 benchmark |
| `examples/shell_solid_contact` | S4-to-C3D8 shell-solid 接触 benchmark |
每个示例目录中的 `README.md` 给出几何、材料、边界、生成脚本和运行命令。新增基准测试应放在 `examples/` 下,并为每个基准案例建立独立文件夹;旧目录可为兼容保留,但新的 CTest 和文档应优先指向独立目录。包含 `.inp` 的示例目录应提供 `run_case.bat`,可在 Windows 下双击自动运行,结果默认写入该目录的 `results\auto_run`。`examples/contact_two_blocks_compression` 的检查脚本会额外生成 `pressure_profile.csv`,用于检查非匹配接触压力、gap、weighted gap、multiplier residual 和 augmented multiplier。`examples/contact_block_sliding` 的检查脚本会额外生成 `sliding_profile.csv`,用于检查多 master 大滑移摩擦、stick/slip、累计滑移、摩擦功和切向力。`examples/shell_shell_contact` 和 `examples/shell_solid_contact` 的检查脚本分别生成 shell contact profile CSV,用于检查 active contact、force、gap、augmented multiplier 和 master search。`examples/strengthReduction` 的 benchmark checker 会生成 `strength_reduction_path.csv`、`strength_reduction_cases.csv`、`strength_reduction_summary.csv`、`plastic_zone.csv` 和 `displacement_probe.csv`,用于检查 PDF 8 工况安全系数曲线、bracket、塑性区和位移停止准则。`examples/euler_column_buckling` 的主程序 checker 会运行 `femlite --buckling`,生成 `buckling_summary.csv` 和 `buckling_mode_1.csv`,用于检查 Euler 临界载荷相对误差、特征残差、`phi^T K_G phi` 归一化和端部横向位移约束。`examples/buckling_corrugated_shell` 的 benchmark checker 会生成 `corrugated_buckling_summary.csv`、`corrugated_buckling_waves.csv`、`corrugated_buckling_modes.csv` 和 `corrugated_buckling_profile.csv`,用于检查循环波数、临界载荷、循环/全模型一致性、循环边界残差和模态输出。`examples/roll_forming` 的 roller kinematics checker 会生成 `roller_kinematics_history.csv` 和 `roller_kinematics_summary.csv`,用于检查辊角速度对切向滑移、正则化牵引、摩擦能、压力和扭矩的影响;springback checker 会生成 `springback_history.csv`、`springback_summary.csv` 和 `plastic_zone.csv`,用于检查 J2 塑性功、塑性区、卸载残余弯矩、残余位移和回弹比例。`examples/ball_adhesion_decohesion` 的 cohesive checker 会生成 `adhesion_history.csv`、`adhesion_summary.csv` 和 `decohesion_profile.csv`,用于检查 force-displacement 滞回、峰值拉脱力、耗散能、损伤和脱粘面积。`examples/Dynamic_Grain_Packing_of_a_Flexible_Container` 的 particle checker 会生成 `grain_container_history.csv` 和 `grain_container_summary.csv`,用于检查真实粒子-facet 接触、映射节点力、容器位移、质量守恒、重叠和能量。
`examples/strengthReduction` 的可选 nonlinear chain/cloud/progress 输出还会记录
`continuation_method`、target/actual/next continuation step、adaptive adjust、
trust radius、damping、merit ratio、trust rejection、MC 子步/分支聚合诊断和直接位移
控制 path 诊断;checker 会拒绝缺失或非法的 NC-2/NC-3/NC-5 字段;NC-4 path 数据由
生产 API/CSV 输出提供。
## 11. 测试
运行全量测试:
```powershell
ctest --test-dir build-win-gcc-16 --output-on-failure
```
运行 V5 验收子集:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -L v5_acceptance --output-on-failure
```
运行指定测试:
```powershell
ctest --test-dir build-win-gcc-16 -R "^(contact|implicit_inp|source_size)$" --output-on-failure
```
运行 V5.3 two-block 非匹配接触 benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_contact_two_blocks_compression_benchmark --output-on-failure
```
运行 V5.3 large-sliding 摩擦 benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_contact_block_sliding_benchmark --output-on-failure
```
运行 V5.3 shell contact benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R "example_shell_(shell|solid)_contact_benchmark" --output-on-failure
```
运行 V5.4 Mohr-Coulomb 材料点测试:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R "material_mohr_coulomb|material_mc_driver|material_mc_envelope" --output-on-failure
```
运行 V5.4 Mohr-Coulomb 强度折减 benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_strength_reduction_benchmark --output-on-failure
```
运行 V5.5 Euler 柱线性屈曲 benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_euler_column_buckling_benchmark --output-on-failure
```
运行 V5.5 波纹壳循环线性屈曲 benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_buckling_corrugated_shell_benchmark --output-on-failure
```
运行 V5.6 roll forming roller kinematics benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_roll_forming_kinematics_benchmark --output-on-failure
```
运行 V5.6 roll forming plastic springback benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_roll_forming_springback_benchmark --output-on-failure
```
运行 V5.7 cohesive 单积分点验收:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R cohesive_contact --output-on-failure
```
运行 V5.7 ball adhesion cohesive benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_ball_adhesion_cohesive_benchmark --output-on-failure
```
运行 V5.8 particle acceptance primitives:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R particle_acceptance --output-on-failure
```
运行 V5.8 dynamic grain container particle benchmark:
```powershell
ctest --test-dir build-win-gcc-16 -C Release -R example_dynamic_grain_container_benchmark --output-on-failure
```
0.4.8 本地记录:
- Windows GCC 16:V4.8 后硬化加入 GMRES、node analytical contact、P1 contact 性能 smoke,并补齐所有文档型 examples 目录后,当前 CTest 记录为 66/66 passed。
- WSL Ubuntu + gfortran 13.3:沿用第三版发布流程复测。
- Windows Intel oneAPI ifx 2026.0 + MSVC:沿用第三版发布流程复测。
V5 当前开发态记录:
- Windows GCC 16 Release:内部 solver 诊断、no-external-solver 回归、非匹配 two-block contact benchmark、大滑移摩擦 benchmark、shell-shell/shell-solid contact benchmark、Mohr-Coulomb 材料点验收、strength reduction benchmark、Euler column buckling benchmark、corrugated shell cyclic buckling benchmark、roll forming kinematics benchmark、roll forming springback benchmark、cohesive 单积分点验收、ball adhesion cohesive benchmark、particle acceptance primitives 和 dynamic grain container particle benchmark 已接入;`ctest --test-dir build-win-gcc-16 -C Release --output-on-failure` 记录为 106/106 passed。
## 12. 常见问题
1. 程序只打印模型摘要,没有计算:
需要显式指定分析模式,例如 `--run` 或 `--static-linear`。
2. 没有输出 VTK 或 CSV:
检查 `--output-interval` 是否为 0,以及输入文件/控制参数是否启用输出。
3. 输入 keyword 被 warning 跳过:
FemLite 只支持 Abaqus inp 子集。不支持 keyword 会跳过,关键数据缺失才报错。
4. 静力求解不收敛:
可先使用 `--static-linear` 检查边界、载荷和材料,再检查约束不足、接触 penalty、材料非线性和载荷增量设置。
5. 接触结果异常:
检查 slave/master surface、face label、法向方向、搜索距离、penalty 和是否存在初始穿透。
## 13. 当前限制
- 不完整兼容 Abaqus 全部 keyword。
- `*SURFACE` 已支持 element/node/analytical plane 子集,但尚不支持完整 Abaqus surface 语义。
- 面-面接触已具备 mortar 权重、mortar 积分点摩擦历史、正则化摩擦、摩擦功输出、BVH 搜索、active set 和 pair 级 augmented penalty 诊断,但仍不是完整工程级 mortar 约束求解器。
- Mohr-Coulomb 当前已具备材料点返回映射、driver、活动集算法一致切线、强度折减参数折减基础和结构级边坡安全系数 benchmark;完整结构级自动 trial 重求解、非线性失稳判据和 PDF 位移/塑性云图复现仍在 V5.4 后续项中完善。
- 线性屈曲当前已具备小规模内部 dense 特征值求解、梁柱几何刚度、Euler 柱 `femlite --buckling` 主程序路径、波纹壳紧凑循环屈曲 benchmark,以及普通 INP 中的小规模 dense `*BUCKLING` 子集;该子集使用已装配线弹性 `K`,并通过 `*BUCKLING GEOMETRIC LINE` 显式给出有限 truss-style `K_G`,通过 `*BUCKLING GEOMETRIC LINE, PRELOAD` 从线性静力预载后的宿主实体应力派生线刚度子集,或在 `*STATIC` 后直接 `*BUCKLING` 时从 C3D4/C3D8 实体预载应力装配 initial-stress `K_G`。静力预载后的完整壳几何刚度、高阶实体几何刚度、完整壳 FE 波纹壳高保真模型和更完整循环扇区约束仍在 V5.5 后续项中完善。
- 循环扇区约束当前支持普通 INP 中的 `*CYCLIC SYMMETRY, SECTORS=n, WAVE=0, DOF=3|6, PENALTY=p`,数据行为显式 `master_node, slave_node` 节点对。主程序会把它展开为 MPC 罚约束;`DOF=3` 适用于实体平移自由度,`DOF=6` 额外映射壳转角自由度。自动边界配对和非零 harmonic wave 主求解语义尚未作为生产输入交付。
- 滚压成形当前已具备刚体辊平移/下压/角速度运动学、角速度参与切向相对速度和正则化牵引的 benchmark,以及基于 J2 多层材料点的塑性成形/卸载回弹 benchmark;主求解器通用滚压成形 step、完整三维工件网格滚压和 restart 驱动多 step 工艺流仍在后续完善。
- S4 几何非线性当前已具备 finite rotation state、S4 finite kinematics、MITC shear、
生产内力、生产切线、section/material 耦合和 drilling 能量项;旧 shell 几何输入别名和
旧生产路径已移除。S3/S6/S8 的 `FINITE_STRAIN` 请求仍会清晰报 unsupported;球冠
V5.11 验收范围是全 S4 finite-strain target deck 的 post-peak load drop 能力证明、
支撑口径和 path 诊断,不声明完整 `uz=-6.2 m` PDF 曲线严格复现。完整 Shell-4/8/16
PDF 曲线匹配、pseudo-arclength branch following 和 late post-peak 性能优化留到后续版本。
- 颗粒耦合当前已具备内置离散球颗粒、颗粒-facet 映射和动态柔性容器紧凑 benchmark;它不是工业规模 DEM 长跑,也不接入外部颗粒求解器。
- 非线性 Newmark-Newton 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
- 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。
## 14. 0.5.3 Diagnostic Output Notes
0.5.3 focuses on explainability. When nonlinear or contact runs fail, users
should inspect:
- nonlinear reason id/name and residual breakdown fields;
- `continuation_path.csv` residual columns:
`residual_total`, `residual_force`, `residual_contact`,
`residual_constraint`, `residual_arc`, `material_failure_count`;
- contact output fields for state counts, penetration/gap norms,
failed projections, active-set flips, slip/friction residuals, multiplier
residuals and augmentation diagnostics.
These fields are meant to separate geometry/search, normal contact, friction,
constraint, linear-solver and material-local causes. They are not a guarantee
that every large industrial AL/mortar contact path will converge in 0.5.3.
## 15. 0.6.0 Lifecycle Diagnostics Notes
0.6.0 adds lifecycle diagnostics for nonlinear runs. Users can inspect whether
a covered nonlinear path is at increment begin, trial begin, iteration result,
accept, reject, cutback, commit or rollback.
For accepted continuation/Riks path output, `continuation_path.csv` keeps the
old columns and appends lifecycle fields:
- `lifecycle_event_id`
- `lifecycle_event_name`
- `lifecycle_audit_status`
- `lifecycle_audit_name`
- `lifecycle_increment`
- `lifecycle_iteration`
- `lifecycle_accept_count`
- `lifecycle_reject_count`
Restart files written by 0.6.0 preserve lifecycle diagnostics for the covered
accepted-increment subset. Older restart files without lifecycle diagnostics
are still accepted by the reader.
Current limitation: lifecycle diagnostics improve explainability and rollback
audit coverage. They do not mean FemLite 0.6.0 has complete industrial
AL/mortar consistent tangent support, generalized mixed-control continuation,
cohesive contact mainline integration or DEM/FEM subcycling.