Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,21 @@ All notable changes to CableDyn are recorded in this file. The format follows
standalone driver and the C API refuse `CoupledPinned` rods by name; FAST.Farm decks still
refuse rods, OpenFAST linearisation still refuses rods, and `CoupledPinned` bodies remain
unsupported. See the manual's OpenFAST page (Lifecycle features).
- A warning when line nodes of a coupled OpenFAST run (`CompMooring = 5`) lie outside the
SeaState wave-kinematics grid (`X_HalfWidth`, `Y_HalfWidth`, `Z_Depth`). SeaState gives such a
node the kinematics of the grid boundary: waves out of phase beyond a half-width, and
kinematics that are too strong below `Z_Depth`. Its fluid load was therefore wrong without
any message. CableDyn now checks its nodes at the static equilibrium and at every CableDyn
step. At the first node outside the grid it prints one warning with the number of nodes,
the farthest node in each direction and the SeaState inputs to enlarge. Only nodes in the
water are checked (a cable or jumper above the free surface carries no fluid load), and
nodes below a grid that reaches the seabed (`Z_Depth` equal to the water depth, its
default) are not reported.
The OpenFAST tutorial and `examples/openfast/README.md` now enlarge the r-test `MD_Shared`
grid (`X_HalfWidth = 100 m`, `Z_Depth = 40 m`), which covers the platform but not the
moorings, and quote their results for the enlarged grid. With the `MD_Shared` grid, the
line-1 fairlead tension standard deviation of the tutorial was 18 % too high. See the
manual's OpenFAST page (SeaState grid).

### Changed

Expand Down
73 changes: 70 additions & 3 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Time step
``DT`` is the OpenFAST glue step; ``dtM`` is CableDyn's committed step. With no deck ``dtM``,
CableDyn targets 0.1 s rounded to a whole number of glue steps and holds its loads (zero-order
hold) between commits. ``dtM = DT`` solves every glue step. The console reports the result, for
example ``CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM )``. A deck ``dtM``
example ``CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM)``. A deck ``dtM``
larger than ``DT`` but not a whole multiple of it is never coarsened: CableDyn uses the largest
multiple of ``DT`` that does not exceed it and reports a warning with both values (``dtM = 0.025``
with ``DT = 0.01`` runs at 0.02 s), matching MoorDyn, which only ever shortens its step to fit the
Expand All @@ -98,6 +98,72 @@ WaterKin file can select file waves, a file depth-dependent current, host waves,
current independently where the field is separable. Unsupported or double-counted combinations
fail during initialisation. The selector matrix is in :doc:`options` and :doc:`driver_format`.

SeaState grid
~~~~~~~~~~~~~

SeaState computes the wave and current kinematics on a grid set in its input file and
interpolates them at the line nodes: ``X_HalfWidth`` and ``Y_HalfWidth`` about the origin,
``Z_Depth`` below the still-water level, and ``NX``, ``NY``, ``NZ`` grid points (``NZ`` is
spaced more finely near the surface). A node outside the grid gets the kinematics of the
nearest grid boundary point, so its fluid load is wrong: beyond a half-width the waves are
out of phase, and below ``Z_Depth`` the wave and current kinematics are those of the grid
bottom, which are too strong. A SeaState file written for the platform alone usually covers
only the platform. The r-test ``MD_Shared`` file used in :doc:`tutorial_openfast` has
``X_HalfWidth = Y_HalfWidth = 100 m``, ``Z_Depth = 40 m`` and ``NZ = 2``, while the anchors lie
838 m from the platform on a 200 m seabed. Size the grid for the lines:

* ``X_HalfWidth`` and ``Y_HalfWidth`` beyond the farthest anchor or cable end, with margin for
the platform offset;
* ``Z_Depth`` equal to the water depth (``"default"``); nodes on the seabed are then inside the
grid; and
* ``NX``, ``NY`` and ``NZ`` raised with the extents to keep the grid spacing: a horizontal
spacing of about a tenth of the peak wavelength or less. A long-crested sea (``WaveDirMod =
0``) that travels along x does not vary in y, so ``NY = 2`` is enough for it.

