A Chrono YAML SPH solver file defines the parameters needed to run a Chrono::FSI-SPH simulation. It consists of the following main objects:

[required] The Chrono version (chrono-version) that is compatible with the YAML model specification. This is a string of the form M.m (major.minor) or M.m.p (major-minor-patch), although only the two fields are verified for compatibility.
The sph object specifying SPH method parameters.
The kernel object specifying the SPH kernel definition.
The discretization object specifying parameters for the SPH discretization.
The boundary_conditions object specifying the method and parameters for treating fluid-solid boundary conditions.
The integration object specifying the type and parameters for the time integrator.
The proximity_search object specifying parameters for the proximity (neighbor) search algorithm.
The particle_shifting object specifying the method and parameters for the particle shifting algorithm.
The viscosity object specifying the method and parameters for viscosity treatment.

All objects listed below are optional; any object or property that is omitted keeps its default value. Note that an SPH solver file specifies neither output nor run-time visualization settings; those belong in the FSI-SPH simulation file.

SPH method specification

The sph object collects the base parameters of the weakly compressible SPH formulation.

Property	Description	Type	Available Values	Required	Default
`eos_type`	Equation of state	enum	`ISOTHERMAL`,`TAIT`	No	`ISOTHERMAL`
`use_delta_sph`	Whether to use delta-SPH density diffusion	boolean	–	No	`true`
`delta_sph_coefficient`	Delta-SPH coefficient	double	–	No	0.1
`max_velocity`	Maximum expected velocity, used for scaling	double	–	No	1.0
`min_distance_coefficient`	Minimum inter-particle distance, as a fraction of the kernel radius	double	–	No	0.01
`density_reinit_steps`	Number of steps between density re-initializations	integer	–	No	2e8
`use_density_based_projection`	Use density-based projection (`IMPLICIT_SPH` only)	boolean	–	No	`false`
`free_surface_threshold`	Divergence threshold used to identify free-surface particles (CRM only)	double	–	No	2.0

free_surface_threshold is compared against the divergence of the position field; particles with divergence below the threshold are treated as free-surface particles.

Kernel specification

The kernel object defines the SPH smoothing kernel and the particle resolution.

Property	Description	Type	Available Values	Required	Default
`kernel_type`	SPH smoothing kernel	enum	`QUADRATIC`,`CUBIC_SPLINE`, `QUINTIC_SPLINE`,`WENDLAND`	No	`CUBIC_SPLINE`
`initial_spacing`	Initial particle spacing	double	–	No	0.01
`d0_multiplier`	Kernel length multiplier; the kernel length is `d0_multiplier * initial_spacing`	double	–	No	1.2

SPH discretization specification

The discretization object selects the consistent (corrected) forms of the SPH differential operators.

Property	Description	Type	Available Values	Required	Default
`use_consistent_gradient_discretization`	Use the G matrix in the SPH gradient approximation	boolean	–	No	`false`
`use_consistent_laplacian_discretization`	Use the L matrix in the SPH Laplacian approximation	boolean	–	No	`false`

Boundary condition treatment

The boundary_conditions object controls how fluid-solid boundaries are enforced.

Property	Description	Type	Available Values	Required	Default
`boundary_method`	Boundary condition enforcement method	enum	`ADAMI`,`HOLMES`	No	`ADAMI`
`num_bce_layers`	Number of BCE marker layers, on boundaries and on solids	integer	–	No	3

Integrator specification

The integration object defines the fluid solver time step and integration scheme.

Property	Description	Type	Available Values	Required	Default
`time_step`	Fluid solver time step size in seconds	double	–	Yes	–
`integration_scheme`	SPH integration scheme	enum	`EULER`,`RK2`,`VERLET`, `SYMPLECTIC`,`IMPLICIT_SPH`	No	`RK2`
`use_variable_time_step`	Whether to adapt the time step during the simulation	boolean	–	No	`false`

Note that time_step is required whenever the integration object is present.

Proximity search treatment

The proximity_search object controls how often neighbor lists are rebuilt.

Property	Description	Type	Available Values	Required	Default
`num_proximity_search_steps`	Number of steps between updates of the neighbor lists	integer	–	No	1

Particle shifting treatment

The particle_shifting object selects the particle shifting algorithm and its coefficients. Which coefficients are relevant depends on the selected shifting_method.

