YAML schema for Chrono::FSI-SPH model specification

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:

chrono-version: 10.0
model:
name: Container
physics_problem: CFD
geometry_type: CARTESIAN
angle_degrees: true
data_path:
type: RELATIVE
root: "../../.."
fluid_properties:
density: 1000.0
viscosity: 1.0
characteristic_length: 1.0
initial_states:
depth_based_pressure: true
zero_height: 3.8
fluid_domain:
dimensions: [3.8, 1, 3.8]
box_origin: [-4, 0, 0]
container:
dimensions: [12, 1, 8]
box_origin: [0, 0, 0]
box_walls:
x: [true, true] # negative, positive
y: [false, false] # negative, positive
z: [true, false] # negative, positive
computational_domain:
aabb_min: [-7, -0.55, -16]
aabb_max: [7, 0.55, 16]
x_bc_type: NONE
y_bc_type: PERIODIC
z_bc_type: NONE

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]