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
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,16 @@ All notable changes to CableDyn are recorded in this file. The format follows
with its source, its test data and the line-type columns it maps to, and Thorsen et al.'s
excitation curve as a `VIV AMPLITUDE` table.

- Wake oscillator for moving cables: an optional `VIV FRAME` section, rows `TypeName Tf`, takes
the free stream of a line type's VIV model relative to the cable's velocity low-pass filtered
over `Tf` [s] (first order). The wake frequency then follows a cable towed or moved by its
floater through still water, which the ambient flow alone never made shed. A taut cable towed
at 0.15 m/s with `Tf` 10 s locks in as the cable held in a 0.15 m/s current (A/D within
0.6 %); on a held cable `Tf` changes A/D by 0.03 %. On `EI = 0` lines and finite-EI cables,
the filtered velocity in the step-recovery, snapshot and checkpoint state; `Tf` 0 or no row
leaves runs unchanged to the bit. The Python deck reader and builder (`viv_frame_tf`) take the
section.

### Fixed

- The statics of a finite-EI line through the free surface could fail at isolated currents:
Expand Down
4 changes: 3 additions & 1 deletion doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,9 @@ Line and constitutive capability
* - 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,
on ``EI = 0`` lines and along finite-EI cables in place of the synchronisation model
on ``EI = 0`` lines and along finite-EI cables in place of the synchronisation model; a
``VIV FRAME`` row (``Tf``) takes its frequency from the flow relative to the cable's
filtered motion (a towed or floater-driven cable)
(:ref:`theory-viv-wake`), its state in the checkpoint
* - Amplitude-dependent VIV coefficients (``VIV AMPLITUDE`` section ``AD``, ``Cv``, ``CdAmp``)
- Standalone and coupled
Expand Down
37 changes: 36 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ 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 / WAKE OSCILLATOR /
VIV AMPLITUDE / VIV DIAMETER / VIV DAMPING / FAILURE / CONTROL → OPTIONS → OUTPUTS
VIV AMPLITUDE / VIV DIAMETER / VIV DAMPING / VIV FRAME / 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 @@ -215,6 +215,7 @@ are collapsed. It must match one of the spellings below; any other name fails wi
| VIV AMPLITUDE | `VIV AMPLITUDE`, `VIV AMPLITUDES` |
| VIV DIAMETER | `VIV DIAMETER`, `VIV DIAMETERS` |
| VIV DAMPING | `VIV DAMPING` |
| VIV FRAME | `VIV FRAME`, `VIV FRAMES` |
| FAILURE | `FAILURE`, `FAILURES` |
| CONTROL | `CONTROL`, `CONTROLS` |
| TURBINES | `TURBINES`, `TURBINE` |
Expand Down Expand Up @@ -1355,6 +1356,40 @@ 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 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)).

