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 @@ -50,6 +50,15 @@ All notable changes to CableDyn are recorded in this file. The format follows
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.
- Cross-flow damping: an optional `VIV DAMPING` section row `TypeName a b [c]` splits the drag
of a finite-EI line type about the ambient normal flow: Morison's drag in line, and across it
the hydrodynamic damping `C_dy = a + b y0/D` of Thorsen et al. (2016) (Eq. 1, `0.31 0.89`) at
the `VIV AMPLITUDE` estimate `y0`, plus a Morison-form term `c Cdn |w| w_y`, blended to
Morison's drag in still water, with exact Jacobians. `0 0 1` is Morison's drag
with the `CdAmp` drag factor on the in-line part alone (the cross-flow VIV motion is not
damped twice); the quadratic form of Thorsen et al. suits cross-flow-only VIV models. Needs a
`VIV AMPLITUDE` table; `EI = 0` lines refused; the Python deck reader and builder take the
section.
- VIV diameter: an optional `VIV DIAMETER` section row `TypeName Dviv` gives the VIV model of a
line type (shedding frequency, wake frequency and coupling, VIV forces, amplitude ratio) a
diameter apart from the `Diam` its drag, added mass and buoyancy keep, for buoyancy-module zones
Expand Down
13 changes: 13 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1336,6 +1336,19 @@ 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")

# The split cross-flow drag of Thorsen et al. (2016) per unit length: Morison at rest, the
# quadratic cross-flow damping across the flow, Morison without ambient flow, exact Jacobians.
add_executable(test_viv_cf_damping_kernel tests/test_viv_cf_damping_kernel.f90)
target_link_libraries(test_viv_cf_damping_kernel PRIVATE cabledyn_core)
add_test(NAME viv_cf_damping_kernel COMMAND test_viv_cf_damping_kernel)
set_tests_properties(viv_cf_damping_kernel PROPERTIES LABELS "fortran;unit;dynamic;viv")
# The split drag on a deck (VIV DAMPING section): Morison recombined, the in-line drag alone
# amplified, Thorsen's quadratic cross-flow damping, the energy ledger and the refusals.
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")

