A Chrono YAML SPH model file defines a fluid system for Chrono::FSI-SPH and contains two 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.
[required] The model object that defines the fluid phase, its material properties, and the problem geometry.

Model specification

An SPH model defines the fluid (or granular) phase: its material properties, the region initially filled with SPH particles, the boundaries that confine it, and the extent of the computational domain. The model object supports the following properties:

Property	Description	Type	Available Values	Required	Default
`physics_problem`	Fluid physics type: incompressible fluid (CFD) or homogenized granular dynamics (CRM)	enum	`CFD`,`CRM`	Yes	–
`geometry_type`	Coordinate geometry used for the domain definitions	enum	`CARTESIAN`,`CYLINDRICAL`	Yes	–
`name`	Name of the model	string	–	No	empty string
`angle_degrees`	Whether angles are specified in degrees (true) or radians (false)	boolean	–	No	`true`
`data_path`	Location of the data files referenced in this specification	object	–	No	absolute paths
`fluid_properties`	Physical parameters of the fluid (`CFD` physics)	object	–	No	see below
`soil_properties`	Physical parameters of the soil (`CRM` physics)	object	–	No	see below
`initial_states`	Initialization of the SPH particle states	object	–	No	zero pressure and velocity
`wave_tank`	A wave tank with a wave maker mechanism	object	–	No	–
`fluid_domain`	Region initially filled with SPH particles	object	–	Yes, unless `wave_tank` is present	–
`container`	Boundary of the fluid container	object	–	No	–
`computational_domain`	Extent of the computational domain and its boundary condition types	object	–	No	unbounded

A wave_tank is an alternative to specifying the domain explicitly: if wave_tank is present, then fluid_domain, container, and computational_domain are all ignored.

The data_path key, if present, specifies the following properties:

Property	Description	Type	Available Values	Required	Default
`type`	Mode for data file location	enum	`ABSOLUTE`,`RELATIVE`	Yes	`ABSOLUTE`
`root`	Root of data files, relative to the location of this file	string	–	No	`.`

Material properties

For a CFD problem, the fluid_properties key specifies:

Property	Description	Type	Available Values	Required	Default
`density`	Fluid density	double	–	No	1000.0
`viscosity`	Laminar viscosity	double	–	No	0.1
`characteristic_length`	Characteristic length for Reynolds number calculation	double	–	No	1.0

For a CRM problem, the soil_properties key specifies:

Property	Description	Type	Available Values	Required	Default
`density`	Bulk density	double	–	No	1000.0
`Young_modulus`	Young's modulus	double	–	No	1e6
`Poisson_ratio`	Poisson's ratio	double	–	No	0.3
`mu_I0`	Reference inertia number	double	–	No	0.03
`mu_fric_s`	Static friction coefficient mu_s in mu = mu(I)	double	–	No	0.7
`mu_fric_2`	Limit friction coefficient mu_2 in mu = mu(I)	double	–	No	0.7
`average_diam`	Average granular particle diameter	double	–	No	0.005
`cohesion_coefficient`	Cohesion coefficient	double	–	No	0

Initial particle states

The initial_states key, if present, specifies:

Property	Description	Type	Available Values	Required	Default
`depth_based_pressure`	Whether to initialize particle pressure from hydrostatic depth	boolean	–	No	`false`
`zero_height`	Height of the zero-pressure level	double	–	Yes, if `depth_based_pressure` is present	–
`initial_velocity`	Uniform initial velocity applied to all SPH particles	array[3]	–	No	[0, 0, 0]

Fluid domain and container

The fluid_domain key defines the region initially filled with SPH particles. The container key defines a (typically larger) region whose walls confine the fluid. Both use the same properties, which depend on the model geometry_type.

For CARTESIAN geometry:

Property	Description	Type	Available Values	Required	Default
`dimensions`	Dimensions of the box	array[3]	–	Yes	–
`box_origin`	Origin of the box	array[3]	–	No	[0, 0, 0]
`box_walls`	Boundary walls of the box	object	–	No	no walls

For CYLINDRICAL geometry:

Property	Description	Type	Available Values	Required	Default
`inner_radius`	Inner radius of the cylindrical annulus	double	–	Yes	–
`outer_radius`	Outer radius of the cylindrical annulus	double	–	Yes	–
`height`	Height of the cylindrical annulus	double	–	Yes	–
`cyl_origin`	Origin of the cylindrical annulus	array[3]	–	No	[0, 0, 0]
`cyl_walls`	Boundary walls of the annulus	object	–	No	no walls