```text
--------------------- VIV FRAME ----------------------------------------
TypeName Tf
(-) (s)
cable 10
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) with 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 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.

### 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
Expand Down
21 changes: 19 additions & 2 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1289,7 +1289,23 @@ mass):
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
the synchronisation model. The ambient flow sets no frequency for a cable moved through still
water, which then never sheds; a ``VIV FRAME`` row with the filter time :math:`T_f > 0` takes
:math:`U_a` relative to the node's velocity low-pass filtered over :math:`T_f`,

.. math::

U_a = \bigl|(\mathbf u - \bar{\mathbf v})_n\bigr|,\qquad
\bar{\mathbf v}_{n+1} = \bar{\mathbf v}_n + \bigl(1 - e^{-\delta t/T_f}\bigr)
(\mathbf v_{n+1} - \bar{\mathbf v}_n),

the exact first-order filter of the converged end velocity held over the step, started at the
node's initial velocity. The slow motion (a tow, a floater's response) then counts as flow, and the
VIV velocity, far faster than :math:`T_f`, is filtered out. On a cable towed at 0.15 m/s through
still water (the taut cable of the deck gate, VIV at 0.28 Hz) :math:`T_f` 10 s gives the lock-in of
the cable held in a 0.15 m/s current to 0.6 % in A/D and 0.001 Hz, where the ambient flow gave no
lock-in; on the held cable it changes A/D by 0.03 %. :math:`\bar{\mathbf v}` is part of the wake
state. 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::
Expand Down Expand Up @@ -1318,7 +1334,8 @@ its exact position and velocity derivatives in the tangent at fixed :math:`q`. O
line it acts at the free nodes as the synchronisation lift does, over the node's tributary length,
with the node's smoothed cross-flow acceleration (the average with its two neighbours) as the
forcing, and :math:`(q, \dot q)` takes the place of the phase and the first motion statistic in
the line's VIV state. :math:`q` starts on
the line's VIV state (with :math:`T_f`, :math:`\bar{\mathbf v}` the next three statistics, and three
more state rows on a finite-EI cable). :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.

Expand Down
26 changes: 26 additions & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,12 @@ class LineType:
synchronisation lift, so ``cl`` stays ``None`` or 0, and acts on
``EI = 0`` lines and 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_frame_tf : float | None
Optional flow frame of a type's VIV model, a ``VIV FRAME`` section row
``Name Tf``: the filter time [s] of the cable velocity the model's free
stream is taken relative to (0: the ambient flow; set it for a cable
moved through the water by a tow or its floater). It sets the wake
oscillator's frequency, so it needs ``wake_cl0``. ``None`` writes no row.
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
Expand Down Expand Up @@ -275,6 +281,7 @@ class LineType:
wake_a: float | None = None
viv_amplitude: list[tuple[float, ...]] | None = None
viv_diameter: float | None = None
viv_frame_tf: float | None = None
viv_damping: tuple[float, ...] | None = None


Expand Down Expand Up @@ -1701,6 +1708,7 @@ def add_line_type(
wake_a: float | None = None,
viv_amplitude: list[tuple[float, ...]] | None = None,
viv_diameter: float | None = None,
viv_frame_tf: 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 @@ -1744,6 +1752,7 @@ def add_line_type(
wake_a,
None if viv_amplitude is None else [tuple(row) for row in viv_amplitude],
viv_diameter,
viv_frame_tf,
None if viv_damping is None else tuple(viv_damping),
)
self._line_types.append(item)
Expand Down Expand Up @@ -2639,6 +2648,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 FRAME", *self._viv_frame_table())
_emit(out, "VIV DAMPING", *self._viv_damp_table())
_emit(out, "FAILURE", *self._failure_table())
_emit(out, "CONTROL", *self._control_table())
Expand Down Expand Up @@ -3086,6 +3096,19 @@ def _viv_diam_table(self) -> tuple[str, str, list[list[str]]]:
rows.append([_text(item.name, what), _num(item.viv_diameter, what)])
return "Name Dviv", "(-) (m)", rows

def _viv_frame_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
if item.viv_frame_tf is None:
continue
what = f"line type {item.name!r}"
if item.wake_cl0 is None:
raise ValueError(
f"{what}: viv_frame_tf sets the frame of its wake oscillator, set wake_cl0"
)
rows.append([_text(item.name, what), _num(item.viv_frame_tf, what)])
return "Name Tf", "(-) (s)", 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 @@ -3309,6 +3332,9 @@ def load(self) -> None:
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("VIV FRAME"):
t = row.tokens
model.line_types[t[0]].viv_frame_tf = _f(t[1])
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
42 changes: 42 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@
"VIV DIAMETER": "VIV DIAMETER",
"VIV DIAMETERS": "VIV DIAMETER",
"VIV DAMPING": "VIV DAMPING",
"VIV FRAME": "VIV FRAME",
"VIV FRAMES": "VIV FRAME",
}
# 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 @@ -120,6 +122,7 @@
"VIV AMPLITUDE",
"VIV DIAMETER",
"VIV DAMPING",
"VIV FRAME",
}
)
_TABLE_SECTIONS = _LIST_DIRECTED_SECTIONS | _WHITESPACE_TABLE_SECTIONS
Expand Down Expand Up @@ -3384,6 +3387,44 @@ 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_frame_section(self, wake_type_names: set[str]) -> None:
"""Native ``apply_type_viv_frame`` for the VIV FRAME section.

A row ``TypeName Tf`` sets the flow frame of a line type's VIV model: with the filter
time ``Tf > 0`` [s] the free stream is the ambient flow relative to the cable's velocity
low-pass filtered over ``Tf`` (0: the ambient flow), at most 1e15. It sets the wake
oscillator's frequency, so the type needs 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 FRAME"):
where = self._at(row)
if len(row.tokens) != 2:
raise DeckFormatError(f"{where}: VIV FRAME rows must be: TypeName Tf")
name = row.tokens[0].lower()
if name not in types:
raise DeckFormatError(
f'{where}: VIV FRAME row names undefined LINE TYPE "{row.tokens[0]}"'
)
if name in named:
raise DeckFormatError(f'{where}: VIV FRAME 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 FRAME Tf must be a plain number") from exc
if not (math.isfinite(value) and 0.0 <= value <= _NATIVE_MAX_COEFFICIENT):
raise DeckFormatError(
f"{where}: VIV FRAME filter time Tf must be >= 0 (0 = the ambient flow), "
"at most 1e15"
)
if name not in wake_type_names:
raise DeckFormatError(
f'{where}: VIV FRAME of LINE TYPE "{types[name]}" sets the flow frame of its '
"wake oscillator: give the type 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.

Expand Down Expand Up @@ -4783,6 +4824,7 @@ 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)
self._check_viv_frame_section(wake_type_names)
damp_type_names = self._check_viv_damp_section(amp_type_names)
amp_lines = {
line_id
Expand Down
20 changes: 20 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,26 @@ def test_viv_amplitude_rows_are_written_with_the_values_given(tmp_path: Path) ->
model.to_text(validate=False)


def test_viv_frame_rows_are_written(tmp_path: Path) -> None:
model = _chain_model(tmp_path)
model.add_line_type(
"towed",
diam=0.1,
mass=10.0,
ea=5.0e7,
ei=1.0,
cdn=1.2,
can=1.0,
wake_cl0=0.3,
viv_frame_tf=8.0,
)
deck = DeckFile.from_text(model.to_text(validate=False), path=tmp_path / "deck.dat")
assert [row.tokens for row in deck._rows("VIV FRAME")] == [("towed", "8.0")]
model.add_line_type("plain", diam=0.1, mass=10.0, ea=5.0e7, viv_frame_tf=8.0)
with pytest.raises(ValueError, match="set wake_cl0"):
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(
Expand Down
34 changes: 34 additions & 0 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -4991,6 +4991,40 @@ def test_viv_diameter_takes_a_wake_oscillator_type():
DeckFile.from_text(_with_section(text, "VIV DIAMETER", "chain 0.9"))


def test_viv_frame_rows_are_read_and_kept(tmp_path):
from cabledyn import DeckModel

text = _with_section(
_with_section(_DYNAMIC, "WAKE OSCILLATOR", "chain 0.3"),
"VIV FRAME",
"TypeName Tf",
"chain 8",
)
DeckFile.from_text(text)
path = tmp_path / "frame.dat"
path.write_text(text, encoding="utf-8")
assert DeckModel.load(path).line_types["chain"].viv_frame_tf == 8.0
saved = tmp_path / "saved.dat"
DeckModel.load(path).save(saved)
assert DeckModel.load(saved).line_types["chain"].viv_frame_tf == 8.0


@pytest.mark.parametrize(
"wake, rows, message",
[
(True, ("chain 8 1",), "rows must be: TypeName Tf"),
(True, ("cable 8",), 'undefined LINE TYPE "cable"'),
(True, ("chain 8", "chain 4"), 'names LINE TYPE "chain" twice'),
(True, ("chain -1",), "filter time Tf must be >= 0"),
(False, ("chain 8",), "give the type a WAKE OSCILLATOR row"),
],
)
def test_viv_frame_rows_follow_the_native_checks(wake, rows, message):
text = _with_section(_DYNAMIC, "WAKE OSCILLATOR", "chain 0.3") if wake else _DYNAMIC
with pytest.raises(DeckFormatError, match=re.escape(message)):
DeckFile.from_text(_with_section(text, "VIV FRAME", *rows))


_DAMP_BASE = _with_section(
_edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8")),
"VIV AMPLITUDE",
Expand Down
22 changes: 22 additions & 0 deletions python/tests/test_end_to_end.py
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,28 @@ def _dia_rows(*rows: str) -> tuple[str, str]:
_AMP_PARITY += _DIA_PARITY


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


_WAKE_RISER = ("riser 0.85 0.15", "riser 0.3")
_FRAME_PARITY = [
("frame-accepted", [_WAKE_LIFT, _WAKE_SECTION, _WAKE_RISER, _frame_rows("riser 8")], True),
("frame-zero", [_WAKE_LIFT, _WAKE_SECTION, _WAKE_RISER, _frame_rows("riser 0")], True),
("frame-negative", [_WAKE_LIFT, _WAKE_SECTION, _WAKE_RISER, _frame_rows("riser -1")], False),
(
"frame-three-columns",
[_WAKE_LIFT, _WAKE_SECTION, _WAKE_RISER, _frame_rows("riser 8 1")],
False,
),
("frame-sync-type", [_frame_rows("riser 8")], False),
]

_AMP_PARITY += _FRAME_PARITY


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