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.

An SPH model with CRM physics and a Cartesian box fluid domain can also be used for the CRM terrain of a wheel test rig simulation. The settings it then uses and ignores are listed on the wheel test rig terrain page.

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 (not used by the MCC rheology) double – No 0
rheology_model CRM rheology model enum MU_OF_I,MCC No MU_OF_I
mcc_M Cam-Clay critical state line slope, q = M p (MCC only) double – No 0
mcc_kappa Cam-Clay swelling index: slope of the elastic unload/reload line in v-ln(p) (MCC only) double – No 0
mcc_lambda Cam-Clay compression index: slope of the normal consolidation line in v-ln(p) (MCC only) double – No 0
mcc_v_lambda Cam-Clay specific volume at the reference pressure of 1000 Pa (MCC only) double – No 2.0

The MCC rheology requires mcc_M > 0, mcc_kappa > 0, and mcc_lambda > mcc_kappa; these are checked when the SPH system is initialized. The initial pre-consolidation pressure is set to 1.01 times the initial particle pressure, which is the hydrostatic pressure if initial_states.depth_based_pressure is enabled and 1 kPa otherwise.

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.
#
# When used for the CRM terrain of a single-wheel test rig (see wheel_rig_simulation.schema), the model must use CRM
# physics and a CARTESIAN box fluid domain. The fluid domain dimensions set the terrain patch size; the box origin,
# container, computational domain, zero-pressure height, and initial velocity are ignored.
#
# =============================================================================
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 (not used by the MCC rheology).
type: number
minimum: 0
default: 0.0
rheology_model:
description: |
CRM rheology model: mu(I) (MU_OF_I) or Modified Cam-Clay critical-state plasticity (MCC).
MCC requires mcc_M > 0, mcc_kappa > 0, and mcc_lambda > mcc_kappa.
The initial pre-consolidation pressure is set to 1.01 times the initial particle pressure, which is the
hydrostatic pressure if `initial_states.depth_based_pressure` is enabled and 1 kPa otherwise.
type: string
enum: [MU_OF_I, MCC]
default: MU_OF_I
mcc_M:
description: Cam-Clay critical state line slope, q = M p (MCC only).
type: number
minimum: 0
default: 0.0
mcc_kappa:
description: |
Cam-Clay swelling index, the slope of the elastic unload/reload line in v-ln(p) (MCC only).
Sets the elastic bulk modulus K = v p / mcc_kappa. Must satisfy 0 < mcc_kappa < mcc_lambda.
type: number
minimum: 0
default: 0.0
mcc_lambda:
description: |
Cam-Clay compression index, the slope of the normal consolidation line in v-ln(p) (MCC only).
Must be larger than mcc_kappa.
type: number
minimum: 0
default: 0.0
mcc_v_lambda:
description: Cam-Clay specific volume at the reference pressure of 1000 Pa (MCC only).
type: number
minimum: 0
default: 2.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 true, `zero_height` is required (except for a wheel test rig terrain, which uses the patch surface).
type: boolean
default: false
zero_height:
description: Height of the zero-pressure level (required if depth_based_pressure is true; ignored for a wheel test rig terrain).
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]