# 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.
Expand Down
7 changes: 7 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,13 @@ Line and constitutive capability
- Standalone and coupled
- a diameter of the VIV model apart from the hydrodynamic one, for buoyancy-module zones and
other sections shedding at a larger outer diameter (:ref:`theory-viv-diameter`)
* - Cross-flow damping (``VIV DAMPING`` section ``a``, ``b``, ``c``)
- Standalone and coupled
- the drag split into its in-line and cross-flow parts about the ambient flow, the
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`)

Loads and environment
---------------------
Expand Down
56 changes: 52 additions & 4 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,8 +133,8 @@ except that `SYROPE IC` must come **after** `LINES`, because its rows name lines
exist. A conventional layout is:

LINE TYPES → BODIES → EXTERNAL LOADS → ROD TYPES → RODS → POINTS → TURBINES → LINES → SYROPE IC →
SECTIONS → END CONNECTIONS / EQUIVALENT BUOYANCY / ATTACHMENTS / STIFFENERS / VIV / FAILURE /
CONTROL → OPTIONS → OUTPUTS
SECTIONS → END CONNECTIONS / EQUIVALENT BUOYANCY / ATTACHMENTS / STIFFENERS / VIV / WAKE OSCILLATOR /
VIV AMPLITUDE / VIV DIAMETER / VIV DAMPING / FAILURE / CONTROL → OPTIONS → OUTPUTS

Within LINE TYPES, the header row must precede the data rows because it selects their column
order.
Expand Down Expand Up @@ -211,6 +211,10 @@ are collapsed. It must match one of the spellings below; any other name fails wi
| ATTACHMENTS | `ATTACHMENTS`, `LINE ATTACHMENTS`, `CLUMPS` |
| STIFFENERS | `STIFFENERS`, `STIFFENER`, `BEND STIFFENERS`, `BEND STIFFENER` |
| VIV | `VIV`, `VORTEX-INDUCED VIBRATION`, `VORTEX INDUCED VIBRATION` |
| WAKE OSCILLATOR | `WAKE OSCILLATOR`, `WAKE OSCILLATORS`, `WAKE` |
| VIV AMPLITUDE | `VIV AMPLITUDE`, `VIV AMPLITUDES` |
| VIV DIAMETER | `VIV DIAMETER`, `VIV DIAMETERS` |
| VIV DAMPING | `VIV DAMPING` |
| FAILURE | `FAILURE`, `FAILURES` |
| CONTROL | `CONTROL`, `CONTROLS` |
| TURBINES | `TURBINES`, `TURBINE` |
Expand Down Expand Up @@ -299,8 +303,9 @@ the half-range and centre of its band in non-dimensional frequency (MoorDyn's `d
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, a [VIV AMPLITUDE](#viv-amplitude-optional) table makes `Cl` (and
`Cd`) depend on the cross-flow amplitude, and a [VIV DIAMETER](#viv-diameter-optional) row gives
the VIV a diameter of its own.
`Cd`) depend on the cross-flow amplitude, a [VIV DIAMETER](#viv-diameter-optional) row gives
the VIV a diameter of its own, and a [VIV DAMPING](#viv-damping-optional-finite-ei-lines) row splits
the drag into an in-line and a cross-flow part with its own law.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down Expand Up @@ -1324,6 +1329,49 @@ Behaviour:
finite-EI cables, standalone and coupled. A row fails if it is not `TypeName Dviv`, names an
undefined or already named type or one without VIV, or holds a value out of range.

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

Splits the normal Morison drag of a line type into an in-line and a cross-flow part in the frame
of the ambient flow, and gives the cross-flow part its own law: the quadratic damping of
Thorsen et al. (2016) and, optionally, a Morison-form term (see
[Cross-flow damping](theory.rst)).

```text
--------------------- VIV DAMPING --------------------------------------
TypeName a b c
(-) (-) (-) (-)
riser 0 0 1
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) with a [VIV AMPLITUDE](#viv-amplitude-optional) table, at most one row each |
| `a`, `b` | the cross-flow damping coefficient `C_dy = a + b y0/D` >= 0, `y0/D` the type's amplitude estimate; Thorsen et al. (2016, Eq. 1) give `0.31 0.89` |
| `c` | optional factor >= 0 of a Morison-form cross-flow term `c Cdn \|w\| w_y`, `Cdn` the type's own (unamplified) normal drag coefficient (default 0) |

Behaviour:

- At each point of the line, with `e_x` along the ambient flow normal to the line and `e_y`
across it, the relative normal velocity `w` splits into `w_x` and `w_y`. The normal drag per
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.
- **`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,
the cross-flow damping included.
- **`0.31 0.89` is the published cross-flow-only model** of Thorsen et al. (2016), fitted to
still-water decay tests for `y0/D` up to about 0.6. It removes the linear part of Morison's
cross-flow damping (`1/2 rho D Cdn U y'`), so use it without in-line VIV: with a `VIV` section
row the in-line force turns with the relative flow and can drive a low-frequency cross-flow
motion that nothing damps.
- `0 0 1` with `CdAmp` 1 is Morison's drag (to round-off). The split acts in the dynamics; the
static solve keeps Morison's drag, which is the same at rest. `DragPow` reports the split drag.
- Finite-EI cables only, standalone and coupled; an `EI = 0` line with the row is refused by name.
A row fails if it is not `TypeName a b [c]`, names an undefined or already named type or one
without an amplitude table, or holds a value out of range.

### 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
41 changes: 41 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1360,6 +1360,47 @@ alike; an uncoupled wake oscillator (:math:`A` = 0) drives the cable at 0.149 Hz
:math:`\mathrm{St}\,U/D_v` = 0.15 Hz; and :math:`D_v` equal to ``Diam`` is the line without the row,
bit for bit.

.. _theory-viv-cf-damping:

Cross-flow damping
~~~~~~~~~~~~~~~~~~

A ``VIV DAMPING`` row splits the normal Morison drag of a finite-EI line type in the frame of the
ambient flow. With :math:`\mathbf t` the tangent, :math:`\mathbf u_n` the ambient flow normal to
it, :math:`\mathbf e_x = \mathbf u_n/|\mathbf u_n|` and :math:`\mathbf e_y = \mathbf t\times\mathbf e_x`,
the relative normal velocity :math:`\mathbf w` splits into :math:`w_x` and :math:`w_y`, and

.. math::

\mathbf f_n = \tfrac12\rho D\left[C_{dn}A_d\,|\mathbf w|\,w_x\,\mathbf e_x
+ \left(C_{dy}|w_y| + c\,C_{dn}|\mathbf w|\right)w_y\,\mathbf e_y\right],\qquad
C_{dy} = a + b\,\frac{y_0^*}{D},

with :math:`A_d` the drag factor of the type's amplitude table and :math:`y_0^*` its amplitude
estimate (:ref:`theory-viv-amplitude`). The quadratic term is the cross-flow hydrodynamic damping of
:ref:`Thorsen et al. (2016) <ref-thorsen2016>` (their Eq. 1, :math:`a = 0.31`, :math:`b = 0.89`
from the still-water decay tests of Vikestad et al. 2000, valid for :math:`y_0/D` up to about
0.6). The :math:`c` term is Morison's own cross-flow drag. Where :math:`|\mathbf u_n|` falls below
: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.

The row serves two uses:

- With :math:`(0, 0, 1)` and the drag factor of :ref:`Chaplin et al. (2005) <ref-chaplin2005>`,
the amplification acts on the mean in-line drag alone, as measured, while the cross-flow drag
stays Morison's.
- :math:`(0.31, 0.89, 0)` is Thorsen's cross-flow model. It drops the linear part
:math:`\tfrac12\rho D C_{dn}U\dot y` of Morison's cross-flow damping, so it is consistent with
cross-flow VIV alone. An in-line force that turns with the relative flow can then drive an
undamped low-frequency cross-flow motion.

On the taut gate line, :math:`(0, 0, 1)` with factor 1 is the line without the row to round-off;
with :math:`C_v = 0` and factor 2 the line settles at the static in-line offset of ``Cd`` 2.4 to the
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-dry-buoyancy:

Buoyancy and wetting
Expand Down
26 changes: 26 additions & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,12 @@ class LineType:
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).
viv_damping : tuple[float, float] | tuple[float, float, float] | None
Optional ``VIV DAMPING`` row ``(a, b[, c])``: the cross-flow damping
``C_dy = a + b y0/D`` of Thorsen et al. (2016) in place of the cross-flow part of the
type's Morison drag, plus a Morison-form term ``c Cdn |w| w_y``; ``(0.31, 0.89)`` is
their published fit, ``(0, 0, 1)`` amplifies the in-line drag alone (with a
``viv_amplitude`` drag factor). Needs ``viv_amplitude``.
viv_diameter : float | None
Optional diameter of the type's VIV model, a ``VIV DIAMETER`` section row
``Name Dviv``: the shedding frequency, the VIV forces and the amplitude
Expand Down Expand Up @@ -269,6 +275,7 @@ class LineType:
wake_a: float | None = None
viv_amplitude: list[tuple[float, ...]] | None = None
viv_diameter: float | None = None
viv_damping: tuple[float, ...] | None = None


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

Expand Down Expand Up @@ -1736,6 +1744,7 @@ def add_line_type(
wake_a,
None if viv_amplitude is None else [tuple(row) for row in viv_amplitude],
viv_diameter,
None if viv_damping is None else tuple(viv_damping),
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2630,6 +2639,7 @@ def to_text(self, *, validate: bool = True) -> str:
_emit(out, "WAKE OSCILLATOR", *self._wake_table())
_emit(out, "VIV AMPLITUDE", *self._viv_amp_table())
_emit(out, "VIV DIAMETER", *self._viv_diam_table())
_emit(out, "VIV DAMPING", *self._viv_damp_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 @@ -3050,6 +3060,19 @@ def _viv_amp_table(self) -> tuple[str, str, list[list[str]]]:
rows.append([_text(item.name, what), *(_num(value, what) for value in row)])
return "Name AD Cv CdAmp", "(-) (-) (-) (-)", rows

def _viv_damp_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
if item.viv_damping is None:
continue
what = f"line type {item.name!r}"
if len(item.viv_damping) not in (2, 3):
raise ValueError(f"{what}: viv_damping is (a, b) or (a, b, c)")
if item.viv_amplitude is None:
raise ValueError(f"{what}: viv_damping takes its amplitude from viv_amplitude")
rows.append([_text(item.name, what)] + [_num(v, what) for v in item.viv_damping])
return "Name a b c", "(-) (-) (-) (-)", rows

def _viv_diam_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
Expand Down Expand Up @@ -3280,6 +3303,9 @@ def load(self) -> None:
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("VIV DAMPING"):
t = row.tokens
model.line_types[t[0]].viv_damping = tuple(_f(v) for v in t[1:])
for row in self.rows("VIV DIAMETER"):
t = row.tokens
model.line_types[t[0]].viv_diameter = _f(t[1])
Expand Down
51 changes: 49 additions & 2 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@
"VIV AMPLITUDES": "VIV AMPLITUDE",
"VIV DIAMETER": "VIV DIAMETER",
"VIV DIAMETERS": "VIV DIAMETER",
"VIV DAMPING": "VIV DAMPING",
}
# Table sections whose rows the native reader takes through a Fortran
# list-directed READ. Their descriptive and units rows are recognized by the
Expand Down Expand Up @@ -118,6 +119,7 @@
"WAKE OSCILLATOR",
"VIV AMPLITUDE",
"VIV DIAMETER",
"VIV DAMPING",
}
)
_TABLE_SECTIONS = _LIST_DIRECTED_SECTIONS | _WHITESPACE_TABLE_SECTIONS
Expand Down Expand Up @@ -3382,6 +3384,45 @@ def _check_viv_diam_section(self, viv_type_names: set[str]) -> None:
"VIV: give the type LINE TYPES Cl > 0 or a WAKE OSCILLATOR row"
)

