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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,15 @@ All notable changes to CableDyn are recorded in this file. The format follows
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.
- Amplitude-dependent VIV coefficients: an optional `VIV AMPLITUDE` section, rows
`TypeName AD Cv [CdAmp]`, gives a line type a table over the cross-flow amplitude ratio of the
coefficient `Cv` that replaces its `Cl` and a factor `CdAmp` of its normal drag coefficient, read
at the amplitude estimate of Thorsen et al. (2016, Eq. 8 and 9) of each node, on `EI = 0` lines
and finite-EI cables, standalone and coupled. `VIVAmp<L>N<J>` writes the estimate. On the taut
example line it follows the steady response amplitude within 0.03 %, a falling `Cv` limits the
response inside its falling range, and a table with `Cv = Cl` and `CdAmp = 1` is the line
without it, bit for bit. The estimate 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 @@ -1330,6 +1330,20 @@ 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)

# VIV amplitude estimate (Thorsen et al. 2016, Eq. 8 and 9) and the amplitude tables.
add_executable(test_viv_amplitude_kernel tests/test_viv_amplitude_kernel.f90)
target_link_libraries(test_viv_amplitude_kernel PRIVATE cabledyn_core)
add_test(NAME viv_amplitude_kernel COMMAND test_viv_amplitude_kernel)
set_tests_properties(viv_amplitude_kernel PROPERTIES LABELS "fortran;unit;dynamic;viv")