Walls are specified as a pair of flags per direction, ordered [negative side, positive side]. For box_walls, all three of the following are required:

Property	Description	Type	Available Values	Required	Default
`x`	Walls normal to the X direction	array[2] of boolean	–	Yes	–
`y`	Walls normal to the Y direction	array[2] of boolean	–	Yes	–
`z`	Walls normal to the Z direction	array[2] of boolean	–	Yes	–

For cyl_walls, both of the following are required:

Property	Description	Type	Available Values	Required	Default
`side`	Cylindrical surfaces [inner, outer]	array[2] of boolean	–	Yes	–
`z`	End caps normal to the Z direction	array[2] of boolean	–	Yes	–

Note that walls may be defined on the fluid domain or on a container, but not both: specifying a container after fluid_domain has already declared walls is an error.

Computational domain

The computational_domain key, if present, bounds the region in which SPH particles are tracked and sets the boundary condition type in each direction.

Property	Description	Type	Available Values	Required	Default
`aabb_min`	Min corner of the computational domain AABB	array[3]	–	Yes	–
`aabb_max`	Max corner of the computational domain AABB	array[3]	–	Yes	–
`x_bc_type`	BC type in the X direction (negative and positive X)	enum	`NONE`,`PERIODIC`,`INLET_OUTLET`	No	`NONE`
`y_bc_type`	BC type in the Y direction (negative and positive Y)	enum	`NONE`,`PERIODIC`,`INLET_OUTLET`	No	`NONE`
`z_bc_type`	BC type in the Z direction (negative and positive Z)	enum	`NONE`,`PERIODIC`,`INLET_OUTLET`	No	`NONE`

For CARTESIAN geometry, a boundary condition type other than NONE in a given direction requires that no fluid domain wall was defined normal to that direction.

Wave tank

A wave_tank is a self-contained alternative to the domain definitions above. It requires physics_problem: CFD and geometry_type: CARTESIAN.

Property	Description	Type	Available Values	Required	Default
`type`	Wave maker mechanism type	enum	`PISTON`,`FLAP`	Yes	–
`tank_dimensions`	Dimensions of the wave tank container	array[3]	–	Yes	–
`water_depth`	Initial water depth in the tank	double	–	Yes	–
`actuation_function`	Function of time defining actuation of the wave maker	object	–	Yes	–
`tank_origin`	Origin of the wave tank container	array[3]	–	No	[0, 0, 0]
`end_wall`	Whether to create a wall at the far end of the tank	boolean	–	No	`true`
`profile`	Profile of the tank bottom, as [[x, z], ...] data points	array	–	No	flat bottom

The actuation_function is a generic function object (see the MBS model schema for the available function types). In addition, it accepts an optional delay property specifying a time offset in seconds before wave maker actuation begins (default: 0).

Example

Below is an example of an SPH model configuration:

YAML schema

The YAML SPH model specification file must follow the data/yaml/schema/fsisph_model.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 model specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
# The `model` object contains the schema for the model YAML specification.
#
# =============================================================================
 
required: [chrono-version, model]
 
chrono-version:
  type: string
  description: Chrono version compatible with this YAML model specification (M.m or M.m.p)
 
# -----------------------------------------------------------------------------
# Definitions of common Chrono types
# -----------------------------------------------------------------------------
 
# Specification of a ChVector3d
vector3d: &VECTOR3D
    type: array
    items:
        type: number
    minItems: 3
    maxItems: 3
 
# Specification of a 3D rotation
# A rotation can be provided as:
# - an Euler angle sequence [yaw, pitch, roll], with angles assumed in radians or degrees, or
# - a unit quaternion [e0, e1, e2, e3]
orientation3d: &ORIENTATION3D
    type: array
    description: Frame orientation as Euler angles or as quaternion
    items:
      type: number
    minItems: 3
    maxItems: 4
 
# Specification of a color
color: &COLOR
  type: array
  description: RGB color [r, g, b]
  items:
    type: number
    minimum: 0
    maximum: 1
  minItems: 3
  maxItems: 3
 
# Specification of a data array with 2 columns
data_array_2: &DATA_ARRAY_2
    type: array
    description: Array of number pairs
    items:
      type: array
      items:
        type: number
      minItems: 2
      maxItems: 2
 
