Xdyn Setup

A practical guide to configuring your vessel's .yml dynamics file for use in LOTUSim. For the underlying concepts (reference frames, conventions, how xdyn works as a tool), see Understanding Xdyn. For the catalog of available force and propeller types, see Forces & Propulsion (Xdyn). For a worked example, see Add a force or propeller in the Tutorial.

⚠️ Watch your indentation. Most Xdyn YAML errors come from inconsistent indentation, not invalid content.

A .yml file has four groups of sections:

Group	Sections	Required?
Environment	rotations convention, environmental constants, environment models	Yes
Bodies	bodies	Yes
Commands	commands, setpoints, controllers	Only if you have propellers/controllers
Output	output	No

---

Environment

Rotations convention -> don't change this! it's the only convention support atm:

rotations convention: [psi, theta', phi''] # yaw, pitch, roll

Environmental constants - global to the whole simulation (see the note in Forces & Propulsion Types):

environmental constants:
	g: {value: 9.81, unit: m/s^2}
	rho: {value: 1025, unit: kg/m^3}
	nu: {value: 1.18e-6, unit: m^2/s}

Environment models - waves, wind, and current. Pick at most one of each:

Type	Minimal example
Flat sea (no waves)	- model: no waves constant sea elevation in NED frame: {value: 0, unit: m}
Airy waves	See Understanding Xdyn for the full spectral/directional setup
No wind	- model: no wind (default if omitted)
Uniform wind	- model: uniform wind velocity: {unit: m/s, value: 8} direction: {unit: deg, value: 135}
Ekman current	- model: ekman current velocity: {value: 1, unit: m/s} wind angle: {value: 0, unit: rad}

Only one current model is supported at a time.

---

Bodies

Each vessel is a bodies list entry. Four things to define:

1. Initial position & velocity

position of body frame relative to mesh:
	frame: mesh
	x: {value: 70.27, unit: m}
	y: {value: 0, unit: m}
	z: {value: -7.55, unit: m}
	phi: {value: 0, unit: rad}
	theta: {value: 0, unit: rad}
	psi: {value: 0, unit: rad}

initial position of body frame relative to NED:
	frame: NED
	x: {value: 0, unit: m}
	y: {value: 0, unit: m}
	z: {value: -1.45, unit: m}
	phi: {value: 0, unit: deg}
	theta: {value: 0, unit: deg}
	psi: {value: 0, unit: deg}

initial velocity of body frame relative to NED:
	frame: body
	u: {value: 2, unit: m/s}
	v: {value: 0, unit: m/s}
	w: {value: 0, unit: m/s}
	p: {value: 0, unit: rad/s}
	q: {value: 0, unit: rad/s}
	r: {value: 0, unit: rad/s}

2. Body characteristics

Mass, inertia, center of gravity: see Understanding Xdyn for full field descriptions.

3. Forces

external forces:

We can divide the forces we need to use between:

• Gravity
• Buoyancy
• Damping

Gravity

- model: gravity

Buoyancy

Three models are currently available:

Basic model

- model: basic buoyancy
  volume: {value: 1.7, unit: m3}

This basic model should only be used if the user has no access to the mesh but still wants to use Xdyn, it's only appropriate for underwater vessels.

Fast model

- model: non-linear hydrostatic (fast)

We recommend this model for buoyancy, it computes the center of buoyancy and the immerged volume based on the mesh.

Exact model

- model: non-linear hydrostatic (exact)

This basic model computes the buoyancy force on every tile of the mesh, the difference is not very significative compared to the fast model for a computed time much higher, that's why we don't recommend this model for LOTUSIM.

Damping

The choice of the appropriate dampings force is complex. Please refer to the Xdyn doc (only in french right now).

- model: linear damping
  damping matrix at the center of gravity projected in the body frame:
	frame: dtmb
	row 1: [ 0, 0,      0,      0,       0, 0]
	row 2: [ 0, 0,      0,      0,       0, 0]
	row 3: [ 0, 0, 8.86e6,      0,       0, 0]
	row 4: [ 0, 0,      0, 3.18e7,       0, 0]
	row 5: [ 0, 0,      0,      0, 1.01e10, 0]
	row 6: [ 0, 0,      0,      0,       0, 0]

- model: quadratic damping
  damping matrix at the center of gravity projected in the body frame:
	frame: dtmb
	row 1: [ 0, 0, 0,      0, 0, 0]
	row 2: [ 0, 0, 0,      0, 0, 0]
	row 3: [ 0, 0, 0,      0, 0, 0]
	row 4: [ 0, 0, 0, 1.16e8, 0, 0]
	row 5: [ 0, 0, 0,      0, 0, 0]
	row 6: [ 0, 0, 0,      0, 0, 0]

- model: diffraction
  hdb: test_ship.hdb
  calculation point in body frame:
	x: {value: 0.696, unit: m}
	y: {value: 0, unit: m}
	z: {value: 1.418, unit: m}
  mirror for 180 to 360: true

- model: resistance curve
  speed: {unit: m/s, values: [0,0.5,1,1.5,2,2.5,3,3.5,4,4.5,5]}
  resistance: {unit: N, values: [0.00E+00,2.10E+02,7.73E+02,1.65E+03,2.80E+03,4.23E+03,6.00E+03,8.50E+03,1.27E+04,2.08E+04,2.79E+04]}

- model: radiation damping
  hdb: test_ship.hdb
  type of quadrature for cos transform: simpson
  type of quadrature for convolution: simpson
  nb of points for retardation function discretization: 50
  omega min: {value: 0, unit: rad/s}
  omega max: {value: 30, unit: rad/s}
  tau min: {value: 0.2094395, unit: s}
  tau max: {value: 10, unit: s}
  output Br and K: false
  calculation point in body frame:
	x: {value: 0.696, unit: m}
	y: {value: 0, unit: m}
	z: {value: 1.418, unit: m}

4. Propellers

Currently, there are 3 propellers models in Xdyn:

• Kt(J) & Kq(J)
• Propeller + Rudder
• Wageningen B-series

Kt(J) & Kq(J)

- name: propeller
  model: Kt(J) & Kq(J)
  position of propeller frame:
  	frame: mesh(LRAUV)
	x: { value: -1.43162, unit: m } # Check if it appears in the correct direction
	y: { value: 0, unit: m }
	z: { value: 0, unit: m }
	phi: { value: 0, unit: rad }
	theta: { value: 0, unit: deg }
	psi: { value: 0, unit: deg }
  wake coefficient w: 0.13 # IDK if it's w or (1-w) but I think it's good
  relative rotative efficiency etaR: 0.8 # Not sure
  thrust deduction factor t: 0.21978 # Hoping it's t and not (1-t) but I think it's good
  rotation: clockwise
  diameter: { value: 0.2539, unit: m }
  J: [-0.001, 1.5]
  Kt: [0.15, 1.0e-08]
  Kq: [0.012, 0.001]

Propeller and rudder

- name: SBPropRudd
  model: propeller+rudder
  position of propeller frame:
  frame: dtmb
	x: {value: -60.695, unit: m}
	y: {value: 4.650, unit: m}
	z: {value: 6.574, unit: m}
	phi: {value: 0, unit: rad}
	theta: {value: 2.95, unit: deg}
	psi: {value: 0, unit: deg}
  wake coefficient w: 0.15
  relative rotative efficiency etaR: 1
  thrust deduction factor t: 0.12
  rotation: clockwise
  number of blades: 5
  blade area ratio AE/A0: 0.58
  diameter: {value: 6.15, unit: m}
  rudder area: {value: 15.4, unit: m^2}
  rudder height: {value: 4.4, unit: m}
  effective aspect ratio factor: 1.7
  lift tuning coefficient: 1.
  drag tuning coefficient: 1.
  position of rudder in body frame:
	  x: {value: -66.27, unit: m}
	  y: {value: 4.75, unit: m}
	  z: {value: 4.60, unit: m}

Wageningen B-series

- name: propeller
  model: wageningen B-series
  position of propeller frame:
	frame: TestShip
	x: {value: -8.4, unit: m}
	y: {value: 0, unit: m}
	z: {value: 0.432, unit: m}
	phi: {value: 0, unit: rad}
	theta: {value: 0, unit: deg}
	psi: {value: 0, unit: deg}
  wake coefficient w: 0
  relative rotative efficiency etaR: 1
  thrust deduction factor t: 0
  rotation: clockwise
  number of blades: 4
  blade area ratio AE/A0: 0.55
  diameter: {value: 1.925, unit: m}

Control Surfaces

model: hydrodynamic polar
  name: centreboard
  position of calculation frame:
      frame: body
      x: {value: 1, unit: m}
      y: {value: 2, unit: m}
      z: {value: 3, unit: m}
      phi: {value: 10, unit: deg}
      theta: {value: 20, unit: deg}
      psi: {value: 30, unit: deg}
  reference area: {value: 1000, unit: m^2}
  angle of attack: {unit: deg, values: [0,7,9,12,28,60,90,120,150,180]}
  lift coefficient: [0.00000,0.94828,1.13793,1.25000,1.42681,1.38319,1.26724,0.93103,0.38793,-0.11207]
  drag coefficient: [0.03448,0.01724,0.01466,0.01466,0.02586,0.11302,0.38250,0.96888,1.31578,1.34483]
  take waves orbital velocity into account: false

---

Commands

Once you've added a propeller or controlled force, you need to tell it what to do. Two options:

Static - a fixed command schedule over time:

commands:
- name: propeller
  t: [0,1,3,10]
  rpm: {unit: rad/s, values: [0, 10, 30, 40]}
  P/D: {unit: 1, values: [1.06,1.06,1.06,1.06]}

t, rpm, and P/D must all have the same number of values.

PID controller - closed-loop control toward a setpoint, e.g. holding a heading:

setpoints:
- t: [0,10,30,60]
  psi_co: {unit: deg, values: [15,30,45,60]}

controllers:
- type: PID
  name: starboard controller
  dt: 0.7
  state weights:
	psi: 1
  setpoint: psi_co
  command: PSPropRudd(beta)
  gains:
	Kp: -1
	Ki: 0
	Kd: -1

---

Output

Add an output section to export vessel state, forces, or wave data.

Vessel position/velocity:

output:
- format: csv
  filename: output.csv
  data: [x(dtmb), y(dtmb), z(dtmb), psi(dtmb), theta(dtmb), phi(dtmb)]

Forces applied to a body:

output:
- format: hdf5
  filename: output.h5
  data: [Fx(gravity, dtmb, dtmb), Mx(sum of forces, dtmb, NED)]

Supported formats: csv, tsv, json, hdf5. See Understanding Xdyn for the full list of exportable values (states, forces, propeller commands, wave elevation).