A Chrono YAML TDPF model file defines a linear potential-flow hydrodynamics model for Chrono::FSI-TDPF and contains two 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 model object that identifies the hydrodynamic data file and, optionally, the wave conditions.

Model specification

A TDPF model does not discretize the fluid. It applies hydrodynamic forces (added mass, radiation damping, and wave excitation) to the FSI bodies of the coupled multibody model, based on pre-computed frequency-domain coefficients read from an HDF5 file.

Property	Description	Type	Available Values	Required	Default
`name`	Name of the 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 below	object	–	No	absolute paths
`h5_file`	Input file with hydrodynamic data (HDF5 format)	string	–	Yes	–
`waves`	Specification of wave conditions	object	–	No	no waves

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

Wave conditions

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

Property	Description	Type	Available Values	Required	Default
`type`	Wave type	enum	`NONE`,`REGULAR`,`IRREGULAR`	Yes	`NONE`
`height`	Wave height (twice the wave amplitude)	double	–	Yes, for `REGULAR`	–
`period`	Wave period in seconds	double	–	Yes, for `REGULAR`	–
`phase`	Wave phase	double	–	No	0
`stretching`	Whether to apply wave stretching	boolean	–	No	`true`

Note that IRREGULAR waves are accepted by the parser but not yet implemented; no waves are generated for that type.

Example

Below is an example of a TDPF model configuration:

chrono-version: 10.0
 
model:
  name: water tank
  angle_degrees: true
   
  data_path:
    type: RELATIVE
    root: "../../.."
 
  h5_file: fsi-tdpf/sphere/sphere.h5
 
  waves:
    type: regular
    height: 3.0
    period: 5.0
    direction: 0.0  # degrees, 0 = positive x
    phase: 0.0
 
    # type: no_wave

YAML schema

The YAML TDPF model specification file must follow the data/yaml/schema/fsitdpf_model.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::TDPF YAML fluid model specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
# The `model` object contains the schema for the model YAML specification.
#
# =============================================================================
 
required: [chrono-version, model]
 
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 a color
color: &COLOR
  type: array
  description: RGB color [r, g, b]
  items:
    type: number
    minimum: 0
    maximum: 1
  minItems: 3
  maxItems: 3
 
# Specification of a data array with 2 columns
data_array_2: &DATA_ARRAY_2
    type: array
    description: Array of number pairs
    items:
      type: array
      items:
        type: number
      minItems: 2
      maxItems: 2
 
# Specification of a function of one variable
function: &FUNCTION
    type: object
    description: Function of one variable
    required: [type]
    properties:
      type:
        type: string
        enum: [CONSTANT, POLYNOMIAL, SINE, RAMP, DATA]
        description: Function type
      repeat:
        type: object
        description: Periodic replication of the underlying function
        start:
          type: number
          description: Slice start position
        width:
          type: number
          description: Slice width
        shift:
          type: number
          description: Slice shift
      value:
        type: number
        description: Constant value for CONSTANT type
      coefficients:
        type: array
        description: Coefficents for POLYNOMIAL type
        items:
          type: number
        minItems: 2
      amplitude:
        type: number
        description: Amplitude for SINE type
      frequency:
        type: number
        description: Frequency for SINE type
      phase:
        type: number
        description: Phase for SINE type
        default: 0.0
      slope:
        type: number
        description: Slope for RAMP type
      intercept:
        type: number
        description: Intercept value for RAMP type
        default: 0.0
      data:
        <<: *DATA_ARRAY_2
        description: Interpolation data points for DATA type [[x, f(x)], ...]  
 
# -----------------------------------------------------------------------------
# Definition of a Chrono::TDPF fluid model
# -----------------------------------------------------------------------------
 
model:
  description: Definition of a Chrono::TDPF fluid model
  type: object
  required: [h5_file]
 
  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: "."
 
    h5_file:
      description: Input file with hydrodynamic data (HDF5 format)
      type: string
 
    waves:
      description: |
        Specification of wave conditions.
        If this object is omitted, or if `type` is NONE, no waves are added.
      type: object
      required: [type]
      properties:
        type:
             type: string
             description: Wave type. IRREGULAR waves are not yet implemented.
             enum: [NONE, REGULAR, IRREGULAR]
             default: NONE
        height:
             type: number
             description: Wave height (twice the wave amplitude). Required for REGULAR waves.
             minimum: 0
        period:
             type: number
             description: Wave period in seconds. Required for REGULAR waves.
             minimum: 0
        phase:
             type: number
             description: Wave phase (REGULAR waves)
             default: 0.0
        stretching:
             type: boolean
             description: Whether to apply wave stretching (REGULAR waves)
             default: true