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 fileds 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 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

** TODO **

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]

Visualization options

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

Property	Description	Type	Available Values	Required	Default
`type`	Type of visualization shapes	enum	`NONE`,`PRIMITIVES`,`MODEL_FILE`,`COLLISION`	No	`NONE`
`render_fps`	Rendering frequency (FPS or Hz)	double	–	No	120
`enable_shadows`	Turn on shadow rendering	boolean	–	No	`true`
`camera`	Camera settings	object	–	No	–

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]

Example

Below is an example of an FSI simulation configuration:

chrono-version: 9.0
type: FSI
 
mbs:   "mbs.yaml"
fluid: "sph.yaml"
 
fsi:
  name: FSI object drop
  angle_degrees: true
  
  data_path:
    type: RELATIVE
    root: "../../.."
 
  fsi_bodies: 
    - name: object
      shapes:
        - type: CYLINDER
          dimensions: [0.9, 0.9, 0.15]
          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]

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 sluid 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, relatiuve to 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]
 
visualization:
  description: Visualization settings
  type: object
  properties:
      type:
          type: string
          description: Visualization type.
          enum: [MODEL_FILE, PRIMITIVES, COLLISION, NONE]
          default: MODEL_FILE
      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]
 
 
  