A Chrono YAML FSI problem specification file defines the multibody and fluid problems and co-simulation parameters required to run a Chrono::FSI co-simulation. It consists of the following 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 mbs object which defines YAML specification of the MBS simulation.
[required] The fluid object which defines YAML specification of the fluid specification.
[required] The fsi object which defines YAML specification of coupled FSI problem.
[required] The simulation object which defines the co-simulation metastep and the simulation duration.
[optional] The output object which specifies output options.
[optional] The visualization object which enables run-time visualization and defines rendering settings.

FSI simulation specification

An FSI problem couples a Chrono MBS model and simulation to a fluid solver. Any fluid solver that implements the Chrono::FSI API can be used.

The multibody and fluid simulations are specified by referring to the corresponding YAML specification files. These file names must include the path to the files, relative to the location of this Chrono::FSI YAML specification.

Multibody and fluid system specification

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

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

Specification of coupled FSI problem

The fsi entry (required) describes the coupling itself: which bodies of the multibody model interact with the fluid, and what geometry represents them on the fluid side.

Property	Description	Type	Available Values	Required	Default
`name`	Name of the coupled 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
`fsi_bodies`	List of rigid bodies that interact with the fluid	array	–	No	no FSI bodies

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	`.`

Each entry of fsi_bodies specifies the following properties:

Property	Description	Type	Available Values	Required	Default
`name`	Name of the body in the multibody model	string	–	Yes	–
`shapes`	Geometry used to generate the fluid-solid interface markers	array	–	Yes	–

The body name is looked up in the MBS model; if no body with that name exists, a warning is issued and the entry is ignored. Note that the lookup matches all instances of that body name, so a single fsi_bodies entry covers every instance of a multiply-instantiated MBS model.

Each entry of shapes specifies the following properties:

Property	Description	Type	Available Values	Required	Default
`type`	Geometric shape type	enum	`SPHERE`,`BOX`,`CYLINDER`,`HULL`,`MESH`	Yes	–
`location`	Shape location relative to the body reference frame	array[3]	–	No	[0, 0, 0]
`orientation`	Shape orientation relative to the body reference frame	array[3] or array[4]	–	No	identity rotation
`dimensions`	Length, width, and height	array[3]	–	Yes, for `BOX`	–
`radius`	Shape radius	double	–	Yes, for `SPHERE` and `CYLINDER`	–
`length`	Cylinder length	double	–	Yes, for `CYLINDER`	–
`axis`	Cylinder axis direction, in the body reference frame	array[3]	–	Yes, for `CYLINDER`	–
`filename`	3D data file name	string	–	Yes, for `MESH` and `HULL`	–
`scale`	Scale factor	double	–	No	1.0

Co-simulation options

Property	Description	Type	Available Values	Required	Default
`time_step`	Co-simulation (meta) step	double	–	Yes	–
`end_time`	Total simulation time in seconds	double	–	No	-1 for infinite simulation
`gravity`	Gravitational acceleration vector [x, y, z]	array[3]	–	No	[0, 0, -9.8]

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 coupled problem is enabled. It must specify a YAML object with the following properties:

Property	Description	Type	Available Values	Required	Default
`render_fps`	Rendering frequency (FPS or Hz)	double	–	No	120
`enable_shadows`	Turn on shadow rendering	boolean	–	No	`true`
`camera`	Camera settings	object	–	No	–
`output`	Image output settings	object	–	No	–

There is no type entry at this level: the mere presence of the visualization key enables rendering. Body visualization shapes are controlled by the visualization entry of the referenced MBS simulation file, and fluid-phase rendering by the visualization entry of the referenced fluid simulation file (SPH or TDPF).

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

Property	Description	Type	Available Values	Required	Default
`vertical`	Vertical direction (camera "up")	enum	`Y`,`Z`	No	`Z`
`location`	Camera initial location	array[3]	–	No	[0,-1,0]
`target`	Camera initial target ("look-at" point)	array[3]	–	No	[0,0,0]

The output key nested under visualization, if present, specifies the following properties:

Property	Description	Type	Available Values	Required	Default
`save_images`	Whether to save rendered frames as image files	boolean	–	No	`false`
`image_type`	Image file type, specified through the file extension	string	–	No	`bmp`

Example

Below is an example of an FSI simulation configuration:

chrono-version: 10.0
type: FSI
 
mbs:   "mbs.yaml"
fluid: "sph.yaml"
 
