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 fileds 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 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
type	Output DB type	enum	NONE,ASCII,HDF5	No	NONE
mode	Output mode	enum	FRAMES,SERIES	No	FRAMES
fps	Output frequency (FPS or Hz)	double	–	No	30

Visualization options

** TODO ** (SPH-specific visualization options)

Example

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

chrono-version: 9.0
tyype: SPH
 
model:  "model_sph.yaml"
solver: "solver_sph.yaml"
 
simulation:  
  end_time: 100
  
output:
    type: 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
    output:
       save_images: false
       output_directory: "."

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 na 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
  properties:
     type:
        type: string
        description: Output DB type
        enum: [NONE, ASCII, HDF5]
        default: NONE
     fps:
        type: number
        description: Output frequency
        minimum: 0
 
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
    # TODO