Complete V5 acceptance milestone

This commit is contained in:
shenw
2026-06-26 12:54:40 +08:00
parent 26639d8dc2
commit a01a4fda24
105 changed files with 8694 additions and 8922 deletions
+132 -15
View File
@@ -1,27 +1,29 @@
# FemLite 0.4.8 用户手册
# FemLite 0.5.x 用户手册
日期:2026-06-24
日期:2026-06-26
## 1. 适用范围
本文档面向 FemLite 0.4.8 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。
本文档面向 FemLite 0.5.x 的使用者,说明如何编译、运行、准备输入文件、查看结果和复现实例。
FemLite 0.4.8 是船舶接触爆炸结构响应 FEM 软件的第四版阶段验收版,当前支持:
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 和外部 file-exchange 后端间切换,并提供预条件、外部后端能力和迭代/残差统计查询。
- 线性求解器可在内部 CG、BiCGSTAB 和 GMRES 间切换,并提供预条件和迭代/残差统计查询;核心模块不依赖第三方或外部稀疏求解器。
- CSV、VTK、restart 和 contact CSV 输出。
- Fortran95 原生接口、C ABI 子集和 Python 调试脚本。
0.4.8 不等价于完整 Abaqus 兼容求解器,也不等价于工程级通用 mortar/摩擦接触最终版。
0.5.x 当前开发态不等价于完整 Abaqus 兼容求解器,也不等价于全部 V5 高保真 benchmark 已完成的最终版。
## 2. 目录概览
@@ -139,6 +141,7 @@ FemLite 使用 Abaqus inp 风格输入文件的子集。0.4.8 常用支持项包
- `*DENSITY`
- `*ELASTIC`
- `*PLASTIC`
- `*MOHR COULOMB`
- `*SOLID SECTION`
- `*SHELL SECTION`
- `*BOUNDARY`
@@ -172,9 +175,28 @@ FemLite 使用 Abaqus inp 风格输入文件的子集。0.4.8 常用支持项包
- 各向同性线弹性:`*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)`
记录最近一次塑性增量。当前结构级强度折减 benchmark 仍在 V5.4 后续项中推进。
## 8. 边界、载荷与接触
常用边界和载荷:
@@ -240,7 +262,7 @@ kind,pair_id,active_count,max_penetration,force_norm,work_estimate,cumulative_wo
`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` 或 `EXTERNAL` 与 `none/Jacobi` 预条件,`fem_get_linear_solver_stats` 查询最近一次线性求解迭代数、残差和状态。C ABI 额外提供 `femlite_set_linear_solver_external_backend`、`femlite_configure_linear_solver_external_file` 和 external diagnostics;file-exchange command 支持 `{manifest:q}`、`{matrix:q}`、`{rhs:q}`、`{solution:q}` 等模板 token。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 整数返回。
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` 查询最近一次线性求解迭代数、残差和状态,`fem_get_linsol_diagnostics` 查询 CSR 矩阵分类、初始残差、最终残差和最终相对残差;其他 method 值会返回错误且不会改变当前设置。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` 默认忽略大规模结果文件。
@@ -261,7 +283,8 @@ Fortran95 API 可通过 `fem_get_convergence_status` 查询最近一次求解的
| `examples/elliptic_membrane` | NAFEMS LE1 椭圆膜缩减静力案例 |
| `examples/membrane_uniaxial_stretching` | 文档参数派生的膜单轴拉伸静力案例 |
| `examples/shell_solid_connection` | 共享节点壳-实体接口静力案例 |
| `examples/strengthReduction` | 强度折减文档派生的线弹性坡体案例 |
| `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 |
@@ -275,18 +298,20 @@ Fortran95 API 可通过 `fem_get_convergence_status` 查询最近一次求解的
| `examples/failure_prediction_in_a_layered_shell` | 四层共享节点壳拉伸回归入口 |
| `examples/pinched_hemispherical_shell` | pinched hemisphere S4 壳动力 smoke |
| `examples/stress_dependent_elasticity` | 分区弹性模量悬臂梁弯曲回归入口 |
| `examples/roll_forming` | 滚压成形文档派生的压紧-摩擦牵引 smoke |
| `examples/roll_forming` | 滚压摩擦 smoke、roller kinematics benchmark 和 springback benchmark |
| `examples/falling_objects` | 多物体显式接触与刚性箱底代表性 smoke |
| `examples/ball_adhesion_decohesion` | 球-膜接触压入 smoke,粘附/脱粘本构为后续能力 |
| `examples/buckling_corrugated_shell` | 波纹锥壳屈曲文档派生的静力预载 smoke |
| `examples/Dynamic_Grain_Packing_of_a_Flexible_Container` | 动态颗粒装填文档派生的柔性容器压力-地面接触 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` | 两实体块面-面压缩接触算例 |
| `examples/contact_two_blocks_compression` | 非匹配两实体块 mortar 压缩接触 benchmark |
| `examples/shell_rigid_plane_contact` | S4 壳-刚性平面接触算例 |
| `examples/contact_block_sliding` | 两实体块正则化摩擦滑移接触算例 |
| `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`。
每个示例目录中的 `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_history.csv`、`strength_reduction_summary.csv`、`plastic_zone.csv` 和 `displacement_probe.csv`,用于检查安全系数 bracket、塑性区和位移探针。`examples/euler_column_buckling` 的 benchmark checker 会生成 `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 接触、映射节点力、容器位移、质量守恒、重叠和能量。
## 11. 测试
@@ -296,18 +321,106 @@ Fortran95 API 可通过 `fem_get_convergence_status` 查询最近一次求解的
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. 程序只打印模型摘要,没有计算:
@@ -330,5 +443,9 @@ ctest --test-dir build-win-gcc-16 -R "^(contact|implicit_inp|source_size)$" --ou
- 不完整兼容 Abaqus 全部 keyword。
- `*SURFACE` 已支持 element/node/analytical plane 子集,但尚不支持完整 Abaqus surface 语义。
- 面-面接触已具备 mortar 权重、mortar 积分点摩擦历史、正则化摩擦、摩擦功输出、BVH 搜索、active set 和 pair 级 augmented penalty 诊断,但仍不是完整工程级 mortar 约束求解器。
- Mohr-Coulomb 当前已具备材料点返回映射、driver、强度折减参数折减基础和结构级边坡安全系数 benchmark;完整结构级自动 trial 重求解、非线性失稳判据和工程切线审计仍在 V5.4 后续项中完善。
- 线性屈曲当前已具备小规模内部 dense 特征值求解、梁柱几何刚度、Euler 柱解析 benchmark 和波纹壳紧凑循环屈曲 benchmark;通用 `*BUCKLING` step、静力预载后的壳/实体几何刚度装配、完整壳 FE 波纹壳高保真模型和循环扇区约束接入主求解流程仍在 V5.5 后续项中完善。
- 滚压成形当前已具备刚体辊平移/下压/角速度运动学、角速度参与切向相对速度和正则化牵引的 benchmark,以及基于 J2 多层材料点的塑性成形/卸载回弹 benchmark;主求解器通用滚压成形 step、完整三维工件网格滚压和 restart 驱动多 step 工艺流仍在后续完善。
- 颗粒耦合当前已具备内置离散球颗粒、颗粒-facet 映射和动态柔性容器紧凑 benchmark;它不是工业规模 DEM 长跑,也不接入外部颗粒求解器。
- 非线性 Newmark-Newton 和复杂壳塑性仍需要更多工程基准和长时间稳定性验证。
- 大型工程算例的并行、内存和接触收敛策略仍需后续版本完善。