fsi:
  name: cylinder_drop
  angle_degrees: true
  
  data_path:
    type: RELATIVE
    root: "../../.."
 
  fsi_bodies: 
    - name: object
      shapes:
        - type: CYLINDER
          location: [0, 0, 0]
          axis: [1, 0, 0]
          radius: 0.12
          length: 0.20
 
simulation:
  time_step: 1e-4
  end_time: -1
  gravity: [0, 0, -9.8]
 
visualization:
  render_fps: 120
  enable_shadows: false
  camera:
    vertical: Z
    location: [2, 2, 1.8]
    target: [0, 0, 0.6]
  output:
    save_images: false
    image_type: "bmp"

YAML schema

The YAML FSI simulation specification file must follow the data/yaml/schema/fsi_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 YAML Chrono::FSI simulation specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
 
required: [chrono-version, type, mbs, fluid, fsi, simulation]
 
chrono-version:
  type: string
  description: Chrono version compatible with this YAML 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 geometric shapes for FSI interaction
shape : &SHAPE
    type: object
    properties:
        type:
            description: Geometric shape type
            type: string
            enum: [SPHERE, BOX, CYLINDER, HULL, MESH]
        location:
            <<: *VECTOR3D
            description: Shape location relative to body reference frame
        orientation:
            <<: *ORIENTATION3D
            description: Shape orientation relative to body reference frame
        dimensions:
            <<: *VECTOR3D
            description: Length, width, and height (required for BOX type)
        radius:
            description: Radius of the sphere (required for SPHERE or CYLINDER type)
            type: number
            minimum: 0.0
        length:
            description: Length (required for CYLINDER type)
            type: number
            minimum: 0.0
        axis:
            <<: *VECTOR3D
            description: Axis direction expressed in body reference frame (required for CYLINDER type)
        filename:
            description: 3D data file name (required for MESH or HULL type)
            type: string
        scale:
            description: Scale factor (for MESH type)
            type: number
            default: 1.0
 
# -----------------------------------------------------------------------------
# Definition of the FSI simulation
 
type:
  description: Type of Chrono simulation (must be FSI)
  type: string
  value: FSI
 
mbs:
  description: |
      YAML file for MBS simulation specification.
      The path to the MBS file must be provided relative to the location of this simulation specification file.
      The MBS file must follow the mbs_simulation.schema.
  type: string
 
fluid:
  description: |
      YAML file for fluid simulation specification.
      The path to the fluid file must be provided relative to the location of this simulation specification file.
      The fluid file must follow the fsisph_simulation.schema or the fsitdpf_simulation.schema.
  type: string
    
fsi:
  description: Specification of the coupled problem
  type: object
  properties:
    name:
      type: string
      description: Name of the model
      default: ''
 
    angle_degrees:
      type: boolean
      description: Whether angles are specified in degrees (true) or radians (false)
      default: true
    
    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: "."
 
    fsi_bodies:
      description: names of FSI rigid bodies (bodies interacting with fluid)
      type: array
      items:
        type: object
        required: [name, shapes]
        properties:
          name:
            description: Name of the body in the multibody system
            type: string
          shapes:
            description: FSI geometry.
            type: array
            items:
              <<: *SHAPE
 
simulation:
  description: Definition of co-simulation metastep and simulation duration
  type: object
  required: [time_step]
  properties:
    time_step:
      description: Co-simulation metastep (duration between inter-phase data communication)
      type: number
      minimum: 0
    end_time:
      description: Simulation duration
      type: number
      minimum: 0
    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: |
    Run-time visualization settings.
    The mere presence of this object enables run-time visualization for the coupled FSI problem.
    Note that body visualization shapes are controlled by the referenced MBS simulation file, and fluid-phase
    rendering by the referenced fluid simulation file; there is no `type` entry at this level.
  type: object
  properties:
      render_fps:
          type: number
          description: Target frames per second for visualization
          minimum: 0
          default: 120
      enable_shadows:
          type: boolean
          description: Whether to enable shadows in run-time visualization system
          default: true
      camera:
          type: object
          properties:
              vertical:
                  type: string
                  description: Vertical axis for camera orientation
                  enum: [Y, Z]
                  default: Z
              location:
                  <<: *VECTOR3D
                  description: Initial camera location
                  default: [0, -1, 0]
              target:
                  <<: *VECTOR3D
                  description: Initial camera look-at point
                  default: [0, 0, 0]
      output:
          type: object
          description: Run-time visualization image output
          properties:
              save_images:
                  type: boolean
                  description: Whether to save rendered frames as image files
                  default: false
              image_type:
                  type: string
                  description: Image file type, specified through the file extension
                  default: bmp
 
 
  