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

74 KiB
Raw Blame History

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. 案例目录结构

推荐新案例使用下面的目录结构:

case/
  pipeline.xml
  config/
    cad.xml
    particle_meshing.xml
    materials.xml
    sph_solver.xml
    post_split_particles.xml
  outputs/

历史 benchmark 中仍可能使用 data/ 目录,例如:

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:

<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>

运行:

.\M3Frame.exe path\to\case\pipeline.xml

调试时也可以直接运行 SPH 求解器配置:

.\M3Frame.exe path\to\case\config\sph_solver.xml

3. 最小 SPH 求解器配置

<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 中:

<ParticleRegion name="water" material="7" spacing="0.01" />

表示生成的水粒子带有 material=7。

sph_solver.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,用于避免流体粒子与壁面粒子重叠。

<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> 中设置:

<InitialCondition
    body_force_x="0"
    body_force_y="-9.81"
    body_force_z="0" />

Poiseuille 通道流中可令体力沿流向:

<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 启用密度求和后,每隔多少步执行一次。

示例:

<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 用于改善强间断、界面和高速流动中的压力振荡。常见设置:

<Solver riemann_solver="riemann_rusanov" />

多相流可启用相间 Riemann 处理:

<Solver
    multiphase_interphase_riemann="on"
    multiphase_riemann_dissipation="0.1" />

12. 黏性模型

人工黏性

<Solver
    artificial_viscosity="0.01"
    artificial_viscosity_beta="0.0" />

人工黏性主要用于数值稳定。若数值看起来像泥浆,通常是 artificial_viscosity 或物理黏性过大。

物理黏性

支持 Morris/Laminar 黏性、Lo-Shao 黏性离散、可变黏度和多材料黏性平均。

示例:

<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 控制成对力离散强度。

液滴振荡案例建议:

<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 等。

<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 配置

基本壁面

<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 表示。

<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、静水箱等需要较稳定壁面压力的场景。

典型设置:

<Boundary
    id="2"
    type="wall_no_slip"
    wall_model="adami_ghost"
    velocity_x="0"
    velocity_y="0"
    velocity_z="0"
    pressure_floor="0.0" />

移动壁面:

<Boundary
    id="3"
    type="wall_no_slip"
    wall_model="adami_ghost"
    velocity_x="0.1"
    velocity_y="0"
    velocity_z="0" />

17. 半解析壁面积分

半解析壁面积分用于更高保真的三角面片或曲面边界:

<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 压力泊松方程相关配置包括:

<Solver
    method="isph"
    isph_pressure_solver="bicgstab"
    isph_pressure_tolerance="1.0e-6"
    isph_pressure_max_iterations="200" />

固壁 Neumann 和弱式边界积分应放在 <Boundary> 中:

<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。

典型关键词:

<Solver
    multiphase_interphase_riemann="on"
    multiphase_riemann_dissipation="0.1" />

21. 湍流模型

支持:

  • SPS turbulence。
  • Smagorinsky LES。
  • 湍流黏性输出控制。
<Solver
    turbulence_model="smagorinsky"
    smagorinsky_constant="0.12"
    output_turbulent_viscosity="on" />

22. 固体 SPH 与断裂

固体 SPH 支持:

  • 大变形运动学。
  • 变形梯度 F。
  • 应变率。
  • 旋转率。
  • Jaumann/Green-Naghdi 客观应力率历史量。
  • 初始邻接拓扑 bond list。
  • bond damage。
  • 拉伸/剪切断裂准则。
  • 裂纹面法向。
  • 碎片识别。

示例关键词:

<Solver
    method="solid_sph"
    solid_identify_fragments="on" />

23. 自适应与多分辨率

支持:

  • particle split/merge。
  • 自适应 smoothing length。
  • 多分辨率过渡区核修正。
  • 质量守恒重采样。
  • 物理量保守投影。

示例:

<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. 梯度修正与粒子正则化

常用选项:

<Solver
    gradient_correction="linear"
    xsph_epsilon="0.05" />

梯度修正用于恢复一阶一致性。对于壁面附近的粒子,边界粒子也应参与修正矩阵构造,否则壁面附近压力和速度梯度会失真。

25. GPU 与并行

SPH 包含 CUDA resident 求解路径的框架。相关关键词:

<Solver enable_cuda_solver_path="on" />

当前 CPU 路径仍是最完整、最稳妥的功能路径。CUDA 路径适合大粒子数和显式流体计算,使用前应通过 benchmark 对比 CPU/GPU 的粒子位置、密度、压力和总能量误差。

26. 输出与后处理

常规输出:

<Output
    directory="outputs/sph"
    basename="case"
    format="vtu"
    pvd="on" />

将流体和壁面分离输出:

<SPHPost>
  <SplitParticles
      input="outputs/sph/case.pvd"
      output_directory="outputs/split"
      by="role" />
</SPHPost>

后处理 pipeline:

<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 中已有读取逻辑整理。若本节与旧案例不一致,以源码当前关键词为准。新案例根节点建议使用:

<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 文件路径。

示例:

<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。

示例:

<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) 通过核函数近似:

f(x) = integral f(x') W(x - x', h) dx'

粒子离散后:

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 是光滑长度。

梯度近似:

grad f_i ≈ sum_j m_j / rho_j * f_j * grad W_ij

工程实现中常使用反对称形式或一阶一致性修正,以改善动量守恒和梯度精度。

