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

1694 lines
74 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.
# SPH 手册
本文档分为两部分:
1. **求解器用户手册**:说明如何组织案例、编写 `pipeline.xml`、`particle_meshing.xml`、`sph_solver.xml`,以及如何设置材料、边界、输出和常用稳定化参数。
2. **理论手册**:说明 M3Frame 当前 SPH 模块背后的主要离散思想、核函数、密度和压力更新、边界处理、表面张力、多相流、固体 SPH 和稳定性机制。
SPH 模块的主要公共入口如下:
- `sph/sph_solver_config.h`:SPH 配置数据模型和读取入口。
- `sph/sph_solver_pipeline.h`:`SPHSimulationPipeline::build/execute/execute_config(...)`。
- `sph/sph_solver_keywords.h`:标准配置关键词常量。
- `sph/sph_discretization.h`:粒子状态、时间推进和整体离散流程。
- `sph/fluid_wcsph.h`:WCSPH 流体动量方程、压力项、黏性、表面张力和壁面相互作用。
- `sph/fluid_isph.h`:ISPH/PPE 压力投影相关功能。
- `sph/boundary_condition.h`、`sph/boundary_region.h`:边界条件、边界区域和壁面模型。
- `sph/sph_post.h`:SPH 后处理,例如流体粒子和壁面粒子拆分输出。
---
# 第一部分:求解器用户手册
## 1. 案例目录结构
推荐新案例使用下面的目录结构:
```text
case/
pipeline.xml
config/
cad.xml
particle_meshing.xml
materials.xml
sph_solver.xml
post_split_particles.xml
outputs/
```
历史 benchmark 中仍可能使用 `data/` 目录,例如:
```text
examples/sph/benchmarks/hydrostatic_tank/
pipeline.xml
data/
cad.xml
particle_meshing.xml
sph_solver.xml
outputs/
```
`data/` 和 `config/` 功能上等价;新文档和新案例建议优先使用 `config/`。
## 2. 通过 pipeline 运行 SPH 案例
典型 `pipeline.xml`:
```xml
<M3FramePipeline version="1.0" name="sph_case">
<Stages>
<Stage kind="geometry" path="config/cad.xml" />
<Stage kind="meshing" mesh_type="particle" path="config/particle_meshing.xml" />
<Stage kind="solver" solver="sph" path="config/sph_solver.xml" />
<Stage kind="post" post="sph_post" path="config/post_split_particles.xml" />
</Stages>
</M3FramePipeline>
```
运行:
```powershell
.\M3Frame.exe path\to\case\pipeline.xml
```
调试时也可以直接运行 SPH 求解器配置:
```powershell
.\M3Frame.exe path\to\case\config\sph_solver.xml
```
## 3. 最小 SPH 求解器配置
```xml
<SPHSimulation>
<Input particles="config/particles.vtu" />
<Domain
min_x="0" min_y="0" min_z="0"
max_x="1" max_y="1" max_z="1" />
<Solver
method="wcsph"
kernel="cubic_spline"
smoothing_length="0.012"
cutoff_radius="0.0264"
time_step="1.0e-5"
steps="1000"
output_interval="100"
integration="euler" />
<MaterialMap>
<Material particle_material="7" library_key="water.newtonian" />
</MaterialMap>
<InitialCondition
body_force_x="0"
body_force_y="-9.81"
body_force_z="0" />
<Boundary
id="2"
type="simple_dynamic_wall"
pressure_floor="0.0"
impenetrability="on"
impenetrability_tolerance="0.002"
impenetrability_velocity_damping="0.8" />
<Output
directory="outputs/sph"
basename="case"
format="vtu"
pvd="on" />
</SPHSimulation>
```
## 4. XML 命名规则
关键词使用小写加下划线,例如:
- `surface_tension_model`
- `density_sum_frequency`
- `gradient_correction`
- `impenetrability_velocity_damping`
布尔值建议使用:
- `on`
- `off`
部分历史配置也兼容 `true/false`,但新案例建议统一使用 `on/off`。
## 5. Solver 与 Boundary 的职责划分
`<Solver>` 只放求解器、时间积分、核函数、黏性、状态方程、周期边界、输出频率等全局求解参数。
`<Boundary>` 只放边界类型、壁面模型、壁面速度、压力地板、排斥力、不可穿透修正、半解析边界积分和 ISPH 壁面 PPE 条件。
边界相关关键词不允许继续写在 `<Solver>` 下。旧关键词也不再兼容。
| 旧关键词 | 新关键词 | 所属节点 |
| --- | --- | --- |
| `boundary_pressure_floor` | `pressure_floor` | `Boundary` |
| `coupled_boundary_repulsion` | `repulsion_coefficient` | `Boundary` |
| `coupled_boundary_repulsion_distance` | `repulsion_distance` | `Boundary` |
| `wall_impenetrability` | `impenetrability` | `Boundary` |
| `wall_impenetrability_tolerance` | `impenetrability_tolerance` | `Boundary` |
| `wall_impenetrability_velocity_damping` | `impenetrability_velocity_damping` | `Boundary` |
## 6. 粒子划分与材料编号
粒子通常由 `particle_meshing.xml` 生成。粒子文件中的 `material` 字段表示粒子材料编号。
例如 `particle_meshing.xml` 中:
```xml
<ParticleRegion name="water" material="7" spacing="0.01" />
```
表示生成的水粒子带有 `material=7`。
`sph_solver.xml` 中:
```xml
<MaterialMap>
<Material particle_material="7" library_key="water.newtonian" />
</MaterialMap>
```
这里的 `particle_material="7"` 指的是从粒子文件读入的材料编号。它与内置材料库中的 XML `Material id="7"` 不是同一个语义层级。
建议理解为:
- `particle_meshing.xml` 的 `material="7"`:写入粒子的材料标签。
- `sph_solver.xml` 的 `particle_material="7"`:选择粒子标签为 7 的那一组粒子。
- `library_key="water.newtonian"`:真正从材料库读取的材料模型。
## 7. 粒子 offset
粒子划分支持 `offset`,用于避免流体粒子与壁面粒子重叠。
```xml
<ParticleRegion
name="fluid"
spacing="0.01"
offset="0.5 0.5 0.5" />
```
`offset="0.5 0.5 0.5"` 表示沿 x、y、z 方向分别偏移 `0.5 * spacing`。
通道流、静水箱、溃坝等含有多层壁面粒子的案例,建议显式检查流体区域和壁面区域的 offset,避免最外层流体粒子与最内层壁面粒子坐标重合。
## 8. Solver 常用关键词
### 基本时间控制
| 关键词 | 含义 |
| --- | --- |
| `method` | 求解方法,例如 `wcsph`、`isph`、`solid_sph`。 |
| `time_step` | 固定时间步长。 |
| `steps` | 总步数。 |
| `output_interval` | 输出间隔。 |
| `integration` | 时间积分方法,例如 `euler`、`velocity_verlet`、`predictor_corrector`。 |
### 核函数和邻域
| 关键词 | 含义 |
| --- | --- |
| `kernel` | 核函数类型,例如 `cubic_spline`。 |
| `smoothing_length` | 光滑长度。 |
| `cutoff_radius` | 截断半径。 |
| `neighbor_search` | 邻域搜索方式。周期边界通常不需要手动设为 `periodic`,代码会根据 `periodic_x/y/z` 和 `Domain` 选择周期 ghost 邻域。 |
### 体力
体力可在 `<InitialCondition>` 中设置:
```xml
<InitialCondition
body_force_x="0"
body_force_y="-9.81"
body_force_z="0" />
```
Poiseuille 通道流中可令体力沿流向:
```xml
<InitialCondition
body_force_x="9.81"
body_force_y="0"
body_force_z="0" />
```
## 9. 密度更新
SPH 流体密度始终通过连续性方程更新。`enable_density_sum` 不是密度更新开关,而是额外的密度求和重初始化开关。
| 关键词 | 默认值 | 含义 |
| --- | --- | --- |
| `enable_density_sum` | `off` | 是否额外启用密度求和修正;连续性方程仍然每步更新密度,该选项只用于周期性重初始化和降低长期密度漂移。 |
| `density_sum_frequency` | `10` | 启用密度求和后,每隔多少步执行一次。 |
示例:
```xml
<Solver
enable_density_sum="on"
density_sum_frequency="10" />
```
静水箱和长时间自由面计算中,密度漂移会逐渐放大,建议启用密度求和重初始化,但不宜每步执行得过强。
## 10. 压力与状态方程
常用状态方程包括:
| 名称 | 适用场景 |
| --- | --- |
| `linear` | 简单弱可压缩问题。 |
| `tait` | 水体自由面和溃坝类 WCSPH。 |
| `ideal_gas` | 气体或教学算例。 |
| `mie_gruneisen` | 冲击、高压或固体动力学。 |
| `tillotson` | 高速冲击或极端状态。 |
弱可压 SPH 通常用人工声速 `c0` 控制密度压缩率。`c0` 太低会导致压力响应迟缓和密度波动;太高会导致时间步要求更严格。
## 11. Riemann-SPH
Riemann-SPH 用于改善强间断、界面和高速流动中的压力振荡。常见设置:
```xml
<Solver riemann_solver="riemann_rusanov" />
```
多相流可启用相间 Riemann 处理:
```xml
<Solver
multiphase_interphase_riemann="on"
multiphase_riemann_dissipation="0.1" />
```
## 12. 黏性模型
### 人工黏性
```xml
<Solver
artificial_viscosity="0.01"
artificial_viscosity_beta="0.0" />
```
人工黏性主要用于数值稳定。若数值看起来像泥浆,通常是 `artificial_viscosity` 或物理黏性过大。
### 物理黏性
支持 Morris/Laminar 黏性、Lo-Shao 黏性离散、可变黏度和多材料黏性平均。
示例:
```xml
<Solver
physical_viscosity="morris"
dynamic_viscosity="0.001" />
```
### 非牛顿流体
工业常见非牛顿模型包括:
- Bingham
- Herschel-Bulkley
- Carreau
- 剪切变稀
- 剪切增稠
- 屈服应力流体
非牛顿模型会根据局部剪切率更新等效黏度,并可通过最小/最大黏度限制避免数值奇异。
## 13. 表面张力
常用模型:
| 模型 | 配置值 | 说明 |
| --- | --- | --- |
| CSF | `surface_tension_model="csf"` | 基于颜色梯度、曲率和连续表面力。 |
| 成对 cohesion | `surface_tension_model="pairwise_cohesion"` | 成对守恒内聚力,适合液滴类案例。 |
| cohesion + adhesion | `surface_tension_model="pairwise_cohesion_adhesion"` | 在 cohesion 基础上加入壁面附着。 |
参数含义:
| 关键词 | 含义 |
| --- | --- |
| `surface_tension` | 物理表面张力系数,通常单位为 N/m。 |
| `surface_tension_cohesion` | pairwise cohesion 模型的数值内聚强度系数。 |
| `surface_tension_adhesion` | 壁面附着强度。 |
| `surface_tension_pair_equilibrium` | 成对力平衡距离参数。 |
| `surface_tension_acceleration_limit` | 表面张力加速度限幅。 |
`surface_tension` 与 `surface_tension_cohesion` 不是同一个量。前者是物理系数,后者是 pairwise 模型中的数值缩放系数。选择 `pairwise_cohesion` 时,`surface_tension` 仍提供物理强度基准,`surface_tension_cohesion` 控制成对力离散强度。
液滴振荡案例建议:
```xml
<Solver
surface_tension_model="pairwise_cohesion"
surface_tension="0.072"
surface_tension_cohesion="1.0"
xsph_epsilon="0.05" />
```
## 14. 周期边界
周期边界适用于通道流、Couette flow、Taylor-Green vortex 等。
```xml
<Domain
min_x="0" min_y="0" min_z="0"
max_x="1" max_y="0.1" max_z="0.1" />
<Solver
periodic_x="on"
periodic_z="on" />
```
使用周期边界时必须给出有效 `Domain`。周期方向上的邻域搜索会构造 ghost view,避免粒子在周期边界附近丢失邻居。
## 15. Boundary 配置
### 基本壁面
```xml
<Boundary
id="2"
type="simple_dynamic_wall"
velocity_x="0"
velocity_y="0"
velocity_z="0"
pressure_floor="0.0"
impenetrability="on"
impenetrability_tolerance="0.002"
impenetrability_velocity_damping="0.8" />
```
常用边界类型:
| 类型 | 说明 |
| --- | --- |
| `wall_no_slip` | 传统无滑移壁面。 |
| `wall_free_slip` | 自由滑移壁面。 |
| `simple_dynamic_wall` | 边界粒子参与密度、压力和温度更新,但位置保持边界约束。 |
| `adami_ghost` | Adami ghost 边界外推。 |
| `coupled_dynamics_solid_wall` | 耦合动力学固体壁面。 |
| `inlet_velocity` | 速度入口。 |
| `outlet_pressure` | 压力出口。 |
| `inlet_buffer` | 入口缓冲区。 |
| `outlet_buffer` | 出口缓冲区。 |
| `periodic` | 周期边界区域。 |
### 壁面模型
推荐使用更清晰的层级:边界类型由 `type` 表示,壁面外推或积分模型由 `wall_model` 表示。
```xml
<Boundary
id="2"
type="wall_no_slip"
wall_model="adami_ghost" />
```
`Solver` 中不再重复定义 `wall_treatment` 或 `wall_model`。
### 边界稳定化参数
| 关键词 | 含义 |
| --- | --- |
| `pressure_floor` | 边界压力下限,避免壁面外推出现过大负压。 |
| `repulsion_coefficient` | 近壁弱排斥力系数,`0.0` 表示关闭。 |
| `repulsion_distance` | 排斥力作用距离。 |
| `impenetrability` | 是否启用几何不可穿透修正。 |
| `impenetrability_tolerance` | 允许穿透容差。 |
| `impenetrability_velocity_damping` | 穿透修正后的法向速度阻尼。 |
`repulsion_*` 和 `impenetrability_*` 不冲突,但物理作用阶段不同:
- `repulsion_*`:动量方程受力阶段的预防性近壁排斥。
- `impenetrability_*`:时间积分后的位置/速度几何纠正。
静水箱优先建议使用 `simple_dynamic_wall + impenetrability`,排斥力设为 0 或很小。
## 16. Adami ghost 边界
Adami ghost 壁面会根据邻近流体粒子外推壁面虚粒子的密度、压力和速度。适合 Couette flow、Poiseuille flow、静水箱等需要较稳定壁面压力的场景。
典型设置:
```xml
<Boundary
id="2"
type="wall_no_slip"
wall_model="adami_ghost"
velocity_x="0"
velocity_y="0"
velocity_z="0"
pressure_floor="0.0" />
```
移动壁面:
```xml
<Boundary
id="3"
type="wall_no_slip"
wall_model="adami_ghost"
velocity_x="0.1"
velocity_y="0"
velocity_z="0" />
```
## 17. 半解析壁面积分
半解析壁面积分用于更高保真的三角面片或曲面边界:
```xml
<Boundary
id="2"
type="wall_no_slip"
wall_model="semi_analytical"
boundary_geometry_integral="on"
boundary_missing_kernel_correction="on"
boundary_corner_stabilization="on"
boundary_integral_area_scale="1.0"
boundary_integral_min_partition="0.05" />
```
相关能力包括:
- 三角面片边界积分。
- 曲面边界积分近似。
- 边界缺失核修正。
- 角点和棱边稳定处理。
- 移动刚体边界一致动量交换。
## 18. ISPH 与 PPE 设置
ISPH 压力泊松方程相关配置包括:
```xml
<Solver
method="isph"
isph_pressure_solver="bicgstab"
isph_pressure_tolerance="1.0e-6"
isph_pressure_max_iterations="200" />
```
固壁 Neumann 和弱式边界积分应放在 `<Boundary>` 中:
```xml
<Boundary
id="2"
type="wall_no_slip"
isph_wall_neumann="on"
isph_wall_weak_boundary_integral="on"
isph_wall_boundary_integral_scale="1.0" />
```
PPE 可结合压力参考点、奇异性诊断、Jacobi/Gauss-Seidel/CG/BiCGSTAB 和预条件器使用。
## 19. 开放边界与 buffer zone
开放边界粒子管理包括:
| 关键词 | 含义 |
| --- | --- |
| `open_boundary_particle_management` | 是否启用开放边界粒子管理。 |
| `open_boundary_spacing` | buffer 粒子间距。 |
| `open_boundary_injection_density` | 入口补粒子密度。 |
| `open_boundary_injection_material` | 入口补粒子材料编号。 |
| `open_boundary_delete_outlet_particles` | 是否删除出口粒子。 |
| `open_boundary_recycle_particles` | 是否循环复用粒子。 |
| `open_boundary_reset_buffer_particles` | 是否重置 buffer 区粒子。 |
| `open_boundary_non_reflecting_outlet` | 是否启用非反射出口。 |
| `open_boundary_nscbc_relaxation` | NSCBC 松弛强度。 |
| `open_boundary_nscbc_probe_distance` | NSCBC 探针距离。 |
## 20. 多相流设置
多相流支持:
- phase/color 标记。
- 大密度比稳定化。
- 界面张力模型。
- drag force。
- mixture model。
- 气液、液固、颗粒流耦合框架。
- conservative volume fraction 演化。
- 压力振荡抑制。
- 相间 Riemann solver。
典型关键词:
```xml
<Solver
multiphase_interphase_riemann="on"
multiphase_riemann_dissipation="0.1" />
```
## 21. 湍流模型
支持:
- SPS turbulence。
- Smagorinsky LES。
- 湍流黏性输出控制。
```xml
<Solver
turbulence_model="smagorinsky"
smagorinsky_constant="0.12"
output_turbulent_viscosity="on" />
```
## 22. 固体 SPH 与断裂
固体 SPH 支持:
- 大变形运动学。
- 变形梯度 `F`。
- 应变率。
- 旋转率。
- Jaumann/Green-Naghdi 客观应力率历史量。
- 初始邻接拓扑 bond list。
- bond damage。
- 拉伸/剪切断裂准则。
- 裂纹面法向。
- 碎片识别。
示例关键词:
```xml
<Solver
method="solid_sph"
solid_identify_fragments="on" />
```
## 23. 自适应与多分辨率
支持:
- particle split/merge。
- 自适应 smoothing length。
- 多分辨率过渡区核修正。
- 质量守恒重采样。
- 物理量保守投影。
示例:
```xml
<Solver
enable_multiresolution_correction="on"
multiresolution_h_ratio_threshold="1.3"
multiresolution_kernel_correction="on"
multiresolution_mass_redistribution="on"
multiresolution_conservative_projection="on"
multiresolution_projection_strength="0.5"
multiresolution_resampling_iterations="2" />
```
## 24. 梯度修正与粒子正则化
常用选项:
```xml
<Solver
gradient_correction="linear"
xsph_epsilon="0.05" />
```
梯度修正用于恢复一阶一致性。对于壁面附近的粒子,边界粒子也应参与修正矩阵构造,否则壁面附近压力和速度梯度会失真。
## 25. GPU 与并行
SPH 包含 CUDA resident 求解路径的框架。相关关键词:
```xml
<Solver enable_cuda_solver_path="on" />
```
当前 CPU 路径仍是最完整、最稳妥的功能路径。CUDA 路径适合大粒子数和显式流体计算,使用前应通过 benchmark 对比 CPU/GPU 的粒子位置、密度、压力和总能量误差。
## 26. 输出与后处理
常规输出:
```xml
<Output
directory="outputs/sph"
basename="case"
format="vtu"
pvd="on" />
```
将流体和壁面分离输出:
```xml
<SPHPost>
<SplitParticles
input="outputs/sph/case.pvd"
output_directory="outputs/split"
by="role" />
</SPHPost>
```
后处理 pipeline:
```xml
<M3FramePipeline version="1.0" name="sph_post">
<Stages>
<Stage kind="post" post="sph_post" path="data/post_split_particles.xml" />
</Stages>
</M3FramePipeline>
```
## 27. 监控与 log
长时间 SPH 计算建议输出:
- step。
- physical time。
- 粒子数。
- 最大速度。
- 最大加速度。
- 密度最小值/最大值。
- 压力最小值/最大值。
- 边界穿透量。
- 总质量。
- 动能、势能、表面能。
监控信息应同时打印到命令行窗口并写入 log 文件,方便判断粒子飞散、压力爆炸或边界失稳发生在哪一步。
## 28. 常见案例设置
### 静水箱
推荐:
- 使用 `simple_dynamic_wall` 或完整 `adami_ghost`。
- 边界粒子至少 2 到 3 层。
- 流体粒子和壁面粒子不能重叠。
- 启用 `impenetrability`。
- `repulsion_coefficient` 设为 0 或很小。
- 启用 `gradient_correction`。
- 适度启用 `enable_density_sum`。
- 时间步要保守。
### 溃坝
推荐:
- 使用 Tait EOS。
- 使用标准 Monaghan 人工黏性,但 alpha 不宜过大。
- 边界使用多层动态壁面粒子。
- 输出水体和壁面分离文件,便于可视化。
### Poiseuille flow
推荐:
- 流向使用周期边界。
- 展向可使用周期边界。
- 体力沿流向。
- 上下壁面使用 `adami_ghost` 或 `simple_dynamic_wall`。
- 主要依赖物理黏性,人工黏性很小。
- benchmark 从结果文件读入速度剖面并与解析解比较。
### Couette flow
推荐:
- x/z 方向周期。
- 上壁面给定切向速度。
- 下壁面固定。
- 上下壁面使用 2 层或更多边界粒子。
- 避免流体粒子与壁面粒子重叠。
### 液滴振荡
推荐:
- 无重力。
- 使用 `pairwise_cohesion`。
- 时间步要小。
- 使用 XSPH 抑制高频噪声。
- 监控液滴主轴长度和总质量。
## 29. 常见问题排查
### 粒子从盒子飞出
检查:
- 边界粒子是否足够厚。
- 流体粒子是否与边界粒子重叠。
- 是否开启 `impenetrability`。
- 时间步是否过大。
- 压力是否出现大负值。
- 声速是否过低。
### 静水箱出现爆炸式膨胀
常见原因:
- 边界压力外推不稳定。
- 密度漂移累积。
- 负压造成张力不稳定。
- 粒子分布无序导致梯度误差放大。
- 排斥力或不可穿透修正过强,向流体注入能量。
建议:
- 关闭强排斥力。
- 保留不可穿透修正但增加速度阻尼。
- 启用密度求和重初始化。
- 降低时间步。
- 检查壁面粒子和水体粒子是否重叠。
### 液滴分团簇聚集
常见原因:
- 表面张力成对力过强。
- 负压张力不稳定。
- 密度求和或压力 EOS 不一致。
- 时间步太大。
建议:
- 降低 `surface_tension_cohesion`。
- 使用加速度限幅。
- 适度增大物理黏性或 XSPH。
- 使用更稳定的压力模型。
### 通道流粒子向内部聚集
常见原因:
- 壁面外推速度方向不正确。
- 边界粒子和流体粒子重叠。
- 周期 ghost 邻域同步不完整。
- 近壁压力地板或排斥力过强。
## 30. SPH XML 关键词总表
本节按 `sph/sph_solver_keywords.h` 和 `sph/sph_solver_config.h` 中已有读取逻辑整理。若本节与旧案例不一致,以源码当前关键词为准。新案例根节点建议使用:
```xml
<M3FrameSPHSimulation version="1.0" name="case_name">
...
</M3FrameSPHSimulation>
```
### 默认值、范围和布尔写法约定
`sph_solver_config.h` 会把 XML 读入 `SPHSimulationDocument`,再写入 `SPHOptions`。如果 XML 中缺少某个关键词,就使用代码默认值。下面的“推荐范围”是工程调参建议,不是强制限制。
布尔值建议写为 `on/off`。配置读取层也能识别常见布尔写法,但新案例统一使用 `on/off` 更清晰。
| 类型 | 推荐写法 | 说明 |
| --- | --- | --- |
| 布尔 | `on`、`off` | 用于开关项,例如 `enable_density_sum="on"`。 |
| 整数 | `0`、`10`、`1000` | 用于步数、频率、材料编号和粒子编号;不应写成带单位字符串。 |
| 实数 | `0.001`、`1.0e-5` | 用于时间步、黏度、长度和数值系数;建议统一使用 SI 单位。 |
| 向量 | 分量关键词 | SPH 配置多用 `vx/vy/vz`、`body_force_x/y/z`。 |
| 枚举 | 小写字符串 | 支持部分同义写法,例如 `velocity_verlet`/`verlet`。 |
常用全局默认值:
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `physics` | `fluid` | `fluid`、`solid` 等 | 决定使用流体、固体或边界物理路径。它会影响力学模型、历史变量和后处理字段。 |
| `formulation` | `wcsph` | 流体常用 `wcsph`,不可压测试可用 `isph` | 决定主要求解方程。`wcsph` 用 EOS 给压力,`isph` 解 PPE,TL/UL 用于固体大变形。 |
| `integration` | `explicit_euler` | 稳态调试用 `explicit_euler`,长时显式动力学可试 `velocity_verlet` | 决定位置和速度推进格式。Verlet 通常比 Euler 更适合长时间动力学。 |
| `kernel` | `wendland` | 自由面流动推荐 Wendland 类核;历史案例可能用 `cubic_spline` | 核函数影响邻居权重、梯度精度和抗粒子配对能力。 |
| `neighbor_search` | `variable_cell` | 大多数案例保持默认 | 邻域搜索策略。周期边界由 `periodic_x/y/z + Domain` 自动触发周期 ghost 搜索。 |
| `skin` | `0.0` | `0` 到数个粒子间距 | 邻域搜索缓冲距离。较大时减少重建频率,但候选邻居和计算量会上升。 |
| `reference_density` | `1000.0` | 水通常 `1000` | 参考密度,参与 EOS、静水压力、归一化和密度漂移判断。 |
| `speed_of_sound` | `20.0` | 通常取最大流速的 10 倍以上 | 弱可压人工声速,越大时间步越小。 |
| `pressure_eos` | `material` | 水体常用材料中的 Tait EOS | 压力来自材料或内置简化 EOS。 |
| `auto_time_step` | `on` | 显式 SPH 推荐开启 | 根据声速、加速度和黏性限制自动收缩时间步,避免固定 dt 在局部高速时失稳。 |
| `cfl` | `0.25` | `0.1` 到 `0.4` | 声速 CFL 系数。越小越稳,计算成本越高。 |
| `min_dt` | `1.0e-12` | 按问题尺度设置 | 自动时间步下限。若下限过大,失稳时无法继续缩小 dt。 |
| `max_dt` | `1.0e30` | 建议设置为期望最大步长 | 自动时间步上限。初始静止问题建议设置有限值,避免首步过大。 |
### 物理模型默认值速查
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `artificial_viscosity` | `0.01` | 水体自由面常用 `0.001` 到 `0.05`;冲击问题可更大 | Monaghan alpha。过大像泥浆。 |
| `artificial_viscosity_beta` | `0.0` | 低速自由面通常 `0`;强冲击可取 `2*alpha` | Monaghan beta。 |
| `physical_viscosity` | `none` | Poiseuille/Couette 推荐 `morris` 或 `lo_shao` | 选择 Navier-Stokes 物理黏性离散。解析通道流应主要依赖该项而非人工黏性。 |
| `dynamic_viscosity` | `0.0` | 水约 `0.001 Pa·s` | 设为正值时会自动启用 Morris 黏性路径。 |
| `kinematic_viscosity` | `0.0` | 水约 `1.0e-6 m^2/s` | 运动黏度 `nu`。与动态黏度的关系为 `mu=rho*nu`。 |
| `viscosity_ratio_limit` | `100.0` | 多材料常用 `10` 到 `1000` | 限制黏度比导致的界面刚性,避免高低黏材料交界处产生异常大力。 |
| `surface_tension` | `0.0` | 水-空气约 `0.072 N/m` | 设为 0 表示关闭表面张力。 |
| `surface_tension_model` | `csf` | 液滴可用 `pairwise_cohesion` | 表面张力离散方式。CSF 依赖曲率估计,pairwise cohesion 更强调成对守恒。 |
| `surface_tension_threshold` | `1.0e-8` | 根据颜色梯度尺度调节 | CSF 界面阈值,用于过滤过小颜色梯度,避免把内部噪声误判为自由面。 |
| `surface_tension_smoothing_iterations` | `0` | `0` 到 `3` | 只对 CSF 平滑有意义;可降低曲率噪声,但会让界面更钝。 |
| `surface_tension_acceleration_limit` | `0.0` | `0` 表示不限幅;不稳定时设置正值 | 限制局部曲率噪声或粒子聚集导致的巨大表面张力加速度。 |
| `surface_tension_cohesion` | `1.0` | `0.1` 到 `2.0` 起试 | pairwise cohesion 数值强度。 |
| `surface_tension_adhesion` | `0.0` | 需要润湿/壁面附着时设正值 | 壁面 adhesion 系数,用于近似液体对固壁的附着或润湿趋势。 |
| `surface_tension_pair_equilibrium` | `1.0` | 内部会夹到合理区间 | pairwise 平衡距离系数。 |
### 稳定化与粒子正则化默认值速查
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `enable_density_sum` | `off` | 静水和长时间自由面可开 | 额外密度求和修正;连续性方程始终更新密度。 |
| `density_sum_frequency` | `10` | `5` 到 `50` 起试 | `enable_density_sum="off"` 时被忽略。 |
| `density_filter` | `none` | 静水可试 `shepard` 或 `delta_sph` | 密度滤波模型,用于降低密度/压力噪声,但会引入额外扩散。 |
| `shepard_filter_frequency` | `0.0` | 正值启用对应频率 | Shepard 滤波频率或间隔控制,用于重归一化密度并减轻长期漂移。 |
| `delta_sph_coefficient` | `0.0` | `0.01` 到 `0.1` 起试 | Delta-SPH 密度扩散。 |
| `particle_regularization` | `none` | 自由面可谨慎试 `particle_shifting` | 粒子正则化类型,用于改善粒子分布无序;过强会扰动真实自由面运动。 |
| `particle_shift_coefficient` | `0.0` | `0.01` 到 `0.1` 起试 | shifting 强度,控制粒子向更均匀分布移动的幅度;过大会引入非物理输运。 |
| `particle_shift_max_fraction` | `0.2` | `0.05` 到 `0.2` | 单步最大 shift 距离占 spacing/h 的比例。 |
| `gradient_correction` | `none` | 静水、边界和固体问题建议 `linear` | 一阶一致性修正,可显著改善壁面附近压力梯度和固体应力梯度。 |
| `free_surface_detection` | `none` | 自由面/表面张力可用 `number_density` 或 `color_gradient` | 自由面识别方法,影响表面张力、开放边界和自由面后处理标记。 |
| `free_surface_threshold` | `0.75` | `0.6` 到 `0.9` 起试 | 自由面识别阈值,决定内部粒子和自由面粒子的分界敏感度。 |
| `enable_xsph` | `off` | 长时自由面可开 | XSPH 开关,用邻域速度平滑粒子输运速度,减少粒子穿插。 |
| `xsph_epsilon` | `0.5` | 常用 `0.02` 到 `0.2`,默认偏强 | XSPH 强度;越大速度场越平滑,但涡结构和剪切梯度会被扩散。 |
| `velocity_damping` | `0.0` | 静力松弛可设小正值 | 全局速度阻尼,用于快速衰减初始扰动;真实瞬态对比中应谨慎使用。 |
### Boundary 默认值速查
`Boundary` 中许多默认值为 `-1`,表示“不覆盖全局默认值”。如果显式写入,则该边界会把对应值应用到选中的边界粒子或求解器选项。
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `type` | `wall_no_slip` | 按物理边界选择 | 边界类型,决定该边界是固壁、入口、出口、周期、耦合接口还是自由面标记。 |
| `boundary_id` | `-1` | 应与粒子文件边界 id 对应 | 负值表示不按 id 匹配;推荐对实体边界粒子使用明确 id。 |
| `wall_model` | 空 | `adami_ghost`、`simple_dynamic_wall`、`semi_analytical` | 壁面模型覆盖,用于指定同一固壁类型下的不同壁面外推或积分方式。 |
| `pressure` | `0.0` | 压力出口或指定壁面压力时使用 | 边界压力值,主要用于压力出口和参考压力边界,不建议代替固壁压力外推。 |
| `density` | `0.0` | 指定密度边界时使用 | 写入后 `prescribe_density=true`。 |
| `buffer_width` | `0.0` | 入口/出口 buffer 通常为数倍 spacing | buffer 宽度,决定开放边界粒子补充、删除和状态松弛的空间范围。 |
| `relaxation_time` | `0.0` | 开放边界松弛用 | 松弛时间,控制 buffer 区向目标速度、密度或压力恢复的快慢。 |
| `pressure_floor` | 不覆盖;全局默认 `0.02` | 静水可用 `0` 到 `0.02` | 边界压力地板系数,用于避免壁面外推负压过大;过大会抬高近壁压力。 |
| `repulsion_coefficient` | 不覆盖;全局默认 `0.01` | 静水建议 `0`,强穿透才小量开启 | 近壁排斥力强度,是受力阶段的防穿透手段;过强会把粒子弹离壁面。 |
| `repulsion_distance` | 不覆盖;全局默认 `0.5` | `0.3` 到 `0.8` 倍 spacing/h 起试 | 排斥力作用距离,决定粒子多近时开始被推离壁面。 |
| `impenetrability` | 不覆盖;全局默认 `off` | 静水箱/容器建议 `on` | 几何不可穿透修正,是积分后的边界保护;不替代真实压力边界。 |
| `impenetrability_tolerance` | 不覆盖;全局默认 `0.0` | 通常取 `0.1` 到 `0.5` 倍 spacing | 穿透容差,越小越严格,但可能导致频繁硬修正。 |
| `impenetrability_velocity_damping` | 不覆盖;全局默认 `0.0` | `0.5` 到 `0.95` 起试 | 法向速度阻尼,用于减少修正后的反弹和能量注入。 |
| `boundary_geometry_integral` | 不覆盖;全局默认 `on` | 半解析壁面使用 | 边界几何积分开关,用真实边界面积和法向补足粒子支持域缺失。 |
| `boundary_missing_kernel_correction` | 不覆盖;全局默认 `on` | 半解析壁面建议开 | 缺失核修正,用于改善近壁密度、压力梯度和黏性项精度。 |
| `boundary_corner_stabilization` | 不覆盖;全局默认 `on` | 角点/棱边建议开 | 角点稳定处理,防止多个壁面交汇处出现法向混乱或粒子从角点逃逸。 |
| `boundary_moving_rigid_momentum_exchange` | 不覆盖;全局默认 `on` | 移动刚体壁面建议开 | 动量交换开关,使移动壁面和流体之间的力学交换更一致。 |
| `boundary_corner_normal_threshold` | 不覆盖;全局默认 `0.65` | `0.5` 到 `0.9` | 角点法向判据,用于判断局部法向变化是否足以触发角点稳定逻辑。 |
| `boundary_integral_area_scale` | 不覆盖;全局默认 `1.0` | 通常 `1.0` | 边界积分面积缩放,用于校准半解析积分贡献。 |
| `boundary_integral_min_partition` | 不覆盖;全局默认 `0.05` | `0.01` 到 `0.1` | 最小边界积分分区/权重下限,避免局部边界贡献过小。 |
### 顶层节点
| 节点 | 作用 |
| --- | --- |
| `Domain` | 计算域、周期边界包围盒。 |
| `Particles` | 输入粒子 VTU 文件。可出现多个。 |
| `Materials` | 材料映射容器。 |
| `MaterialLibrary` | 外部材料库路径。 |
| `Material` | 粒子材料编号到材料库 key 的映射。 |
| `InitialCondition` | 初始速度、密度、压力、质量、材料和角色覆盖。 |
| `BoundaryConditions` | 边界容器。 |
| `Boundary` | 单个边界区域或边界类型。 |
| `Solver` | SPH 求解器、物理模型和数值算法控制。 |
| `Control` | 起止时间、时间步、最大步数和输出间隔。 |
| `Output` | VTU/PVD 输出控制。 |
| `Monitor` | 运行监控和 log 输出控制。 |
### 通用属性
| 关键词 | 说明 |
| --- | --- |
| `name` | 名称。 |
| `path` | 文件路径。 |
| `type` | 类型。 |
| `id` | 编号。 |
| `key` | 材料库或配置 key。 |
| `enabled` | 是否启用。 |
### Domain
| 关键词 | 说明 |
| --- | --- |
| `min_x`、`min_y`、`min_z` | 计算域最小坐标。 |
| `max_x`、`max_y`、`max_z` | 计算域最大坐标。 |
周期边界 `periodic_x/y/z` 依赖有效 `Domain`。
### Particles
| 关键词 | 说明 |
| --- | --- |
| `path` | 输入粒子 VTU 文件路径。 |
示例:
```xml
<Particles path="data/particles.vtu" />
```
### MaterialLibrary 与 Material
| 节点 | 关键词 | 说明 |
| --- | --- | --- |
| `MaterialLibrary` | `path` | 材料库 XML/配置文件路径。相对路径会按配置文件所在目录解析。 |
| `Material` | `id` | 粒子文件中的材料编号,用于把 VTU 中的 `material` 标签映射到具体材料模型。 |
| `Material` | `key` | 材料库 key,例如 `water.newtonian`。建议优先使用 key,而不是依赖内置材料 id 的顺序。 |
| `Material` | `dynamic_viscosity` | 覆盖材料动态黏度,适合在同一材料库 key 下快速测试不同黏度。 |
| `Material` | `kinematic_viscosity` | 覆盖材料运动黏度,适合 Poiseuille/Couette 等直接给定 `nu` 的 benchmark。 |
示例:
```xml
<Materials>
<MaterialLibrary path="material/builtin_materials.xml" />
<Material id="7" key="water.newtonian" />
</Materials>
```
### InitialCondition
| 关键词 | 说明 |
| --- | --- |
| `vx`、`vy`、`vz` | 初始速度。 |
| `density` | 初始密度覆盖。 |
| `pressure` | 初始压力覆盖。 |
| `h` | 初始光滑长度覆盖。 |
| `mass` | 初始质量覆盖。 |
| `material` | 初始材料编号覆盖。 |
| `role` | 初始粒子角色,例如 `fluid`、`boundary`。 |
| `body_force_x`、`body_force_y`、`body_force_z` | 体力加速度,也可在 `Solver` 中读取。 |
### Solver:基础求解控制
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `physics` | `fluid`、`solid`、`porous_solid`、`debris`、`boundary` | 决定粒子按流体、固体或边界物理路径处理。普通水体、气体和自由面流动用 `fluid`;弹性杆冲击、断裂等用 `solid`;该选项会影响后续力学模型和历史变量更新。 |
| `formulation` | `wcsph`、`isph`、`total_lagrangian_solid`/`tl_solid`、`updated_lagrangian_solid`/`ul_solid` | 决定主要离散格式。`wcsph` 用状态方程给压力,适合显式自由面;`isph` 通过 PPE 约束不可压;TL/UL 固体格式用于大变形固体 SPH。 |
| `integration` | `explicit_euler`、`velocity_verlet`/`verlet`、`predictor_corrector` | 控制粒子位置和速度推进。Euler 最简单;Velocity-Verlet 对长时间动力学更稳;Predictor-Corrector 会增加一次预测/修正流程。 |
| `kernel` | 字符串 | 核函数名称,由核函数模块解释。核函数会影响邻域平滑、梯度精度和抗粒子配对能力;自由面和长时间计算建议使用抗配对性较好的核。 |
| `neighbor_search` | 字符串 | 邻域搜索类型,默认 `variable_cell`。通常无需手动改;若启用周期边界,应使用 `periodic_x/y/z + Domain`,不要把它简单理解为普通搜索类型开关。 |
| `skin` | 实数 | 邻域搜索缓冲距离。较大 skin 可减少重建邻域频率,但会增加候选邻居数量;显式大位移问题可适当增大。 |
| `reference_density` | 实数 | 参考密度 `rho0`,用于 EOS、静水压力和归一化。水一般为 `1000`;多材料时应与材料库密度保持一致。 |
| `speed_of_sound` | 实数 | 人工声速 `c0`。越大密度波动越小,但显式稳定时间步越小;WCSPH 通常要求 `c0` 至少为特征流速的 10 倍左右。 |
| `pressure_eos` | `material`、`linear_reference`、`rho_c0_squared` | 选择压力计算路径。`material` 使用材料库 EOS;`linear_reference` 使用 `rho-rho0` 型线性压力;`rho_c0_squared` 使用 `p=rho*c0^2`,通常只适合特定测试。 |
| `pressure_flux` | `symmetric`、`riemann_rusanov`/`rusanov`/`godunov` | 压力相互作用形式。`symmetric` 是传统成对守恒格式;Riemann/Rusanov 可增强间断和多相界面稳定性,但会引入额外耗散。 |
| `fluid_pressure_floor` | 实数 | 流体压力下限。用于限制过大负压和张力不稳定;设置过高会改变真实压力场,静水或液滴案例需谨慎。 |
### Solver:黏性与非牛顿流体
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `artificial_viscosity` | 实数 | Monaghan 人工黏性 alpha,用于抑制粒子穿插和高频速度噪声。自由面水体通常保持很小;过大会让水体表现得像高黏泥浆。 |
| `artificial_viscosity_beta` | 实数 | Monaghan 人工黏性 beta,主要用于强压缩或冲击问题。低速不可压流和静水问题通常设为 0。 |
| `physical_viscosity` | `none`、`morris`/`laminar`、`lo_shao` | 选择物理黏性离散。Poiseuille、Couette 等黏性 benchmark 应使用物理黏性;`lo_shao` 对边界附近黏性扩散更稳。 |
| `dynamic_viscosity` | 实数 | 动态黏度 `mu`,单位通常为 Pa·s。若设为正值而 `physical_viscosity=none`,代码会自动走 Morris 物理黏性路径。 |
| `kinematic_viscosity` | 实数 | 运动黏度 `nu=mu/rho`。与 `dynamic_viscosity` 二选一或保持一致,避免同时给出互相矛盾的黏度尺度。 |
| `viscosity_ratio_limit` | 实数 | 多材料黏度平均时的黏度比限制,避免高黏/低黏界面产生过大剪切力和时间步刚性。 |
| `rheology_model` | `newtonian`、`power_law`、`bingham`、`herschel_bulkley`、`carreau` | 非牛顿流变模型。泥浆、浆料、屈服应力流体可用 Bingham/Herschel-Bulkley;聚合物流体可用 Carreau。 |
| `rheology_min_dynamic_viscosity` | 实数 | 非牛顿等效黏度下限,防止剪切变稀时黏度过低导致时间推进不稳定。 |
| `rheology_max_dynamic_viscosity` | 实数 | 非牛顿等效黏度上限,防止剪切率接近零或屈服区导致等效黏度趋于无穷。 |
| `rheology_consistency_index` | 实数 | 幂律/Herschel-Bulkley 的稠度系数 `K`,直接决定给定剪切率下的黏度幅值。 |
| `rheology_flow_behavior_index` | 实数 | 幂律指数 `n`。`n<1` 表示剪切变稀,`n>1` 表示剪切增稠,`n=1` 退化为牛顿型。 |
| `rheology_yield_stress` | 实数 | 屈服应力。Bingham/Herschel-Bulkley 中用于描述未屈服区;过大时会显著降低流动性。 |
| `rheology_regularization` | 实数 | 屈服应力模型正则化参数,用有限大黏度近似理想屈服行为;数值越大越接近理想屈服,但越刚。 |
| `carreau_zero_shear_viscosity` | 实数 | Carreau 模型低剪切极限黏度,控制流体在近静止区域的高黏平台。 |
| `carreau_infinite_shear_viscosity` | 实数 | Carreau 模型高剪切极限黏度,控制高速剪切区域的低黏平台。 |
| `carreau_time_constant` | 实数 | Carreau 转换时间尺度,决定从低剪切平台过渡到高剪切平台的剪切率位置。 |
| `carreau_exponent` | 实数 | Carreau 指数,控制黏度曲线过渡陡峭程度。 |
### Solver:湍流
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `turbulence_model` | `none`、`sps`、`smagorinsky`/`les` | 选择亚粒子尺度湍流模型。小尺度层流 benchmark 应保持 `none`;高雷诺数自由面流可尝试 LES/SPS。 |
| `smagorinsky_constant` | 实数 | Smagorinsky 常数,控制湍流黏性强度。越大耗散越强,涡结构越容易被抹平。 |
| `sps_coefficient` | 实数 | SPS 模型系数,用于亚粒子应力耗散。需要结合分辨率和实验/解析结果校准。 |
### Solver:表面张力
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `surface_tension` | 实数 | 物理表面张力系数 `sigma`。设置为 0 时表面张力关闭;液滴案例需与粒子尺度和时间步一起校准。 |
| `surface_tension_model` | `csf`、`pairwise_cohesion`、`pairwise_cohesion_adhesion` | 选择表面张力离散。CSF 依赖曲率估计,pairwise cohesion 更成对守恒,液滴保持形状时通常更稳。 |
| `surface_tension_threshold` | 实数 | CSF 中用于判断有效界面法向的阈值。过低会把噪声当界面,过高会漏掉真实自由面。 |
| `surface_tension_smoothing_iterations` | 整数 | CSF 法向/曲率平滑次数。可降低 parasitic current,但过多会扩散界面并改变曲率。 |
| `surface_tension_acceleration_limit` | 实数 | 表面张力加速度限幅。用于防止小粒距或局部聚集时出现瞬时巨大加速度;0 表示不限幅。 |
| `surface_tension_cohesion` | 实数 | pairwise cohesion 的数值强度系数,与 `surface_tension` 共同决定成对内聚力幅值;过大会产生团簇聚集。 |
| `surface_tension_adhesion` | 实数 | 壁面附着强度,只在 cohesion-adhesion 模型中有意义;用于润湿、接触角趋势等近似。 |
| `surface_tension_pair_equilibrium` | 实数 | pairwise 模型的平衡距离系数,影响粒子间吸引/排斥切换位置;偏离过大会改变液滴平衡间距。 |
### Solver:多相流
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `multiphase_model` | `none`、`color`/`color_function`、`mixture` | 选择多相描述方式。`color` 适合界面标记和表面张力,`mixture` 适合相间拖曳和混合物近似。 |
| `interface_tension` | 实数 | 相间界面张力,常用于不同流体材料之间。与自由面 `surface_tension` 不完全等价,应按相对界面单独标定。 |
| `drag_coefficient` | 实数 | 相间拖曳系数,用于气液、颗粒-流体或混合物模型的速度松弛。过大时会使两相速度被强制锁定。 |
| `multiphase_density_ratio_limit` | 实数 | 限制相间密度比在数值离散中的极端影响,避免大密度比界面压力项过刚。 |
| `multiphase_density_relaxation` | 实数 | 相间密度松弛强度,用于抑制界面密度噪声;过大会抹平真实密度跳跃。 |
| `multiphase_velocity_relaxation` | 实数 | 相间速度松弛强度,用于抑制界面速度振荡;过大会削弱真实滑移。 |
| `multiphase_phase_from_material` | 布尔 | 开启后根据粒子材料编号自动生成 phase/color 标记,适合由 `particle_meshing.xml` 分材料生成的多相案例。 |
| `multiphase_interface_reinitialization` | 布尔 | 是否对界面标记进行重新初始化,使界面厚度和颜色场保持稳定;界面被数值扩散时可开启。 |
| `multiphase_reinitialization_strength` | 实数 | 重新初始化强度。过小作用不明显,过大可能移动界面或损失小尺度结构。 |
| `multiphase_pressure_oscillation_suppression` | 布尔 | 是否启用大密度比界面压力振荡抑制,用于减轻轻重流体界面压力跳动。 |
| `multiphase_pressure_suppression_strength` | 实数 | 压力振荡抑制强度。需要从小值开始调,避免过度耗散界面压力。 |
| `multiphase_interphase_riemann` | 布尔 | 启用相间 Riemann solver,用于改善界面压力和法向速度耦合,适合 Rayleigh-Taylor 等大密度比问题。 |
| `multiphase_riemann_dissipation` | 实数 | 相间 Riemann 耗散强度。越大界面越稳但越耗散,可能抑制物理不稳定增长。 |
| `multiphase_conservative_volume_fraction` | 布尔 | 启用保守体积分数演化,用于减少相体积/质量漂移。 |
| `multiphase_volume_fraction_relaxation` | 实数 | 体积分数松弛强度,用于稳定体积分数场;过大可能导致界面变厚。 |
### Solver:密度、粒子正则化和自适应
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `enable_density_sum` | 布尔 | 额外启用密度求和重初始化。注意连续性方程始终更新密度;该项只是周期性纠偏。 |
| `density_sum_frequency` | 整数 | 密度求和执行频率。值越小纠偏越频繁,但可能干扰瞬态压力波;需大于 0。 |
| `density_filter` | `none`、`shepard`、`delta_sph` | 密度滤波方式。Shepard 更像重归一化,Delta-SPH 更像密度扩散;都用于降低密度噪声。 |
| `shepard_filter_frequency` | 实数 | Shepard 滤波频率或间隔控制。适合静水保持,但过强会削弱真实密度变化。 |
| `delta_sph_coefficient` | 实数 | Delta-SPH 密度扩散系数。可抑制压力噪声,过大会让自由面和界面变钝。 |
| `particle_regularization` | `none`、`particle_shifting`/`pst`、`transport_velocity`/`tvf` | 粒子位置正则化方法。用于改善粒子分布无序,但需要避免破坏自由面和质量守恒。 |
| `particle_shift_coefficient` | 实数 | 粒子 shifting 强度。建议从小值开始,过大时粒子会出现非物理横向漂移。 |
| `particle_shift_max_fraction` | 实数 | 单步最大 shifting 距离比例,用于限制正则化位移,防止一次修正过大。 |
| `adaptive_resolution` | `none`、`smoothing_length`/`h`、`split_merge` | 自适应分辨率方式。`h` 只调光滑长度,`split_merge` 会改变粒子数和质量分布。 |
| `adaptive_min_h` | 实数 | 自适应光滑长度下限,防止 h 过小导致邻居不足和时间步过小。 |
| `adaptive_max_h` | 实数 | 自适应光滑长度上限,防止 h 过大导致过度平滑和计算量增加。 |
| `adaptive_split_density_ratio` | 实数 | split 判据,通常表示局部密度/分辨率超过阈值时细化。设置过低会快速增加粒子数。 |
| `adaptive_merge_density_ratio` | 实数 | merge 判据,通常表示局部分辨率过高或密度偏低时合并。设置过高会损失局部细节。 |
| `enable_multiresolution_correction` | 布尔 | 多分辨率过渡区修正总开关。不同 h 或粒子质量共存时建议开启。 |
| `multiresolution_h_ratio_threshold` | 实数 | 判断是否处于变分辨率交界区的 h 比值阈值。越接近 1,识别越敏感。 |
| `multiresolution_kernel_correction` | 布尔 | 对交界区核权重和梯度进行修正,减小粗细粒子相互作用偏差。 |
| `multiresolution_mass_redistribution` | 布尔 | 在 split/merge 或分辨率过渡后重新分配质量,减少总质量误差和局部密度跳变。 |
| `multiresolution_conservative_projection` | 布尔 | 对速度、密度等物理量做守恒投影,尽量保持质量、动量或标量总量。 |
| `multiresolution_projection_strength` | 实数 | 保守投影强度。过小修正不足,过大可能引入局部振荡。 |
| `multiresolution_resampling_iterations` | 整数 | 重采样/投影迭代次数。次数越多越平滑,但计算成本增加。 |
| `gradient_correction` | `none`、`linear`/`renormalization` | 一阶一致性核梯度修正。边界、静水、固体和应力计算建议开启;粒子严重无序时矩阵可能病态。 |
| `free_surface_detection` | `none`、`number_density`、`color_gradient` | 自由面识别方法。表面张力、开放边界和输出分析可依赖该标记。 |
| `free_surface_threshold` | 实数 | 自由面识别阈值。阈值太低会误判内部粒子,太高会漏检真实自由面。 |
| `enable_xsph` | 布尔 | 启用 XSPH 速度平滑输运,减少粒子穿插和高频噪声。 |
| `xsph_epsilon` | 实数 | XSPH 平滑系数。小值用于稳定粒子排列,大值会显著扩散速度场。 |
| `velocity_damping` | 实数 | 全局速度阻尼。适合静力松弛或快速稳定初始场,不应长期用于真实动力学对比。 |
### Solver:时间步、ISPH、开放边界、周期和 CUDA
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `auto_time_step` | 布尔 | 启用后根据声速、加速度和黏性条件更新建议时间步。显式流体推荐开启,调试解析解时可关闭固定步长。 |
| `cfl` | 实数 | 声速 CFL 系数,控制 `h/(c0+vmax)` 类时间步。值越小越稳但计算更慢。 |
| `min_dt` | 实数 | 自动时间步下限。若设置过大,自动时间步无法充分缩小;若过小,计算可能在失稳前变得极慢。 |
| `max_dt` | 实数 | 自动时间步上限。建议设为物理上可接受的最大显式步长,避免初始静止时步长突然过大。 |
| `isph_free_surface_dirichlet` | 布尔 | ISPH 自由面压力 Dirichlet 条件。自由面不可压计算通常需要给压力参考,否则 PPE 可能漂移。 |
| `isph_pressure_reference` | 布尔 | 是否启用 PPE 压力参考。泊松方程只有压力差有意义,通常需要参考点或平均压力约束消除奇异性。 |
| `isph_pressure_reference_particle` | 整数 | 指定压力参考粒子编号。若为负值,代码可使用内部策略选择参考。 |
| `isph_pressure_reference_value` | 实数 | 压力参考值,常设为 0。用于给 PPE 解固定压力基准。 |
| `isph_diagnose_singularity` | 布尔 | 开启 PPE 矩阵奇异性诊断,帮助发现全 Neumann 边界、孤立粒子或对角项异常。 |
| `isph_singularity_diagonal_tolerance` | 实数 | 奇异性诊断的对角容差。过大可能误报,过小可能漏掉病态行。 |
| `isph_pressure_solver` | `conjugate_gradient`、`jacobi`、`gauss_seidel`、`bicgstab` | PPE 线性求解器。CG 适合对称正定近似,BiCGSTAB 对非对称或病态矩阵更宽容。 |
| `isph_pressure_preconditioner` | `none`、`jacobi`/`diagonal`、`amg`/`multigrid` | PPE 预条件器。Jacobi 成本低,AMG/多重网格适合大规模 PPE,但需要更严格的矩阵质量。 |
| `open_boundary_particle_management` | 布尔 | 启用入口补粒子、出口删除和 buffer 重置等开放边界粒子管理。未开启时相关 open boundary 参数不会生效。 |
| `open_boundary_spacing` | 实数 | buffer 区生成粒子的目标间距,应与内部流体粒子 spacing 接近,避免入口密度跳变。 |
| `open_boundary_injection_density` | 实数 | 入口补粒子的初始密度。应与入口材料参考密度一致,否则入口会产生压力波。 |
| `open_boundary_injection_material` | 整数 | 入口补粒子的材料编号。应能在 `Material` 映射中找到对应材料。 |
| `open_boundary_delete_outlet_particles` | 布尔 | 出口粒子离开计算域后删除,避免粒子在域外继续参与邻域搜索。 |
| `open_boundary_recycle_particles` | 布尔 | 将出口粒子回收到入口或 buffer,减少频繁分配和粒子数波动。 |
| `open_boundary_reset_buffer_particles` | 布尔 | 对 buffer 区粒子速度、密度等状态做重置或松弛,保证入口剖面稳定。 |
| `open_boundary_non_reflecting_outlet` | 布尔 | 启用非反射出口,减少压力波在出口反射回计算域。 |
| `open_boundary_nscbc_relaxation` | 实数 | NSCBC 松弛系数。值越大出口越强制,反射可能减少但也可能改写内部解。 |
| `open_boundary_nscbc_probe_distance` | 实数 | NSCBC 探针距离,用于从内部采样外推出口状态;通常取若干粒子间距。 |
| `periodic_x`、`periodic_y`、`periodic_z` | 布尔 | 指定周期方向。必须配合有效 `Domain`,代码会构造周期 ghost 邻居。 |
| `enable_cuda_solver_path` | 布尔 | 启用 CUDA 求解路径。适合大规模显式计算;正式使用前应与 CPU 结果做一致性验证。 |
### Solver:静水平衡和固体 SPH
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `body_force_x`、`body_force_y`、`body_force_z` | 实数 | 体力加速度,例如重力或 Poiseuille 驱动力。方向和单位应与几何尺度一致。 |
| `hydrostatic_equilibrium_projection` | 布尔 | 静水平衡投影,用于快速构造接近平衡的静水压力场;真实瞬态模拟或验证求解器稳定性时可关闭。 |
| `hydrostatic_free_surface_y` | 实数 | 静水自由面高度,用于按深度计算静水压力。坐标方向需与重力方向一致。 |
| `hydrostatic_velocity_damping` | 实数 | 静水投影/松弛中的速度阻尼。值越大越快衰减速度,但可能掩盖真实不稳定。 |
| `hydrostatic_zero_acceleration` | 布尔 | 静水投影时是否置零加速度。用于保持初始平衡,但不应作为真实动力学的长期替代。 |
| `tensile_instability_control` | 实数 | 张力不稳定控制系数,用于抑制负压下粒子成团。过强会改变真实拉伸状态。 |
| `solid_damage_threshold` | 实数 | 固体粒子损伤阈值,达到后可触发退化或断裂逻辑。 |
| `solid_fracture_stress` | 实数 | 基于应力的断裂阈值。适合简单脆性断裂测试,需与材料强度单位一致。 |
| `solid_kinematics_dt` | 实数 | 固体运动学历史量更新所用时间步。通常与全局 `dt` 一致或由求解器内部同步。 |
| `solid_objective_rate` | `jaumann`、`green_naghdi`/`gn`、`truesdell` | 大变形固体的客观应力率。Jaumann 简单常用,Green-Naghdi 对大转动更稳健。 |
| `solid_fracture_deactivate` | 布尔 | bond 或粒子断裂后是否停用相互作用。开启可形成裂纹面,关闭则只记录损伤。 |
| `solid_use_bond_fracture` | 布尔 | 启用基于初始邻接拓扑的 bond 断裂,而不是只按粒子 damage 判断。 |
| `solid_bond_tensile_strain` | 实数 | bond 拉伸断裂应变阈值,用于法向拉伸破坏。 |
| `solid_bond_shear_strain` | 实数 | bond 剪切断裂应变阈值,用于切向滑移或剪切破坏。 |
| `solid_bond_damage_rate` | 实数 | bond damage 演化速率。值越大,超过阈值后损伤累积越快。 |
| `solid_bond_break_damage` | 实数 | bond 完全断裂的 damage 阈值。达到该值后 bond 可被删除或失活。 |
| `solid_identify_fragments` | 布尔 | 断裂后识别连通碎片 id,便于输出和后处理统计碎片数量。 |
### Boundary
| 关键词 | 可选值或类型 | 说明 |
| --- | --- | --- |
| `name` | 字符串 | 边界名称,仅用于日志、调试和可读性,不要求唯一但建议唯一。 |
| `boundary_id` 或 `boundary` | 整数 | 匹配粒子文件中的边界 id。对于由粒子划分生成的壁面,推荐用该 id 打通几何、粒子和边界条件。 |
| `type` | 见下表 | 边界物理类型,决定边界如何约束粒子、入口出口或耦合界面。 |
| `wall_model` | `pressure_floor`、`adami_ghost`、`semi_analytical`、`simple_dynamic_wall`、`coupled_dynamics_solid_wall` 等 | 壁面外推或壁面力学模型。它可以覆盖基础 `type` 的壁面处理方式,例如把普通固壁设为 Adami ghost。 |
| `min_x`、`min_y`、`min_z`、`max_x`、`max_y`、`max_z` | 实数 | 边界盒,用于按空间范围选择粒子或定义 inlet/outlet buffer 区。盒子过大可能误选流体粒子。 |
| `vx`、`vy`、`vz` | 实数 | 边界速度。移动壁、Couette 上壁和入口速度边界会使用这些分量。 |
| `nx`、`ny`、`nz` 或 `normal_x/y/z` | 实数 | 边界法向。压力出口、对称面、壁面 Neumann 和半解析边界积分会用到。 |
| `pressure` | 实数 | 指定边界压力,常用于压力出口或参考压力边界。不可随意用于固壁替代真实壁面压力外推。 |
| `density` | 实数 | 指定边界密度。写入后该边界会被视为 prescribed density,适合入口或特殊边界粒子。 |
| `buffer_width` | 实数 | inlet/outlet buffer 宽度。一般取数倍粒子间距,以保证粒子补充或删除有足够缓冲区。 |
| `relaxation_time` | 实数 | buffer 区状态松弛时间。过小会强制入口状态,过大则入口/出口调节不明显。 |
| `pressure_floor` | 实数 | 边界压力地板,用于避免壁面外推产生过大负压。静水箱中设得过高会抬高近壁压力。 |
| `repulsion_coefficient` | 实数 | 近壁排斥力系数,是动量方程中的预防性力。静水箱通常设为 0;穿透严重时可小量开启。 |
| `repulsion_distance` | 实数 | 近壁排斥力作用距离。距离太小来不及防穿透,太大则会影响正常近壁流动。 |
| `boundary_geometry_integral` | 布尔 | 启用半解析边界积分,用三角面片/曲面几何补偿缺失支持域。复杂 CAD 边界建议开启。 |
| `boundary_missing_kernel_correction` | 布尔 | 对壁面截断造成的缺失核积分做修正,可改善近壁密度、压力和梯度精度。 |
| `boundary_corner_stabilization` | 布尔 | 针对角点和棱边处法向不连续的稳定化处理,防止粒子从角点缝隙穿出。 |
| `boundary_moving_rigid_momentum_exchange` | 布尔 | 移动刚体边界与流体进行一致动量交换,适合移动壁、刚体边界和耦合问题。 |
| `boundary_corner_normal_threshold` | 实数 | 判断角点/棱边法向突变的阈值。值越小越容易触发角点稳定处理。 |
| `boundary_integral_area_scale` | 实数 | 边界积分面积缩放,用于校准半解析积分强度;通常保持 1。 |
| `boundary_integral_min_partition` | 实数 | 半解析积分的最小 partition 或权重下限,避免局部边界贡献过小导致支持域塌陷。 |
| `isph_wall_neumann` | 布尔 | ISPH/PPE 中的固壁 Neumann 条件,控制压力泊松方程壁面法向梯度。 |
| `isph_wall_weak_boundary_integral` | 布尔 | 用弱式边界积分装配 ISPH 壁面项,比简单粒子约束更接近连续 Neumann 条件。 |
| `isph_wall_boundary_integral_scale` | 实数 | ISPH 壁面积分项缩放因子,用于校准壁面 PPE 贡献强度。 |
| `impenetrability` | 布尔 | 时间积分后的几何不可穿透修正。它不是物理壁面力,而是防止粒子越界的最后保护。 |
| `impenetrability_tolerance` | 实数 | 允许穿透容差。应与粒子间距相关;太小可能频繁硬修正,太大则可见穿透。 |
| `impenetrability_velocity_damping` | 实数 | 穿透修正后的法向速度阻尼。较大阻尼可减少反弹,过大则会吸收真实动能。 |
| `tolerance` | 实数 | 边界盒或距离判断容差。用于粒子选择,过大会扩大边界影响范围。 |
`type` 支持:
| 类型值 | 说明 |
| --- | --- |
| `wall`、`solid_wall`、`wall_no_slip` | 固壁/无滑移壁面,通常配合多层边界粒子、Adami ghost 或半解析壁面积分使用。 |
| `free_slip_wall` | 自由滑移壁面,只约束法向穿透,允许切向滑移,适合对称或理想滑移边界。 |
| `moving_wall` | 移动壁面,使用 `vx/vy/vz` 指定壁面速度,可用于 Couette flow 或移动固壁。 |
| `inlet_velocity` | 速度入口,给定入口速度和必要状态量,用于开放通道或入流测试。 |
| `outlet_pressure` | 压力出口,指定出口压力或参考压力,通常需要配合非反射/缓冲区避免反射。 |
| `inlet_buffer`、`buffer_inlet` | 入口 buffer,通过补粒子和状态松弛维持入流剖面。 |
| `outlet_buffer`、`buffer_outlet` | 出口 buffer,用于删除、回收或重置离开计算域的粒子。 |
| `periodic` | 周期边界区域。实际邻域周期性主要由 `periodic_x/y/z` 与 `Domain` 控制。 |
| `free_surface` | 自由面边界标记,用于后处理或 ISPH 自由面压力条件。 |
| `symmetry_plane` | 对称面,通常约束法向速度和法向通量。 |
| `solid_contact` | 固体接触边界,用于固体 SPH 或耦合接触问题。 |
| `fem_interface` | FEM-SPH 接口,用于流固耦合或区域数据交换。 |
| `coupled_dynamics_solid_wall` | 耦合动力学固壁,会插值壁面虚粒子状态并参与流体受力计算。 |
| `simple_dynamic_wall` | 简单动态壁面,边界粒子参与密度/压力等状态更新,但位置保持边界约束不变。 |
### Control
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `start_time` | `0.0` | 通常保持 0 | 起始物理时间,只影响输出时间戳和时间推进初值,不会自动初始化速度或压力。 |
| `end_time` | `1.0e-3` | 应与 `dt * max_steps` 协调 | 终止物理时间。计算会受 `end_time` 和 `max_steps` 双重限制,哪个先到就停止。 |
| `dt` | `1.0e-4` | 显式 SPH 应满足 CFL;静水/表面张力问题要更小 | 基础时间步。若 `auto_time_step=on`,它也是初始/参考步长之一。 |
| `max_steps` | `1000` | 根据计算时长设置 | 最大步数,用于防止自动时间步过小导致运行无限延长。 |
| `output_interval` | `1` | 大案例常用 `50`、`100`、`200` | 每隔多少步写一次结果。值越小结果越细,但 IO 开销和磁盘占用越大。 |
### Output
| 关键词 | 默认值 | 可选值/建议 | 说明 |
| --- | --- | --- | --- |
| `directory` | `sph_outputs` | 路径 | 主输出目录。VTU、PVD 和可选拆分结果默认都相对该目录组织。 |
| `prefix` | `sph` | 字符串 | 主输出文件前缀,例如 `sph_0.vtu`、`sph_100.vtu`。 |
| `pvd` | `sph.pvd` | 文件名 | 主 PVD 文件名,用于 ParaView 按时间序列读取所有 VTU 帧。 |
| `format` | `ascii` | `ascii`、`appended_binary`/`binary` | VTU 数据格式。调试用 ASCII,大数据用 binary。 |
| `compression` | `none` | `none`、`zlib` | VTU 压缩方式。大规模输出可用 `zlib` 节省磁盘空间,但写文件耗时会增加。 |
| `output_turbulent_viscosity` | `on` | 布尔 | 是否把湍流黏性场写入 VTU。未启用湍流模型时该字段通常为零或无实际意义。 |
| `split_particles` | `off` | 布尔 | 是否在求解输出阶段直接将流体和边界粒子分别写出,便于可视化时隐藏壁面或单独检查穿透。 |
| `fluid_directory` | 空;开启拆分时默认为 `directory/water` | 路径 | 流体粒子输出目录。若不指定,开启拆分后自动放到主输出目录下的 `water`。 |
| `boundary_directory` | 空;开启拆分时默认为 `directory/walls` | 路径 | 边界粒子输出目录。若不指定,开启拆分后自动放到主输出目录下的 `walls`。 |
| `fluid_prefix` | `fluid` | 字符串 | 流体粒子输出前缀,用于区分主结果和拆分结果。 |
| `boundary_prefix` | `boundary` | 字符串 | 边界粒子输出前缀,建议与边界类型或案例名称保持一致。 |
| `fluid_pvd` | `fluid.pvd` | 文件名 | 流体粒子 PVD,仅记录拆分后的流体序列。 |
| `boundary_pvd` | `boundary.pvd` | 文件名 | 边界粒子 PVD,仅记录拆分后的边界序列。 |
### Monitor
| 关键词 | 默认值 | 推荐范围/建议 | 说明 |
| --- | --- | --- | --- |
| `enabled` | `off` | 长时间案例建议 `on` | 是否启用运行监控。监控不会改变求解结果,但有助于定位飞散、压力爆炸和边界穿透发生的时间步。 |
| `console` | `on` | 调试时建议 `on` | 是否同步打印到命令行。关闭后可只写 log,适合批量后台运行。 |
| `log` 或 `path` | 空 | 建议写到 `outputs/*.log` | log 文件路径。若为空且启用监控,可能只输出到控制台或使用默认路径。 |
| `interval` | `0` | `0` 表示使用求解器默认/输出节奏;大案例可设 `10`、`50` | 每隔多少步输出一次监控信息。比 VTU 输出更频繁时可更早发现失稳。 |
| `velocity` | `on` | 布尔 | 是否监控速度范围。最大速度突然增大通常是粒子飞散或边界失稳的前兆。 |
| `acceleration` | `on` | 布尔 | 是否监控加速度范围。最大加速度突增常由压力尖峰、表面张力过强或排斥力过硬引起。 |
| `density` | `on` | 布尔 | 是否监控密度范围。WCSPH 中密度偏离参考值过多说明声速、时间步或密度修正需要调整。 |
| `pressure` | `on` | 布尔 | 是否监控压力范围。大负压可能导致张力不稳定,大正压尖峰可能导致爆炸式膨胀。 |
| `bounds` | `on` | 布尔 | 是否监控粒子坐标范围。坐标超出 `Domain` 或容器范围可快速发现穿透和飞散。 |
| `time_step` | `on` | 布尔 | 是否输出时间步信息。自动时间步计算中可观察 dt 是否被声速、黏性或加速度条件压低。 |
---
# 第二部分:理论手册
## 1. SPH 基本思想
SPH 是一种无网格拉格朗日粒子方法。连续场函数 `f(x)` 通过核函数近似:
```text
f(x) = integral f(x') W(x - x', h) dx'
```
粒子离散后:
```text
f_i ≈ sum_j m_j / rho_j * f_j * W_ij
```
其中:
- `m_j` 是粒子质量。
- `rho_j` 是粒子密度。
- `W_ij = W(x_i - x_j, h)` 是核函数。
- `h` 是光滑长度。
梯度近似:
```text
grad f_i ≈ sum_j m_j / rho_j * f_j * grad W_ij
```
工程实现中常使用反对称形式或一阶一致性修正,以改善动量守恒和梯度精度。
## 2. 核函数和支持域
核函数需要满足:
- 紧支撑。
- 非负。
- 归一化。
- 足够光滑。
- 随距离单调衰减。
常用截断半径为 `2h` 或 `2.2 * spacing` 附近。邻域粒子过少会导致梯度误差大;邻域粒子过多会增加数值扩散和计算量。
## 3. WCSPH 控制方程
弱可压 SPH 求解:
```text
d rho / dt = -rho div(v)
dv / dt = -1/rho grad(p) + viscous + body + surface_tension + boundary
dx / dt = v
```
密度通过连续性方程更新,压力通过状态方程给出。
## 4. 密度连续性方程
常见 SPH 密度更新:
```text
d rho_i / dt = sum_j m_j (v_i - v_j) · grad W_ij
```
M3Frame 中 SPH 流体始终使用连续性方程推进密度。密度求和是额外的重初始化:
```text
rho_i = sum_j m_j W_ij
```
密度求和可以减小漂移,但频繁或过强会破坏瞬态连续性,因此作为可选稳定化使用。
## 5. 压力项离散
常用对称压力梯度:
```text
dv_i/dt = -sum_j m_j (p_i/rho_i^2 + p_j/rho_j^2) grad W_ij
```
这种形式保证成对动量守恒。壁面粒子和多相粒子需要特殊处理,否则容易产生压力穿透、压力振荡或界面噪声。
## 6. Tait 状态方程
水体常用 Tait EOS:
```text
p = B [(rho/rho0)^gamma - 1]
B = rho0 c0^2 / gamma
```
其中:
- `rho0` 是参考密度。
- `c0` 是人工声速。
- `gamma` 对水常取 7。
人工声速决定密度压缩率和显式稳定时间步。典型弱可压要求密度波动小于 1%。
## 7. Riemann-SPH 理论
Riemann-SPH 用局部一维 Riemann 解替代或修正传统压力项。Rusanov 通量可理解为在界面压力中加入速度跳跃耗散:
```text
p* = average(p_L, p_R) - 0.5 rho_bar c_bar (u_R - u_L)
```
优点:
- 改善压力振荡。
- 提高界面和冲击稳定性。
- 对多相大密度比问题更稳。
代价:
- 引入额外数值耗散。
- 参数不合适时会抹平真实波动。
## 8. 人工黏性
Monaghan 人工黏性用于处理粒子靠近时的非物理穿透和冲击:
```text
Pi_ij = (-alpha c_bar mu_ij + beta mu_ij^2) / rho_bar
```
人工黏性只在粒子相互接近时生效。自由面流动中 alpha 过大时,水体会显得像泥浆。
## 9. 物理黏性
物理黏性对应 Navier-Stokes 方程中的黏性扩散项。SPH 中常用 Morris 黏性形式:
```text
a_i^nu = sum_j m_j * 2 nu_ij (v_i - v_j) / rho_j * (r_ij · grad W_ij) / (|r_ij|^2 + eta^2)
```
Lo-Shao 黏性离散在边界和自由面附近有更好的稳定性。多材料黏性平均需要使用调和平均或受限平均,避免高黏/低黏界面出现过大剪切力。
## 10. 非牛顿流体
非牛顿流体的黏度依赖剪切率:
```text
mu_eff = mu(gamma_dot)
```
典型模型:
- Bingham:存在屈服应力。
- Herschel-Bulkley:幂律 + 屈服应力。
- Carreau:从零剪切黏度过渡到无限剪切黏度。
- 剪切变稀:剪切率越大,黏度越小。
- 剪切增稠:剪切率越大,黏度越大。
数值上必须给黏度上下限,避免剪切率接近零时黏度奇异。
## 11. 表面张力理论
### CSF 模型
CSF 将界面张力写成体力:
```text
f_sigma = sigma kappa n delta_s
```
SPH 中通过颜色场梯度估计法向:
```text
n = grad C
kappa = -div(n / |n|)
```
CSF 对粒子无序和曲率估计很敏感,容易出现 parasitic current。
### Pairwise cohesion 模型
成对 cohesion 模型用粒子间成对吸引/排斥力模拟表面张力。优点是成对守恒、实现直接,适合液滴振荡。缺点是系数需要校准,过强会造成团簇聚集。
M3Frame 中 pairwise cohesion 的强度由物理 `surface_tension` 和数值 `surface_tension_cohesion` 共同决定。
## 12. XSPH 修正
XSPH 用邻域平均速度修正粒子输运速度:
```text
dx_i/dt = v_i + epsilon sum_j m_j/rho_j (v_j - v_i) W_ij
```
它可以降低粒子相对穿插和高频噪声,但过大时会造成数值扩散,抹平真实涡结构。
## 13. 梯度修正
标准 SPH 梯度在边界附近不满足一阶一致性。梯度修正通过矩阵:
```text
L_i = [sum_j V_j (x_j - x_i) ⊗ grad W_ij]^{-1}
```
修正核梯度:
```text
grad W_ij^corr = L_i grad W_ij
```
边界粒子也需要参与修正矩阵构造,否则壁面附近会出现压力梯度和黏性梯度偏差。
## 14. 粒子无序和正则化
SPH 粒子无序会导致:
- 密度噪声。
- 压力振荡。
- 自由面毛刺。
- 壁面附近空腔。
- 表面张力团簇化。
常用正则化:
- XSPH。
- particle shifting。
- 密度求和重初始化。
- 核梯度修正。
- 多分辨率保守投影。
## 15. 壁面边界理论
SPH 壁面边界困难的核心原因是流体粒子的支持域在壁面处被截断。直接缺失邻域会导致:
- 密度不足。
- 压力偏低。
- 黏性力方向错误。
- 粒子穿透。
### 多层边界粒子
用 2 到 3 层边界粒子补足支持域,是工程中最常见的方法。优点是简单稳健;缺点是几何角点、曲面和边界重叠需要仔细处理。
### Adami ghost
Adami ghost 通过流体邻域外推边界虚粒子压力、密度和速度,使壁面对流体粒子表现得像物理边界。
### Simple dynamic wall
`simple_dynamic_wall` 将边界粒子作为正常粒子参与密度和压力更新,但冻结位置。它适合静水箱等需要壁面稳定填充支持域的场景。
### 半解析壁面积分
半解析方法直接对三角面片或曲面边界积分,理论上更贴近连续边界条件,适合复杂 CAD 几何和高保真工业计算。
## 16. 周期边界理论
周期边界要求:
- 粒子跨周期边界后位置映射正确。
- 邻域搜索能看到周期镜像粒子。
- 物理量和材料属性同步。
- 输出时可选择真实粒子而非 ghost view。
如果周期邻域缺失,粒子靠近周期边界时支持域突然减少,可能导致压力脉冲和粒子飞散。
## 17. 开放边界理论
开放边界需要同时处理:
- 入口补粒子。
- 出口删除粒子。
- buffer 区重置。
- 非反射波动条件。
- 质量守恒。
NSCBC 出口基于特征线思想,将进入计算域的波幅控制到较小,避免压力波反射回流场。
## 18. 多相流理论
多相 SPH 的难点:
- 大密度比导致压力项刚性。
- 界面处压力振荡。
- 体积分数扩散。
- 表面张力和黏性跳跃。
常用稳定化:
- color/phase 标记。
- conservative volume fraction。
- interface reinitialization。
- pressure oscillation suppression。
- interphase Riemann solver。
- drag/mixture model。
## 19. 湍流模型理论
SPH 的 LES 通常通过亚粒子应力或湍流黏性建模:
```text
nu_t = (C_s Delta)^2 |S|
```
其中:
- `C_s` 是 Smagorinsky 常数。
- `Delta` 是粒子尺度。
- `S` 是应变率张量。
湍流黏性可输出到 VTU,用于检查局部耗散区域。
## 20. 固体 SPH 理论
固体 SPH 需要更新:
- 变形梯度 `F`。
- 应变率 `D`。
- 自旋张量 `W`。
- Cauchy 应力。
- 客观应力率。
- 材料历史变量。
大变形固体常用:
- Total Lagrangian SPH。
- Updated Lagrangian SPH。
- Jaumann 应力率。
- Green-Naghdi 应力率。
- 有限塑性返回映射。
断裂可通过初始 bond network 记录粒子间拓扑。当 bond 满足拉伸或剪切断裂准则后,降低或删除相互作用,形成裂纹面和碎片。
## 21. ISPH 理论
ISPH 通过压力泊松方程保证不可压约束:
```text
div(v^{n+1}) = 0
```
预测速度:
```text
v* = v^n + dt * non_pressure_forces
```
压力泊松方程:
```text
∇²p = rho / dt * div(v*)
```
修正速度:
```text
v^{n+1} = v* - dt / rho * grad(p)
```
PPE 的难点在于:
- 自由面压力条件。
- 固壁 Neumann 条件。
- 压力参考点。
- 奇异性诊断。
- 预条件器。
## 22. 时间积分理论
### Euler 显式
简单、便宜,但耗散和稳定性受时间步限制明显。
```text
v^{n+1} = v^n + dt a^n
x^{n+1} = x^n + dt v^n
```
### Velocity Verlet
比 Euler 更适合保守系统和长时间显式动力学:
```text
x^{n+1} = x^n + dt v^n + 0.5 dt^2 a^n
v^{n+1} = v^n + 0.5 dt (a^n + a^{n+1})
```
### Predictor-Corrector
先预测位置和速度,再根据新加速度修正,可改善显式稳定性。
## 23. 稳定时间步
显式 SPH 时间步通常受三个条件限制:
```text
dt_cfl ~ h / (c0 + vmax)
dt_force ~ sqrt(h / |a|max)
dt_viscous ~ h^2 / nu
```
最终取:
```text
dt = C * min(dt_cfl, dt_force, dt_viscous)
```
静水箱、液滴和强表面张力问题通常需要比普通溃坝更小的时间步。
## 24. 静水压力为什么困难
静水箱看似简单,但对 SPH 很苛刻:
- 正确解是速度为零,压力线性分布。
- 任何微小压力噪声都会驱动粒子运动。
- 壁面支持域缺失会破坏压力梯度。
- 负压会触发张力不稳定。
- 密度漂移会缓慢积累。
- 几何不可穿透修正若太硬,会向系统注入能量。
因此稳定静水箱通常需要:
- 高质量初始粒子排布。
- 多层且不重叠的壁面粒子。
- 稳定壁面压力外推。
- 密度漂移控制。
- 小时间步。
- 一阶一致性修正。
## 25. Benchmark 和误差评估
推荐使用以下 benchmark 检查不同功能:
| 案例 | 检查内容 |
| --- | --- |
| Hydrostatic tank | 静水压力、壁面稳定性、密度漂移。 |
| Dam break | 自由面大变形、壁面冲击、压力峰值。 |
| Poiseuille flow | 黏性、周期边界、解析速度剖面。 |
| Couette flow | 移动壁面、无滑移边界、黏性扩散。 |
| Oscillating droplet | 表面张力、质量守恒、主轴振荡周期。 |
| Taylor-Green vortex | 涡衰减、黏性耗散、周期边界。 |
| Rayleigh-Taylor | 多相界面、大密度比稳定性。 |
| Elastic bar impact | 固体 SPH、大变形、接触边界。 |
| Kalthoff-Winkler | 动态断裂、bond damage、碎片识别。 |
误差评估建议输出:
- L2 误差。
- L∞ 误差。
- 总质量误差。
- 动量误差。
- 能量变化。
- 压力峰值误差。
- 解析剖面对比 CSV。