Files
FemLite/docs/07_user_manual.md
shenw 8f9c1ece61
FemLite CI / build-test (push) Has been cancelled
Complete V4.8 hardening and examples coverage
2026-06-25 11:27:59 +08:00

14 KiB
Raw Permalink Blame History

FemLite 0.4.8 用户手册

日期:2026-06-24

1. 适用范围

本文档面向 FemLite 0.4.8 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。

FemLite 0.4.8 是船舶接触爆炸结构响应 FEM 软件的第四版阶段验收版,当前支持:

  • 三维实体和壳单元结构分析。
  • 显式瞬态动力学。
  • 线性静力学和非线性静力学。
  • 隐式 Newmark 和非线性 Newmark-Newton 主流程。
  • 各向同性线弹性、J2 弹塑性、Johnson-Cook 相关材料路径。
  • Abaqus inp 输入子集。
  • element/node/analytical surface 子集、contact property 子集、刚性平面接触和面-面 contact pair 阶段能力。
  • contact pair active set、gap residual 和 augmented penalty 诊断输出。
  • 静力/隐式求解的收敛状态和 cutback 诊断查询接口。
  • 内部线性求解器可在 CG、BiCGSTAB 和 GMRES 间切换,并提供预条件和迭代统计查询。
  • CSV、VTK、restart 和 contact CSV 输出。
  • Fortran95 原生接口、C ABI 子集和 Python 调试脚本。

0.4.8 不等价于完整 Abaqus 兼容求解器,也不等价于工程级通用 mortar/摩擦接触最终版。

2. 目录概览

常用目录:

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

在仓库根目录运行:

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

可执行程序通常位于:

build-win-gcc-16\femlite.exe

4.2 WSL gfortran

在 Windows PowerShell 中可调用 WSL:

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. 命令行用法

基本形式:

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 动力学

通用选项:

参数 含义
--output-dir path 设置结果输出目录
--output-interval n 设置输出间隔;0 表示不输出步结果

示例:

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
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

6. 输入文件

FemLite 使用 Abaqus inp 风格输入文件的子集。0.4.8 常用支持项包括:

  • *NODE
  • *ELEMENT
  • *NSET
  • *ELSET
  • *MATERIAL
  • *DENSITY
  • *ELASTIC
  • *PLASTIC
  • *SOLID SECTION
  • *SHELL SECTION
  • *BOUNDARY
  • *CLOAD
  • *DLOAD
  • *AMPLITUDE
  • *STEP
  • *DYNAMIC
  • *STATIC
  • *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 流动应力、应变率和损伤相关路径为阶段能力,具体格式见设计和示例输入。

密度是动力学分析的必需材料参数。

8. 边界、载荷与接触

常用边界和载荷:

  • *BOUNDARY:节点或集合自由度约束。
  • *CLOAD:集中节点力。
  • *DLOAD:面压力等分布载荷子集。
  • *AMPLITUDE:时间或增量相关幅值。

contact pair 支持两种输入方式。

header 式:

*CONTACT PAIR, SLAVE=slave_target, MASTER=master_target, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION=value, FRICTION_REGULARIZATION=value, AUGMENT=value

contact property 继承式:

*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 主要用于节点目标/刚性平面接触子集。
  • 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 当前字段包含:

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 查询最近一次求解的增量、迭代、残差、位移修正范数和收敛标志,通过 fem_get_convergence_metrics 查询相对残差、contact gap residual 和 combined norm,通过 fem_get_convergence_diagnostics 查询 cutback 次数、最后步长、最后有效时间、状态码和失败原因码。fem_set_linear_solver 可选择 CG、BiCGSTAB 或 GMRES 与 none/Jacobi 预条件,fem_get_linear_solver_stats 查询最近一次线性求解迭代数、残差和状态。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 强度折减文档派生的线弹性坡体案例
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 球冠中心载荷 S4 壳静力回归入口
examples/two_arches 双拱壳-壳接触 smoke
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 分区弹性模量悬臂梁弯曲回归入口
examples/roll_forming 滚压成形文档派生的压紧-摩擦牵引 smoke
examples/falling_objects 多物体显式接触与刚性箱底代表性 smoke
examples/ball_adhesion_decohesion 球-膜接触压入 smoke,粘附/脱粘本构为后续能力
examples/buckling_corrugated_shell 波纹锥壳屈曲文档派生的静力预载 smoke
examples/Dynamic_Grain_Packing_of_a_Flexible_Container 动态颗粒装填文档派生的柔性容器压力-地面接触 smoke
examples/thick_plate NAFEMS LE10 厚板压力静力回归入口
examples/contact_rigid_plane_indentation 刚性平面压入接触算例
examples/contact_two_blocks_compression 两实体块面-面压缩接触算例
examples/shell_rigid_plane_contact S4 壳-刚性平面接触算例
examples/contact_block_sliding 两实体块正则化摩擦滑移接触算例

每个示例目录中的 README.md 给出几何、材料、边界、生成脚本和运行命令。新增基准测试应放在 examples/ 下,并为每个基准案例建立独立文件夹;旧目录可为兼容保留,但新的 CTest 和文档应优先指向独立目录。包含 .inp 的示例目录应提供 run_case.bat,可在 Windows 下双击自动运行,结果默认写入该目录的 results\auto_run。

11. 测试

运行全量测试:

ctest --test-dir build-win-gcc-16 --output-on-failure

运行指定测试:

ctest --test-dir build-win-gcc-16 -R "^(contact|implicit_inp|source_size)$" --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:沿用第三版发布流程复测。

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 约束求解器。
  • 非线性 Newmark-Newton 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
  • 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。