SeaState holds the whole time history of the grid in memory, so memory and initialisation time
grow with (2 ``NX`` − 1)(2 ``NY`` − 1) ``NZ`` ``WaveTMax`` / ``WaveDT``. For the
IEA-15MW case of :doc:`tutorial_openfast` (Hs 6 m, Tp 12 s, ``WaveTMax = 4800 s``,
``WaveDT = 0.2 s``), ``X_HalfWidth = Y_HalfWidth = 900``, the default ``Z_Depth``, ``NX = 37``
(25 m spacing), ``NY = 2`` and ``NZ = 11`` needs about 4.6 GB. Halving the spacing (``NX = 73``)
or using ``NZ = 16`` changes the 10–70 s platform and fairlead-tension statistics by less than
0.1 %. The ``MD_Shared`` grid gives a line-1 fairlead tension standard deviation 18 % too high
(0.136 MN instead of 0.115 MN).

CableDyn compares its nodes with the grid at the static equilibrium and at every CableDyn step.
At the first node found outside it prints one warning and continues:

.. code-block:: text

WARNING: CableDyn mooring module: 147 of the 153 CableDyn sampling nodes in the water lie
outside the SeaState wave-kinematics grid at t = 0 s (warned once). SeaState clamps them to
the grid boundary, so their fluid kinematics and loads are not physical. Farthest: x = -837.6
m (grid |x| <= X_HalfWidth = 100 m); y = 725.38 m (grid |y| <= Y_HalfWidth = 100 m); z =
-200.01 m (grid z >= -Z_Depth = -40 m). In the SeaState input file enlarge X_HalfWidth,
Y_HalfWidth and Z_Depth (Z_Depth at most WtrDpth + MSL2SWL, its default) to cover the lines
with margin for their motion, and raise NX, NY and NZ to keep the grid spacing.

Only nodes in the water are checked: a node above the free surface carries no fluid load,
whatever kinematics SeaState would give it, so a suspended cable or jumper above the water may
leave the grid. A node counts as in the water at or below the free-surface elevation sampled
for it, which also decides its wetting in CableDyn (the still-water level when the host waves
are off), and, without wave stretching (``WaveStMod = 0``), at or below the still-water level,
above which SeaState gives zero kinematics without reading the grid. Only the directions in
which nodes leave the grid are listed. Waves are checked in all three
directions and a SeaState current (uniform in x and y) only in depth; under Wheeler stretching
(``WaveStMod = 3``) the depth checked is the one SeaState interpolates at, the node depth mapped
linearly from the range between the seabed and the local wave elevation onto the range between
the seabed and the still-water level (with the elevation SeaState sampled, also when only the
host current is used). A dynamic current field (an InflowWind-driven current) is read on its
own grid; when that field is gridded, a separate one-time warning reports nodes outside its
vertical extent or lateral half-width. SeaState measures its field from the still-water level, and the
mooring samples it at positions relative to the mean sea level, so a run with host waves or
current from SeaState refuses a nonzero ``MSL2SWL`` at initialisation (a deck that takes
both from WaterKin does not query SeaState and is not affected). Excursions smaller than
1 % of the grid spacing at the boundary are ignored, and so are nodes below a grid that reaches
the seabed (``Z_Depth = WtrDpth + MSL2SWL``): they are in the seabed, where the kinematics of the
grid bottom are the right ones. FAST.Farm runs, which use still water, and SeaState fields
without waves or current are not checked.

Run and confirm
---------------

Expand Down Expand Up @@ -193,8 +259,9 @@ Example files

