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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,14 @@ All notable changes to CableDyn are recorded in this file. The format follows
- The cross-flow VIV columns `Cl [dF cF]` may follow the 14-column finite-EI `LINE TYPES` row
(15 or 17 columns), so a line restrained in torsion can carry VIV; such a row free in torsion
runs as the 13-column one. The Python deck reader and builder take it.
- Wake-oscillator VIV: an optional `WAKE OSCILLATOR` section row `TypeName CL0 [St [eps [A]]]`
replaces the synchronisation lift of a type (which keeps `Cl` 0) by the van der Pol wake
oscillator of Facchinetti et al. (2004) with acceleration coupling (defaults St 0.2, eps 0.3,
A 12), distributed along finite-EI cables, standalone and coupled. The kernel follows the
published forced-wake lift magnification within 2 %; on the taut example cable the wake locks
the cable in at its first mode (A/D 0.58 against 0.10 uncoupled) and the drag and damping take
out the wake lift's power within 0.3 %. Its state is in the step-recovery, snapshot and
checkpoint state; the Python deck reader and builder take the section.
- Load power channels `VIVPow<L>`, `DragPow<L>` and `DampPow<L>` [W], and `<name><L>N<J>` per
unit length about a node [W/m]: the power the VIV loads, the drag and the structural damping
(`BA`, `Bb`) deliver to a line at the committed state, on `EI = 0` lines and finite-EI cables,
Expand Down
14 changes: 14 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1316,6 +1316,20 @@ target_link_libraries(test_viv_kernels PRIVATE cabledyn_core)
add_test(NAME viv_kernels COMMAND test_viv_kernels)
set_tests_properties(viv_kernels PROPERTIES LABELS "fortran;unit;dynamic;viv")

# Wake-oscillator kernel (Facchinetti et al. 2004): the free limit cycle, the forced lift
# magnification of their Eq. 17, and the sub-stepped Runge-Kutta advance.
add_executable(test_viv_wake_kernel tests/test_viv_wake_kernel.f90)
target_link_libraries(test_viv_wake_kernel PRIVATE cabledyn_core)
add_test(NAME viv_wake_kernel COMMAND test_viv_wake_kernel)
set_tests_properties(viv_wake_kernel PROPERTIES LABELS "fortran;unit;dynamic;viv")

# Wake-oscillator VIV on a deck: lock-in against the uncoupled wake, the power balance, CL0 0 as no
# section, and the refusals of the WAKE OSCILLATOR section.
add_executable(test_viv_wake_deck tests/test_viv_wake_deck.f90)
target_link_libraries(test_viv_wake_deck PRIVATE cabledyn_core)
add_test(NAME viv_wake_deck COMMAND test_viv_wake_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_wake_deck PROPERTIES LABELS "fortran;integration;dynamic;viv" TIMEOUT 1200)

add_executable(test_hermite_viv tests/test_hermite_viv.f90)
target_link_libraries(test_hermite_viv PRIVATE cabledyn_core)
add_test(NAME hermite_viv COMMAND test_hermite_viv)
Expand Down
5 changes: 5 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,11 @@ Line and constitutive capability
the optional higher-harmonic force of Ulveseter et al. (2019) (``Chh``), on
``EI = 0`` lines and finite-EI cables wherever the cross-flow lift runs
(:ref:`theory-viv-inline`), its state in the checkpoint
* - Wake-oscillator VIV (``WAKE OSCILLATOR`` section ``CL0``, ``St``, ``eps``, ``A``)
- Standalone and coupled
- the van der Pol wake oscillator of Facchinetti et al. (2004) with acceleration coupling,
distributed along finite-EI cables in place of the synchronisation model
(:ref:`theory-viv-wake`), its state in the checkpoint

