# FEM 求解器手册
本文说明 M3Frame 中 FEM 求解器的标准配置方式、常用 XML 关键词、求解流程和验证建议。FEM 的公共入口主要包括:
- `fem/fem_solver_config.h`:FEM 配置数据模型与读取入口。
- `fem/fem_solver_config_io.h`:XML/JSON/YAML 统一配置读入与 `execute_config(...)`。
- `fem/fem_solver_pipeline.h`:FEM 仿真流程调度。
- `fem/fem_solver.h`:FEM 配置数据模型、共享类型和求解器依赖。
头文件职责建议保持分层:
| 文件 | 职责 | 建议使用方式 |
|---|---|---|
| `fem_solver_config.h` | 用户侧统一入口,汇总关键词、pipeline 和配置读入能力。 | 示例程序、pipeline、外部调用优先包含这个文件。 |
| `fem_solver_config_io.h` | 配置文件解析与 `FEMSimulationDocument` 映射实现。 | FEM 内部维护使用,普通案例不需要直接包含。 |
| `fem_solver_keywords.h` | FEM 标准配置关键词常量。 | 需要生成或校验配置文件时使用。 |
| `fem_solver_pipeline.h` | `FEMSimulationPipeline` 的声明与实现,包括 build/execute、输出和监控流程。 | 调度层或高级接口使用。 |
| `fem_solver.h` | FEM 配置数据模型、共享类型和求解器依赖。 | 核心开发时使用,案例代码尽量通过 `fem_solver_config.h` 进入。 |
因此,`fem_solver_config.h` 和 `fem_solver_config_io.h` 不建议合并:前者保持轻量公共入口,后者保留较重的读写实现,便于后续继续支持 XML/JSON/YAML 和减少公共 API 的噪声。
推荐所有工程案例使用 `pipeline.xml` 串联几何、网格、材料、FEM 求解和后处理。单独调试 FEM 时,也可以直接调用 FEM 标准配置文件。
## 推荐案例结构
```text
case/
pipeline.xml
config/
cad.xml
meshing.xml
fem_solver.xml
outputs/
```
典型 `pipeline.xml`:
```xml
```
## FEM 标准 XML 骨架
```xml
```
## 根节点
根节点固定为:
```xml
```
常用属性:
| 属性 | 说明 |
|---|---|
| `name` | 案例名称,用于日志和输出标识。 |
| `problem_type` | 问题类型,默认 `standard`。多孔弹性专用流程使用 `poro_elasticity` 等可识别类型。 |
## 网格输入
```xml
```
FEM 当前以 VTU 网格作为主要输入。网格应包含节点、单元拓扑,并建议包含:
- `material_id`:材料编号。
- `region_id`:区域编号。
- `boundary_id`:边界编号,用于边界条件和载荷选择。
支持的主要单元拓扑:
| 类别 | 单元 |
|---|---|
| 实体 | `tet4`、`hex8`、`wedge`/`wedge6`、`pyramid`/`pyramid5` |
| 面/壳/膜 | `tri3`、`quad4` |
| 梁/索 | `line2` |
| 点质量 | `vertex`/`vertex1` |
## 材料设置
从材料库读取:
```xml
```
也可以直接在 FEM 文件中给出材料参数:
```xml
```
常用属性:
| 属性 | 说明 |
|---|---|
| `id` | 材料编号,网格 `material_id` 会与它关联。 |
| `key` | 材料库中的可读键,例如 `steel.linear_elastic`、`rubber.neo_hookean`。 |
| `model` | 直接指定材料模型,如 `linear_elastic`、`neo_hookean`、`elastoplastic_damage`、`porous_elastoplastic_damage`。 |
| `density` | 密度。 |
| `young_modulus`、`poisson_ratio` | 线弹性参数。 |
| `yield_stress`、`hardening_modulus` | 弹塑性参数。 |
| `damage_threshold`、`damage_rate`、`max_damage` | 损伤参数。 |
| `biot_coefficient`、`initial_porosity`、`permeability0`、`porosity_compressibility` | 多孔介质参数。 |
材料库和材料模型的详细说明见 [material_manual.md](material_manual.md)。
## NodeSet 选择
`NodeSet` 用于把几何/网格上的节点选择成可复用集合。
```xml
```
常用属性:
| 属性 | 说明 |
|---|---|
| `id` | 节点集合名称。 |
| `selector` | 选择方式,常用 `plane`、`nearest`、`explicit`、`boundary_id`、`all`。 |
| `axis` | `plane` 选择用,可取 `x`、`y`、`z`。 |
| `side` | `plane` 选择用,当前源码按坐标极值面选择;`min`/`lower` 选最小坐标面,`max`/`upper`/`top` 选最大坐标面。 |
| `from` | `nearest` 选择可选父节点集,只在该节点集内部寻找最近点。 |
| `tolerance` | 选择容差。 |
| `x`、`y`、`z` | 最近点坐标。 |
| `node_ids` | 显式节点列表,逗号分隔。 |
| `boundary_id` | 按网格边界编号选择。 |
注意:当前 `selector="plane"` 不是按任意 `value` 坐标截面选点,而是选择指定轴向的最小或最大外边界面。如果需要任意内部截面,建议先在网格或后处理阶段生成显式节点列表,或后续扩展 `NodeSet` 选择器。
## 边界条件与载荷
边界条件使用 ``,接触也可以使用 ``。
### 位移约束
```xml
```
支持自由度:
| 自由度 | 说明 |
|---|---|
| `ux`、`uy`、`uz` | 平动自由度。 |
| `rx`、`ry`、`rz` | 转角自由度,梁/壳/膜常用。 |
| `p` 或 `pore_pressure` | 孔压自由度。 |
| `temperature` | 温度自由度。 |
### 外力与体力
```xml
```
### 孔压、温度和通量
```xml
```
### 对称边界、MPC 与刚体参考点
```xml
```
## 梁、索、壳和膜截面
梁单元和索单元使用 `line2` 网格,通过 `` 控制截面:
```xml
```
索/缆网:
```xml
```
壳/膜单元通过 `` 控制厚度和剪切修正:
```xml
```
## 求解器设置
`` 控制物理场、运动学、积分、线性求解器、非线性迭代和稳定化选项。
```xml
```
### 物理场
| `physics` | 说明 |
|---|---|
| `solid` | 固体力学,默认。 |
| `poromechanics` | 位移-孔压耦合。 |
| `thermal_solid` | 热-固体相关自由度。 |
### 运动学
| `kinematics` | 说明 |
|---|---|
| `small_strain` | 小应变。 |
| `total_lagrangian` | Total Lagrangian 大变形。 |
| `updated_lagrangian` | Updated Lagrangian 大变形。 |
### 单元积分
| `integration` | 说明 |
|---|---|
| `gauss` | Gauss 积分,默认。 |
| `lagrange`、`nodal` | Lagrange/节点积分。 |
| `reduced` | 减缩积分。 |
### 线性求解器
| `linear_solver` | 说明 |
|---|---|
| `bicgstab` | 默认迭代求解器。 |
| `cg` 或 `conjugate_gradient` | 共轭梯度。 |
| `jacobi` | Jacobi 迭代。 |
| `gauss_seidel` | Gauss-Seidel 迭代。 |
## 静力学、准静态和动力学
`` 控制时间步和求解类型:
```xml
```
| `analysis` | 说明 |
|---|---|
| `static` | 静力学或准静态单步加载。 |
| `quasi_static` | 多步准静态加载。 |
| `implicit_dynamic` | 隐式动力学。 |
| `explicit_dynamic` | 显式动力学。 |
### 隐式动力学:Newmark-beta
```xml
```
### 隐式动力学:广义 alpha
```xml
```
也可以显式给出:
```xml
```
### 显式动力学:velocity-Verlet
```xml
```
## 非线性控制
强非线性问题建议启用 line search、加载步自动缩减和位移增量限制:
```xml
```
说明:
- `nonlinear_tolerance` 控制残差收敛。
- `energy_convergence` 和 `energy_tolerance` 启用能量收敛检查。
- `line_search` 会与材料状态 commit/rollback 配合,避免失败迭代污染历史变量。
- `load_step_cutback` 用于强非线性不收敛时自动减小加载步。
## 稳定性与锁定控制
```xml
```
建议:
| 问题 | 建议 |
|---|---|
| 近不可压材料 | 优先考虑 `bbar_method` 或 `fbar_method`。 |
| 壳/板剪切锁定 | 使用 `ans_method`、`eas_method` 或剪切锁定控制。 |
| 减缩积分 hourglass | 启用 `hourglass_control`。 |
| 大变形畸变 | 启用网格质量和 Jacobian 监测。 |
## 网格质量和畸变检测
```xml
```
其中:
- `mesh_quality_check` 在初始网格读入后检查质量。
- `distortion_check` 在计算过程中检查单元畸变。
- `min_detF` 用于大变形计算中的变形梯度行列式下限。
- `stop_on_distortion=true` 时发现严重畸变会终止计算。
## 接触设置
节点-面、面-面、双向接触、摩擦、接触阻尼和 mortar 接触可通过 `` 和 `` 共同控制。
```xml
```
接触建议:
- 简单碰撞可先用 penalty 接触。
- 大滑移问题启用 `enable_contact_spatial_search`。
- 主从面不易手动指定时启用 `enable_contact_auto_match`。
- 接触振荡明显时启用 `enable_contact_damping`。
- 工程级面-面压力分布测试可启用 mortar 接触,但应先用接触 benchmark 校验。
## OpenMP 与 CUDA
CPU 多线程:
```xml
```
CUDA:
```xml
```
CUDA 适合显式动力学、大量 Tet4、接触搜索和大规模稀疏线性代数。对于复杂梁壳、强非线性接触、材料路径相关问题,建议先用 CPU/OpenMP 与 CUDA 做小规模一致性测试。
## 输出与监控
```xml
```
输出建议:
- 场变量使用 VTU/PVD。
- 时间历程、反力、能量、误差指标使用 CSV。
- 日志同时用于命令行进度和 `log` 文件保存。
常见输出内容包括:
- 位移、速度、加速度。
- 应力、应变、von Mises、主应力。
- 反力、外力功、应变能、动能。
- 孔压、孔隙率、渗透率。
- 接触穿透量、接触力。
- 材料损伤变量和等效塑性应变。
## 多孔弹性与孔压耦合
多孔介质问题使用:
```xml
```
多孔介质相关材料参数包括:
- `biot_coefficient`
- `initial_porosity`
- `permeability0`
- `porosity_compressibility`
典型验证包括 Terzaghi 一维固结、排水/不排水压缩、位移-孔压 patch test。
## 后处理
FEM 后处理入口为 `fem/fem_post.h`。常用任务:
- 反力按边界汇总。
- 应变能密度、外力功和内能平衡检查。
- von Mises 与主应力输出。
- Patch test 误差汇总。
- CSV 时间历程输出。
后处理配置建议单独放在 `config/post.xml`,由 pipeline 的 post stage 或 benchmark 程序调用。
## 常见问题
### 线性问题没有一步收敛
检查:
- 约束是否足以消除刚体模态。
- 载荷单位和材料刚度是否量级合理。
- 网格是否存在负体积、退化单元或错误节点顺序。
- `linear_solver`、`linear_tolerance` 和 `max_linear_iterations` 是否足够。
### 大变形计算发散
检查:
- 是否启用合适的 `kinematics`。
- `min_detF` 是否过小或单元严重畸变。
- 材料切线是否适配当前大变形模型。
- 是否需要 `line_search`、`load_step_cutback` 和 `max_displacement_increment`。
### 接触穿透明显
检查:
- `contact_penalty` 是否过小。
- `contact_search_radius` 是否覆盖可能接触距离。
- 主从面方向、边界编号和法向是否正确。
- 显式动力学中时间步是否过大。
- 是否需要接触阻尼或双向接触。
### 动力学结果振荡过强
检查:
- 时间步是否满足稳定性要求。
- 是否需要 Rayleigh 阻尼:`rayleigh_alpha`、`rayleigh_beta`。
- 隐式动力学可考虑 `generalized_alpha`。
- 显式动力学可启用 `adaptive_time_step`。
## 推荐验证顺序
1. Tet4/Hex8 patch test。
2. Tri3/Quad4 patch test。
3. 单轴拉伸/压缩。
4. 梁拉伸、弯曲、扭转。
5. 壳/板膜内拉伸、纯弯曲、剪切锁定测试。
6. 体力、面力积分和反力平衡。
7. MPC、刚体参考点和 NodeSet 选择测试。
8. J2 弹塑性、损伤、卸载/循环加载材料路径测试。
9. Total Lagrangian / Updated Lagrangian 大变形测试。
10. 无摩擦、库仑摩擦、Hertz、mortar 和大滑移接触测试。
11. 多孔弹性和渗流-变形耦合 patch test。
12. 工程级网格收敛和畸变鲁棒性测试。
## 求解模式选择建议
| 目标问题 | 推荐 `analysis` | 推荐 `time_integration` | 说明 |
|---|---|---|---|
| 小变形线弹性静力 | `static` | 可省略 | 最简单,优先用于 patch test、单轴拉伸、受压块。 |
| 接触或材料非线性准静态 | `quasi_static` | 可省略 | 建议启用 `line_search`、`load_step_cutback` 和 `energy_convergence`。 |
| 低频结构瞬态 | `implicit_dynamic` | `newmark_beta` | 平均加速度法稳定,适合较大时间步。 |
| 需要数值高频耗散 | `implicit_dynamic` | `generalized_alpha` | 通过 `spectral_radius_infinity` 控制高频耗散。 |
| 冲击、碰撞、自由落体 | `explicit_dynamic` | `velocity_verlet` | 建议启用 `adaptive_time_step`,严格控制接触刚度和时间步。 |
| 多孔介质固结 | `quasi_static` 或专用 `poro_elasticity` | 视案例而定 | 需要孔压边界、Biot 系数、渗透率和储水项。 |
一般顺序是先用静力或准静态做同一网格的基准验证,再切换到动力学。如果动力学结果异常,优先检查质量矩阵、初始速度、阻尼、时间步和接触参数。
## 标准 FEM XML 检查清单
提交计算前建议逐项检查:
- `Mesh path` 是否存在,且 VTU 能正常读入。
- 网格是否包含正确的 `material_id`、`region_id`、`boundary_id`。
- `` 的 `id` 是否与网格 `material_id` 匹配。
- `NodeSet` 是否能选中预期节点,特别是平面容差 `tolerance`。
- 位移约束是否足以消除刚体模态。
- 载荷方向和单位是否与模型坐标系一致。
- 大变形问题是否设置了 `kinematics="total_lagrangian"` 或 `updated_lagrangian`。
- 动力学问题是否给出了合理的 `density`、`dt`、`steps` 和初始条件。
- 接触问题是否设置了合理的 `contact_search_radius` 和 `contact_penalty`。
- 输出目录是否与案例目录一致,避免写到旧路径。
推荐最小 FEM 配置由以下标签组成:
```xml
```
## 时间积分参数速查
### Newmark-beta
平均加速度法:
```xml
```
适用场景:
- 结构低频响应。
- 需要比显式动力学更大时间步。
- 接触不太剧烈的隐式动力学。
### 广义 alpha
```xml
```
建议:
- `spectral_radius_infinity` 越小,高频耗散越强。
- 若位移响应被过度平滑,可增大到 `0.8` 到 `1.0`。
- 若高频振荡明显,可降低到 `0.5` 到 `0.8`。
### Velocity-Verlet
```xml
```
建议:
- 显式动力学时间步应由单元尺寸、材料波速和接触刚度共同约束。
- 接触 penalty 太大时会显著降低稳定时间步。
- 结果出现穿透或能量爆炸时,优先减小 `dt` 或开启 `adaptive_time_step`。
## 载荷和边界的建模建议
### 位移边界
优先使用 `NodeSet`,避免直接在 XML 中写大量 `node_ids`:
```xml
```
直接指定节点只适合很小的单元测试:
```xml
```
### 面力和压力
均布面力建议通过 `boundary_id` 或 `face_ids` 施加:
```xml
```
曲面内压/外压可使用 `RadialPressure`:
```xml
```
### 体力
重力可以用 `body_force`:
```xml
```
体力方向与单位要和几何长度单位、密度单位保持一致。如果几何使用米、密度使用 `kg/m^3`,重力用 `m/s^2`。
## 接触参数调试顺序
接触问题建议按以下顺序调试:
1. 先关闭摩擦,只保留无摩擦法向 penalty 接触。
2. 选择较小时间步或准静态加载,确认不会发生明显穿透。
3. 调整 `contact_penalty`,使穿透量可接受且不导致迭代发散。
4. 设置 `contact_search_radius` 覆盖可能的接触距离。
5. 启用 `enable_contact_spatial_search` 改善大模型接触搜索效率。
6. 再启用 `friction_coefficient`、`tangential_penalty_ratio`。
7. 动力学碰撞中启用 `enable_contact_damping`,减少非物理反弹。
8. 面-面压力分布敏感时,再考虑 `enable_mortar_contact`。
接触常用组合:
```xml
```
## 大变形建模建议
小应变、大变形 Total Lagrangian 和 Updated Lagrangian 的适用范围不同:
| 运动学 | 适用场景 | 应力度量 |
|---|---|---|
| `small_strain` | 小变形、小转动 | 小应变应力。 |
| `total_lagrangian` | 参考构型清晰、网格不频繁更新 | Green-Lagrange 应变、Second Piola-Kirchhoff 应力。 |
| `updated_lagrangian` | 当前构型主导、接触和大位移更明显 | 当前构型应变、Cauchy 应力。 |
示例:
```xml
```
大变形问题建议同时输出:
- `current_position`
- `reference_position`
- 应力/应变张量
- `von_mises`
- `principal_stress`
- `strain_energy_density`
- `detF` 或 Jacobian 监控日志
## 多孔介质配置建议
多孔介质算例需要同时检查固体骨架和孔压自由度:
```xml
```
建议先运行:
- 一维固结。
- 排水/不排水压缩。
- 位移-孔压 patch test。
- 多孔弹塑性压缩。
确认孔压边界、Biot 系数、渗透率演化和块矩阵装配正确后,再进入复杂工程模型。
## 输出字段和后处理建议
VTU/PVD 用于空间场,CSV 用于时间历程。
推荐 VTU 字段:
| 字段 | 位置 | 用途 |
|---|---|---|
| `displacement` | PointData | 位移。 |
| `velocity` | PointData | 动力学速度。 |
| `acceleration` | PointData | 动力学加速度。 |
| `external_force` | PointData | 外力。 |
| `internal_force` | PointData | 内力。 |
| `reaction_force` | PointData | 反力。 |
| `stress` | CellData | 单元平均应力。 |
| `strain` | CellData | 单元平均应变。 |
| `von_mises` | CellData | 等效应力。 |
| `principal_stress` | CellData | 主应力。 |
| `strain_energy_density` | CellData | 应变能密度。 |
| `damage` | CellData | 损伤变量。 |
| `equivalent_plastic_strain` | CellData | 等效塑性应变。 |
| `pore_pressure` | PointData 或 CellData | 孔压。 |
推荐 CSV 文件:
- `reaction_report.csv`:按边界汇总反力。
- `energy_report.csv`:外力功、内能、动能和能量误差。
- `convergence_report.csv`:每步 Newton 残差和能量范数。
- `contact_report.csv`:最大穿透、接触力和活动接触数。
- `material_history_report.csv`:最大损伤、平均损伤、最大塑性应变。
## 后处理配置入口
`fem/fem_post.h` 提供 `FEMPostProcessor::execute_config(...)`。该入口会根据根标签、`type` 属性或 ``/`` 自动识别后处理任务。它适合 benchmark 和结果复核,不建议把几何建模、网格划分和 FEM 求解都塞进后处理文件中;常规工程流程仍应由 `pipeline.xml` 串联 CAD、meshing、FEM solver 和 post。
源码当前可识别的后处理任务包括:
| 任务 | 可识别名称 | 主要用途 |
|---|---|---|
| von Mises/主应力 | `mises_principal_stress`、`mises_principal`、`principal_stress`、`von_mises` | 检查应力不变量和主应力输出。 |
| 能量平衡 | `energy_balance`、`energy`、`post_energy_test`、`strain_energy` | 输出应变能、外力功、内能平衡误差。 |
| 边界反力 | `boundary_reaction`、`reaction_force` | 按边界汇总反力和力矩。 |
| Patch test | `patch_test` | Tet4/Hex8/Tri3/Quad4 等单元的常应变或线性位移场验证。 |
后处理会向 VTU 中追加:
- 点场:`displacement`、`velocity`、`acceleration`、`external_force`、`internal_force`、`reaction_force`、`reaction_moment`。
- 单元场:`stress`、`strain`、`von_mises`、`principal_stress_1/2/3`、`strain_energy_density`。
边界反力 CSV 推荐格式由 `io::ReactionHistoryCSV` 统一输出,适合后续画时间历程曲线或做解析解对比。
## Solver 高级参数补充
以下参数在源码中已经由 `` 或 `` 读取,适合在非线性、动力学和点质量问题中使用:
| 参数 | 说明 |
|---|---|
| `default_density` 或 `density` | 没有从材料中取得密度时的默认密度。 |
| `point_mass` 或 `mass` | `vertex`/`vertex1` 点质量单元的默认质量。 |
| `rayleigh_alpha`、`rayleigh_beta` | Rayleigh 阻尼系数,阻尼矩阵近似为 `alpha*M + beta*K`。 |
| `line_search_damping` | 初始 line search 阻尼系数。 |
| `line_search_min_damping` | line search 最小可接受阻尼。 |
| `line_search_reduction` | 每次回溯时的阻尼缩减比例。 |
| `line_search_sufficient_decrease` | 充分下降判据参数。 |
| `max_line_search_iterations` | 每个 Newton 迭代内最大 line search 次数。 |
| `thermal_conductivity`、`heat_capacity`、`thermal_source` | `physics="thermal_solid"` 路径中的热传导、热容和热源参数。 |
动力学中建议同时设置材料密度或 `default_density`。如果质量矩阵过小或缺失,显式动力学的稳定时间步和加速度都会变得不可信。
## 示例案例索引
常用 FEM 示例位于 `examples/fem`:
| 目录 | 用途 |
|---|---|
| `uniaxial_loading` | 单轴拉伸/压缩基础验证。 |
| `tet4_patch_test`、`hex8_patch_test` | 实体单元 patch test。 |
| `tri3_quad4_patch_test` | 二维退化或板壳基础验证。 |
| `beam`、`beam_concentrated_force`、`beam_moment` | 梁单元轴拉、弯曲、扭转和解析解对比。 |
| `shell` | 壳/板膜内、弯曲和剪切锁定测试。 |
| `cube_press` | 均匀压缩和反力检查。 |
| `surface_integrate_test`、`body_force_test` | 面力和体力积分验证。 |
| `boundary_test`、`nodeset_pick_test`、`mpc_test`、`rigid_body` | 约束系统验证。 |
| `cnt_*` | 接触、摩擦、mortar、大滑移和 Hertz 接触验证。 |
| `material_*` | 材料路径、泊松比、近不可压、J2、DP、损伤测试。 |
| `ld_*` | 大变形、TL/UL、超弹性和刚体旋转测试。 |
| `poro_*` | 多孔弹性和渗流-变形耦合测试。 |
| `solver_*` | 线性求解器、Newton、line search、rollback 和奇异约束测试。 |
| `mesh_*` | 网格收敛、贴体性、Tet4/Hex8 对比和畸变鲁棒性测试。 |
## 从失败计算中定位问题
建议按以下顺序排查:
1. 查看 log 中的 `step/time/dt`,确认计算是否真正推进。
2. 查看 `residual_history`,判断是线性求解失败还是非线性迭代失败。
3. 查看 `min_jacobian`,确认是否有单元翻转或严重畸变。
4. 查看 `reaction_balance`,确认约束反力与外载是否平衡。
5. 查看 `energy_balance`,确认动力学或接触问题中能量是否爆炸。
6. 查看 `contact_penetration`,确认穿透是否发生在接触搜索半径之外。
7. 查看材料历史变量,确认损伤或塑性变量是否异常跳变。
8. 在 ParaView 中按 `material_id`、`region_id`、`boundary_id` 着色,确认网格分组正确。
如果一个工程算例不稳定,应先构造同材料、同单元、同边界类型的小 benchmark,确认基础路径正确后再回到大模型。
## 源码对照:配置读入路径
当前 FEM 配置读入链路为:
```text
fem_solver_config.h
-> fem_solver_config_io.h
-> io::ConfigIO::read(...)
-> FEMSimulationDocument
-> FEMSimulationPipeline::execute(...)
```
这意味着 XML、JSON、YAML 等格式最终都会先转为 `io::ConfigDocument`,再映射到 `FEMSimulationDocument`。用户侧建议只包含 `fem/fem_solver_config.h`,不要直接依赖旧的 `fem_solver_xml.h` 名称。
`FEMSimulationDocument` 中的主要字段和 XML 标签对应关系如下:
| `FEMSimulationDocument` 字段 | XML 标签/属性 | 说明 |
|---|---|---|
| `name` | `` | 案例名称。 |
| `problem_type` | `` | `standard` 或多孔介质专用流程。 |
| `mesh_path` | `` | VTU 网格输入。 |
| `material_config_path` | `` | 材料库路径。 |
| `material_id/material_key/material_model` | `` | 材料编号、材料库 key 或直接模型名。 |
| `node_sets` | `` | 节点集定义。 |
| `boundaries` | ``、`` | 约束、载荷和接触。 |
| `initial_conditions` | `` | 初始位移、速度、加速度、孔压、温度。 |
| `radial_pressures` | `` | 圆柱/球壳压力类解析测试辅助载荷。 |
| `affine_displacements` | `` | patch test 中的线性位移场。 |
| `options` | ``、`` | 求解器、时间积分、并行和稳定化参数。 |
| `output_*` | `` | VTU/PVD 输出控制。 |
| `monitor` | `` | 命令行和 log 监控。 |
## 源码支持的枚举值
### 物理场和运动学
| 参数 | 支持值 | 源码映射 |
|---|---|---|
| `physics` | `solid`、`poromechanics`、`thermal_solid` | `FEMPhysics`。 |
| `kinematics` | `small_strain`、`updated_lagrangian`、`total_lagrangian` | `FEMKinematics`。 |
| `integration` / `element_integration` | `gauss`、`lagrange`、`langrange`、`nodal`、`reduced`、`reduced_integration` | `FEMElementIntegrationRule`。 |
| `linear_solver` | `jacobi`、`gauss_seidel`、`cg`/`conjugate_gradient`、`bicgstab` | `FEMLinearSolverType`。 |
| `backend` | `cpu`、`serial`、`openmp`、`cuda`、`gpu` | `FEMExecutionBackend`。 |
`lagrange` 和历史拼写 `langrange` 都会被接受。对于工程配置,建议统一写 `lagrange`。
### 分析类型和时间积分
| 参数 | 支持值/别名 | 行为 |
|---|---|---|
| `analysis` | `static`、`quasi_static`、`quasi-static`、`quasistatic` | 准静态或静力流程。 |
| `analysis` | `dynamic`、`transient`、`implicit_dynamic`、`newmark`、`generalized_alpha`、`velocity_verlet` | 动力学流程。 |
| `dynamics_solver` / `solver_type` | `implicit`、`implicit_dynamic` | 隐式动力学。 |
| `dynamics_solver` / `solver_type` | `explicit`、`explicit_dynamic` | 显式动力学。 |
| `time_integration` | `newmark` | 隐式 Newmark。 |
| `time_integration` | `generalized_alpha`、`generalized-alpha` | 广义 alpha。 |
| `time_integration` | `velocity_verlet`、`velocity-verlet`、`verlet` | 显式 Velocity-Verlet。 |
默认约定是:隐式动力学使用 Newmark,显式动力学使用 Velocity-Verlet。若给出 `spectral_radius_infinity`、`generalized_alpha_m` 或 `generalized_alpha_f`,会自动切换到广义 alpha。
### 自由度和边界类型
| 参数 | 支持值 |
|---|---|
| `dof` | `ux`、`uy`、`uz`、`rx`、`ry`、`rz`、`p`/`pore_pressure`、`T`/`temperature` |
| `Boundary type` | `fixed`、`prescribed_displacement`、`prescribed_pore_pressure`、`prescribed_temperature`、`temperature`、`nodal_force`、`surface_traction`、`body_force`、`flux`、`contact`、`symmetry`、`symmetry_plane`、`mpc`、`multi_point_constraint`、`rigid_reference`、`rigid_reference_point` |
| `Contact` | `` 会强制作为接触边界处理,也可用 `` |
## `` 支持字段
`InitialCondition` 会根据 `field` 或 `field_name` 选择变量:
| `field` 值 | 内部字段 |
|---|---|
| `u`、`displacement`、`disp` | 位移 |
| `v`、`velocity`、`vel` | 速度 |
| `a`、`acceleration`、`accel` | 加速度 |
| `p`、`pressure`、`pore_pressure` | 孔压 |
| `temperature`、`temp`、`t` | 温度 |
向量型初值可使用 `x/y/z`,也可使用更具体的 `ux/uy/uz`、`vx/vy/vz`、`ax/ay/az`。标量型初值使用 `value`。`region_id` 或 `region` 小于 0 时作用于全域,否则只作用于对应区域。
示例:
```xml
```
## `` 和 ``
这两个标签主要服务于 patch test、圆筒/球壳压力等 benchmark。
`AffineDisplacement` 支持:
```xml
```
`RadialPressure` 支持:
```xml
```
其中 `direction` 用于控制径向压力方向,`center` 和 `axis` 用于确定径向方向。
## 截面与单元族
`line2` 网格默认按梁单元处理,可通过 `` 切换为索/桁架类单元。
| 标签/属性 | 说明 |
|---|---|
| `` | Euler-Bernoulli/Timoshenko 风格的工程梁路径,使用平动和转角自由度。 |
| `` | Cable/truss 路径,主要使用平动自由度,可设置仅受拉。 |
| `area`、`iy`、`iz`、`j` | 梁截面积、惯性矩和扭转常数。 |
| `cable_area`、`cable_initial_tension`、`cable_tension_only` | 索单元面积、初拉力和仅受拉开关。 |
| `` | 壳/膜厚度。 |
| `shear_correction`、`shear_scale` | 壳剪切修正。 |
| `drilling_stiffness_ratio` | 壳 drilling DOF 稳定化刚度比例。 |
实体单元包括 `Tet4`、`Hex8`、`Wedge6`、`Pyramid5`;面单元包括 `Tri3`、`Quad4`;点质量使用 `Vertex1`。网格 XML 中可写 `wedge`/`pyramid`/`vertex`,进入 FEM 后会归一为 `Wedge6`、`Pyramid5`、`Vertex1`。
## 稳定化和单元质量检查
`` 中的稳定化和质量检查参数如下:
| 参数 | 作用 |
|---|---|
| `shear_locking_control`、`shear_locking_scale` | 剪切锁定缓解,主要用于壳/梁/低阶单元。 |
| `volumetric_locking_control`、`volumetric_locking_factor` | 体积锁定缓解。 |
| `hourglass_control`、`hourglass_stiffness` | 减缩积分或低阶单元的 hourglass 控制。 |
| `bbar_method` | B-bar 体积应变投影路径。 |
| `fbar_method` | F-bar 大变形体积修正路径。 |
| `eas_method`、`eas_stabilization` | EAS 增强假定应变路径。 |
| `ans_method`、`ans_shear_scale` | ANS 假定自然应变路径。 |
| `mesh_quality_check` | 求解前网格质量检查。 |
| `distortion_check`、`stop_on_distortion` | 计算过程中畸变检查和是否遇到畸变立即停止。 |
| `min_cell_measure` | 最小单元体积/面积/长度阈值。 |
| `max_aspect_ratio` | 最大长宽比阈值;为 0 时通常不启用该限制。 |
| `min_detF` | 大变形最小 `det(F)` 阈值。 |
建议:先打开 `mesh_quality_check` 和 `distortion_check`,确认模型稳定后,再逐步测试 B-bar/F-bar/EAS/ANS 等稳定化选项对结果的影响。
## CUDA 参数总表
CUDA 后端通过 `` 开启,细分功能可单独控制:
| 参数 | 说明 |
|---|---|
| `cuda_device` | CUDA 设备编号。 |
| `cuda_explicit_dynamics` 或 `cuda_velocity_verlet` | 显式动力学 Velocity-Verlet 路径 GPU 化。 |
| `cuda_tet4_internal_force` | Tet4 内力 GPU 路径。 |
| `cuda_tet4_material_update` | Tet4 材料更新 GPU 路径。 |
| `cuda_structural_elements` | 梁/壳/膜结构单元的 CUDA 路径。 |
| `cuda_high_fidelity_element_assembly` | 更接近 CPU 单元公式的高保真装配路径。 |
| `cuda_poromechanics_blocks` | 位移-孔压块矩阵和渗流项 CUDA 路径。 |
| `cuda_thermal_blocks` | 热传导块 CUDA 路径。 |
| `cuda_contact_search` | 接触搜索 CUDA 路径。 |
| `cuda_contact_force_scatter` | 接触力 scatter CUDA 路径。 |
| `cuda_global_system_cache` 或 `cuda_resident_global_system` | 全局矩阵/向量 GPU 常驻缓存。 |
| `cuda_sparse_solver` 或 `cuda_linear_solver` | 稀疏线性求解器 CUDA 路径。 |
| `cuda_sparse_jacobi_solver` | CUDA Jacobi 迭代路径。 |
工程建议:CUDA 计算应先在小网格上和 CPU/OpenMP 做位移、内力、能量、接触穿透量的一致性对比,再用于大规模计算。
## 多孔弹性专用配置标签
当根节点设置 `problem_type="poro_elasticity"` 时,`FEMSimulationPipeline::execute_config(...)` 会进入多孔弹性专用流程。源码支持以下专用标签:
| 标签 | 主要属性 | 说明 |
|---|---|---|
| `` | `height`、`drainage` | 固结层厚度和排水条件。 |
| `` | `coefficient_of_consolidation`、`constrained_modulus`、`initial_excess_pore_pressure`、`biot_coefficient`、`fluid_bulk_modulus`、`porosity`、`storage_coefficient`、`hydraulic_conductivity` | 多孔介质解析/半解析测试参数。 |
| `` | `terms` | Terzaghi 级数项数。 |
| `