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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,11 @@ 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.
- 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
with ATTACHMENTS, on `EI = 0` lines and finite-EI cables, standalone and coupled. `Dviv` equal to
`Diam` is the type without it, bit for bit; 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
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1344,6 +1344,13 @@ 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)

# The diameter of the VIV model on a deck (VIV DIAMETER section), both line kinds: Dviv = Diam as
# no section, the shedding band and the uncoupled wake frequency following Dviv, and the refusals.
add_executable(test_viv_diameter_deck tests/test_viv_diameter_deck.f90)
target_link_libraries(test_viv_diameter_deck PRIVATE cabledyn_core)
add_test(NAME viv_diameter_deck COMMAND test_viv_diameter_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_diameter_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
4 changes: 4 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,10 @@ Line and constitutive capability
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
* - 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
other sections shedding at a larger outer diameter (:ref:`theory-viv-diameter`)

Loads and environment
---------------------
Expand Down
39 changes: 37 additions & 2 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,8 +298,9 @@ 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, and a [VIV AMPLITUDE](#viv-amplitude-optional) table makes `Cl` (and
`Cd`) depend on the cross-flow amplitude.
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.

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

### VIV DIAMETER (optional)

The diameter of the VIV model of a line type, apart from the hydrodynamic diameter `Diam` that
its drag, added mass and buoyancy keep (see [VIV diameter](theory.rst)).

```text
--------------------- VIV DIAMETER -------------------------------------
TypeName Dviv
(-) (m)
zone 0.9
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) with VIV (`Cl > 0`, or a WAKE OSCILLATOR row), at most one row each |
| `Dviv` | diameter > 0 of its VIV model [m], at most 1e15 |

Behaviour:

- The VIV of the type takes `Dviv` wherever it takes the diameter: the shedding frequency
`cF U/Dviv` and its band (or the wake frequency `2 pi St U/Dviv` and the coupling `A/Dviv`), the
lift, in-line and higher-harmonic forces `1/2 rho Dviv C U^2`, and the amplitude ratio of a
[VIV AMPLITUDE](#viv-amplitude-optional) table. The drag, added mass, buoyancy and seabed
contact keep `Diam`; so do the stiffener and attachment loads.
- A buoyancy-module zone of a cable whose modules are ATTACHMENTS rows can be given its own VIV:
split the line into SECTIONS at the zone, give the zone a copy of the cable's line type with
`Dviv` the module diameter and its own `Cl`, `dF` and `cF` (or `Cl 0` for no VIV there), and
keep the modules' mass, volume and drag in ATTACHMENTS. CableDyn models no shedding
interaction between modules and bare cable; the coefficients of such a zone are the user's
choice.
- A row with `Dviv` equal to `Diam` 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 Dviv`, names an
undefined or already named type or one without VIV, 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
24 changes: 24 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1336,6 +1336,30 @@ at 0.3 holds the response at A/D 0.28; :math:`C_v = 0` with a drag factor 2 sett
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-viv-diameter:

VIV diameter
~~~~~~~~~~~~

A ``VIV DIAMETER`` row gives the VIV model of a line type a diameter :math:`D_v` of its own. The
shedding frequency :math:`2\pi(c_F + d_F\sin(\phi_y - \phi))U/D_v` (or the wake frequency
:math:`2\pi\,\mathrm{St}\,U_a/D_v` with the coupling :math:`A/D_v`), the VIV forces
:math:`\tfrac12\rho D_v C U^2` and the amplitude ratio :math:`y_0^*/D_v` of a ``VIV AMPLITUDE``
table take it, while the drag, added mass, buoyancy and contact keep the type's ``Diam``. It
serves a section whose shedding is set by a larger outer diameter than its hydrodynamic one, as a
buoyancy-module zone whose modules are ATTACHMENTS on the bare cable: a copy of the cable's type
with :math:`D_v` the module diameter and its own synchronisation coefficients. The shedding of
such a zone, where modules and bare cable alternate, has no established model; :math:`D_v` and
the coefficients are the user's.

On the taut line of the wake-oscillator gate (``Diam`` 0.1 m) the synchronisation model locks in
near the first mode, at 0.287 Hz; with :math:`D_v` = 0.2 m its band,
0.075-0.195 Hz, lies below the mode, where the motion lags the lift by less than a quarter period
and the phase runs at the top of the band, 0.196 Hz, on ``EI = 0`` lines and finite-EI cables
alike; an uncoupled wake oscillator (:math:`A` = 0) drives the cable at 0.149 Hz against
: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-dry-buoyancy:

Buoyancy and wetting
Expand Down
25 changes: 25 additions & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,11 @@ 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_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
ratio take it in place of ``diam`` (which the drag, added mass and
buoyancy keep); it needs ``cl`` or ``wake_cl0``.
"""

name: str
Expand Down Expand Up @@ -263,6 +268,7 @@ class LineType:
wake_eps: float | None = None
wake_a: float | None = None
viv_amplitude: list[tuple[float, ...]] | None = None
viv_diameter: float | None = None


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

Expand Down Expand Up @@ -1728,6 +1735,7 @@ def add_line_type(
wake_eps,
wake_a,
None if viv_amplitude is None else [tuple(row) for row in viv_amplitude],
viv_diameter,
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2621,6 +2629,7 @@ def to_text(self, *, validate: bool = True) -> str:
_emit(out, "VIV", *self._viv_table())
_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, "FAILURE", *self._failure_table())
_emit(out, "CONTROL", *self._control_table())
_emit(out, "EXTERNAL LOADS", *self._external_load_table())
Expand Down Expand Up @@ -3041,6 +3050,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_diam_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
if item.viv_diameter is None:
continue
what = f"line type {item.name!r}"
if item.cl is None and item.wake_cl0 is None:
raise ValueError(
f"{what}: viv_diameter is the diameter of its VIV, set cl or wake_cl0"
)
rows.append([_text(item.name, what), _num(item.viv_diameter, what)])
return "Name Dviv", "(-) (m)", 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 @@ -3258,6 +3280,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 DIAMETER"):
t = row.tokens
model.line_types[t[0]].viv_diameter = _f(t[1])
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
39 changes: 39 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@
"WAKE": "WAKE OSCILLATOR",
"VIV AMPLITUDE": "VIV AMPLITUDE",
"VIV AMPLITUDES": "VIV AMPLITUDE",
"VIV DIAMETER": "VIV DIAMETER",
"VIV DIAMETERS": "VIV DIAMETER",
}
# 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 @@ -115,6 +117,7 @@
"VIV",
"WAKE OSCILLATOR",
"VIV AMPLITUDE",
"VIV DIAMETER",
}
)
_TABLE_SECTIONS = _LIST_DIRECTED_SECTIONS | _WHITESPACE_TABLE_SECTIONS
Expand Down Expand Up @@ -3344,6 +3347,41 @@ def _check_wake_section(self, lift_type_names: set[str]) -> set[str]:
wake.add(name)
return wake

def _check_viv_diam_section(self, viv_type_names: set[str]) -> None:
"""Native ``apply_type_viv_diam`` for the VIV DIAMETER section.

A row ``TypeName Dviv`` sets the diameter of a line type's VIV model, ``Dviv > 0`` (at
most 1e15). The type needs VIV (LINE TYPES ``Cl > 0`` or a WAKE OSCILLATOR row with
``CL0 > 0``); 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 DIAMETER"):
where = self._at(row)
if len(row.tokens) != 2:
raise DeckFormatError(f"{where}: VIV DIAMETER rows must be: TypeName Dviv")
name = row.tokens[0].lower()
if name not in types:
raise DeckFormatError(
f'{where}: VIV DIAMETER row names undefined LINE TYPE "{row.tokens[0]}"'
)
if name in named:
raise DeckFormatError(
f'{where}: VIV DIAMETER names LINE TYPE "{types[name]}" twice'
)
named.add(name)
try:
value = _native_float(row.tokens[1])
except ValueError as exc:
raise DeckFormatError(f"{where}: VIV DIAMETER Dviv must be a plain number") from exc
if not (math.isfinite(value) and 0.0 < value <= _NATIVE_MAX_COEFFICIENT):
raise DeckFormatError(f"{where}: VIV DIAMETER needs Dviv > 0, at most 1e15")
if name not in viv_type_names:
raise DeckFormatError(
f'{where}: VIV DIAMETER of LINE TYPE "{types[name]}" sets the diameter of its '
"VIV: give the type LINE TYPES Cl > 0 or a WAKE OSCILLATOR row"
)

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 @@ -4598,6 +4636,7 @@ def end_key(token: str) -> str:
self._check_viv_section(line_type_meta, viv_type_names)
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)
amp_lines = {
line_id
for line_id, section_types in section_types_by_line.items()
Expand Down
13 changes: 13 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,19 @@ def test_viv_amplitude_rows_are_written_with_the_values_given(tmp_path: Path) ->
model.to_text(validate=False)


def test_viv_diameter_rows_are_written(tmp_path: Path) -> None:
model = _chain_model(tmp_path)
model.add_line_type(
"zone", diam=0.1, mass=10.0, ea=5.0e7, cdn=1.2, can=1.0, cl=0.4, viv_diameter=0.9
)
deck = DeckFile.from_text(model.to_text(validate=False), path=tmp_path / "deck.dat")
rows = [row.tokens for row in deck._rows("VIV DIAMETER")]
assert rows == [("zone", "0.9")]
model.add_line_type("plain", diam=0.1, mass=10.0, ea=5.0e7, viv_diameter=0.9)
with pytest.raises(ValueError, match="set cl or wake_cl0"):
model.to_text(validate=False)


def test_build_spread_mooring_with_multi_section_lines() -> None:
import math

Expand Down
40 changes: 40 additions & 0 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -4951,6 +4951,46 @@ def test_viv_amplitude_rows_follow_the_native_checks(lift, rows, message):
DeckFile.from_text(_with_section(text, "VIV AMPLITUDE", *rows))


def test_viv_diameter_rows_are_read_and_kept(tmp_path):
from cabledyn import DeckModel

text = _with_section(
_edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8")),
"VIV DIAMETER",
"TypeName Dviv",
"chain 0.9",
)
DeckFile.from_text(text)
path = tmp_path / "dia.dat"
path.write_text(text, encoding="utf-8")
assert DeckModel.load(path).line_types["chain"].viv_diameter == 0.9
saved = tmp_path / "saved.dat"
DeckModel.load(path).save(saved)
assert DeckModel.load(saved).line_types["chain"].viv_diameter == 0.9


@pytest.mark.parametrize(
"lift, rows, message",
[
(True, ("chain 0.9 1.0",), "rows must be: TypeName Dviv"),
(True, ("cable 0.9",), 'undefined LINE TYPE "cable"'),
(True, ("chain 0.9", "chain 0.8"), 'names LINE TYPE "chain" twice'),
(True, ("chain 0.0",), "Dviv > 0, at most 1e15"),
(True, ("chain -0.9",), "Dviv > 0, at most 1e15"),
(False, ("chain 0.9",), "give the type LINE TYPES Cl > 0 or a WAKE OSCILLATOR row"),
],
)
def test_viv_diameter_rows_follow_the_native_checks(lift, rows, message):
text = _edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8")) if lift else _DYNAMIC
with pytest.raises(DeckFormatError, match=re.escape(message)):
DeckFile.from_text(_with_section(text, "VIV DIAMETER", *rows))


def test_viv_diameter_takes_a_wake_oscillator_type():
text = _with_section(_DYNAMIC, "WAKE OSCILLATOR", "chain 0.3")
DeckFile.from_text(_with_section(text, "VIV DIAMETER", "chain 0.9"))


def test_viv_amplitude_channel_needs_a_table():
text = _edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8"))
text = _edit(text, ("FairTen1\n", "FairTen1\nVIVAmp1N2\n"))
Expand Down
31 changes: 31 additions & 0 deletions python/tests/test_end_to_end.py
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,37 @@ def _amp_table(*rows: str) -> tuple[str, str]:
]


def _dia_rows(*rows: str) -> tuple[str, str]:
"""The edit that puts a VIV DIAMETER section with ``rows`` before OPTIONS."""
block = "--------------------- VIV DIAMETER -----\n" + "".join(f"{row}\n" for row in rows)
return _AMP_OPTIONS, block + _AMP_OPTIONS


_DIA_PARITY = [
("dia-accepted", [_dia_rows("riser 0.3")], True),
("dia-zero", [_dia_rows("riser 0.0")], False),
("dia-repeated", [_dia_rows("riser 0.3", "riser 0.2")], False),
("dia-three-columns", [_dia_rows("riser 0.3 1.0")], False),
(
"dia-wake-type",
[
_WAKE_LIFT,
_WAKE_SECTION,
("riser 0.85 0.15", "riser 0.3"),
_dia_rows("riser 0.3"),
],
True,
),
(
"dia-no-viv",
[_WAKE_LIFT, ("riser 0.85 0.15", ""), _dia_rows("riser 0.3")],
False,
),
]

_AMP_PARITY += _DIA_PARITY


@pytest.mark.parametrize(
("label", "edits", "accepted"), _AMP_PARITY, ids=[item[0] for item in _AMP_PARITY]
)
Expand Down
Loading
Loading