Files
FemLite/docs/07_user_manual.md
T
shenw cde2b82c91
FemLite CI / build-test (push) Has been cancelled
Add user and developer manuals
2026-06-24 17:33:55 +08:00

291 lines
8.8 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.3.3 用户手册
日期:2026-06-24
## 1. 适用范围
本文档面向 FemLite 0.3.3 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。
FemLite 0.3.3 是船舶接触爆炸结构响应 FEM 软件的第三版阶段验收版,当前支持:
- 三维实体和壳单元结构分析。
- 显式瞬态动力学。
- 线性静力学和非线性静力学。
- 隐式 Newmark 和非线性 Newmark-Newton 主流程。
- 各向同性线弹性、J2 弹塑性、Johnson-Cook 相关材料路径。
- Abaqus inp 输入子集。
- 刚性平面接触和面-面 contact pair 阶段能力。
- CSV、VTK、restart 和 contact CSV 输出。
- Fortran95 原生接口、C ABI 子集和 Python 调试脚本。
0.3.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。
## 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.3.3 常用支持项包括:
- `*NODE`
- `*ELEMENT`
- `*NSET`
- `*ELSET`
- `*MATERIAL`
- `*DENSITY`
- `*ELASTIC`
- `*PLASTIC`
- `*SOLID SECTION`
- `*SHELL SECTION`
- `*BOUNDARY`
- `*CLOAD`
- `*DLOAD`
- `*AMPLITUDE`
- `*STEP`
- `*DYNAMIC`
- `*STATIC`
- `*SURFACE`
- `*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
```
数据行式:
```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
*CONTACT PAIR, PENALTY=value, DAMPING=value, SEARCH=value, FRICTION=value
slave_surface, master_surface
```
说明:
- `PENALTY` 必填。
- `DAMPING`、`SEARCH`、`FRICTION` 可选,默认 0。
- `SLAVE` 和 `MASTER` 可为 surface 名称、elset 名称、element id 字符串或 `ALL`。
- `*SURFACE` 当前支持 `TYPE=ELEMENT` 子集。
- 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,ftx,fty,ftz
```
建议把大型结果输出到 `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` | 刚球冲击板壳接触算例 |
每个示例目录中的 `README.md` 给出几何、材料、边界、生成脚本和运行命令。
## 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.3.3 本地记录:
- Windows GCC 16:33/33 passed。
- WSL Ubuntu + gfortran 13.3:33/33 passed。
- Windows Intel oneAPI ifx 2026.0 + MSVC:33/33 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-target 子集,尚不支持完整 node-based/analytic rigid surface。
- 面-面接触已具备 mortar 权重、摩擦历史和 BVH 搜索,但仍不是完整工程级 mortar 约束求解器。
- 非线性 Newmark-Newton 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
- 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。