# 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,slip_increment_norm,slip_residual,friction_residual,friction_work,friction_work_total,friction_regularization,ftx,fty,ftz,status,activation_count,release_count,gap_residual,gap_mean,gap_l2,failed_projection_count,active_set_flip_count,open_count,closed_stick_count,closed_slip_count,closed_restick_count,separating_count,state_failed_projection_count,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。 当输出目录启用且存在非线性生命周期状态时,`nonlinear_lifecycle.csv` 记录最新 increment 的事件、失败/切回原因、残差分解、线性求解器 method、 preconditioner、迭代数、状态、残差和 fail class,以及 rollback/commit audit 计数。`continuation_path.csv` 保持旧列顺序,并在尾部追加 Riks/arc 诊断列: `arc_mode`、`arc_predictor_consistent`、`arc_load_reversal`、 `arc_turning_point`、`arc_length`、`arc_load_delta` 和 `arc_predictor_dot`。 `arc_mode=1` 表示载荷型 Riks path,`arc_mode=2` 表示直接位移控制 path。 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.