def _check_viv_damp_section(self, amp_type_names: set[str]) -> set[str]:
"""Native ``apply_type_viv_damp`` for the VIV DAMPING section; the types it names.

A row ``TypeName a b [c]`` gives a line type the cross-flow hydrodynamic damping
``C_dy = a + b y0/D`` of Thorsen et al. (2016) in place of the cross-flow part of its
Morison drag, plus a Morison-form term ``c Cdn |w| w_y`` (default 0); ``a, b, c >= 0``,
each at most 1e15. ``y0`` is the amplitude estimate of the type's VIV AMPLITUDE table,
so the type needs one. A type takes one row.
"""
types = {row.tokens[0].lower(): row.tokens[0] for row in self.line_types}
named: set[str] = set()
for row in self._rows("VIV DAMPING"):
where = self._at(row)
if len(row.tokens) not in (3, 4):
raise DeckFormatError(f"{where}: VIV DAMPING rows must be: TypeName a b [c]")
name = row.tokens[0].lower()
if name not in types:
raise DeckFormatError(
f'{where}: VIV DAMPING row names undefined LINE TYPE "{row.tokens[0]}"'
)
if name in named:
raise DeckFormatError(f'{where}: VIV DAMPING names LINE TYPE "{types[name]}" twice')
try:
values = [_native_float(token) for token in row.tokens[1:]]
except ValueError as exc:
raise DeckFormatError(
f"{where}: VIV DAMPING a, b and c must be plain numbers"
) from exc
if not all(math.isfinite(v) and 0.0 <= v <= _NATIVE_MAX_COEFFICIENT for v in values):
raise DeckFormatError(f"{where}: VIV DAMPING needs a, b and c >= 0, at most 1e15")
if name not in amp_type_names:
raise DeckFormatError(
f'{where}: VIV DAMPING of LINE TYPE "{types[name]}" takes the amplitude '
"estimate of its VIV AMPLITUDE table: give the type Cl > 0 and a VIV "
"AMPLITUDE table"
)
named.add(name)
return named