The turbine sub-models are not part of this repository. :doc:`tutorial_openfast` gives the exact
steps to fetch them from OpenFAST's ``r-test`` (``glue-codes/fast-farm/MD_Shared`` at revision
``dd5feaaaa500ba7283140107806300d551cff0a7``) and to reset that farm model's turbine-1 initial
pose to a single turbine at the origin.
``dd5feaaaa500ba7283140107806300d551cff0a7``), to reset that farm model's turbine-1 initial
pose to a single turbine at the origin, and to enlarge its SeaState grid to cover the moorings
(see *SeaState grid*).

Mixed moorings and power cables
-------------------------------
Expand Down
16 changes: 13 additions & 3 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -521,6 +521,8 @@ Warnings and notes that do not stop a run
:header-rows: 1
:widths: 42 58

* - Message
- Cause and fix
* - ``Note: line <L> is torsionally restrained at one end only; ... no torsion is solved``
- with the other end free to twist the line carries no torque, so the torsion columns of the
restrained end have no effect. Restrain both ends to solve torsion.
Expand All @@ -529,9 +531,17 @@ Warnings and notes that do not stop a run
- the static twist stage of a torsional line. A non-zero descent count means the straight or
untwisted branch was unstable at the imposed twist and the solve moved to a buckled shape;
check the shape and the ``Twist<L>`` channel.

* - Message
- Cause and fix
* - ``WARNING: CableDyn mooring module: <n> of the <N> CableDyn sampling nodes in the water
lie outside the SeaState wave-kinematics grid at t = ... s (warned once)`` (OpenFAST)
- the SeaState grid (``X_HalfWidth``, ``Y_HalfWidth``, ``Z_Depth``) does not cover the
lines in the water (nodes above the free surface carry no fluid load and are not
counted), and SeaState gives the nodes outside it the kinematics of the grid boundary: waves
out of phase beyond a half-width, kinematics that are too strong below ``Z_Depth``. The
message names the farthest node in each direction. Enlarge the listed inputs in the
SeaState file past the farthest anchor (``Z_Depth`` to the water depth, its default) and
raise ``NX``, ``NY``, ``NZ`` to keep the spacing. A SeaState file written for the
platform alone, such as the r-test ``MD_Shared`` file, triggers it. See
:ref:`openfast:SeaState grid` for sizes and memory.
* - ``WARNING: line type ... sinks ... m into the seabed ...; kBot is soft for this line``
- a grounded run of this type would sink deeper than its own diameter into the penalty
seabed. Raise ``kBot``; the default ``1.0e5`` embeds a heavy chain by about half its
Expand Down
89 changes: 55 additions & 34 deletions doc/tutorial_openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ CableDyn results, compare against stock MoorDyn in the same binary, and add a la
cable.

**Needs:** ``openfast.exe`` from the release, the ``examples`` folder, and Git (or a browser) to
fetch the turbine model · **Run time:** about 5 s for 70 s of simulation (the MoorDyn comparison run
takes a few minutes)
fetch the turbine model · **Run time:** under half a minute for 70 s of simulation, about a
third of it SeaState generating the wave grid (the MoorDyn comparison run takes a few minutes)

.. contents::
:local:
Expand Down Expand Up @@ -75,8 +75,8 @@ The folder now holds, among others:
``HydroData\``, ``Airfoils\``, …
- the turbine and platform model from ``MD_Shared``

3. Make the model a single turbine at the origin
------------------------------------------------
3. Prepare the turbine model
----------------------------