Property	Description	Type	Available Values	Required	Default
`shifting_method`	Particle shifting method	enum	`NONE`,`PPST`,`XSPH`, `PPST_XSPH`,`DIFFUSION`, `DIFFUSION_XSPH`	No	`XSPH`
`shifting_xsph_eps`	XSPH coefficient (`XSPH`, `PPST_XSPH`, `DIFFUSION_XSPH`)	double	–	No	0.5
`shifting_ppst_push`	PPST pushing coefficient (`PPST`, `PPST_XSPH`)	double	–	No	3.0
`shifting_ppst_pull`	PPST pulling coefficient (`PPST`, `PPST_XSPH`)	double	–	No	1.0
`shifting_beta_implicit`	Shifting coefficient used by the implicit solver (`IMPLICIT_SPH` scheme)	double	–	No	1.0
`shifting_diffusion_A`	Diffusion-based shifting coefficient A (`DIFFUSION`, `DIFFUSION_XSPH`)	double	1 to 6	No	1.0
`shifting_diffusion_AFSM`	Diffusion-based shifting coefficient AFSM (`DIFFUSION`, `DIFFUSION_XSPH`)	double	–	No	3.0
`shifting_diffusion_AFST`	Diffusion-based shifting coefficient AFST (`DIFFUSION`, `DIFFUSION_XSPH`)	double	–	No	2.0

Viscosity treatment

The viscosity object selects the viscosity model and its coefficient.

Property	Description	Type	Available Values	Required	Default
`viscosity_method`	Viscosity treatment method	enum	`LAMINAR`, `ARTIFICIAL_UNILATERAL`, `ARTIFICIAL_BILATERAL`	No	`ARTIFICIAL_UNILATERAL`
`artificial_viscosity`	Artificial viscosity coefficient (both `ARTIFICIAL_*` methods)	double	–	No	0.02

The LAMINAR method uses the physical viscosity given by the fluid_properties entry of the SPH model file instead.

Example

Below is an example of an SPH solver configuration:

chrono-version: 10.0
 
sph:
   eos_type: TAIT
   use_delta_sph: true
   delta_sph_coefficient: 0.1
   max_velocity: 4.538
   min_distance_coefficient: 0.01
   density_reinit_steps: 200000
   use_density_based_projection: false
 
kernel:
   kernel_type: CUBIC_SPLINE
   initial_spacing: 0.1
   d0_multiplier: 1
 
discretization:
   use_consistent_gradient_discretization: false
   use_consistent_laplacian_discretization: false
 
boundary_conditions:
   boundary_method: ADAMI
   num_bce_layers: 3
 
integration:
   integration_scheme: RK2
   time_step: 5e-5
   use_variable_time_step: false
 
proximity_search:
   num_proximity_search_steps: 1
 
particle_shifting:
   shifting_method: XSPH
   shifting_xsph_eps: 0.5
   shifting_ppst_push: 3.0
   shifting_ppst_pull: 1.0
   shifting_beta_implicit: 1.0
   shifting_diffusion_A: 1.0
   shifting_diffusion_AFSM: 3.0
   shifting_diffusion_AFST: 2.0
 
viscosity:
   viscosity_method: ARTIFICIAL_UNILATERAL
   artificial_viscosity: 0.03

YAML schema

The YAML SPH solver specification file must follow the data/yaml/schema/fsisph_solver.schema.yaml provided in the Chrono data directory:

# =============================================================================
# PROJECT CHRONO - http://projectchrono.org
#
# Copyright (c) 2025 projectchrono.org
# All rights reserved.
#
# Use of this source code is governed by a BSD-style license that can be found
# in the LICENSE file at the top level of the distribution and at
# http://projectchrono.org/license-chrono.txt.
# =============================================================================
#
# Schema for a Chrono::SPH YAML fluid solver specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
 
required: [chrono-version]
 
chrono-version:
  type: string
  description: Chrono version compatible with this YAML specification (M.m or M.m.p)
 
# -----------------------------------------------------------------------------
# Definitions of common Chrono types
 
vector3d: &VECTOR3D   # Specification of a ChVector3d
    type: array
    items:
        type: number
    minItems: 3
    maxItems: 3
 
# -----------------------------------------------------------------------------
# Definition of a Chrono::SPH solver
#
# All objects below are optional; any object or property that is omitted keeps its default value.
# Note that output and run-time visualization settings are *not* specified here; they belong in the
# SPH simulation file (see fsisph_simulation.schema).
 
