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
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,20 @@ All notable changes to CableDyn are recorded in this file. The format follows
leaves runs unchanged to the bit. The Python deck reader and builder (`viv_frame_tf`) take the
section.

- The `VIV FRAME` section on the synchronisation model (LINE TYPES `Cl > 0`): `Tf > 0` takes the
cable's filtered velocity as the frame of the cross-flow and in-line phases (the node's
velocity relative to it; the shedding speed stays the relative normal speed), of the amplitude
estimate (and so `Cv` and `CdAmp`) and of the axes and blend of the `VIV DAMPING` split. A cable
moved through still water had a phase input of zero cross-flow velocity, `y0 = 0`, `Cv(0)`,
`CdAmp(0)` and Morison's drag. A pipe moved at 0.6 m/s amplitude and 40 s period in still water
now gives peak A/D 0.819 against 0.819 for the same pipe held in the moving water with the
amplitude table and damping (0.711 against 0.850 without the row), and 0.713 against 0.714 with
the lift alone (0.711 against 0.736); a cable towed at 0.15 m/s gives the A/D of the cable held
in the current with the same row within 0.01 %. On `EI = 0` lines and finite-EI cables, the
filtered velocity in rows 7-9 of the VIV motion statistics, so in the step-recovery, snapshot
and checkpoint state; `Tf` 0 or no row leaves runs unchanged to the bit. A VIV FRAME row now
needs LINE TYPES `Cl > 0` or a WAKE OSCILLATOR row; the Python deck reader and builder follow.

### Fixed

- The statics of a finite-EI line through the free surface could fail at isolated currents:
Expand Down
16 changes: 16 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1356,6 +1356,13 @@ add_executable(test_viv_cf_damping_deck tests/test_viv_cf_damping_deck.f90)
target_link_libraries(test_viv_cf_damping_deck PRIVATE cabledyn_core)
add_test(NAME viv_cf_damping_deck COMMAND test_viv_cf_damping_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_cf_damping_deck PROPERTIES LABELS "fortran;integration;dynamic;viv;driver")
# The flow frame (VIV FRAME section) of the synchronisation model on a deck: a Tf 0 row as no
# section, a cable towed through still water against the same cable held in a current, the frame
# leaving the held cable's response on both cores, and the refusals.
add_executable(test_viv_frame_deck tests/test_viv_frame_deck.f90)
target_link_libraries(test_viv_frame_deck PRIVATE cabledyn_core)
add_test(NAME viv_frame_deck COMMAND test_viv_frame_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_frame_deck PROPERTIES LABELS "fortran;integration;dynamic;viv;driver")

# Amplitude-dependent VIV coefficients on a deck (VIV AMPLITUDE section), both line kinds: the
# identity table, the amplitude channel against the response, self-limiting, drag amplification
Expand Down Expand Up @@ -1385,6 +1392,15 @@ target_link_libraries(test_hermite_viv_inline PRIVATE cabledyn_core)
add_test(NAME hermite_viv_inline COMMAND test_hermite_viv_inline)
set_tests_properties(hermite_viv_inline PROPERTIES LABELS "fortran;dynamic;viv")

# The flow frame of the synchronisation model (Set_VIV tf): a pipe moved through still water
# against the same pipe held in the water moving the other way, with the lift alone and with the
# amplitude tables and the cross-flow damping; the refusals, the all-zero identity and the
# snapshot replay.
add_executable(test_hermite_viv_frame tests/test_hermite_viv_frame.f90)
target_link_libraries(test_hermite_viv_frame PRIVATE cabledyn_core)
add_test(NAME hermite_viv_frame COMMAND test_hermite_viv_frame)
set_tests_properties(hermite_viv_frame PROPERTIES LABELS "fortran;dynamic;viv")

