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

604 lines
21 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.
# 网格与粒子划分
M3Frame 将 FEM 网格划分和 SPH 粒子划分分开配置。
推荐案例目录中,网格和粒子划分配置放在 `config/`:
```text
case/
pipeline.xml
config/
cad.xml
meshing.xml
particle_meshing.xml
outputs/
mesh/
particles/
```
`meshing.xml` 用于 FEM 网格,`particle_meshing.xml` 用于 SPH 粒子集。二者都从 `cad.xml` 中读取几何对象。
## FEM 网格划分
标准文件通常命名为 `meshing.xml`:
```xml
<M3FrameMeshing version="1.0" name="mesh" cad="config/cad.xml">
<Defaults mesh_size="0.1"
volume_method="delaunay"
mesh_type="tet4"
generate_boundary_faces="true" />
<Tasks>
<Task id="solid_mesh" source="solid" domain="volume3d" mesh_type="tet4">
<Export format="vtu" path="outputs/mesh/solid_mesh.vtu" />
</Task>
</Tasks>
</M3FrameMeshing>
```
常用 `domain`:
- `curve1d`:线段网格。
- `surface2d`:三角形或四边形曲面网格。
- `volume3d`:四面体或六面体体网格。
常用 `mesh_type`:
- `line2`
- `tri3`
- `quad4`
- `tet4`
- `hex8`
## Meshing XML 关键词
推荐使用以下标准关键词。历史别名可能仍可读取,但新案例应统一使用标准名称。
| 关键词 | 位置 | 说明 |
|---|---|---|
| `M3FrameMeshing` | 根节点 | FEM 网格划分配置根节点。 |
| `version` | 根节点属性 | 配置格式版本。 |
| `name` | 根节点属性 | 网格划分任务名称。 |
| `cad` | 根节点属性 | 输入 CAD 配置文件路径,通常为 `config/cad.xml`。 |
| `Defaults` | 根节点子节点 | 全局默认网格参数。 |
| `Tasks` | 根节点子节点 | 网格划分任务集合。 |
| `Task` | `Tasks` 子节点 | 每个任务引用一个 CAD 对象并生成一个网格。 |
| `id` | `Task` 属性 | 输出网格名称。 |
| `source` | `Task` 属性 | CAD primitive 或 boolean 的 id。 |
| `domain` | `Task` 属性 | `curve1d`、`surface2d`、`volume3d`。 |
| `mesh_type` | 默认或任务属性 | `line2`、`tri3`、`quad4`、`tet4`、`hex8`。 |
| `mesh_size` | 默认或任务属性 | 目标网格尺寸。 |
| `curve_segments` | 默认或任务属性 | 曲线划分段数。 |
| `surface_u_segments` | 默认或任务属性 | 曲面 u 方向采样段数。 |
| `surface_v_segments` | 默认或任务属性 | 曲面 v 方向采样段数。 |
| `volume_x_segments` | 默认或任务属性 | 体网格 x 方向分段数。 |
| `volume_y_segments` | 默认或任务属性 | 体网格 y 方向分段数。 |
| `volume_z_segments` | 默认或任务属性 | 体网格 z 方向分段数。 |
| `volume_method` | 默认或任务属性 | `delaunay`、`voxel_tet`、`body_fitted`。 |
| `material_id` | 默认或任务属性 | 单元材料编号。 |
| `region_id` | 默认或任务属性 | 区域编号。 |
| `compact_unused_nodes` | 默认或任务属性 | 是否清理未使用节点。 |
| `generate_boundary_faces` | 默认或任务属性 | 是否自动提取体网格边界面。 |
| `backend` | 默认或任务属性 | `auto`、`serial`、`openmp`、`mpi`、`cuda`。 |
| `task_type` | `Task` 属性 | 专用任务类型。 |
| `Export` | `Task` 子节点 | 输出设置。 |
| `format` | `Export` 属性 | 输出格式,当前为 `vtu`。 |
| `path` | `Export` 属性 | 输出文件路径。 |
兼容的历史别名:
| 历史别名 | 推荐关键词 | 说明 |
|---|---|---|
| `element_type` | `mesh_type` | 旧单元类型字段。 |
| `topology` | `mesh_type` | 旧拓扑字段。 |
| `material` | `material_id` | 旧材料编号字段。 |
| `region` | `region_id` | 旧区域编号字段。 |
| `type` | `task_type` | 旧专用任务类型字段。 |
常用 `Defaults` 示例:
```xml
<Defaults mesh_size="0.02"
curve_segments="32"
surface_u_segments="48"
surface_v_segments="24"
volume_x_segments="20"
volume_y_segments="20"
volume_z_segments="20"
volume_method="delaunay"
mesh_type="tet4"
material_id="1"
region_id="0"
backend="auto"
compact_unused_nodes="true"
generate_boundary_faces="true" />
```
任务级属性会覆盖 `Defaults`。例如粗网格和细网格可以共用同一个 `cad.xml`:
```xml
<Task id="coarse_tet" source="solid" domain="volume3d" mesh_size="0.05">
<Export format="vtu" path="outputs/mesh/coarse_tet.vtu" />
</Task>
<Task id="fine_tet" source="solid" domain="volume3d" mesh_size="0.02">
<Export format="vtu" path="outputs/mesh/fine_tet.vtu" />
</Task>
```
## 一维、二维、三维网格
不同 `domain` 对应不同几何和单元:
| `domain` | 常用几何 | 常用单元 | 用途 |
|---|---|---|---|
| `curve1d` | `line_segment`、`polyline`、圆弧 | `line2` | 梁、杆、一维路径测试。 |
| `surface2d` | `rectangle_face`、`disk`、球面、圆柱面 | `tri3`、`quad4` | 壳、膜、边界面、可视化表面。 |
| `volume3d` | `box`、`sphere`、`cylinder`、布尔体 | `tet4`、`hex8` | 实体 FEM 网格。 |
规则盒体优先考虑 `hex8`;复杂曲面和布尔体优先考虑 `tet4`。
## `mesh_size` 与分段数
`mesh_size` 是推荐的目标尺寸。对于不同几何,程序会把它转换为合适的分段数:
- 盒体:根据 `length/width/height` 推算 `volume_x_segments`、`volume_y_segments`、`volume_z_segments`。
- 球体:根据球面周长和半周长推算 `segments`、`rings`。
- 圆柱、圆、圆盘:根据圆周长推算周向分段。
- 圆弧和扇形:根据弧长推算分段。
如果同时给出 `mesh_size` 和显式分段数,任务级设置优先;具体几何可能用 `mesh_size` 重新估算更合理的分段数。
示例:
```xml
<Defaults mesh_size="0.02" volume_method="delaunay" mesh_type="tet4" />
```
如果想完全控制规则网格数量,可以直接设置:
```xml
<Task id="block_hex" source="block" domain="volume3d"
mesh_type="hex8"
volume_x_segments="10"
volume_y_segments="5"
volume_z_segments="20" />
```
## SPH 粒子划分
标准文件通常命名为 `particle_meshing.xml`:
```xml
<M3FrameParticleMeshing version="1.0" name="particles" cad="config/cad.xml">
<Defaults spacing="0.01"
mass="0.001"
density="1000"
smoothing_length="0.013"
material="7"
role="fluid" />
<Tasks>
<Task id="fluid_particles" source="fluid_domain">
<Export format="vtu" path="outputs/particles/fluid.vtu" />
</Task>
</Tasks>
</M3FrameParticleMeshing>
```
## Particle Meshing XML 关键词
| 关键词 | 位置 | 说明 |
|---|---|---|
| `M3FrameParticleMeshing` | 根节点 | SPH 粒子划分配置根节点。 |
| `version` | 根节点属性 | 配置格式版本。 |
| `name` | 根节点属性 | 粒子划分任务名称。 |
| `cad` | 根节点属性 | 输入 CAD 配置文件路径。 |
| `Defaults` | 根节点子节点 | 全局粒子采样默认值。 |
| `Tasks` | 根节点子节点 | 粒子采样任务集合。 |
| `Task` | `Tasks` 子节点 | 每个任务生成一个粒子集。 |
| `id` | `Task` 属性 | 粒子集名称。 |
| `source` | `Task` 属性 | CAD primitive 或 union boolean id。 |
| `spacing` | 默认或任务属性 | 粒子间距。 |
| `mass` | 默认或任务属性 | 单粒子质量。 |
| `density` | 默认或任务属性 | 初始密度。 |
| `pressure` | 默认或任务属性 | 初始压力。 |
| `smoothing_length` | 默认或任务属性 | SPH 光滑长度。 |
| `material` | 默认或任务属性 | 材料编号。 |
| `boundary_id` | 默认或任务属性 | 边界编号。 |
| `role` | 默认或任务属性 | `fluid`、`boundary`、`ghost`、`solid`。 |
| `vx/vy/vz` | 默认或任务属性 | 初始速度。 |
| `backend` | 默认或任务属性 | `auto`、`serial`、`openmp`、`mpi`、`cuda`。 |
| `sample_shape` | `Task` 属性 | 特殊采样形状,目前常用 `ellipsoid`。 |
| `cx/cy/cz` | `Task` 属性 | 特殊采样中心。 |
| `rx/ry/rz` | `Task` 属性 | 椭球三个方向半径。 |
| `Export` | `Task` 子节点 | 输出设置。 |
| `format` | `Export` 属性 | 输出格式,当前为 `vtu`。 |
| `path` | `Export` 属性 | 输出文件路径。 |
兼容的历史别名:
| 历史别名 | 推荐关键词 | 说明 |
|---|---|---|
| `boundary` | `boundary_id` | 旧边界编号字段。 |
常用默认值写法:
```xml
<Defaults spacing="0.01"
mass="0.001"
density="1000"
pressure="0"
smoothing_length="0.013"
material="7"
boundary_id="-1"
role="fluid"
vx="0" vy="0" vz="0" />
```
经验上,`smoothing_length` 可先取 `1.2` 到 `1.5` 倍 `spacing`,再根据核函数、截断半径和稳定性调整。
## 支持的粒子采样源
当前粒子划分主要支持从 CAD primitive 或 union boolean 采样:
| source 类型 | 支持情况 |
|---|---|
| `box` | 支持规则笛卡尔采样。 |
| `sphere` | 支持隐式体采样。 |
| `cylinder` | 支持隐式体采样。 |
| `union` boolean | 支持多个 primitive 的并集采样。 |
| `difference` / `intersection` boolean | 粒子划分阶段暂不作为通用路径使用。 |
| `plane` | 无限平面不能作为有限体积采样。 |
如果需要边界实体,推荐在 CAD 中构造有限厚度的 `box`、`cylinder` 或 union 几何,而不是使用无限平面。
## 粒子角色
| `role` | 说明 |
|---|---|
| `fluid` | 流体粒子。 |
| `boundary` | 固壁或边界粒子。 |
| `ghost` | 虚粒子。 |
| `solid` | 固体 SPH 粒子。 |
## 椭球采样
液滴等案例可用任务级参数采样椭球:
```xml
<Task id="droplet" source="droplet_seed"
sample_shape="ellipsoid"
cx="0.0005" cy="0.0005" cz="0.0005"
rx="0.0005" ry="0.0003125" rz="0.0003125" />
```
## 初始速度和场分布
粒子划分阶段可以直接写入初始速度:
```xml
<Task id="moving_wall" source="top_wall"
role="boundary" vx="0.1" vy="0" vz="0"
boundary_id="2" />
```
部分案例也可使用速度或压力分布参数,例如 Couette flow 或静水压力初始化。推荐将复杂物理初始化写在求解器或专门前处理阶段,粒子划分阶段只保存基础粒子属性。
当前内置的简单 profile:
| 参数 | 取值 | 说明 |
|---|---|---|
| `velocity_profile` | `couette_linear` 或 `linear_y` | 按 y 方向线性分布设置 `vx`。 |
| `profile_velocity` | 数值 | 顶部或参考速度。 |
| `profile_origin_y` | 数值 | 线性分布起点。 |
| `profile_height` | 数值 | 线性分布高度。 |
| `pressure_profile` | `hydrostatic_y` 或 `hydrostatic` | 按 y 方向静水压力初始化。 |
| `pressure_reference_y` | 数值 | 静水压力自由面或参考高度。 |
| `gravity_y` | 数值 | y 方向重力加速度。 |
Couette 初始化示例:
```xml
<Task id="fluid" source="fluid_domain"
velocity_profile="couette_linear"
profile_velocity="0.1"
profile_origin_y="0.0"
profile_height="0.01" />
```
静水压力初始化示例:
```xml
<Task id="water" source="water_domain"
pressure_profile="hydrostatic_y"
pressure_reference_y="0.2"
gravity_y="-9.81" />
```
## 网格质量
Tet4 默认推荐 `volume_method="delaunay"`,并启用 sliver 检测、平滑、局部重剖分等质量改进选项。复杂曲面边界请优先检查 `outputs/mesh/*.vtu` 是否贴体。
## 体网格方法选择
| `volume_method` | 说明 | 推荐场景 |
|---|---|---|
| `delaunay` | 默认 Tet4 方法,基于候选点云执行 Delaunay 四面体剖分。 | 通用实体、曲面实体、自动化案例。 |
| `voxel_tet` | 背景规则网格分解为四面体。 | 快速测试、体素式几何、对贴体要求不高的调试。 |
| `body_fitted` | 对已支持的解析体做贴体生成或边界投影。 | 圆柱、球体、曲面 benchmark。 |
如果 `mesh_type="hex8"`,通常生成规则 Hex8 网格,不走 Delaunay Tet4 默认路径。
## Tet4 生成流程
三维四面体网格推荐流程:
```text
Delaunay 初始剖分
-> Sliver 检测
-> Laplacian/Optimization smoothing
-> Edge flip
-> Local remeshing
-> Steiner insertion
-> 再优化
```
推荐 XML 写法:
```xml
<Defaults mesh_size="0.01"
mesh_type="tet4"
volume_method="delaunay"
tet4_sliver_detection="true"
tet4_smoothing="true"
tet4_edge_flip="true"
tet4_local_remeshing="true"
tet4_steiner_insertion="true"
tet4_sliver_quality_threshold="1.0e-4" />
```
Tet4 质量控制关键词:
| 参数 | 推荐默认 | 说明 |
|---|---|---|
| `tet4_sliver_detection` | `true` | 检测瘦长 sliver 单元。 |
| `tet4_smoothing` | `true` | 开启 Laplacian 或优化平滑。 |
| `tet4_edge_flip` | `true` | 局部边/面翻转改善质量。 |
| `tet4_local_remeshing` | `true` | 局部重剖分。 |
| `tet4_steiner_insertion` | `true` | 插入 Steiner 点改善局部质量。 |
| `tet4_smoothing_iterations` | `2` | 平滑迭代次数。 |
| `tet4_max_steiner_points` | `64` | 最大 Steiner 点数。 |
| `tet4_sliver_quality_threshold` | `1.0e-4` | sliver 判定阈值。 |
注意:轻量内置 Delaunay 适合当前自动化案例和中小规模 benchmark。复杂工业 CAD 后续仍建议接入更专业的外部网格器或增强曲面约束 Delaunay。
## Hex8 规则网格
如果几何是规则盒体或结构化区域,可以使用 `mesh_type="hex8"` 生成规则六面体网格:
```xml
<Task id="block_hex"
source="block"
domain="volume3d"
mesh_type="hex8"
nx="10" ny="10" nz="20" />
```
Hex8 更适合规则 patch test、压缩块、单轴加载等验证案例;复杂曲面仍建议使用 Tet4 或更高阶贴体网格。
## 边界面和边界 id
FEM 计算常需要按边界施加载荷、约束或接触。体网格生成时建议开启:
```xml
generate_boundary_faces="true"
```
输出 VTU 中通常应包含:
- 节点或面的 `boundary_id`。
- 单元的 `material_id`。
- 单元的 `region_id`。
如果后续 FEM 约束无法选中边界,优先检查网格文件中是否真的写出了边界 id,而不是先改求解器。
## 专用几何任务
部分 benchmark 会使用专用任务参数,例如厚壁圆筒、厚壁球壳、弹性球接触地面等。
常见参数包括:
| 参数 | 说明 |
|---|---|
| `inner_radius` / `outer_radius` | 厚壁圆筒或球壳内外半径。 |
| `hole_radius` | 圆孔板或环形区域内孔半径;通常可作为 `inner_radius` 的语义别名。 |
| `thickness` | 厚度参数,供部分专用任务或后续扩展使用。 |
| `length` | 圆筒、梁形区域或轴向几何长度。 |
| `radial_divisions` | 径向划分数。 |
| `circumferential_divisions` | 周向划分数。 |
| `axial_divisions` | 轴向划分数。 |
| `inner_boundary_id` / `outer_boundary_id` | 内外边界编号。 |
| `ground_z` / `ground_half_size` | 接触地面位置和大小。 |
| `ball_boundary_id` / `ground_boundary_id` | 球体与地面边界编号。 |
这些任务更适合 benchmark 和验证算例;通用工程几何仍建议通过 CAD primitive、CSG 和标准体网格任务描述。
当前常见 `task_type` / 历史 `type`:
| `task_type` | 说明 |
|---|---|
| `annulus_quad` / `hole_plate` | 圆孔板或环形区域的 Quad 网格。 |
| `thick_cylinder` / `cylinder_shell` | 厚壁圆筒 Hex 网格,适合 Lamé 解验证。 |
| `thick_sphere` / `sphere_shell` | 厚壁球壳 Hex 网格,适合球壳内压验证。 |
| `elastic_ball_ground` / `ball_ground_contact` | 球体实体网格并附加地面接触面。 |
示例:
```xml
<Task id="pressure_cylinder"
task_type="thick_cylinder"
source="thick_cylinder"
domain="volume3d"
mesh_type="hex8"
inner_radius="0.05"
outer_radius="0.10"
length="0.30"
radial_divisions="4"
circumferential_divisions="48"
axial_divisions="12"
inner_boundary_id="10"
outer_boundary_id="20">
<Export format="vtu" path="outputs/mesh/pressure_cylinder.vtu" />
</Task>
```
圆孔板示例:
```xml
<Task id="plate_with_hole"
task_type="annulus_quad"
source="annulus_quad"
domain="surface2d"
mesh_type="quad4"
inner_radius="0.02"
outer_radius="0.10"
radial_divisions="8"
circumferential_divisions="64"
inner_boundary_id="11"
outer_boundary_id="12">
<Export format="vtu" path="outputs/mesh/plate_with_hole.vtu" />
</Task>
```
## Mesh VTU 输出字段
网格 VTU 通常包含:
| 字段 | 位置 | 说明 |
|---|---|---|
| `boundary_id` | PointData / CellData | 节点或边界面的编号。 |
| `material_id` | CellData | 单元材料编号。 |
| `region_id` | CellData | 单元区域编号。 |
`generate_boundary_faces="true"` 时,Tet4 体网格会附加边界三角面,便于 FEM 载荷、约束、接触和后处理选择边界。
## 粒子划分质量检查
SPH 粒子划分后至少检查:
- 粒子数是否符合预期。
- 边界粒子与流体粒子是否重叠。
- `material_id`、`boundary_id`、`role` 是否正确写入 VTU。
- 粒子间距是否均匀,角点和棱边是否缺粒子。
对于多层边界粒子,建议用 ParaView 按 `role` 或 `boundary_id` 着色检查。
## SPH 边界粒子建议
固壁边界粒子建议:
- 壁面厚度取 2 到 3 层粒子间距。
- 壁面块体之间不要重叠。
- 角点和棱边必须连续覆盖。
- Couette、Poiseuille 等通道流在流向和展向可优先使用周期边界,减少端部壁面干扰。
如果需要将水体和壁面分开输出,可在粒子划分阶段分成多个任务:
```xml
<Task id="water_particles" source="water" role="fluid" material="7" boundary_id="-1">
<Export format="vtu" path="outputs/particles/water.vtu" />
</Task>
<Task id="wall_particles" source="tank_wall" role="boundary" material="8" boundary_id="1">
<Export format="vtu" path="outputs/particles/wall.vtu" />
</Task>
```
然后在 `sph_solver.xml` 中同时读取多个粒子文件。
## Particle VTU 输出字段
粒子 VTU 会把每个粒子写成一个 `Vertex` 单元,并输出以下点数据:
| 字段 | 类型 | 说明 |
|---|---|---|
| `density` | scalar | 初始密度。 |
| `mass` | scalar | 粒子质量。 |
| `pressure` | scalar | 初始压力。 |
| `smoothing_length` | scalar | 光滑长度。 |
| `velocity` | vector | 初始速度。 |
| `acceleration` | vector | 初始加速度,通常为 0。 |
| `material_id` | integer scalar | 材料编号。 |
| `boundary_id` | integer scalar | 边界编号。 |
| `role` | integer scalar | 粒子角色编码。 |
SPH 求解器读入粒子时,至少应能识别坐标、质量、密度、光滑长度、材料编号和角色。若 ParaView 中字段长度异常,优先检查粒子 VTU 写出是否完整。
## 并行后端
`backend` 用于选择离散阶段的执行后端:
| 后端 | 说明 |
|---|---|
| `auto` | 由程序自动选择。 |
| `serial` | 单线程路径,便于调试。 |
| `openmp` | 多线程 CPU 路径,适合中等规模网格和粒子。 |
| `mpi` | 分片生成局部 piece,适合分布式扩展。 |
| `cuda` | 当前部分路径可回退到主机或使用 GPU 增强路径,具体以模块实现为准。 |
如果结果异常,建议先用 `serial` 或 `openmp` 复现,再启用更复杂后端。
## 当前实现边界
FEM 网格划分当前重点支持:
- CAD primitive 的曲线、曲面和体网格划分。
- Tet4 默认 Delaunay 体网格路径。
- Hex8 规则体网格和若干 benchmark 专用网格。
- Tet4 边界面提取和未使用节点压缩。
- VTU 输出和读回数量检查。
仍需谨慎对待:
- 从外部 STL/OBJ/STP 反向读入后直接划分。
- 通用 NURBS/B-Rep 高保真曲面约束网格。
- 大规模工业 CAD 的鲁棒 Delaunay 和曲面恢复。
- 完全 CUDA kernel 化的网格生成。
SPH 粒子划分当前重点支持:
- `box`、`sphere`、`cylinder` 和 union primitive 体采样。
- 椭球采样。
- 初始速度、静水压力和 Couette 线性速度 profile。
- VTU 点云输出。
- OpenMP/MPI 风格分片采样。
仍需谨慎对待:
- 直接从 STL/OBJ/STP 表面封闭体采样。
- Poisson disk / blue-noise 高质量采样。
- 自动边界层粒子生成。
- 多相混合采样和变分辨率采样。
- 完全 CUDA kernel 化粒子生成。
## 常见问题
| 现象 | 可能原因 | 建议 |
|---|---|---|
| FEM 网格不贴体 | 几何表面太粗或用了体素化方法 | 提高 `segments/rings`,使用 `delaunay` 或 `body_fitted`。 |
| Tet4 有异常应力单元 | sliver、负体积或节点顺序问题 | 开启质量检查,检查 Jacobian 和 sliver。 |
| Hex8 只适合盒体 | 规则网格不能表达复杂曲面 | 曲面几何改用 Tet4 或专用贴体网格。 |
| 粒子重叠 | 多个采样任务区域重叠 | 拆分不重叠几何或用布尔差集。 |
| 边界漏粒子 | 壁面太薄或角点缺口 | 增加边界层数,检查 `boundary_id`。 |
| 粒子数过少 | `spacing` 太大或几何尺寸太小 | 减小 `spacing`,同步更新 `mass` 和 `smoothing_length`。 |
| 粒子数爆炸 | `spacing` 太小 | 先用粗粒子测试,再逐步细化。 |
| MPI 输出文件带 rank 后缀 | 后端使用分片输出 | 在后处理或 PVD 中按 piece 汇总。 |
| 读回 VTU 数量不一致 | 写出字段或单元数量异常 | 检查 `Export path` 和 VTU 点/单元数组长度。 |
## 推荐检查流程
1. 运行 CAD 阶段,检查几何文件。
2. 运行 meshing 或 particle_meshing 阶段,打开 VTU。
3. 按 `material_id`、`region_id`、`boundary_id`、`role` 着色。
4. 检查节点/粒子数量、包围盒、边界覆盖和曲面贴合。
5. 确认离散结果正确后,再运行 SPH/FEM 求解器。