sph:
  description: Base SPH method parameters
  type: object
  properties:
    eos_type:
      type: string
      description: Equation of state (weakly compressible SPH)
      enum: [ISOTHERMAL, TAIT]
      default: ISOTHERMAL
    use_delta_sph:
      type: boolean
      description: Whether to use delta-SPH density diffusion
      default: true
    delta_sph_coefficient:
      type: number
      description: Delta-SPH coefficient
      minimum: 0
      default: 0.1
    max_velocity:
      type: number
      description: Maximum expected velocity, used for scaling
      minimum: 0
      default: 1.0
    min_distance_coefficient:
      type: number
      description: Minimum inter-particle distance, as a fraction of the kernel radius
      minimum: 0
      default: 0.01
    density_reinit_steps:
      type: integer
      description: Number of steps between density re-initializations
      minimum: 0
      default: 200000000
    use_density_based_projection:
      type: boolean
      description: Use density-based projection (IMPLICIT_SPH only)
      default: false
    free_surface_threshold:
      type: number
      description: |
        Threshold on the divergence of the position field used to identify free-surface particles (CRM only).
        Particles with divergence below this threshold are treated as free-surface particles.
      default: 2.0
 
kernel:
  description: SPH kernel definition
  type: object
  properties:
    kernel_type:
      type: string
      description: SPH smoothing kernel
      enum: [QUADRATIC, CUBIC_SPLINE, QUINTIC_SPLINE, WENDLAND]
      default: CUBIC_SPLINE
    initial_spacing:
      type: number
      description: Initial particle spacing
      minimum: 0
      default: 0.01
    d0_multiplier:
      type: number
      description: Kernel length multiplier; the kernel length is d0_multiplier * initial_spacing
      minimum: 0
      default: 1.2
 
discretization:
  description: Parameters for the SPH discretization operators
  type: object
  properties:
    use_consistent_gradient_discretization:
      type: boolean
      description: Use the G matrix in the SPH gradient approximation
      default: false
    use_consistent_laplacian_discretization:
      type: boolean
      description: Use the L matrix in the SPH Laplacian approximation
      default: false
 
boundary_conditions:
  description: Treatment of fluid-solid boundary conditions
  type: object
  properties:
    boundary_method:
      type: string
      description: Boundary condition enforcement method
      enum: [ADAMI, HOLMES]
      default: ADAMI
    num_bce_layers:
      type: integer
      description: Number of BCE marker layers (on boundaries and solids)
      minimum: 1
      default: 3
 
integration:
  description: Time integration type and parameters
  type: object
  required: [time_step]
  properties:
    time_step:
      type: number
      description: Fluid solver time step size in seconds
      minimum: 0
    integration_scheme:
      type: string
      description: SPH integration scheme
      enum: [EULER, RK2, VERLET, SYMPLECTIC, IMPLICIT_SPH]
      default: RK2
    use_variable_time_step:
      type: boolean
      description: Whether to adapt the time step during the simulation
      default: false
 
proximity_search:
  description: Parameters for the proximity (neighbor) search algorithm
  type: object
  properties:
    num_proximity_search_steps:
      type: integer
      description: Number of steps between updates of the neighbor lists
      minimum: 1
      default: 1
 
particle_shifting:
  description: Particle shifting method and parameters
  type: object
  properties:
    shifting_method:
      type: string
      description: Particle shifting method
      enum: [NONE, PPST, XSPH, PPST_XSPH, DIFFUSION, DIFFUSION_XSPH]
      default: XSPH
    shifting_xsph_eps:
      type: number
      description: XSPH coefficient (XSPH, PPST_XSPH, and DIFFUSION_XSPH methods)
      default: 0.5
    shifting_ppst_push:
      type: number
      description: PPST pushing coefficient (PPST and PPST_XSPH methods)
      default: 3.0
    shifting_ppst_pull:
      type: number
      description: PPST pulling coefficient (PPST and PPST_XSPH methods)
      default: 1.0
    shifting_beta_implicit:
      type: number
      description: Shifting coefficient used by the implicit solver (IMPLICIT_SPH scheme)
      default: 1.0
    shifting_diffusion_A:
      type: number
      description: Diffusion-based shifting coefficient A (DIFFUSION and DIFFUSION_XSPH methods)
      minimum: 1
      maximum: 6
      default: 1.0
    shifting_diffusion_AFSM:
      type: number
      description: Diffusion-based shifting coefficient AFSM (DIFFUSION and DIFFUSION_XSPH methods)
      default: 3.0
    shifting_diffusion_AFST:
      type: number
      description: Diffusion-based shifting coefficient AFST (DIFFUSION and DIFFUSION_XSPH methods)
      default: 2.0
 
viscosity:
  description: Viscosity treatment method and parameters
  type: object
  properties:
    viscosity_method:
      type: string
      description: Viscosity treatment method
      enum: [LAMINAR, ARTIFICIAL_UNILATERAL, ARTIFICIAL_BILATERAL]
      default: ARTIFICIAL_UNILATERAL
    artificial_viscosity:
      type: number
      description: Artificial viscosity coefficient (ARTIFICIAL_UNILATERAL and ARTIFICIAL_BILATERAL methods)
      minimum: 0
      default: 0.02
  