add_executable(test_hermite_load_power tests/test_hermite_load_power.f90)
target_link_libraries(test_hermite_load_power PRIVATE cabledyn_core)
add_test(NAME hermite_load_power COMMAND test_hermite_load_power)
Expand Down
12 changes: 9 additions & 3 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,10 @@ Line and constitutive capability
- Standalone and coupled
- MoorDyn v2's synchronisation model on ``EI = 0`` lines and, as a distributed lift, on
finite-EI cables of the Hermite and multibody marches (:ref:`theory-viv`), with the
host's fluid field on the coupled routes and its state in the checkpoint
host's fluid field on the coupled routes and its state in the checkpoint; a ``VIV FRAME``
row (``Tf``) takes the cable's filtered motion as the frame of its phases, amplitude
estimate and cross-flow damping (a towed or floater-driven cable,
:ref:`theory-viv-frame`)
* - In-line VIV (``VIV`` section ``ClX``, ``alpha``)
- Standalone and coupled
- the in-line shedding force of Ulveseter et al. (2018) at twice the cross-flow frequency, and
Expand All @@ -168,7 +171,9 @@ Line and constitutive capability
- a table over the cross-flow amplitude of the synchronisation coefficient and a drag
factor, read at the amplitude estimate of Thorsen et al. (2016) (``VIVAmp`` channel), on
``EI = 0`` lines and finite-EI cables (:ref:`theory-viv-amplitude`), its state in the
checkpoint
checkpoint; a ``VIV FRAME`` row (``Tf``) takes the estimate, and the ``VIV DAMPING``
axes, relative to the cable's filtered motion (a towed or floater-driven cable,
:ref:`theory-viv-frame`)
* - VIV diameter (``VIV DIAMETER`` section ``Dviv``)
- Standalone and coupled
- a diameter of the VIV model apart from the hydrodynamic one, for buoyancy-module zones and
Expand All @@ -179,7 +184,8 @@ Line and constitutive capability
cross-flow part ``C_dy = a + b y0/D`` of Thorsen et al. (2016) read at the amplitude
estimate plus a Morison-form term ``c``; ``0 0 1`` keeps Morison's drag and lets the
``VIV AMPLITUDE`` drag factor act on the in-line part alone; finite-EI cables
(:ref:`theory-viv-cf-damping`)
(:ref:`theory-viv-cf-damping`); with a ``VIV FRAME`` row about the flow relative to the
cable's filtered motion (:ref:`theory-viv-frame`)

Loads and environment
---------------------
Expand Down
51 changes: 35 additions & 16 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1301,7 +1301,9 @@ Behaviour:

- Each node estimates its cross-flow amplitude as Thorsen et al. do (their Eq. 8 and 9): half the
travel of the node across the ambient flow between two zero crossings of its cross-flow
velocity, smoothed by a tenth of the difference at every time step. An element takes the mean of
velocity, smoothed by a tenth of the difference at every time step (with a
[VIV FRAME](#viv-frame-optional) row, the flow and the velocity relative to the cable's filtered
motion). An element takes the mean of
its free nodes over its diameter as A/D (the one free node next to a fixed end or anchor), and
from its table `Cv` (for the lift) and `CdAmp`
(times `Cd`, for the normal Morison drag), linear between rows and held beyond the first and
Expand Down Expand Up @@ -1358,10 +1360,12 @@ Behaviour:

### VIV FRAME (optional)

The flow frame of the VIV model of a line type: the flow the model takes as its free stream, the
ambient flow by default. A cable moved through the water by a tow or by its floater sees no
ambient flow, so its wake oscillator never shed; with a filter time `Tf` the free stream is the
ambient flow relative to the cable's own slow motion (see [Wake oscillator](theory.rst)).
The flow frame of the VIV model of a line type: the frame the model takes the cable's motion and
the free stream in, the earth and the ambient flow by default. A cable moved through the water by
a tow or by its floater sees no ambient flow, so its wake oscillator never shed, and its
synchronisation phase saw no cross-flow velocity and its amplitude estimate stayed at zero; with a
filter time `Tf` the frame moves with the cable's own slow motion (see
[Wake oscillator](theory.rst) and [Flow frame of the synchronisation model](theory.rst)).

