Files
MDHelper/docs/fem_manual.md
T
2026-05-25 17:12:00 +08:00

1214 lines
45 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.
# 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
<M3FramePipeline version="1.0" name="fem_case">
<Stages>
<Stage kind="geometry" path="config/cad.xml" />
<Stage kind="meshing" mesh_type="volume" path="config/meshing.xml" />
<Stage kind="solver" solver="fem" path="config/fem_solver.xml" />
</Stages>
</M3FramePipeline>
```
## FEM 标准 XML 骨架
```xml
<M3FrameFEMSimulation version="1.0" name="uniaxial_tension" problem_type="standard">
<Mesh path="outputs/mesh.vtu" />
<MaterialLibrary path="material/builtin_materials.xml" />
<Material id="1" key="steel.linear_elastic" />
<NodeSet id="bottom" selector="plane" axis="z" side="min" tolerance="1e-8" />
<NodeSet id="top" selector="plane" axis="z" side="max" tolerance="1e-8" />
<Boundary name="bottom_fixed" type="fixed" node_set="bottom" />
<Boundary name="top_uz" type="prescribed_displacement" node_set="top" dof="uz" value="0.001" />
<Solver physics="solid"
kinematics="small_strain"
integration="gauss"
linear_solver="bicgstab"
linear_tolerance="1e-10"
nonlinear_tolerance="1e-8"
max_linear_iterations="1000"
max_nonlinear_iterations="20" />
<Control analysis="static" dt="1.0" steps="1" />
<Output directory="outputs/fem" prefix="uniaxial" pvd="uniaxial.pvd" output_interval="1" />
<Monitor enabled="true" log="outputs/fem/uniaxial.log"
reaction_balance="true"
residual_history="true"
min_jacobian="true" />
</M3FrameFEMSimulation>
```
## 根节点
根节点固定为:
```xml
<M3FrameFEMSimulation version="1.0" name="case_name" problem_type="standard">
```
常用属性:
| 属性 | 说明 |
|---|---|
| `name` | 案例名称,用于日志和输出标识。 |
| `problem_type` | 问题类型,默认 `standard`。多孔弹性专用流程使用 `poro_elasticity` 等可识别类型。 |
## 网格输入
```xml
<Mesh path="outputs/mesh.vtu" />
```
FEM 当前以 VTU 网格作为主要输入。网格应包含节点、单元拓扑,并建议包含:
- `material_id`:材料编号。
- `region_id`:区域编号。
- `boundary_id`:边界编号,用于边界条件和载荷选择。
支持的主要单元拓扑:
| 类别 | 单元 |
|---|---|
| 实体 | `tet4`、`hex8`、`wedge`/`wedge6`、`pyramid`/`pyramid5` |
| 面/壳/膜 | `tri3`、`quad4` |
| 梁/索 | `line2` |
| 点质量 | `vertex`/`vertex1` |
## 材料设置
从材料库读取:
```xml
<MaterialLibrary path="material/builtin_materials.xml" />
<Material id="1" key="steel.linear_elastic" />
```
也可以直接在 FEM 文件中给出材料参数:
```xml
<Material id="1"
model="linear_elastic"
density="7850"
young_modulus="2.10e11"
poisson_ratio="0.30" />
```
常用属性:
| 属性 | 说明 |
|---|---|
| `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
<NodeSet id="left" selector="plane" axis="x" side="min" tolerance="1e-8" />
<NodeSet id="load_point" selector="nearest" x="1.0" y="0.0" z="0.0" />
<NodeSet id="explicit_nodes" selector="explicit" node_ids="0,1,2,3" />
<NodeSet id="wall_nodes" selector="boundary_id" boundary_id="2" />
```
常用属性:
| 属性 | 说明 |
|---|---|
| `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` 选择器。
## 边界条件与载荷
边界条件使用 `<Boundary>`,接触也可以使用 `<Contact>`。
### 位移约束
```xml
<Boundary name="fixed_left" type="fixed" node_set="left" />
<Boundary name="top_uz" type="prescribed_displacement" node_set="top" dof="uz" value="0.001" />
```
支持自由度:
| 自由度 | 说明 |
|---|---|
| `ux`、`uy`、`uz` | 平动自由度。 |
| `rx`、`ry`、`rz` | 转角自由度,梁/壳/膜常用。 |
| `p` 或 `pore_pressure` | 孔压自由度。 |
| `temperature` | 温度自由度。 |
### 外力与体力
```xml
<Boundary name="tip_force" type="nodal_force" node_set="tip" fx="0" fy="0" fz="-100" />
<Boundary name="gravity" type="body_force" fx="0" fy="-9.81" fz="0" />
<Boundary name="pressure_face" type="surface_traction" boundary_id="5" fx="0" fy="0" fz="-1e5" />
```
### 孔压、温度和通量
```xml
<Boundary name="drained_top" type="prescribed_pore_pressure" node_set="top" dof="p" value="0" />
<Boundary name="fixed_temperature" type="prescribed_temperature" node_set="left" value="293.15" />
<Boundary name="fluid_flux" type="flux" boundary_id="3" value="1e-6" />
```
### 对称边界、MPC 与刚体参考点
```xml
<Boundary name="sym_x" type="symmetry_plane" node_set="xmin" dof="ux" />
<Boundary name="slave_tracks_master"
type="mpc"
node_ids="12"
master_node="3"
dof="ux"
slave_coefficient="1.0"
master_coefficient="-1.0" />
<Boundary name="rigid_face"
type="rigid_reference_point"
node_set="rigid_surface"
reference_node="0" />
```
## 梁、索、壳和膜截面
梁单元和索单元使用 `line2` 网格,通过 `<BeamSection>` 控制截面:
```xml
<BeamSection line2_element="beam"
area="1.0e-4"
iy="8.33e-10"
iz="8.33e-10"
j="1.67e-9" />
```
索/缆网:
```xml
<BeamSection line2_element="cable"
cable_area="1.0e-4"
cable_initial_tension="100"
cable_tension_only="true" />
```
壳/膜单元通过 `<ShellSection>` 控制厚度和剪切修正:
```xml
<ShellSection thickness="0.01"
shear_correction="0.8333333333"
shear_scale="1.0"
drilling_stiffness_ratio="1e-3" />
```
## 求解器设置
`<Solver>` 控制物理场、运动学、积分、线性求解器、非线性迭代和稳定化选项。
```xml
<Solver physics="solid"
kinematics="small_strain"
integration="gauss"
linear_solver="bicgstab"
linear_tolerance="1e-10"
nonlinear_tolerance="1e-8"
max_linear_iterations="1000"
max_nonlinear_iterations="20"
line_search="true" />
```
### 物理场
| `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 迭代。 |
## 静力学、准静态和动力学
`<Control>` 控制时间步和求解类型:
```xml
<Control analysis="static" dt="1.0" steps="1" />
```
| `analysis` | 说明 |
|---|---|
| `static` | 静力学或准静态单步加载。 |
| `quasi_static` | 多步准静态加载。 |
| `implicit_dynamic` | 隐式动力学。 |
| `explicit_dynamic` | 显式动力学。 |
### 隐式动力学:Newmark-beta
```xml
<Control analysis="implicit_dynamic"
time_integration="newmark_beta"
newmark_scheme="average_acceleration"
newmark_beta="0.25"
newmark_gamma="0.5"
dt="1.0e-4"
steps="1000" />
```
### 隐式动力学:广义 alpha
```xml
<Control analysis="implicit_dynamic"
time_integration="generalized_alpha"
spectral_radius_infinity="0.8"
dt="1.0e-4"
steps="1000" />
```
也可以显式给出:
```xml
<Control time_integration="generalized_alpha"
generalized_alpha_m="0.0"
generalized_alpha_f="0.3333333333"
newmark_beta="0.4444444444"
newmark_gamma="0.8333333333" />
```
### 显式动力学:velocity-Verlet
```xml
<Control analysis="explicit_dynamic"
time_integration="velocity_verlet"
adaptive_time_step="true"
time_step_safety="0.8"
min_dt="1e-8"
max_dt="1e-5"
dt="1e-6"
steps="10000" />
```
## 非线性控制
强非线性问题建议启用 line search、加载步自动缩减和位移增量限制:
```xml
<Solver line_search="true"
line_search_damping="1.0"
line_search_min_damping="1e-4"
line_search_reduction="0.5"
max_line_search_iterations="10"
energy_convergence="true"
energy_tolerance="1e-10" />
<Control load_step_cutback="true"
load_step_cutback_factor="0.5"
load_step_min_dt="1e-8"
max_load_step_cutbacks="8"
displacement_increment_limit="true"
max_displacement_increment="1e-3" />
```
说明:
- `nonlinear_tolerance` 控制残差收敛。
- `energy_convergence` 和 `energy_tolerance` 启用能量收敛检查。
- `line_search` 会与材料状态 commit/rollback 配合,避免失败迭代污染历史变量。
- `load_step_cutback` 用于强非线性不收敛时自动减小加载步。
## 稳定性与锁定控制
```xml
<Solver shear_locking_control="true"
shear_locking_scale="0.5"
volumetric_locking_control="true"
volumetric_locking_factor="0.25"
hourglass_control="true"
hourglass_stiffness="0.05"
bbar_method="true"
fbar_method="false"
eas_method="false"
eas_stabilization="0.2"
ans_method="true"
ans_shear_scale="0.5" />
```
建议:
| 问题 | 建议 |
|---|---|
| 近不可压材料 | 优先考虑 `bbar_method` 或 `fbar_method`。 |
| 壳/板剪切锁定 | 使用 `ans_method`、`eas_method` 或剪切锁定控制。 |
| 减缩积分 hourglass | 启用 `hourglass_control`。 |
| 大变形畸变 | 启用网格质量和 Jacobian 监测。 |
## 网格质量和畸变检测
```xml
<Solver mesh_quality_check="true"
distortion_check="true"
stop_on_distortion="true"
min_cell_measure="1e-12"
max_aspect_ratio="100"
min_detF="1e-8" />
```
其中:
- `mesh_quality_check` 在初始网格读入后检查质量。
- `distortion_check` 在计算过程中检查单元畸变。
- `min_detF` 用于大变形计算中的变形梯度行列式下限。
- `stop_on_distortion=true` 时发现严重畸变会终止计算。
## 接触设置
节点-面、面-面、双向接触、摩擦、接触阻尼和 mortar 接触可通过 `<Contact>` 和 `<Solver>` 共同控制。
```xml
<Contact name="ball_floor"
type="contact"
slave_boundary_id="10"
master_boundary_id="20"
penalty="1e7"
friction_coefficient="0.2"
contact_damping="10"
use_mortar="false" />
<Solver contact_penalty="1e7"
contact_tolerance="1e-5"
contact_search_radius="0.02"
friction_coefficient="0.2"
tangential_penalty_ratio="0.1"
enable_contact_damping="true"
contact_damping="10"
contact_tangential_damping_ratio="0.2"
enable_contact_spatial_search="true"
enable_contact_auto_match="true"
enable_bidirectional_contact="true"
enable_mortar_contact="false"
mortar_integration_order="2"
enable_augmented_lagrangian_contact="false" />
```
接触建议:
- 简单碰撞可先用 penalty 接触。
- 大滑移问题启用 `enable_contact_spatial_search`。
- 主从面不易手动指定时启用 `enable_contact_auto_match`。
- 接触振荡明显时启用 `enable_contact_damping`。
- 工程级面-面压力分布测试可启用 mortar 接触,但应先用接触 benchmark 校验。
## OpenMP 与 CUDA
CPU 多线程:
```xml
<Solver backend="openmp"
openmp="true"
openmp_threads="4" />
```
CUDA:
```xml
<Solver backend="cuda"
cuda_device="0"
cuda_explicit_dynamics="true"
cuda_tet4_internal_force="true"
cuda_tet4_material_update="true"
cuda_contact_search="true"
cuda_contact_force_scatter="true"
cuda_global_system_cache="true"
cuda_sparse_solver="true" />
```
CUDA 适合显式动力学、大量 Tet4、接触搜索和大规模稀疏线性代数。对于复杂梁壳、强非线性接触、材料路径相关问题,建议先用 CPU/OpenMP 与 CUDA 做小规模一致性测试。
## 输出与监控
```xml
<Output directory="outputs/fem"
prefix="case"
pvd="case.pvd"
output_interval="10" />
<Monitor enabled="true"
log="outputs/fem/case.log"
interval="1"
reaction_balance="true"
energy_balance="true"
momentum_conservation="true"
mass_conservation="true"
residual_history="true"
max_kinematics="true"
min_jacobian="true"
contact_penetration="true"
material_history="true" />
```
输出建议:
- 场变量使用 VTU/PVD。
- 时间历程、反力、能量、误差指标使用 CSV。
- 日志同时用于命令行进度和 `log` 文件保存。
常见输出内容包括:
- 位移、速度、加速度。
- 应力、应变、von Mises、主应力。
- 反力、外力功、应变能、动能。
- 孔压、孔隙率、渗透率。
- 接触穿透量、接触力。
- 材料损伤变量和等效塑性应变。
## 多孔弹性与孔压耦合
多孔介质问题使用:
```xml
<M3FrameFEMSimulation name="poro_case" problem_type="poro_elasticity">
<Mesh path="outputs/poro_mesh.vtu" />
<Material id="6" key="soil.porous_elastoplastic_damage" />
<Solver physics="poromechanics"
kinematics="small_strain"
linear_solver="bicgstab" />
<Boundary name="drained_top" type="prescribed_pore_pressure" node_set="top" dof="p" value="0" />
<Control dt="100.0" steps="100" />
</M3FrameFEMSimulation>
```
多孔介质相关材料参数包括:
- `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`。
- `<Material>` 的 `id` 是否与网格 `material_id` 匹配。
- `NodeSet` 是否能选中预期节点,特别是平面容差 `tolerance`。
- 位移约束是否足以消除刚体模态。
- 载荷方向和单位是否与模型坐标系一致。
- 大变形问题是否设置了 `kinematics="total_lagrangian"` 或 `updated_lagrangian`。
- 动力学问题是否给出了合理的 `density`、`dt`、`steps` 和初始条件。
- 接触问题是否设置了合理的 `contact_search_radius` 和 `contact_penalty`。
- 输出目录是否与案例目录一致,避免写到旧路径。
推荐最小 FEM 配置由以下标签组成:
```xml
<M3FrameFEMSimulation name="case" problem_type="standard">
<Mesh path="outputs/mesh.vtu" />
<MaterialLibrary path="material/builtin_materials.xml" />
<Material id="1" key="steel.linear_elastic" />
<NodeSet id="fixed" selector="plane" axis="x" value="0" tolerance="1e-8" />
<Boundary name="fixed" type="fixed" node_set="fixed" />
<Solver physics="solid" kinematics="small_strain" linear_solver="bicgstab" />
<Control analysis="static" dt="1" steps="1" />
<Output directory="outputs/fem" prefix="case" pvd="case.pvd" />
</M3FrameFEMSimulation>
```
## 时间积分参数速查
### Newmark-beta
平均加速度法:
```xml
<Control analysis="implicit_dynamic"
time_integration="newmark_beta"
newmark_scheme="average_acceleration"
dt="1e-4"
steps="1000" />
```
适用场景:
- 结构低频响应。
- 需要比显式动力学更大时间步。
- 接触不太剧烈的隐式动力学。
### 广义 alpha
```xml
<Control analysis="implicit_dynamic"
time_integration="generalized_alpha"
spectral_radius_infinity="0.7"
dt="1e-4"
steps="1000" />
```
建议:
- `spectral_radius_infinity` 越小,高频耗散越强。
- 若位移响应被过度平滑,可增大到 `0.8` 到 `1.0`。
- 若高频振荡明显,可降低到 `0.5` 到 `0.8`。
### Velocity-Verlet
```xml
<Control analysis="explicit_dynamic"
time_integration="velocity_verlet"
adaptive_time_step="true"
time_step_safety="0.8"
min_dt="1e-8"
max_dt="1e-5"
dt="1e-6"
steps="10000" />
```
建议:
- 显式动力学时间步应由单元尺寸、材料波速和接触刚度共同约束。
- 接触 penalty 太大时会显著降低稳定时间步。
- 结果出现穿透或能量爆炸时,优先减小 `dt` 或开启 `adaptive_time_step`。
## 载荷和边界的建模建议
### 位移边界
优先使用 `NodeSet`,避免直接在 XML 中写大量 `node_ids`:
```xml
<NodeSet id="left" selector="plane" axis="x" value="0.0" tolerance="1e-8" />
<Boundary name="left_fixed" type="fixed" node_set="left" />
```
直接指定节点只适合很小的单元测试:
```xml
<Boundary name="node_0_fixed" type="fixed" node_ids="0" />
```
### 面力和压力
均布面力建议通过 `boundary_id` 或 `face_ids` 施加:
```xml
<Boundary name="top_pressure"
type="surface_traction"
boundary_id="3"
fx="0"
fy="0"
fz="-1e5" />
```
曲面内压/外压可使用 `RadialPressure`:
```xml
<RadialPressure name="inner_pressure"
boundary_id="10"
pressure="1e6"
direction="outward"
cx="0"
cy="0"
cz="0"
axis="z" />
```
### 体力
重力可以用 `body_force`:
```xml
<Boundary name="gravity" type="body_force" fx="0" fy="-9.81" fz="0" />
```
体力方向与单位要和几何长度单位、密度单位保持一致。如果几何使用米、密度使用 `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
<Solver contact_penalty="1e7"
contact_search_radius="0.02"
enable_contact_spatial_search="true"
enable_bidirectional_contact="true"
friction_coefficient="0.0"
enable_contact_damping="true"
contact_damping="5.0" />
```
## 大变形建模建议
小应变、大变形 Total Lagrangian 和 Updated Lagrangian 的适用范围不同:
| 运动学 | 适用场景 | 应力度量 |
|---|---|---|
| `small_strain` | 小变形、小转动 | 小应变应力。 |
| `total_lagrangian` | 参考构型清晰、网格不频繁更新 | Green-Lagrange 应变、Second Piola-Kirchhoff 应力。 |
| `updated_lagrangian` | 当前构型主导、接触和大位移更明显 | 当前构型应变、Cauchy 应力。 |
示例:
```xml
<Solver physics="solid"
kinematics="total_lagrangian"
line_search="true"
energy_convergence="true"
mesh_quality_check="true"
distortion_check="true"
min_detF="0.2" />
```
大变形问题建议同时输出:
- `current_position`
- `reference_position`
- 应力/应变张量
- `von_mises`
- `principal_stress`
- `strain_energy_density`
- `detF` 或 Jacobian 监控日志
## 多孔介质配置建议
多孔介质算例需要同时检查固体骨架和孔压自由度:
```xml
<M3FrameFEMSimulation name="poro_patch" problem_type="poro_elasticity">
<Mesh path="outputs/poro_mesh.vtu" />
<Material id="6"
model="porous_elastoplastic_damage"
young_modulus="5e7"
poisson_ratio="0.3"
density="1800"
biot_coefficient="1.0"
initial_porosity="0.35"
permeability0="1e-12"
porosity_compressibility="1e-9" />
<Solver physics="poromechanics" linear_solver="bicgstab" />
<Boundary name="top_drained" type="prescribed_pore_pressure" node_set="top" dof="p" value="0" />
<Control analysis="quasi_static" dt="100" steps="100" />
</M3FrameFEMSimulation>
```
建议先运行:
- 一维固结。
- 排水/不排水压缩。
- 位移-孔压 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` 属性或 `<PostProcess>`/`<Task>` 自动识别后处理任务。它适合 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 高级参数补充
以下参数在源码中已经由 `<Solver>` 或 `<Control>` 读取,适合在非线性、动力学和点质量问题中使用:
| 参数 | 说明 |
|---|---|
| `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` | `<M3FrameFEMSimulation name="...">` | 案例名称。 |
| `problem_type` | `<M3FrameFEMSimulation problem_type="...">` | `standard` 或多孔介质专用流程。 |
| `mesh_path` | `<Mesh path="..."/>` | VTU 网格输入。 |
| `material_config_path` | `<MaterialLibrary path="..."/>` | 材料库路径。 |
| `material_id/material_key/material_model` | `<Material id="..." key="..." model="..."/>` | 材料编号、材料库 key 或直接模型名。 |
| `node_sets` | `<NodeSet .../>` | 节点集定义。 |
| `boundaries` | `<Boundary .../>`、`<Contact .../>` | 约束、载荷和接触。 |
| `initial_conditions` | `<InitialCondition .../>` | 初始位移、速度、加速度、孔压、温度。 |
| `radial_pressures` | `<RadialPressure .../>` | 圆柱/球壳压力类解析测试辅助载荷。 |
| `affine_displacements` | `<AffineDisplacement .../>` | patch test 中的线性位移场。 |
| `options` | `<Solver .../>`、`<Control .../>` | 求解器、时间积分、并行和稳定化参数。 |
| `output_*` | `<Output .../>` | VTU/PVD 输出控制。 |
| `monitor` | `<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` | `<Contact .../>` 会强制作为接触边界处理,也可用 `<Boundary type="contact" .../>` |
## `<InitialCondition>` 支持字段
`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
<InitialCondition field="velocity" vx="0" vy="-1.0" vz="0" />
<InitialCondition field="pore_pressure" value="100000" region_id="2" />
```
## `<AffineDisplacement>` 和 `<RadialPressure>`
这两个标签主要服务于 patch test、圆筒/球壳压力等 benchmark。
`AffineDisplacement` 支持:
```xml
<AffineDisplacement name="linear_field"
node_set="all_nodes"
ux0="0" uy0="0" uz0="0"
ux_x="0.01" ux_y="0" ux_z="0"
uy_x="0" uy_y="-0.003" uy_z="0"
uz_x="0" uz_y="0" uz_z="-0.003" />
```
`RadialPressure` 支持:
```xml
<RadialPressure name="inner_pressure"
boundary_id="2"
pressure="1.0e6"
direction="outward"
cx="0" cy="0" cz="0"
axis="z" />
```
其中 `direction` 用于控制径向压力方向,`center` 和 `axis` 用于确定径向方向。
## 截面与单元族
`line2` 网格默认按梁单元处理,可通过 `<BeamSection line2_element="cable">` 切换为索/桁架类单元。
| 标签/属性 | 说明 |
|---|---|
| `<BeamSection line2_element="beam">` | Euler-Bernoulli/Timoshenko 风格的工程梁路径,使用平动和转角自由度。 |
| `<BeamSection line2_element="cable">` | Cable/truss 路径,主要使用平动自由度,可设置仅受拉。 |
| `area`、`iy`、`iz`、`j` | 梁截面积、惯性矩和扭转常数。 |
| `cable_area`、`cable_initial_tension`、`cable_tension_only` | 索单元面积、初拉力和仅受拉开关。 |
| `<ShellSection thickness="...">` | 壳/膜厚度。 |
| `shear_correction`、`shear_scale` | 壳剪切修正。 |
| `drilling_stiffness_ratio` | 壳 drilling DOF 稳定化刚度比例。 |
实体单元包括 `Tet4`、`Hex8`、`Wedge6`、`Pyramid5`;面单元包括 `Tri3`、`Quad4`;点质量使用 `Vertex1`。网格 XML 中可写 `wedge`/`pyramid`/`vertex`,进入 FEM 后会归一为 `Wedge6`、`Pyramid5`、`Vertex1`。
## 稳定化和单元质量检查
`<Solver>` 中的稳定化和质量检查参数如下:
| 参数 | 作用 |
|---|---|
| `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 后端通过 `<Solver backend="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(...)` 会进入多孔弹性专用流程。源码支持以下专用标签:
| 标签 | 主要属性 | 说明 |
|---|---|---|
| `<Layer>` | `height`、`drainage` | 固结层厚度和排水条件。 |
| `<Material>` | `coefficient_of_consolidation`、`constrained_modulus`、`initial_excess_pore_pressure`、`biot_coefficient`、`fluid_bulk_modulus`、`porosity`、`storage_coefficient`、`hydraulic_conductivity` | 多孔介质解析/半解析测试参数。 |
| `<Series>` | `terms` | Terzaghi 级数项数。 |
| `<Time>` | `value` | 输出或采样时间。 |
| `<Depth>` | `value` | 孔压采样深度。 |
| `<Compression>` | `type`、`height`、`applied_total_stress`、`drained_pore_pressure` | 排水/不排水压缩测试。 |
| `<PatchTest>` | `type`、`displacement_gradient`、`pressure_gradient` | 位移-孔压块矩阵 patch test。 |
| `<ElastoPlasticCompression>` | `type`、`final_axial_strain`、`final_pore_pressure`、`steps` | 多孔弹塑性压缩测试。 |
| `<Checks>` | `monotonic_tolerance`、`drained_pressure_tolerance`、`final_degree_min`、`block_tolerance` 等 | 自动验证阈值。 |
| `<Visualization>` | `depth_samples` | 一维孔压剖面 VTU 采样点数。 |
| `<Output>` | `report` | CSV 报告路径。 |
`type` 常用值包括 `drained_undrained_compression`、`coupled_patch_test`、`poro_patch_test`、`poro_elasto_plasticity`、`poro_elastoplasticity`。
## 配置文件最小模板
静力/准静态最小模板:
```xml
<M3FrameFEMSimulation name="minimum_static" problem_type="standard">
<Mesh path="outputs/mesh.vtu" />
<MaterialLibrary path="material/builtin_materials.xml" />
<Material id="1" key="steel.linear_elastic" />
<NodeSet id="fixed" selector="plane" axis="x" side="min" />
<Boundary name="fixed" type="fixed" node_set="fixed" />
<Solver physics="solid" kinematics="small_strain" linear_solver="bicgstab" />
<Control analysis="static" dt="1.0" steps="1" />
<Output directory="outputs/fem" prefix="minimum_static" pvd="minimum_static.pvd" />
</M3FrameFEMSimulation>
```
显式动力学最小模板:
```xml
<M3FrameFEMSimulation name="minimum_explicit" problem_type="standard">
<Mesh path="outputs/mesh.vtu" />
<Material id="1" model="neo_hookean" density="1100" young_modulus="1.0e6" poisson_ratio="0.45" />
<Solver physics="solid"
kinematics="updated_lagrangian"
analysis="explicit_dynamic"
dynamics_solver="explicit"
time_integration="velocity_verlet"
adaptive_time_step="true"
time_step_safety="0.7" />
<InitialCondition field="velocity" vx="0" vy="-1" vz="0" />
<Boundary name="gravity" type="body_force" fx="0" fy="-9.81" fz="0" />
<Control analysis="explicit_dynamic" dt="1.0e-6" steps="1000" />
<Output directory="outputs/fem" prefix="minimum_explicit" pvd="minimum_explicit.pvd" output_interval="10" />
<Monitor enabled="true" log="outputs/fem/minimum_explicit.log"
max_kinematics="true" energy_balance="true" min_jacobian="true" />
</M3FrameFEMSimulation>
```