# Specification of a function of one variable
function: &FUNCTION
    type: object
    description: Function of one variable
    required: [type]
    properties:
      type:
        type: string
        enum: [CONSTANT, POLYNOMIAL, SINE, RAMP, DATA]
        description: Function type
      repeat:
        type: object
        description: Periodic replication of the underlying function
        start:
          type: number
          description: Slice start position
        width:
          type: number
          description: Slice width
        shift:
          type: number
          description: Slice shift
      value:
        type: number
        description: Constant value for CONSTANT type
      coefficients:
        type: array
        description: Coefficents for POLYNOMIAL type
        items:
          type: number
        minItems: 2
      amplitude:
        type: number
        description: Amplitude for SINE type
      frequency:
        type: number
        description: Frequency for SINE type
      phase:
        type: number
        description: Phase for SINE type
        default: 0.0
      slope:
        type: number
        description: Slope for RAMP type
      intercept:
        type: number
        description: Intercept value for RAMP type
        default: 0.0
      data:
        <<: *DATA_ARRAY_2
        description: Interpolation data points for DATA type [[x, f(x)], ...]  
 
# -----------------------------------------------------------------------------
# Definition of a Chrono::SPH fluid model
# -----------------------------------------------------------------------------
 
model:
  description: Definition of a Chrono::SPH fluid model
  type: object
  required: [physics_problem, geometry_type]
  # note: fluid_domain is required unless a wave_tank is specified
 
  properties:
 
    name:
      type: string
      description: Name of the model
      default: ''
 
    physics_problem:
      description: Fluid physics type (incompressible fluid or homogenized granular dynamics).
      type: string
      enum: [CFD, CRM]
 
    geometry_type:
      description: Cartesian or cylindrical coordinate geometry.
      type: string
      enum: [CARTESIAN, CYLINDRICAL]
 
    data_path:
      type: object
      description: Location of data files in the model specification.
      required: [type]
      properties:
        type: 
            type: string
            description: Mode for data file location
            enum: [ABSOLUTE, RELATIVE]
            default: ABSOLUTE
        root:
            type: string
            description: Root of data files, relative to the location of this script
            default: "."
 
    fluid_properties:
      description: Physical parameters of the fluid (CFD physics).
      type: object
      properties:
        density:
          description: Fluid density.
          type: number
          minimum: 0
          default: 1000.0
        viscosity:
          description: Laminar viscosity.
          type: number
          minimum: 0
          default: 0.1
        characteristic_length:
          description: Characteristic length for Reynolds number calculation.
          type: number
          minimum: 0
          default: 1.0
 
    soil_properties:
      description: Physical parameters of the soil (CRM physics).
      type: object
      properties:
        density:
          description: Bulk density.
          type: number
          minimum: 0
          default: 1000.0
        Young_modulus:
          description: Young's modulus.
          type: number
          minimum: 0
          default: 1e6
        Poisson_ratio:
          description: Poisson's ratio.
          type: number
          default: 0.3
        mu_I0:
          description: Reference inertia number.
          type: number
          minimum: 0
          default: 0.03
        mu_fric_s:
          description: Static friction coefficient mu_s in mu = mu(I).
          type: number
          minimum: 0
          default: 0.7
        mu_fric_2:
          description: Limit friction coefficient mu_2 in mu = mu(I).
          type: number
          minimum: 0
          default: 0.7
        average_diam:
          description: Average granular particle diameter.
          type: number
          minimum: 0
          default: 0.005
        cohesion_coefficient:
          description: Cohesion coefficient.
          type: number
          minimum: 0
          default: 0.0
 
    initial_states:
      description: Initialization of the SPH particle states.
      type: object
      properties:
        depth_based_pressure:
          description: |
            Whether to initialize particle pressure from hydrostatic depth.
            If present and true, `zero_height` is required.
          type: boolean
          default: false
        zero_height:
          description: Height of the zero-pressure level (required if depth_based_pressure is set).
          type: number
        initial_velocity:
          <<: *VECTOR3D
          description: Uniform initial velocity applied to all SPH particles.
          default: [0, 0, 0]
 
    wave_tank:
      description: Specification of a wave tank with wave maker mechanism.
      type: object
      required: [type, tank_dimensions, water_depth, actuation_function]
      properties:
        type:
          description: Wave maker mechanism type.
          type: string
          enum: [PISTON, FLAP]
        tank_dimensions:
          <<: *VECTOR3D
          description: Dimensions of the wave tank container.
        tank_origin:
          <<: *VECTOR3D
          description: Origin of the wave tank container.
        water_depth:
          description: Initial water depth in the tank.
          type: number
          minimum: 0
        end_wall:
          description: Whether to create a wall at the far end of the tank.
          type: boolean
          default: true
        profile:
          <<: *DATA_ARRAY_2
          description: Profile function of the water tank bottom.
        actuation_function:
          <<: *FUNCTION
          description: |
            Function of time defining actuation of the wave maker mechanism.
            In addition to the properties of a generic function object, an optional `delay` property
            specifies a time offset (in seconds) before wave maker actuation begins (default: 0).
 
    fluid_domain:
      description: Specification of the SPH fluid domain.
      type: object
      properties:
        dimensions:
          <<: *VECTOR3D
          description: Dimensions of the fluid domain box (CARTESIAN geometry).
        box_origin:
          <<: *VECTOR3D
          description: Origin of the fluid domain box (CARTESIAN geometry).
        box_walls:
          description: |
            Boundary walls around the fluid domain (CARTESIAN geometry).
            Each entry is a pair of flags [negative side, positive side] for the corresponding direction.
          type: object
          required: [x, y, z]
          properties:
            x:
              description: Walls normal to the X direction [X_NEG, X_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            y:
              description: Walls normal to the Y direction [Y_NEG, Y_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            z:
              description: Walls normal to the Z direction [Z_NEG, Z_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
        inner_radius:
          description: Inner radius of the fluid domain cylindrical annulus (CYLINDRICAL geometry)
          type: number
        outer_radius:
          description: Outer radius of the fluid domain cylindrical annulus (CYLINDRICAL geometry)
          type: number
        height:
          description: Height of the fluid domain cylindrical annulus (CYLINDRICAL geometry)
          type: number
        cyl_origin:
          <<: *VECTOR3D
          description: Origin of the fluid domain cylindrical annulus (CYLINDRICAL geometry).
        cyl_walls:
          description: |
            Boundary walls around the fluid domain (CYLINDRICAL geometry).
            Each entry is a pair of flags for the two sides of the corresponding boundary.
          type: object
          required: [side, z]
          properties:
            side:
              description: Cylindrical surfaces [inner (SIDE_INT), outer (SIDE_EXT)]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            z:
              description: End caps normal to the Z direction [Z_NEG, Z_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
 
    container:
      description: Specification of the container boundary.
      type: object
      properties:
        dimensions:
          <<: *VECTOR3D
          description: Dimensions of the box container (CARTESIAN geometry).
        box_origin:
          <<: *VECTOR3D
          description: Origin of the box container (CARTESIAN geometry).
        box_walls:
          description: |
            Container boundary walls (CARTESIAN geometry).
            Each entry is a pair of flags [negative side, positive side] for the corresponding direction.
          type: object
          required: [x, y, z]
          properties:
            x:
              description: Walls normal to the X direction [X_NEG, X_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            y:
              description: Walls normal to the Y direction [Y_NEG, Y_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            z:
              description: Walls normal to the Z direction [Z_NEG, Z_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
        inner_radius:
          description: Inner radius of the cylindrical annulus container (CYLINDRICAL geometry)
          type: number
        outer_radius:
          description: Outer radius of the cylindrical annulus container (CYLINDRICAL geometry)
          type: number
        height:
          description: Height of the cylindrical annulus container (CYLINDRICAL geometry)
          type: number
        cyl_origin:
          <<: *VECTOR3D
          description: Origin of the cylindrical annulus container (CYLINDRICAL geometry).
        cyl_walls:
          description: |
            Container boundary walls (CYLINDRICAL geometry).
            Each entry is a pair of flags for the two sides of the corresponding boundary.
          type: object
          required: [side, z]
          properties:
            side:
              description: Cylindrical surfaces [inner (SIDE_INT), outer (SIDE_EXT)]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
            z:
              description: End caps normal to the Z direction [Z_NEG, Z_POS]
              type: array
              items:
                type: boolean
              minItems: 2
              maxItems: 2
 
    computational_domain:
      description: Specification of the FSI computational domain (AABB) and boundary condition types.
      type: object
      properties:
        aabb_min:
          <<: *VECTOR3D
          description: Min corner of the computational domain AABB.
        aabb_max:
          <<: *VECTOR3D
          description: Max corner of the computational domain AABB.
        x_bc_type:
          description: BC type in X direction (negative and positive X)
          type: string
          enum: [NONE, PERIODIC, INLET_OUTLET]
        y_bc_type:
          description: BC type in Y direction (negative and positive Y)
          type: string
          enum: [NONE, PERIODIC, INLET_OUTLET]
        z_bc_type:
          description: BC type in Z direction (negative and positive Z)
          type: string
          enum: [NONE, PERIODIC, INLET_OUTLET]