YAML schema for Chrono::FSI-TDPF model specification

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 –
h5_reference_points Points about which the coefficients in h5_file are given, one per body in HDF5 body order, in the body reference frame array of 3D vectors – No body reference frame origins
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: 11.0
model:
name: TDPF_sphere_decay
angle_degrees: true
data_path:
type: RELATIVE
root: "../../.."
h5_file: fsi-tdpf/sphere_0.12/sphere.h5
# Points about which the hydrodynamic coefficients are given, one per body in HDF5 body order,
# in the body reference frame (default: origins of the body reference frames)
#h5_reference_points:
# - [0, 0, 0]
waves:
type: none

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
h5_reference_points:
description: |
Points about which the hydrodynamic coefficients in the HDF5 file are given, one per body, in the order of the
bodies in that file. Each point is expressed in the reference frame of the corresponding body.
If omitted, the coefficients are assumed to be given about the origins of the body reference frames.
type: array
items: *VECTOR3D
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