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

335 lines
14 KiB
Markdown
Raw Permalink 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.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. 目录概览
常用目录:
```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\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
```
## 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 式:
```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` 或 `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. 测试
运行全量测试:
```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.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 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
- 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。