2. 核函数和支持域

核函数需要满足:

  • 紧支撑。
  • 非负。
  • 归一化。
  • 足够光滑。
  • 随距离单调衰减。

常用截断半径为 2h 或 2.2 * spacing 附近。邻域粒子过少会导致梯度误差大;邻域粒子过多会增加数值扩散和计算量。

3. WCSPH 控制方程

弱可压 SPH 求解:

d rho / dt = -rho div(v)
dv / dt = -1/rho grad(p) + viscous + body + surface_tension + boundary
dx / dt = v

密度通过连续性方程更新,压力通过状态方程给出。

4. 密度连续性方程

常见 SPH 密度更新:

d rho_i / dt = sum_j m_j (v_i - v_j) · grad W_ij

M3Frame 中 SPH 流体始终使用连续性方程推进密度。密度求和是额外的重初始化:

rho_i = sum_j m_j W_ij

密度求和可以减小漂移,但频繁或过强会破坏瞬态连续性,因此作为可选稳定化使用。

5. 压力项离散

常用对称压力梯度:

dv_i/dt = -sum_j m_j (p_i/rho_i^2 + p_j/rho_j^2) grad W_ij

这种形式保证成对动量守恒。壁面粒子和多相粒子需要特殊处理,否则容易产生压力穿透、压力振荡或界面噪声。

6. Tait 状态方程

水体常用 Tait EOS:

p = B [(rho/rho0)^gamma - 1]
B = rho0 c0^2 / gamma

其中:

  • rho0 是参考密度。
  • c0 是人工声速。
  • gamma 对水常取 7。

人工声速决定密度压缩率和显式稳定时间步。典型弱可压要求密度波动小于 1%。

7. Riemann-SPH 理论

Riemann-SPH 用局部一维 Riemann 解替代或修正传统压力项。Rusanov 通量可理解为在界面压力中加入速度跳跃耗散:

p* = average(p_L, p_R) - 0.5 rho_bar c_bar (u_R - u_L)

优点:

  • 改善压力振荡。
  • 提高界面和冲击稳定性。
  • 对多相大密度比问题更稳。

代价:

  • 引入额外数值耗散。
  • 参数不合适时会抹平真实波动。

8. 人工黏性

Monaghan 人工黏性用于处理粒子靠近时的非物理穿透和冲击:

Pi_ij = (-alpha c_bar mu_ij + beta mu_ij^2) / rho_bar

人工黏性只在粒子相互接近时生效。自由面流动中 alpha 过大时,水体会显得像泥浆。

9. 物理黏性

物理黏性对应 Navier-Stokes 方程中的黏性扩散项。SPH 中常用 Morris 黏性形式:

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. 非牛顿流体

非牛顿流体的黏度依赖剪切率:

mu_eff = mu(gamma_dot)

典型模型:

  • Bingham:存在屈服应力。
  • Herschel-Bulkley:幂律 + 屈服应力。
  • Carreau:从零剪切黏度过渡到无限剪切黏度。
  • 剪切变稀:剪切率越大,黏度越小。
  • 剪切增稠:剪切率越大,黏度越大。

数值上必须给黏度上下限,避免剪切率接近零时黏度奇异。

11. 表面张力理论

CSF 模型

CSF 将界面张力写成体力:

f_sigma = sigma kappa n delta_s

SPH 中通过颜色场梯度估计法向:

n = grad C
kappa = -div(n / |n|)

CSF 对粒子无序和曲率估计很敏感,容易出现 parasitic current。

Pairwise cohesion 模型

成对 cohesion 模型用粒子间成对吸引/排斥力模拟表面张力。优点是成对守恒、实现直接,适合液滴振荡。缺点是系数需要校准,过强会造成团簇聚集。

M3Frame 中 pairwise cohesion 的强度由物理 surface_tension 和数值 surface_tension_cohesion 共同决定。

12. XSPH 修正

XSPH 用邻域平均速度修正粒子输运速度:

dx_i/dt = v_i + epsilon sum_j m_j/rho_j (v_j - v_i) W_ij

它可以降低粒子相对穿插和高频噪声,但过大时会造成数值扩散,抹平真实涡结构。

13. 梯度修正

标准 SPH 梯度在边界附近不满足一阶一致性。梯度修正通过矩阵:

L_i = [sum_j V_j (x_j - x_i) ⊗ grad W_ij]^{-1}

修正核梯度:

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 通常通过亚粒子应力或湍流黏性建模:

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 通过压力泊松方程保证不可压约束:

div(v^{n+1}) = 0

预测速度:

v* = v^n + dt * non_pressure_forces

压力泊松方程:

∇²p = rho / dt * div(v*)

修正速度:

v^{n+1} = v* - dt / rho * grad(p)

PPE 的难点在于:

  • 自由面压力条件。
  • 固壁 Neumann 条件。
  • 压力参考点。
  • 奇异性诊断。
  • 预条件器。

22. 时间积分理论

Euler 显式

简单、便宜,但耗散和稳定性受时间步限制明显。

v^{n+1} = v^n + dt a^n
x^{n+1} = x^n + dt v^n

Velocity Verlet

比 Euler 更适合保守系统和长时间显式动力学:

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 时间步通常受三个条件限制:

dt_cfl ~ h / (c0 + vmax)
dt_force ~ sqrt(h / |a|max)
dt_viscous ~ h^2 / nu

最终取:

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。