YAML schema for Chrono::FSI-SPH simulation specification

A Chrono YAML SPH simulation file defines the setup for 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.
  • [required] The simulation type, which must be SPH here.
  • [required] The SPH model object which defines YAML specification of SPH problem.
  • [required] The SPH solver object which defines YAML specification of SPH solver algorithms.
  • [optional] The output object which specifies output options from the SPH simulation.
  • [optional] The visualization object which specifies SPH-specific run-time visualization settings.

FSI-SPH simulation specification

An FSI-SPH simulation must specify the SPH model to be simulated, SPH solver settings, as well as optional output and SPH-specific run-time visualization settings.

Model and solver specification

The model entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with an SPH model specification (which must follow the SPH model schema).

The solver entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with an SPH solver specification (which must follow the SPH solver schema).

Output options

If the output key is present, it must specify a YAML object with the following properties:

Property Description Type Available Values Required Default
format Output DB format enum NONE,ASCII,HDF5 Yes –
mode Output mode (one file per output frame, or a single time-series file) enum FRAMES,SERIES No FRAMES
fps Output frequency (FPS or Hz) double – No 100

Note that format is required whenever the output key is present. HDF5 output silently falls back to NONE in a build without HDF5 support.

Visualization options

If the visualization key is present, run-time visualization of the fluid phase is enabled. The following SPH-specific properties can be set:

Property Description Type Available Values Required Default
sph_markers Render SPH particles boolean – No true
bndry_bce_markers Render boundary BCE markers boolean – No true
rigid_bce_markers Render BCE markers on rigid solids boolean – No true
flex_bce_markers Render BCE markers on flexible solids boolean – No true
active_boxes Render the active domain boxes associated with FSI solids boolean – No false
color_map Colormap-based coloring of SPH particles object – No no coloring
visibility Marker visibility control through a set of half-spaces object – No all markers visible
splashsurf Fluid surface reconstruction object – No disabled

Note that camera and general rendering settings for a coupled FSI simulation are specified in the FSI simulation file, not here.

Particle coloring

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

Property Description Type Available Values Required Default
type Particle quantity used for coloring enum NONE,HEIGHT,VELOCITY,
DENSITY,PRESSURE 		Yes –
map Colormap enum BLACK_BODY,BLUE,BROWN,
COPPER,FAST,INFERNO,
JET,KINDLMANN,PLASMA,
RED_BLUE 		No JET
min Lower end of the color data range double – Yes, unless type is NONE –
max Upper end of the color data range double – Yes, unless type is NONE –
up Direction along which height is measured array[3] – No [0, 0, 1]
bimodal Use a bimodal (two-sided) color scale boolean – Yes, for PRESSURE –

up is used only for the HEIGHT type and bimodal only for the PRESSURE type.

Marker visibility

The visibility key, if present, hides markers based on their position relative to a set of planes, for example to cut away part of the domain and reveal immersed solids. A marker is in front of a plane if it lies on the side the plane normal points to. With mode: ALL, a marker is hidden if it is in front of all planes; with mode: ANY, a marker is hidden if it is in front of at least one plane.

Property Description Type Available Values Required Default
planes List of cutting planes array – Yes –
mode Hide markers in front of all planes (ALL) or in front of at least one plane (ANY) enum ALL,ANY No ALL
SPH Apply the visibility criterion to SPH particles boolean – No true
BCE Apply the visibility criterion to boundary (wall) BCE markers boolean – No true

Each entry of planes specifies the following properties (both required):

Property Description Type Available Values Required Default
point A point on the plane array[3] – Yes –
normal Plane normal direction, pointing toward the side whose markers are hidden array[3] – Yes –

The visibility criterion does not apply to rigid-body and flexible-body BCE markers, which are always rendered (if enabled with rigid_bce_markers and flex_bce_markers). For example, the following hides all SPH particles and wall BCE markers with negative y coordinate, revealing a solid in the plane y = 0 to a camera looking along +y:

visibility:
planes:
- point: [0, 0, 0]
normal: [0, -1, 0]

Surface reconstruction

The mere presence of the splashsurf key enables fluid surface reconstruction. The following optional properties can be set:

Property Description Type Available Values Required Default
smoothing_length Smoothing length for the SPH kernel, in multiples of the particle radius double – No 1.5
cube_size Marching-cubes edge length, in multiples of the particle radius double – No 0.5
surface_threshold Iso-surface density threshold, in multiples of the rest density double – No 0.6

Example

Below is an example of an FSI-SPH simulation configuration:

chrono-version: 10.0
type: SPH
model: "sph_model.yaml"
solver: "sph_solver.yaml"
simulation:
end_time: 100
output:
format: HDF5
mode: FRAMES
fps: 20
visualization:
sph_markers: true
bndry_bce_markers: true
rigid_bce_markers: true
flex_bce_markers: true
active_boxes: false
color_map:
type: VELOCITY
map: FAST
min: 0.0
max: 5.0

YAML schema

The YAML SPH simulation specification file must follow the data/yaml/schema/fsisph_simulation.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::FSI-SPH YAML fluid simulation specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
required: [chrono-version, type, model, solver]
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::FSI-SPH simulation
type:
description: Type of Chrono simulation (must be SPH)
type: string
value: SPH
model:
description: |
Model specification YAML file.
The path to the model file must be provided relative to the location of this simulation specification file.
The model file must follow the fsisph_model.schema.
type: string
solver:
description: |
Solver specification YAML file
The path to the solver file must be provided relative to the location of this simulation specification file.
The solver file must follow the fsisph_solver.schema.
type: string
simulation:
description: Simulation settings
type: object
properties:
end_time:
type: number
description: |
Total simulation duration in seconds.
The simulation will run from t=0 to t=end_time. A negative value indicates an infinite end time.
default: -1
gravity:
type: array
<<: *VECTOR3D
description: Gravitational acceleration vector [x, y, z]
default: [0, 0, -9.8]
output:
description: Output settings
type: object
required: [format]
properties:
format:
type: string
description: Output DB format
enum: [NONE, ASCII, HDF5]
default: NONE
mode:
type: string
description: Output mode (one file per output frame, or a single time-series file)
enum: [FRAMES, SERIES]
default: FRAMES
fps:
type: number
description: Output frequency (FPS or Hz)
minimum: 0
default: 100
visualization:
description: SPH-specific run-time visualization settings
type: object
properties:
sph_markers:
type: boolean
description: Render SPH particles
default: true
bndry_bce_markers:
type: boolean
description: Render boundary BCE markers
default: true
rigid_bce_markers:
type: boolean
description: Render BCE markers on rigid solids
default: true
flex_bce_markers:
type: boolean
description: Render BCE markers on flexible solids
default: true
active_boxes:
type: boolean
description: Render the active domain boxes associated with FSI solids
default: false
color_map:
description: Colormap-based coloring of SPH particles
type: object
required: [type]
properties:
type:
type: string
description: Particle quantity used for coloring
enum: [NONE, HEIGHT, VELOCITY, DENSITY, PRESSURE]
default: NONE
map:
type: string
description: Colormap
enum: [BLACK_BODY, BLUE, BROWN, COPPER, FAST, INFERNO, JET, KINDLMANN, PLASMA, RED_BLUE]
default: JET
min:
type: number
description: Lower end of the color data range (required unless type is NONE)
max:
type: number
description: Upper end of the color data range (required unless type is NONE)
up:
<<: *VECTOR3D
description: Direction along which height is measured (HEIGHT type only)
default: [0, 0, 1]
bimodal:
type: boolean
description: Use a bimodal (two-sided) color scale (required for PRESSURE type)
visibility:
description: |
Marker visibility control through a set of planes (e.g., to cut away part of the domain).
A marker is "in front of" a plane if it lies on the side the plane normal points to.
With mode ALL, a marker is hidden if it is in front of all planes; with mode ANY, a marker
is hidden if it is in front of at least one plane.
The criterion can be applied to SPH particles and to boundary (wall) BCE markers; rigid-body
and flexible-body BCE markers are not affected.
type: object
required: [planes]
properties:
planes:
description: List of planes; markers in front of a plane (on the side of its normal) are candidates for hiding
type: array
items:
type: object
required: [point, normal]
properties:
point:
<<: *VECTOR3D
description: A point on the plane
normal:
<<: *VECTOR3D
description: Plane normal direction (points toward the side whose markers are hidden)
mode:
type: string
description: |
Hide a marker if it is in front of all planes (ALL) or in front of at least one plane (ANY)
enum: [ALL, ANY]
default: ALL
SPH:
type: boolean
description: Apply the visibility criterion to SPH particles
default: true
BCE:
type: boolean
description: Apply the visibility criterion to boundary (wall) BCE markers
default: true
splashsurf:
description: |
Fluid surface reconstruction (splashsurf).
The mere presence of this object enables surface reconstruction.
type: object
properties:
smoothing_length:
type: number
description: Smoothing length for the SPH kernel, in multiples of the particle radius
default: 1.5
cube_size:
type: number
description: Marching-cubes edge length, in multiples of the particle radius
default: 0.5
surface_threshold:
type: number
description: Iso-surface density threshold, in multiples of the rest density
default: 0.6