``MD_Shared`` is a two-turbine FAST.Farm case. Its turbine-1 files start the platform at its farm
pose (20.3 m surge, 180° yaw, small roll/pitch/heave) and set HydroDyn's reference yaw
Expand All @@ -102,6 +102,28 @@ This sets ``PtfmSurge``, ``PtfmSway``, ``PtfmHeave``, ``PtfmRoll``, ``PtfmPitch`
321 MN fairlead tension. Always read the initial fairlead tensions before trusting a coupled
run.

``MD_Shared``'s ``SeaState.dat`` computes the wave kinematics on a grid that covers only the
platform: ``X_HalfWidth = Y_HalfWidth = 100 m``, ``Z_Depth = 40 m``, ``NX = NY = NZ = 2``. The
mooring lines reach anchors 838 m away on the 200 m seabed, and SeaState gives every line node
outside the grid the kinematics of the grid boundary. Enlarge the grid to cover the lines:

.. code-block:: powershell

$ss = 'SeaState.dat'
(Get-Content $ss) -replace '^\s*\S+(\s+[XY]_HalfWidth\s)', ' 900$1' `
-replace '^\s*\S+(\s+Z_Depth\s)', ' "default"$1' `
-replace '^\s*\S+(\s+NX\s)', ' 37$1' `
-replace '^\s*\S+(\s+NZ\s)', ' 11$1' |
Set-Content $ss -Encoding ascii

This sets ``X_HalfWidth`` and ``Y_HalfWidth`` to 900 m, ``Z_Depth`` to the water depth, 37 grid
points along each half of x (25 m spacing) and 11 in depth. ``NY`` stays 2 because the
long-crested sea travels along x and does not vary in y. SeaState then needs about 4.6 GB of
memory and several seconds to generate the grid. Without this step the run still completes, but
CableDyn warns that 147 of its 153 line nodes lie outside the SeaState wave-kinematics grid, and
the line-1 fairlead tension standard deviation comes out 18 % too high. Grid sizing is
described in :ref:`openfast:SeaState grid`.

4. How CableDyn is wired in
---------------------------