# 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
# and the refusals.
add_executable(test_viv_amplitude_deck tests/test_viv_amplitude_deck.f90)
target_link_libraries(test_viv_amplitude_deck PRIVATE cabledyn_core)
add_test(NAME viv_amplitude_deck COMMAND test_viv_amplitude_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_amplitude_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
6 changes: 6 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,12 @@ Line and constitutive capability
- 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
* - Amplitude-dependent VIV coefficients (``VIV AMPLITUDE`` section ``AD``, ``Cv``, ``CdAmp``)
- Standalone and coupled
- 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

Loads and environment
---------------------
Expand Down
53 changes: 52 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,7 +298,8 @@ the half-range and centre of its band in non-dimensional frequency (MoorDyn's `d
`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; a [WAKE OSCILLATOR](#wake-oscillator-optional) row replaces the
lift by a wake oscillator.
lift by a wake oscillator, and a [VIV AMPLITUDE](#viv-amplitude-optional) table makes `Cl` (and
`Cd`) depend on the cross-flow amplitude.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down Expand Up @@ -1239,6 +1240,55 @@ Behaviour:
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.

### VIV AMPLITUDE (optional)

Amplitude-dependent coefficients of the synchronisation model of a line type (Thorsen et al.
2016): a table over the cross-flow amplitude ratio A/D of the coefficient `Cv` that replaces the
type's LINE TYPES `Cl`, and of a factor `CdAmp` of its normal drag coefficient `Cd` (see
[Amplitude-dependent coefficients](theory.rst)). The rows of one type follow each other in
increasing A/D.

```text
--------------------- VIV AMPLITUDE ------------------------------------
TypeName AD Cv CdAmp
(-) (-) (-) (-)
riser 0.0 0.8 1.0
riser 0.3 0.9 1.5
riser 0.6 0.0 2.0
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) whose `Cl > 0` |
| `AD` | amplitude ratio A/D >= 0 of the row, strictly increasing over the type's rows |
| `Cv` | cross-flow coefficient >= 0 at that amplitude, in place of `Cl` |
| `CdAmp` | optional factor > 0 of the type's normal drag coefficient at that amplitude (default 1) |

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
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
last. The coefficients of a step use the estimate of the committed state. The estimate starts
at 0, and the static equilibrium takes the type's own `Cd`, so a table whose `CdAmp` at A/D 0
is not 1 starts the run off that equilibrium.
- `VIVAmp<L>N<J>` (OUTPUTS) is the smoothed amplitude of node J [m].
- A table whose `Cv` falls to zero above some A/D limits the response there (Thorsen et al. fit
such a curve to riser tests, their Fig. 7). `CdAmp` gives the drag amplification of a vibrating
cylinder, for example Chaplin et al. (2005, Eq. 4), `Cd/Cd0 = 1 + 2.3 s + 1.7 s^2` with the
r.m.s. cross-flow displacement `s = (A/D)/sqrt(2)` of a harmonic response.
- The estimate assumes a narrow-band response, as theirs does. With the in-line VIV of a `VIV`
section row, `ClX` and `Chh` stay constant. The estimate is part of the step-recovery, snapshot
and checkpoint state. A table with `Cv = Cl` and `CdAmp = 1` throughout runs as the type
without it.
- It acts on `EI = 0` lines and finite-EI cables, standalone and coupled. A row fails if it is not
`TypeName AD Cv [CdAmp]`, names an undefined type or one without the synchronisation lift
(`Cl = 0`, as a wake-oscillator type), holds a value out of range, does not increase in `AD`,
or has other columns than the type's earlier rows; a type takes 2 to 32 rows.

### 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 Expand Up @@ -1713,6 +1763,7 @@ bending moment. None of these channels is mandatory.
| `DragPow<L>` | line L power of the Morison drag (and, on a finite-EI line, its ATTACHMENTS' drag) | W |
| `DampPow<L>` | line L power of the structural damping (`BA`, and `EI|Bb` on a finite-EI line); never positive | W |
| `VIVPow<L>N<J>`, `DragPow<L>N<J>`, `DampPow<L>N<J>` | the same per unit unstretched length about node J (node J's share: half of each of its elements' power and its own node loads', over half their unstretched length) | W/m |
| `VIVAmp<L>N<J>` | line L smoothed cross-flow amplitude estimate at node J (Thorsen et al. 2016, Eq. 9), which a [VIV AMPLITUDE](#viv-amplitude-optional) table reads; only on a line with such a table; 0 at a node without VIV | m |

- `<L>`/`<P>` are deck LINE/POINT **ids**, not array positions. A channel that matches no
supported form, names an unknown id, or carries trailing text (for example `Point2px_raw`) is a
Expand Down
9 changes: 9 additions & 0 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -918,6 +918,15 @@ three balance within 0.5 % of the VIV power, the line's loss of energy over the
response settles, and as an ``EI = 0`` line the same. Integrating a channel over the output times gives the work of its
load, :math:`W = \int P\,dt`; a static run reports 0.

VIV amplitude channel
~~~~~~~~~~~~~~~~~~~~~

``VIVAmp<L>N<J>`` [m] is the smoothed cross-flow amplitude estimate of node ``J`` of line ``L``,
the amplitude at which a ``VIV AMPLITUDE`` table reads the coefficients of the node's elements
(:ref:`theory-viv-amplitude`): half the node's travel across the ambient flow between two zero
crossings of its cross-flow velocity, smoothed over about ten time steps. It is requested only on
a line with such a table, and is 0 at a node without VIV and in a static run.

Point channels
~~~~~~~~~~~~~~

Expand Down
44 changes: 44 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1292,6 +1292,50 @@ steady mid-span A/D of 0.58; with :math:`A` = 0 the uncoupled wake drives it at
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-viv-amplitude:

Amplitude-dependent coefficients
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ``VIV AMPLITUDE`` table makes the cross-flow coefficient of the synchronisation model and the
normal drag coefficient of a line type functions of the cross-flow amplitude, the form of
:ref:`Thorsen et al. (2016) <ref-thorsen2016>`, who fit an excitation curve
:math:`C_v(y_0/D)` to riser tests. Each node estimates its amplitude as they do (their Eq. 8 and
9):

.. math::

y_0 = \frac{1}{2}\int_{t_1}^{t_2} |\dot y|\,\mathrm{d}t, \qquad
\frac{\mathrm{d}y_0^*}{\mathrm{d}t} = k_a\,(y_0 - y_0^*), \quad k_a = \frac{0.1}{\Delta t},

with :math:`t_1, t_2` the last two zero crossings of :math:`\dot y` (a narrow-band response
travels :math:`2y_0` between them) and :math:`y_0^*` the smoothed amplitude, which moves a tenth
of the way to :math:`y_0` in each time step :math:`\Delta t`. :math:`\dot y` is the node's
velocity across the ambient flow normal to the line, :math:`\dot{\mathbf r}\cdot(\mathbf t\times
\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.
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.

An element takes the mean :math:`y_0^*` of its free nodes (the VIV nodes; a fixed end node has
none) over its diameter as :math:`A/D` and reads its table there: :math:`C_v` in place of ``Cl`` in the lift, and a factor of ``Cd`` in the
normal Morison drag, linear between rows and held beyond the end ones. The coefficients of a step
use the estimate of the committed state, so the Jacobians only scale. The estimate is updated at
the end of each converged step from the committed one, so a repeated or rewound step updates it
once, and it is part of the step-recovery, snapshot and checkpoint state.

On the taut line of the wake-oscillator gate (Cl 0.8, ``EI = 0`` and finite-EI alike) the
smoothed mid-span estimate follows the half peak-to-peak cross-flow displacement of the steady
response within 0.03 % at A/D 0.68; a table whose :math:`C_v` falls from 0.8 at A/D 0.1 to zero
at 0.3 holds the response at A/D 0.28; :math:`C_v = 0` with a drag factor 2 settles at the static
offset of ``Cd`` 2.4 to six digits; and a table with :math:`C_v` = ``Cl`` and factor 1 is the
line without it, bit for bit.

.. _theory-dry-buoyancy:

Buoyancy and wetting
Expand Down
41 changes: 40 additions & 1 deletion python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,9 @@
("line", re.compile(r"(tdp)([0-9]+)(s|x|y|z|lay|exc|grd)", re.IGNORECASE)),
(
"line",
re.compile(r"(ten|curvx|curvy|curv|bendmom|stfmom|torq)([0-9]+)(n[0-9]+)", re.IGNORECASE),
re.compile(
r"(ten|curvx|curvy|curv|bendmom|stfmom|torq|vivamp)([0-9]+)(n[0-9]+)", re.IGNORECASE
),
),
("line", re.compile(r"(twist)([0-9]+)(n[0-9]+|)", re.IGNORECASE)),
("line", re.compile(r"(vivpow|dragpow|damppow)([0-9]+)(n[0-9]+|)", re.IGNORECASE)),
Expand Down Expand Up @@ -227,6 +229,13 @@ class LineType:
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.
viv_amplitude : list of tuples | None
Optional amplitude-dependent VIV coefficients of a type (Thorsen et al.
2016), the rows of a ``VIV AMPLITUDE`` section table ``Name AD Cv
[CdAmp]`` as ``(AD, Cv)`` or ``(AD, Cv, CdAmp)`` tuples, all of one
length, 2 to 32 of them in increasing amplitude ratio ``AD``: ``Cv``
replaces ``cl`` at that amplitude (so ``cl`` must be set) and ``CdAmp``
multiplies the normal drag coefficient ``cdn`` (1 when left out).
"""

name: str
Expand All @@ -253,6 +262,7 @@ class LineType:
wake_st: float | None = None
wake_eps: float | None = None
wake_a: float | None = None
viv_amplitude: list[tuple[float, ...]] | None = None


@dataclass(eq=False)
Expand Down Expand Up @@ -1676,6 +1686,7 @@ def add_line_type(
wake_st: float | None = None,
wake_eps: float | None = None,
wake_a: float | None = None,
viv_amplitude: list[tuple[float, ...]] | None = None,
) -> LineType:
"""Add a ``LINE TYPES`` row; see :class:`LineType` for the fields.

Expand Down Expand Up @@ -1716,6 +1727,7 @@ def add_line_type(
wake_st,
wake_eps,
wake_a,
None if viv_amplitude is None else [tuple(row) for row in viv_amplitude],
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2608,6 +2620,7 @@ def to_text(self, *, validate: bool = True) -> str:
_emit(out, "STIFFENERS", *self._stiffener_table())
_emit(out, "VIV", *self._viv_table())
_emit(out, "WAKE OSCILLATOR", *self._wake_table())
_emit(out, "VIV AMPLITUDE", *self._viv_amp_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 @@ -3008,6 +3021,26 @@ def _wake_table(self) -> tuple[str, str, list[list[str]]]:
rows.append(row)
return "Name CL0 St eps A", "(-) (-) (-) (-) (-)", rows

def _viv_amp_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
if item.viv_amplitude is None:
continue
what = f"line type {item.name!r}"
table = list(item.viv_amplitude)
if not table:
raise ValueError(f"{what}: viv_amplitude needs at least two rows")
widths = {len(row) for row in table}
if len(widths) != 1 or not widths <= {2, 3}:
raise ValueError(
f"{what}: viv_amplitude rows are (AD, Cv) or (AD, Cv, CdAmp), all of one length"
)
if item.cl is None:
raise ValueError(f"{what}: viv_amplitude scales the synchronisation lift, set cl")
for row in table:
rows.append([_text(item.name, what), *(_num(value, what) for value in row)])
return "Name AD Cv CdAmp", "(-) (-) (-) (-)", 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 @@ -3219,6 +3252,12 @@ def load(self) -> None:
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("VIV AMPLITUDE"):
t = row.tokens
item = model.line_types[t[0]]
if item.viv_amplitude is None:
item.viv_amplitude = []
item.viv_amplitude.append(tuple(_f(token) for token in t[1:]))
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
Loading
Loading