def _check_viv_amp_section(self, lift_type_names: set[str]) -> set[str]:
"""Native ``apply_type_viv_amp`` for the VIV AMPLITUDE section; the types with a table.

Expand Down Expand Up @@ -4637,15 +4678,21 @@ def end_key(token: str) -> str:
wake_type_names = self._check_wake_section(viv_type_names)
amp_type_names = self._check_viv_amp_section(viv_type_names)
self._check_viv_diam_section(viv_type_names | wake_type_names)
damp_type_names = self._check_viv_damp_section(amp_type_names)
amp_lines = {
line_id
for line_id, section_types in section_types_by_line.items()
if {line_type.lower() for line_type in section_types} & amp_type_names
}
# native build_one_hermite_cable and the EI = 0 line wiring: the wake oscillator acts
# on finite-EI cables only, and a cable takes one VIV model
# native build_one_hermite_cable and the EI = 0 line wiring: the wake oscillator and the
# cross-flow damping act on finite-EI cables only, and a cable takes one VIV model
for line_id, section_types in section_types_by_line.items():
types_used = {line_type.lower() for line_type in section_types}
if types_used & damp_type_names and line_id not in finite_line_ids:
raise DeckFormatError(
f"{self._label}: line {line_id}: the cross-flow damping (VIV DAMPING "
"section) acts on finite-EI cables (EI > 0) only"
)
if not types_used & wake_type_names:
continue
if line_id not in finite_line_ids:
Expand Down
Loading
Loading