# FemLite 0.4.3 用户手册 日期:2026-06-24 ## 1. 适用范围 本文档面向 FemLite 0.4.3 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。 FemLite 0.4.3 是船舶接触爆炸结构响应 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 间切换,并提供预条件和迭代统计查询。 - CSV、VTK、restart 和 contact CSV 输出。 - Fortran95 原生接口、C ABI 子集和 Python 调试脚本。 0.4.3 不等价于完整 Abaqus 兼容求解器,也不等价于工程级通用 mortar/摩擦接触最终版。 ## 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 动力学 | 通用选项: | 参数 | 含义 | |---|---| | `--output-dir path` | 设置结果输出目录 | | `--output-interval n` | 设置输出间隔;0 表示不输出步结果 | 示例: ```powershell build-win-gcc-16\femlite.exe examples\ScordelisLo\scordelislo_tri_static.inp --output-dir examples\ScordelisLo\results\tri_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 ``` ## 6. 输入文件 FemLite 使用 Abaqus inp 风格输入文件的子集。0.4.3 常用支持项包括: - `*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 式: ```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 主要用于节点目标/刚性平面接触子集。 - 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` 查询最近一次求解的增量、迭代、残差、位移修正范数和收敛标志,通过 `fem_get_convergence_metrics` 查询相对残差、contact gap residual 和 combined norm,通过 `fem_get_convergence_diagnostics` 查询 cutback 次数、最后步长、最后有效时间、状态码和失败原因码。`fem_set_linear_solver` 可选择 `CG` 或 `BiCGSTAB` 与 `none/Jacobi` 预条件,`fem_get_linear_solver_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/Kirsch` | Kirsch 带孔板静力基准 | | `examples/shell_patch_test` | 壳单元 patch test | | `examples/clamped_square_plate_pressure_pulse` | 固支方板压力脉冲 | | `examples/rigid_sphere_impact_plate` | 刚球冲击板壳接触算例 | | `examples/contact_rigid_plane_indentation` | 刚性平面压入接触算例 | | `examples/contact_two_blocks_compression` | 两实体块面-面压缩接触算例 | | `examples/shell_rigid_plane_contact` | S4 壳-刚性平面接触算例 | | `examples/contact_block_sliding` | 两实体块正则化摩擦滑移接触算例 | 每个示例目录中的 `README.md` 给出几何、材料、边界、生成脚本和运行命令。第四版新增接触示例提供 `run_case.bat`,可在 Windows 下双击自动运行并检查结果。 ## 11. 测试 运行全量测试: ```powershell ctest --test-dir build-win-gcc-16 --output-on-failure ``` 运行指定测试: ```powershell ctest --test-dir build-win-gcc-16 -R "^(contact|implicit_inp|source_size)$" --output-on-failure ``` 0.4.3 本地记录: - Windows GCC 16:34/34 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 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。 - 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。