```text
--------------------- VIV FRAME ----------------------------------------
Expand All @@ -1372,23 +1376,37 @@ cable 10

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) with a WAKE OSCILLATOR row, at most one row each |
| `TypeName` | an existing LINE TYPES name (case-insensitive) with LINE TYPES `Cl > 0` or a WAKE OSCILLATOR row, at most one row each |
| `Tf` | filter time >= 0 [s], at most 1e15; `0` is the ambient flow |

Behaviour:

- With `Tf > 0` the wake frequency `2 pi St U_a/D` takes `U_a` = the speed normal to the line of
the ambient flow less the node's velocity low-pass filtered over `Tf` (first order, started at
the node's initial velocity). The slow motion then counts as flow; the cable's own VIV
velocity, much faster than `Tf`, does not modulate the frequency.
- Take `Tf` several VIV periods long and short against the motion. A taut cable towed at 0.15 m/s
through still water (VIV at 0.28 Hz) with `Tf` 10 s locks in as the same cable held in a
0.15 m/s current, A/D within 0.6 % and frequency within 0.001 Hz, where the ambient flow gave it
no lock-in. On a held cable in a current `Tf` changes A/D by 0.03 %.
- The node's velocity is low-pass filtered over `Tf` (first order, started at the node's initial
velocity). The slow motion then counts as flow; the cable's own VIV velocity, much faster than
`Tf`, does not.
- On a wake-oscillator type the wake frequency `2 pi St U_a/D` takes `U_a` = the speed normal to
the line of the ambient flow less the filtered velocity.
- On a synchronisation type (LINE TYPES `Cl > 0`) the cross-flow and in-line phases take the
node's velocity less the filtered velocity, along the axes of the relative flow, so the shedding
speed stays the relative normal speed; with a VIV AMPLITUDE table the amplitude estimate takes
that velocity across the ambient flow less the filtered velocity, and with it the table's `Cv`
and `CdAmp`; on a finite-EI cable with VIV DAMPING the split takes its in-line and cross-flow
axes, and its blend to Morison's drag, from that flow. The lift and drag act on the relative
velocity, unchanged.
- Take `Tf` several VIV periods long and short against the motion: the filter scales the VIV
velocity at `omega` by `omega Tf/sqrt(1 + (omega Tf)^2)` (0.9985 at 0.29 Hz with `Tf` 10 s) and
lags a motion at `omega_m` by `atan(omega_m Tf)`. A taut cable towed at 0.15 m/s through still
water (VIV at 0.28 Hz) with `Tf` 10 s locks in as the same cable held in a 0.15 m/s current:
with the wake oscillator A/D within 0.6 % and frequency within 0.001 Hz, where the ambient flow
gave it no lock-in; with the synchronisation model A/D within 0.01 % of the held cable with the
same row (within 0.25 % without the row), with or without a VIV AMPLITUDE table and VIV DAMPING. On a
held cable in a current `Tf` changes A/D by 0.03 % (wake oscillator) and at most 0.23 %
(synchronisation model).
- The filtered velocity is part of the step-recovery, snapshot and checkpoint state. A row with
`Tf = 0` leaves the run exactly as without it. It acts on `EI = 0` lines and finite-EI cables,
standalone and coupled. A row fails if it is not `TypeName Tf`, names an undefined or already
named type or one without a WAKE OSCILLATOR row, or holds a value out of range.
named type or one without VIV (neither LINE TYPES `Cl > 0` nor a WAKE OSCILLATOR row), or holds
a value out of range.

### VIV DAMPING (optional, finite-EI lines)

Expand Down Expand Up @@ -1417,7 +1435,8 @@ Behaviour:
unit length becomes `1/2 rho D [Cdn CdAmp |w| w_x e_x + (C_dy |w_y| + c Cdn |w|) w_y e_y]`:
Morison's in-line part, with the drag factor `CdAmp` of the type's amplitude table, and the
cross-flow law of the row. Where the ambient normal flow falls below 0.01 m/s the axes are
undefined and the drag blends smoothly back to Morison's.
undefined and the drag blends smoothly back to Morison's. With a [VIV FRAME](#viv-frame-optional)
row the axes and the blend take the ambient flow relative to the cable's filtered motion.
- **`0 0 1` amplifies the in-line drag alone.** With an amplitude table's `CdAmp` (for example
Chaplin et al. 2005, Eq. 4), the mean in-line drag of a vibrating cable rises while its
cross-flow drag stays Morison's. A `CdAmp` without this row multiplies the whole normal drag,
Expand Down
95 changes: 91 additions & 4 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1374,9 +1374,10 @@ velocity across the ambient flow normal to the line, :math:`\dot{\mathbf r}\cdot
\mathbf u_n)/|\mathbf u_n|`: their :math:`y` is measured across the incoming flow, and the
cross-flow axis of the phase, across the relative flow, turns with the node's own velocity, which
at a response velocity comparable to the flow would shorten the projected velocity by
:math:`U/|\mathbf v_n|` (16 % at the A/D of 0.68 of the gate below). The travel is integrated by
the trapezoidal rule over each step, with a crossing inside a step placed by linear interpolation;
the error is that of the rule, :math:`(\omega\Delta t)^2/12` relative for a harmonic response.
:math:`U/|\mathbf v_n|` (16 % at the A/D of 0.68 of the gate below); a ``VIV FRAME`` row takes the
flow and the velocity relative to the cable's filtered motion (:ref:`theory-viv-frame`). The
travel is integrated by the trapezoidal rule over each step, with a crossing inside a step
placed by linear interpolation; the error is that of the rule, :math:`(\omega\Delta t)^2/12` relative for a harmonic response.
The travel is carried signed, :math:`\int\dot y\,\mathrm{d}t` since the last crossing, whose sign
is that of the half cycle: a velocity that reverses through a sample at zero ends the half cycle
there, and one that touches zero without a sign change ends none.
Expand Down Expand Up @@ -1443,7 +1444,8 @@ from the still-water decay tests of Vikestad et al. 2000, valid for :math:`y_0/D
:math:`u_{ref} = 0.01` m/s the axes are undefined, and :math:`\mathbf f_n` blends to Morison's as
:math:`\beta\,\mathbf f_s + (1-\beta)\,\mathbf f_M` with :math:`\beta = U^2/(U^2 + u_{ref}^2)`.
The force and its Jacobians in the relative velocity and in the tangent are exact, and the
tangential drag is unchanged.
tangential drag is unchanged. With a ``VIV FRAME`` row the axes and the blend take the ambient flow
relative to the cable's filtered motion (:ref:`theory-viv-frame`).

