# 网格与粒子划分
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
```
常用 `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`。例如粗网格和细网格可以共用同一个 `cad.xml`:
```xml
```
## 一维、二维、三维网格
不同 `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
```
如果想完全控制规则网格数量,可以直接设置:
```xml
```
## SPH 粒子划分
标准文件通常命名为 `particle_meshing.xml`:
```xml
```
## 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
```
经验上,`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
```
## 初始速度和场分布
粒子划分阶段可以直接写入初始速度:
```xml
```
部分案例也可使用速度或压力分布参数,例如 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
```
静水压力初始化示例:
```xml
```
## 网格质量
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
```
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
```
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
```
圆孔板示例:
```xml
```
## 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
```
然后在 `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 求解器。