Loads and environment
---------------------
Expand Down
41 changes: 40 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,8 @@ the half-range and centre of its band in non-dimensional frequency (MoorDyn's `d
`cF = 0.18` when only `Cl` is given). `Cl = 0` is no VIV; `Cl > 0` needs `cF > 0` and
`0 <= dF < cF`, and the line's drag in water. It acts in the dynamics on `EI = 0` lines and
finite-EI cables (see [Cross-flow VIV](theory.rst)). The in-line force of a type is a
[VIV](#viv-optional) section row.
[VIV](#viv-optional) section row; a [WAKE OSCILLATOR](#wake-oscillator-optional) row replaces the
lift by a wake oscillator.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down Expand Up @@ -1200,6 +1201,44 @@ Behaviour:
Each was fitted to its experiments by the authors and is a starting point, not a universal set;
MoorDyn's band defaults (`dF` 0.08, `cF` 0.18) are those of the first.

### WAKE OSCILLATOR (optional)

Wake-oscillator vortex-induced vibration of a line type, the model of Facchinetti et al. (2004):
a van der Pol oscillator per node stands for the near wake and drives the cross-flow lift, coupled
to the cable's cross-flow acceleration (see [Wake oscillator](theory.rst)). It replaces the
synchronisation model of the LINE TYPES `Cl` column for that type, so the type keeps `Cl = 0`, and
it acts on finite-EI cables.

```text
--------------------- WAKE OSCILLATOR ----------------------------------
TypeName CL0 St eps A
(-) (-) (-) (-) (-)
cable 0.3 0.2 0.3 12
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive), at most one row each |
| `CL0` | reference lift coefficient `C_L0` >= 0 of a fixed cylinder, at most 1e15; `0` is off |
| `St` | optional Strouhal number > 0 of the wake frequency `2 pi St U/D` (default 0.2) |
| `eps` | optional van der Pol parameter > 0 (default 0.3) |
| `A` | optional acceleration coupling >= 0 (default 12; `0` uncouples the wake from the cable) |

Behaviour:

- Per unit length the lift is `1/4 rho D CL0 q U^2` across the relative flow, the direction of the
`Cl` lift (`U` the relative normal flow speed), with `q'' + eps om (q^2 - 1) q' + om^2 q = (A/D) y''`
at each node, `om = 2 pi St U_a/D` with `U_a` the ambient flow speed normal to the line and `y''`
the node's cross-flow acceleration. The defaults are the values Facchinetti et al. fix
from forced-wake data. The cross-flow damping of the fluid is the Morison drag of the type's
`Cd`, which the paper's `gamma = Cd/(4 pi St)` linearises.
- `q` starts on its limit cycle at the node's VIV phase seed, `q = 2 cos(phi_0)` (`VIVphaseSeed`),
and is part of the step-recovery, snapshot and checkpoint state. The Outputs flag `V` file and
`VIVPow` carry the wake lift. A row with `CL0 = 0` leaves the run exactly as without it.
- A row fails if it is not `TypeName CL0 [St [eps [A]]]`, names an undefined or already named
type, or holds a value out of range; `CL0 > 0` fails on a type with `Cl > 0`. A line whose types
mix the two models fails, and so does an `EI = 0` line with the wake oscillator.

### FAILURE (optional, EI = 0 decks)

A FAILURE row detaches line ends from a point during a dynamic run, with MoorDyn's trigger rules.
Expand Down
12 changes: 12 additions & 0 deletions doc/references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,18 @@ Verification and validation references
the IEA Wind 15-Megawatt Offshore Reference Wind Turbine.* Technical Report
NREL/TP-5000-76773, National Renewable Energy Laboratory. https://doi.org/10.2172/1660012

.. _ref-facchinetti2004:

- **Facchinetti, M. L., de Langre, E. & Biolley, F. (2004).** Coupling of structure and wake
oscillators in vortex-induced vibrations. *Journal of Fluids and Structures* **19**\ (2),
123–140. https://doi.org/10.1016/j.jfluidstructs.2003.12.004

.. _ref-violette2010:

- **Violette, R., de Langre, E. & Szydlowski, J. (2010).** A linear stability approach to
vortex-induced vibrations and waves. *Journal of Fluids and Structures* **26**\ (3), 442–466.
https://doi.org/10.1016/j.jfluidstructs.2010.01.002

.. _ref-holcombe2025:

- **Holcombe, A., Hann, M., Brown, S., et al. (2025).** Experimental–numerical model
Expand Down
60 changes: 60 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1232,6 +1232,66 @@ at the phase sum, and its derivatives enter the tangent with the lift's. Ulveset
in-line example with ``Chh`` 1.0 the quarter-span in-line response at four times the cross-flow
frequency grows from A/D 0.002 to 0.007, the same on an ``EI = 0`` line.

.. _theory-viv-wake:

Wake oscillator
~~~~~~~~~~~~~~~

A ``WAKE OSCILLATOR`` row ``TypeName CL0 [St [eps [A]]]`` replaces the synchronisation model of a
line type by the wake oscillator of :ref:`Facchinetti et al. (2004) <ref-facchinetti2004>`,
distributed along the line as in :ref:`Violette et al. (2010) <ref-violette2010>`. At each node a
van der Pol oscillator in the reduced lift coefficient :math:`q = 2C_L/C_{L0}` stands for the
near wake, forced by the node's cross-flow acceleration :math:`\ddot y` (the acceleration
coupling Facchinetti et al. found to reproduce lock-in, the Griffin plot and the effective added
mass):

.. math::

\ddot q + \varepsilon\,\omega_f\,(q^2 - 1)\,\dot q + \omega_f^2\,q = \frac{A}{D}\,\ddot y,
\qquad \omega_f = 2\pi\,\mathrm{St}\,\frac{U_a}{D},

with :math:`U_a` the speed of the ambient flow (current and host field) normal to the line, the
free stream of the paper, so that the cable's own cross-flow velocity does not modulate the wake
frequency, and :math:`\ddot y` along the cross-flow axis :math:`\mathbf t\times\mathbf v_n/U` of
the synchronisation model. The lift per unit length acts across the relative normal flow
:math:`\mathbf v_n` of speed :math:`U`, as the synchronisation lift does:

.. math::

\mathbf f = \tfrac{1}{4}\rho\,D\,C_{L0}\,q\;U\,(\mathbf t\times\mathbf v_n) ,

the synchronisation lift with :math:`C_L\cos\phi` replaced by :math:`C_{L0}q/2`: a free wake
settles on the limit cycle :math:`q = 2\cos\omega_f t`, the lift :math:`C_{L0}` of a fixed
cylinder. The defaults St 0.2, :math:`\varepsilon` 0.3 and :math:`A` 12 are theirs, fixed from
forced-wake data with :math:`C_{L0}` 0.3, which the row gives. Their
fluid-added damping :math:`\gamma\,\omega_f\,\rho D^2\dot y` with
:math:`\gamma = C_D/(4\pi\mathrm{St})` is the linearised Morison drag, which CableDyn applies
in full, and their inviscid added mass is the Morison :math:`C_a`; the wake adds the lift only.

The wake state :math:`(q, \dot q)` of a node is integrated beside the cable, as the phase of the
synchronisation model is. At the start of a step it is advanced under the step-start
acceleration to give the :math:`q` the step's lift takes; at the converged end it is advanced
again from the committed state with the acceleration linear between the step's ends, at the
step-start :math:`\omega_f`, and committed. Both use classical Runge-Kutta in equal sub-steps of
:math:`r\,\delta t \le 0.1`, :math:`r = \omega_f\max(1, \varepsilon q^2)` the faster of the
oscillation and the van der Pol damping rate at the start of the interval, so a large
:math:`\varepsilon` stays resolved; should the rate exceed :math:`0.2/\delta t` on the way, or the
result not be finite, the interval is redone with twice the sub-steps. The lift is integrated on a finite-EI cable at the Gauss
points of the synchronisation lift, :math:`q` interpolated between the element's end nodes, with
its exact position and velocity derivatives in the tangent at fixed :math:`q`. :math:`q` starts on
its limit cycle at the node's phase seed, :math:`q = 2\cos\phi_0`, :math:`\dot q = 0`, and the
state is part of the step-recovery, snapshot and checkpoint state.

The kernel reproduces the limit cycle (amplitude 2.001, the van der Pol period shift of
:math:`\varepsilon^2/16`), and forced at its own frequency by a cylinder moving as
:math:`y_0 D\cos\omega_f t` it follows the lift magnification of their Eq. 17 within 0.2 % at
:math:`y_0 = 0.05` and 1.9 % at :math:`y_0 = 0.5`, the gap growing with the third harmonic their
one-harmonic balance leaves out. On the taut cable of ``viv_taut_cable_inline.dat`` with
``Cl`` 0 and ``CL0`` 0.3 the cable locks in at 0.282 Hz, below the wake's own 0.30 Hz, at a
steady mid-span A/D of 0.58; with :math:`A` = 0 the uncoupled wake drives it at 0.298 Hz at A/D
0.10, and over the lock-in the drag and damping take out the wake lift's power within 0.3 %. The
wake oscillator acts on finite-EI cables, cross-flow only.

.. _theory-dry-buoyancy:

Buoyancy and wetting
Expand Down
47 changes: 47 additions & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,14 @@ class LineType:
Optional higher-harmonic coefficient of the ``VIV`` row (``Name ClX alpha
Chh``, Ulveseter et al. 2019; it needs ``clx``); ``None`` leaves it out
(0). With ``chh`` set and ``il_alpha`` ``None`` the row writes alpha 0.15.
wake_cl0, wake_st, wake_eps, wake_a : float | None
Optional wake-oscillator VIV of a type (Facchinetti et al. 2004), a
``WAKE OSCILLATOR`` section row ``Name CL0 [St [eps [A]]]``: the
reference lift coefficient, the Strouhal number, the van der Pol
parameter and the acceleration coupling. It replaces the
synchronisation lift, so ``cl`` stays ``None`` or 0, and acts on
finite-EI cables. ``None`` leaves a trailing value out of the row (the
solver takes 0.2, 0.3 and 12); a value given writes the ones before it.
"""

name: str
Expand All @@ -241,6 +249,10 @@ class LineType:
clx: float | None = None
il_alpha: float | None = None
chh: float | None = None
wake_cl0: float | None = None
wake_st: float | None = None
wake_eps: float | None = None
wake_a: float | None = None


@dataclass(eq=False)
Expand Down Expand Up @@ -1660,6 +1672,10 @@ def add_line_type(
clx: float | None = None,
il_alpha: float | None = None,
chh: float | None = None,
wake_cl0: float | None = None,
wake_st: float | None = None,
wake_eps: float | None = None,
wake_a: float | None = None,
) -> LineType:
"""Add a ``LINE TYPES`` row; see :class:`LineType` for the fields.

Expand Down Expand Up @@ -1696,6 +1712,10 @@ def add_line_type(
clx,
il_alpha,
chh,
wake_cl0,
wake_st,
wake_eps,
wake_a,
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2587,6 +2607,7 @@ def to_text(self, *, validate: bool = True) -> str:
_emit(out, "ATTACHMENTS", *self._attachment_table())
_emit(out, "STIFFENERS", *self._stiffener_table())
_emit(out, "VIV", *self._viv_table())
_emit(out, "WAKE OSCILLATOR", *self._wake_table())
_emit(out, "FAILURE", *self._failure_table())
_emit(out, "CONTROL", *self._control_table())
_emit(out, "EXTERNAL LOADS", *self._external_load_table())
Expand Down Expand Up @@ -2968,6 +2989,25 @@ def _viv_table(self) -> tuple[str, str, list[list[str]]]:
rows.append(row)
return "Name ClX alpha Chh", "(-) (-) (-) (-)", rows

def _wake_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
defaults = (0.2, 0.3, 12.0)
for item in self._line_types:
what = f"line type {item.name!r}"
rest = (item.wake_st, item.wake_eps, item.wake_a)
if item.wake_cl0 is None:
if any(value is not None for value in rest):
raise ValueError(f"{what}: wake_st, wake_eps and wake_a need wake_cl0")
continue
row = [_text(item.name, what), _num(item.wake_cl0, what)]
# the values up to the last one given, the solver's defaults filling the gaps
last = max((index for index, value in enumerate(rest) if value is not None), default=-1)
for index in range(last + 1):
value = rest[index]
row.append(_num(defaults[index] if value is None else value, what))
rows.append(row)
return "Name CL0 St eps A", "(-) (-) (-) (-) (-)", rows

def _syrope_table(self) -> tuple[str, str, list[list[str]]]:
rows = [
[_line_list(row.lines), _num(row.tmax0, "SYROPE IC"), _num(row.tmean0, "SYROPE IC")]
Expand Down Expand Up @@ -3172,6 +3212,13 @@ def load(self) -> None:
item.clx = _f(t[1])
item.il_alpha = _f(t[2]) if len(t) >= 3 else None
item.chh = _f(t[3]) if len(t) == 4 else None
for row in self.rows("WAKE OSCILLATOR"):
t = row.tokens
item = model.line_types[t[0]]
item.wake_cl0 = _f(t[1])
item.wake_st = _f(t[2]) if len(t) >= 3 else None
item.wake_eps = _f(t[3]) if len(t) >= 4 else None
item.wake_a = _f(t[4]) if len(t) == 5 else None
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
Loading
Loading