The row serves two uses:

Expand All @@ -1460,6 +1462,91 @@ with :math:`C_v = 0` and factor 2 the line settles at the static in-line offset
printed digits; Thorsen's form raises the steady cross-flow amplitude from :math:`A/D` 0.68 to 1.02;
and the drag, damping and VIV powers balance within 0.2 %.

.. _theory-viv-frame:

Flow frame of the synchronisation model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The synchronisation model takes the node's motion in the earth frame. Its phase reads the
cross-flow velocity :math:`\dot{\mathbf r}\cdot\mathbf e` across the relative flow, which is
:math:`\mathbf u\cdot\mathbf e` and so zero in still water; the amplitude estimate and the
cross-flow damping are defined across the ambient flow, which still water does not have. A cable
moved through still water, by a tow or by its floater, therefore locks its phase on
:math:`\ddot y` alone, keeps :math:`y_0^* = 0`, :math:`C_v(0)` and the drag factor at 0, and its
damping blends to Morison's, while the same problem in the cable's frame (the water moving past
the held cable) does not. A ``VIV FRAME`` row with :math:`T_f > 0` on a synchronisation type
(LINE TYPES ``Cl > 0``) takes these quantities in the frame of the node's filtered velocity
:math:`\bar{\mathbf v}` of :ref:`theory-viv-wake` (the same filter, started at the node's
velocity):

