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:

Property	Description	Type	Available Values	Required	Default
`planes`	List of planes defining the half-spaces	array	–	Yes	–
`mode`	Whether a marker must satisfy all half-spaces or any one of them	enum	`ALL`,`ANY`	No	`ALL`
`SPH`	Apply the visibility criterion to SPH particles	boolean	–	No	`true`
`BCE`	Apply the visibility criterion to 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	array[3]	–	Yes	–

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:  "model_sph.yaml"
solver: "solver_sph.yaml"
 
simulation:  
  end_time: 100
  
output:
    format: NONE
    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: 1.0
    visibility:
       SPH: true
       BCE: true
       mode: ALL
       planes:
           - point: [0, 0, 0]
             normal: [1, 0, 0]
           - point: [0, 0, 0]
             normal: [0, 1, 0]
    splashsurf:
       smoothing_length: 2.0
       cube_size: 0.3
       surface_threshold: 0.6

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.
      minimum: 0
      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 half-spaces.
        A marker is hidden depending on its position relative to the specified planes.
      type: object
      required: [planes]
      properties:
        planes:
          description: List of planes defining the half-spaces
          type: array
          items:
            type: object
            required: [point, normal]
            properties:
              point:
                <<: *VECTOR3D
                description: A point on the plane
              normal:
                <<: *VECTOR3D
                description: Plane normal direction
        mode:
          type: string
          description: Whether a marker must be inside all half-spaces or any one of them
          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 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
 