A Chrono YAML TDPF simulation file defines the setup for a Chrono::FSI-TDPF 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 TDPF here.
[required] The model entry which names the YAML specification of the TDPF problem.
[required] The solver entry which names the YAML specification of the TDPF solver settings.
[optional] The simulation object which specifies settings for the fluid phase.
[optional] The output object which specifies output options from the TDPF simulation.
[optional] The visualization object which specifies TDPF-specific run-time visualization settings.

FSI-TDPF simulation specification

An FSI-TDPF simulation must specify the TDPF model to be simulated, as well as optional output and TDPF-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 a TDPF model specification (which must follow the TDPF 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 a TDPF solver specification (which must follow the TDPF solver schema).

Simulation options

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

Property	Description	Type	Available Values	Required	Default
`gravity`	Gravitational acceleration vector [x, y, z]	array[3]	–	No	[0, 0, -9.8]

Note that in a coupled FSI simulation the gravitational acceleration given in the FSI simulation file governs both phases and overrides this value, exactly as it does for Chrono::FSI-SPH. This setting therefore takes effect when the TDPF fluid system is driven on its own, as it is through the Chrono preCICE adapter, where the two phases run as separate processes and nothing reconciles their gravity for you.

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 water surface is enabled. The following TDPF-specific properties can be set:

Property	Description	Type	Available Values	Required	Default
`update_fps`	Frequency (FPS or Hz) at which the wave mesh is updated	double	–	No	30
`color_map`	Colormap-based coloring of the wave mesh	object	–	No	no coloring

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

Property	Description	Type	Available Values	Required	Default
`type`	Wave mesh quantity used for coloring	enum	`NONE`,`HEIGHT`,`VELOCITY`	Yes	–
`map`	Colormap	enum	`BLACK_BODY`,`BLUE`,`BROWN`, `COPPER`,`FAST`,`INFERNO`, `JET`,`KINDLMANN`,`PLASMA`, `RED_BLUE`	No	`FAST`
`min`	Lower end of the color data range	double	–	No	-1
`max`	Upper end of the color data range	double	–	No	1

Settings common to all Chrono run-time visualization (render_fps, camera, and output, documented with the MBS simulation schema) are read from this same visualization object. In a coupled FSI simulation they are overridden by the corresponding settings in the FSI simulation file, so there is no reason to duplicate them here. They do take effect when this file is the top-level specification, as it is for a Chrono preCICE participant; in that case a camera entry is effectively required, since the default places the eye in the z=0 plane.

Example

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

chrono-version: 10.0
type: TDPF
  
model:  "tdpf_model.yaml"
solver: "tdpf_solver.yaml"
 
output:
  format: NONE
  mode: FRAMES
  fps: 20
 
visualization:
  update_fps: 30
  color_map:
    type: HEIGHT
    map: BLUE
    min: -1.5
    max: 1.5
  

YAML schema

The YAML TDPF simulation specification file must follow the data/yaml/schema/fsitdpf_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-TDPF 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-TDPF simulation
 
type:
  description: Type of Chrono simulation (must be TDPF)
  type: string
  value: TDPF
 
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 fsitdpf_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 fsitdpf_solver.schema.
  type: string
 
simulation:
  description: |
      Simulation settings for the fluid phase.
      Note that in a coupled FSI simulation the gravitational acceleration given in the FSI simulation
      file governs both phases and overrides the value below, exactly as for Chrono::FSI-SPH. This
      setting therefore takes effect when the TDPF fluid system is driven on its own, as it is through
      the Chrono preCICE adapter.
  type: object
  properties:
    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.
      Settings common to all Chrono run-time visualization (`render_fps`, `camera`, and `output`) are read
      from this same object, per the mbs_simulation schema. In a coupled FSI simulation they are overridden
      by those in the FSI simulation file; they take effect when this file is the top-level specification,
      as it is for a Chrono preCICE participant.
      The TDPF-specific settings below control water surface visualization.
  type: object
  properties:
    update_fps:
      type: number
      description: Frequency (FPS or Hz) at which the wave mesh is updated
      minimum: 0
      default: 30
 
    color_map:
      description: Colormap-based coloring of the wave mesh
      type: object
      required: [type]
      properties:
        type:
          type: string
          description: Wave mesh quantity used for coloring
          enum: [NONE, HEIGHT, VELOCITY]
          default: NONE
        map:
          type: string
          description: Colormap
          enum: [BLACK_BODY, BLUE, BROWN, COPPER, FAST, INFERNO, JET, KINDLMANN, PLASMA, RED_BLUE]
          default: FAST
        min:
          type: number
          description: Lower end of the color data range
          default: -1
        max:
          type: number
          description: Upper end of the color data range
          default: 1
 