- the phases (cross-flow, and in-line where it runs) take :math:`\dot{\mathbf r} -
\bar{\mathbf v}` along their axes, which the relative flow sets, so the axes and the shedding
speed :math:`U` stay those of the relative flow; the acceleration stays the node's, since
:math:`\bar{\mathbf v}` changes slowly and its rate :math:`(\mathbf v - \bar{\mathbf v})/T_f`
would carry the VIV velocity;
- the amplitude estimate takes

.. math::

\dot y = (\dot{\mathbf r} - \bar{\mathbf v})\cdot
\frac{\mathbf t\times(\mathbf u - \bar{\mathbf v})_n}{|(\mathbf u - \bar{\mathbf v})_n|},

and with it the table's :math:`C_v`, drag factor and :math:`C_{dy}`;
- the damping takes :math:`\mathbf e_x`, :math:`\mathbf e_y` and the blend :math:`\beta` from
:math:`(\mathbf u - \bar{\mathbf v})_n`, an element the mean :math:`\bar{\mathbf v}` of its end
nodes.

:math:`\bar{\mathbf v}` is held over a step (the step-start value), so the Jacobians are
unchanged, and it is updated at the converged end. The lift and the drag act on the relative
velocity, which does not depend on the frame, and are unchanged. For a frame moving at a constant
velocity (a steady tow) the model is that of the held cable exactly. The velocity relative to
:math:`\bar{\mathbf v}` loses the part of the VIV velocity that passes the filter: for a response
at :math:`\omega` it is scaled by :math:`\omega T_f/\sqrt{1 + \omega^2 T_f^2}` and led by
:math:`\arctan(1/\omega T_f)` (0.9985 and 3.1° at 0.29 Hz with :math:`T_f` 10 s). For a motion at
:math:`\omega_m` the filter lags by :math:`\arctan\omega_m T_f`. :math:`T_f` is therefore taken
several VIV periods long and short against the motion.

A pipe of the displaced mass (20 m, :math:`D` 0.1 m, ``Cl`` 0.8) moved in still water with
velocity amplitude 0.6 m/s and period 40 s, against the same pipe held in the water moving the
other way (the held fluid field, so the Froude-Krylov load acts; a pipe of another mass would
differ by :math:`(m - \rho A)\dot V`), with :math:`T_f` 0.6 s:

.. list-table::
:header-rows: 1

* - Pipe
- Frame
- Peak A/D moving / held
- RMS A/D moving / held
* - Amplitude table and Thorsen's damping
- ``Tf`` 0.6 s
- 0.819 / 0.819
- 0.446 / 0.447
* -
- none
- 0.711 / 0.850
- 0.349 / 0.450
* - ``Cl`` alone
- ``Tf`` 0.6 s
- 0.713 / 0.714
- 0.372 / 0.371
* -
- none
- 0.711 / 0.736
- 0.349 / 0.375

With the row the RMS of the two frames agrees within 0.2 % and the peak within 1 % (the moving
pipe's peak, a single extreme, ranges 0.811-0.819 over builds, OpenBLAS kernels and platforms),
the rest being the filter's lag
(:math:`\omega_m T_f` = 0.094). A taut cable towed at 0.15 m/s with :math:`T_f` 10 s gives A/D
0.7905 against 0.7906 held in the current with the same row (0.792 without it; 0.665 towed without
the row) with the table and damping, and 0.6764 against 0.6764 with ``Cl`` alone. On the held
cable :math:`T_f` changes A/D by at most 0.23 % on both line kinds. :math:`\bar{\mathbf v}` takes
rows 7-9 of the node's motion statistics on both line kinds (nine rows; rows 3-6, the amplitude
estimate, stay 0 without a table), so it is part of the step-recovery, snapshot and checkpoint
state; an ``EI = 0`` line filters its smoothed node velocity. :math:`T_f` 0 or no row leaves the
run unchanged to the bit.

.. _theory-viv-coefficients:

Published coefficient sets
Expand Down
Loading
Loading