291 lines
8.8 KiB
Markdown
291 lines
8.8 KiB
Markdown
# 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 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
|
||
- 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。
|