Expand Down Expand Up @@ -148,7 +170,7 @@ The CableDyn part of the console (other modules' lines trimmed):
Running CableDyn (v0.1.1, 2026-10-09).
CableDyn: geometrically nonlinear cable & mooring dynamics for floating wind.
...
CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM )
CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM)
Parsing CableDyn input file: .\CableDyn_UMaine.dat
CableDyn: SeaState wave/current kinematics drive the mooring hydro (153 sampling nodes,
refreshed every mooring step).
Expand All @@ -163,30 +185,29 @@ The CableDyn part of the console (other modules' lines trimmed):
...
CableDyn initialization completed.
Requested CableDyn OUTPUTS at t = 0 s (equilibrium pose, SeaState kinematics at t = 0):
FairTen1 = 2.43621E+06 (N)
AnchTen1 = 1.35173E+06 (N)
FairTen1 = 2.43752E+06 (N)
AnchTen1 = 1.35164E+06 (N)
FairIncl1 = 55.685 (deg)
...
These values are also the t = 0 CableDyn columns in the OpenFAST output file.
Time: 0 of 70 seconds.
...
Total Real Time: 4.63 seconds
Simulated Time: 70 seconds
Time Ratio (Sim/CPU): 15.887

OpenFAST terminated normally.

Check, in order:

#. ``Running CableDyn (`` — the CableDyn-enabled executable is in use. A stock OpenFAST rejects
``CompMooring = 5`` during input validation.
#. The line inventory (3 lines, 6 points) and ``dtM``.
#. The line inventory (3 lines, 6 points) and ``dtM``, and no ``WARNING: CableDyn mooring module:
... lie outside the SeaState wave-kinematics grid`` line (step 3).
#. The initial fairlead tensions: 2.437 MN per line, with the line tangent 55.7° below
horizontal, as in the standalone ``spread_3line_chain.dat`` of :doc:`tutorial_spread`. The
tension is the magnitude of the line-end force, which includes the fairlead node's share of
the chain weight, so the force points slightly steeper, 56.3° below horizontal, with a
horizontal component of 1.351 MN.
#. The ``OUTPUTS`` at t = 0: ``FairTen1`` reads 2.436 MN, 0.04 % below the equilibrium value
#. The ``OUTPUTS`` at t = 0: ``FairTen1`` reads 2.4375 MN, 0.02 % above the equilibrium value
above. The equilibrium is solved before the SeaState kinematics act, and at t = 0 the wave
kinematics add their hydrodynamic load on the fairlead end node. In still water
(``WaveMod = 0``) the two values are equal. ``.CD.static.out`` holds the equilibrium, and the
Expand Down Expand Up @@ -218,8 +239,8 @@ Check, in order:

Time FairTen1 AnchTen1 FairIncl1 AnchIncl1 FairTen2 ...
(s) (N) (N) (deg) (deg) (N) ...
0.0000000E+00 2.436210E+06 1.351729E+06 5.568478E+01 -1.961023E-02 2.435610E+06 ...
2.5000000E-02 2.434498E+06 1.352272E+06 5.568418E+01 -1.957846E-02 2.433048E+06 ...
0.0000000E+00 2.437520E+06 1.351636E+06 5.568478E+01 -1.961023E-02 2.436576E+06 ...
2.5000000E-02 2.438082E+06 1.351645E+06 5.568463E+01 -1.961023E-02 2.435530E+06 ...

CableDyn channels are chosen in the deck's ``OUTPUTS`` section (keep its closing ``END``), not in
the ``.fst`` ``OutList``. Channel names and units: :doc:`outputs`; sign and angle conventions:
Expand Down Expand Up @@ -254,30 +275,30 @@ the main ``.out``. Statistics over 10–70 s from the two main output files:
- CableDyn std
- MoorDyn std
* - ``PtfmSurge`` (m)
- 0.893
- 0.893
- 1.364
- 1.363
- 0.899
- 0.899
- 1.380
- 1.378
* - ``PtfmHeave`` (m)
- −1.030
- −1.030
- 1.216
- 1.215
- 1.221
- 1.221
* - ``PtfmPitch`` (deg)
- 1.497
- 1.497
- 1.382
- 1.381
- 1.496
- 1.496
- 1.390
- 1.390
* - fairlead tension, line 1 (MN)
- 2.452
- 2.452
- 0.136
- 0.136
- 2.456
- 2.456
- 0.115
- 0.116
* - fairlead tension, line 2 (MN)
- 2.376
- 2.376
- 0.069
- 0.069
- 2.372
- 2.372
- 0.064
- 0.064

The platform motions agree to within 0.2 %, the mean fairlead tensions to within 0.01 % and
their standard deviations to within 0.5 %. Both codes report the fairlead tension as the force
Expand Down Expand Up @@ -319,7 +340,7 @@ seabed. Copy it into the case folder and point a copy of the ``.fst`` at it:
force [Fx, Fy, Fz]: [1230, 0, -11858] N, inclination=84.078 deg
line tangent: inclination=83.943 deg, declination=173.94 deg, azimuth=0 deg
...
Curv4N38 = 9.01821E-02 (1/m)
Curv4N38 = 9.01822E-02 (1/m)
BendMom4N38 = 1794.6 (N.m)

CableDyn found the cable's touchdown and lazy-wave shape by itself: in
Expand All @@ -339,9 +360,9 @@ Exercises
``MD_Shared`` InflowWind and AeroDyn files are already present) and compare the mean surge and
line-1 tension with the parked case.
2. **Supercycling.** Remove the ``dtM`` row from ``CableDyn_UMaine.dat``. The console now
reports ``dtM = 0.1 s (4 x glue DT; the default )``, the run takes about 3 s instead of 5 s,
reports ``dtM = 0.1 s (4 x glue DT; the default)``, CableDyn solves once per four glue steps,
and ``.CD.out`` has one row per 0.1 s. Here the line-1 tension statistics over 10–70 s barely
move (mean 2.453 MN, std 0.136 MN, against 2.452 and 0.136 MN); verify that for your own
move (mean 2.456 MN, std 0.116 MN, against 2.456 and 0.115 MN); verify that for your own
quantities before adopting a coarser step.
3. **Still water.** Set ``WaveMod = 0`` in ``SeaState.dat``. Without waves the platform settles
toward its still-water pose (mean heave −1.1 m, pitch 1.5°) with a decaying heave–pitch
Expand Down
Loading
Loading