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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Added

- `VIV FRAME` method `cycle`: an optional third column, rows `TypeName Tf [Method]`, `filter` (the
default) or `cycle`. With `cycle` the frame velocity of a synchronisation type is the mean of the
node velocity over the window `Tf` plus half its change over it, which drops a component of
period `Tf` and its harmonics (the cross-flow VIV and the in-line VIV at twice its frequency) and
passes the slow motion of a towed or floater-driven cable without the first-order filter's lag;
`Tf` is then one period of the response. The filter's lag leaves the frame faster than the cable
on a decelerating motion and slower on an accelerating one; on the moving pipe of the frame gate
the cycle mean follows the imposed velocity within 0.17 % of its amplitude, the filter within
1.7 %. A ring of 66 samples per node is the new state (step recovery, snapshots, checkpoints; an
invalid restored state fails closed). `EI = 0` lines and finite-EI cables, standalone and
coupled; one method per line; rows without the column are unchanged to the bit.

- `OPTIONS CDOutDt` (alias `cd_out_dt`): the interval of the coupled `.CD.out` rows (OpenFAST and
FAST.Farm), a whole multiple of the CableDyn step; `0`, the default, keeps a row after every
committed step. A row re-evaluates and writes every deck channel, so on a cable with many
Expand Down
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1324,6 +1324,13 @@ target_link_libraries(test_viv_kernels PRIVATE cabledyn_core)
add_test(NAME viv_kernels COMMAND test_viv_kernels)
set_tests_properties(viv_kernels PROPERTIES LABELS "fortran;unit;dynamic;viv")

# The cycle-mean flow frame kernel (VIV FRAME method cycle): a component of period T and its second
# harmonic drop out, a ramp passes without lag, a quadratic gives the second-order error.
add_executable(test_viv_cycle_frame tests/test_viv_cycle_frame.f90)
target_link_libraries(test_viv_cycle_frame PRIVATE cabledyn_core)
add_test(NAME viv_cycle_frame COMMAND test_viv_cycle_frame)
set_tests_properties(viv_cycle_frame PROPERTIES LABELS "fortran;unit;dynamic;viv")

# Time-step convergence of a locked-in VIV response (the line and the synchronisation model or the
# wake oscillator coupled): second order in the step at rho_inf 1 and 0.4 on an EI = 0 line, and
# on a finite-EI cable; the lock-in does not move with the numerical damping.
Expand Down
3 changes: 2 additions & 1 deletion doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,8 @@ Line and constitutive capability
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`)
:ref:`theory-viv-frame`), by a first-order filter or (method ``cycle``) the lag-free mean
over one response period
* - Stochastic VIV band centre (``VIV STOCHASTIC`` section ``sigma``, ``c``, ``Nf``, ``seed``)
- Standalone and coupled
- the slowly varying random synchronisation centre of Ulveseter et al. (2017) on ``EI = 0``
Expand Down
26 changes: 19 additions & 7 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1382,15 +1382,16 @@ filter time `Tf` the frame moves with the cable's own slow motion (see

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

| Column | Meaning |
|--------|---------|
| `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 |
| `Tf` | filter time >= 0 [s], at most 1e15; `0` is the ambient flow; with `Method cycle` the window, one period of the VIV response |
| `Method` | optional: `filter` (the default) or `cycle` (synchronisation model only, `Tf > 0`) |

Behaviour:

Expand Down Expand Up @@ -1420,11 +1421,22 @@ Behaviour:
in the relative velocity (`omega_m Tf <= 0.1`) needs a motion period at least 30 VIV periods
long. For a motion only a few VIV periods long (a floater heave close to the VIV frequency) no
`Tf` separates the two, and the response depends on `Tf`: report its sensitivity to `Tf`.
- `Method cycle` takes the frame velocity as the mean over the window `Tf` plus half its change
over it, `(1/Tf) int_{t-Tf}^{t} v dt' + (v(t) - v(t-Tf))/2`: a component of period `Tf` and its
harmonics (the cross-flow VIV and the in-line VIV at twice its frequency) drop out, and the
slow motion passes without the filter's lag, so a decelerating motion does not leave the frame
faster than the cable. Give `Tf` as one period of the response (`1/f`): off the period the VIV
velocity passes into the frame by about `|sin(pi delta)|` for `f Tf = 1 + delta` (a taut cable
responding at 0.29 Hz locks in at A/D 0.79 with `Tf` 3.5 s and at 0.55 with `Tf` 1 s), so it
suits a response at one known frequency. A line takes one method; its ring of 66 samples per node
is part of the step-recovery, snapshot and checkpoint state (see
[Flow frame of the synchronisation model](theory.rst)).
- 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 VIV (neither LINE TYPES `Cl > 0` nor a WAKE OSCILLATOR row), or holds
a value out of range.
standalone and coupled. A row fails if it is not `TypeName Tf [Method]`, names an undefined or
already named type or one without VIV (neither LINE TYPES `Cl > 0` nor a WAKE OSCILLATOR row),
holds a value out of range or a `Method` other than `filter` and `cycle`, or takes `cycle` on a
type without `Cl > 0` or with `Tf = 0`; a line whose types mix the two methods fails.

### VIV STOCHASTIC (optional)

Expand Down
37 changes: 37 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1682,6 +1682,43 @@ estimate, stay 0 without a table), so it is part of the step-recovery, snapshot
state; an ``EI = 0`` line filters its smoothed node velocity. :math:`T_f` 0 or no row leaves the
run unchanged to the bit.

**Cycle mean** (``VIV FRAME`` method ``cycle``). The first-order filter lags a motion at
:math:`\omega_m` by :math:`\arctan\omega_m T_f`, so on a decelerating motion the frame keeps more
of the earlier, faster velocity than the cable has, and on an accelerating one less, so the frame
speed differs between the two half-cycles at the same flow speed. With the method ``cycle`` the frame velocity is instead the mean over the
window :math:`T = T_f` plus half the change over it,

.. math::

\bar{\mathbf v}(t) = \frac{1}{T}\int_{t-T}^{t}\mathbf v\,dt'
+ \tfrac12\left[\mathbf v(t) - \mathbf v(t - T)\right].

A component of period :math:`T` and its harmonics drop out of both terms (the cross-flow VIV at
:math:`f = 1/T` and the in-line one at :math:`2f`), and a velocity linear in time passes unchanged,
without lag; a velocity quadratic in time is off by :math:`T^2/12` times its second derivative.
The integral :math:`I = \int\mathbf v\,dt` is sampled every :math:`h = T/64`, exactly for the
velocity linear over a step, in a ring of 66 samples per node held relative to :math:`I` at the
committed time, and :math:`I(t - T)` and :math:`\mathbf v(t - T) = I'(t - T)` come from the
quadratic through the three samples around :math:`t - T`; the sampled harmonics at :math:`f` and
:math:`2f` leave 0.25 % of their amplitude (``viv_cycle_frame``). On the pipe moved through still
water above (``Tf`` 0.6 s against the window 1 s) the frame velocity is off the imposed velocity
by 0.17 % of its amplitude over 5-15 s, against 1.7 % for the filter (``hermite_viv_frame``). The
window must be one period of the response, :math:`T = 1/f`: off the period the VIV velocity
passes into :math:`\bar{\mathbf v}` by about :math:`|\sin(\pi\,\delta)|` for a mismatch
:math:`fT = 1 + \delta`, and the phases and the amplitude estimate lose it (the taut cable of the
deck gate, its response at 0.29 Hz, locks in at A/D 0.79 with :math:`T` 3.5 s and at 0.55 with
:math:`T` 1 s). It therefore suits a response at one known frequency; a response that moves
between modes needs the filter. The method acts on the synchronisation model (not the wake
oscillator), one method per line. The sample time, the ring slot and the ring are
:math:`2 + 3 \times 66` rows of the node's motion statistics after rows 7-9, so they are part of
the step-recovery, snapshot and checkpoint state, and a restart that installs a sample time off
:math:`[0, 1]` or a slot off the ring fails closed. On the L3-O cylinder with the published sets,
the window :math:`T = 1/f_1` = 0.373 s against the filter of the record (:math:`T_f` 0.2 s), the
mean gap between the decelerating and accelerating paths becomes 0.413 / 0.599 for uls19 at
:math:`U_{R,max}` 6.5 / 7.9 (0.426 / 0.498 with the filter; measured 0.089 / 0.123) and
0.320 / 0.267 for b1 (0.364 / 0.380): the method removes the filter's lag from the frame, not the
deceleration hold of these sets.

.. _theory-viv-stochastic:

Stochastic band centre
Expand Down
28 changes: 27 additions & 1 deletion python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,11 @@ class LineType:
the phases, the amplitude estimate (and so the ``viv_amplitude``
coefficients) and the ``viv_damping`` split, so it needs ``cl > 0`` or
``wake_cl0``. ``None`` writes no row.
viv_frame_method : str | None
Optional method of the ``VIV FRAME`` row, its third column: ``"filter"`` (the
first-order filter, as without the column) or ``"cycle"`` (the lag-free mean over the
window ``viv_frame_tf``, one period of the response; synchronisation model only,
``viv_frame_tf > 0``). ``None`` writes the two-column row.
viv_stochastic : tuple[float, ...] | None
Optional stochastic band centre of a type's synchronisation model, a
``VIV STOCHASTIC`` section row ``Name sigma c [Nf [seed]]`` as
Expand Down Expand Up @@ -297,6 +302,7 @@ class LineType:
viv_frame_tf: float | None = None
viv_damping: tuple[float, ...] | None = None
viv_stochastic: tuple[float, ...] | None = None
viv_frame_method: str | None = None


@dataclass(eq=False)
Expand Down Expand Up @@ -1725,6 +1731,7 @@ def add_line_type(
viv_frame_tf: float | None = None,
viv_damping: tuple[float, ...] | None = None,
viv_stochastic: tuple[float, ...] | None = None,
viv_frame_method: str | None = None,
) -> LineType:
"""Add a ``LINE TYPES`` row; see :class:`LineType` for the fields.

Expand Down Expand Up @@ -1770,6 +1777,7 @@ def add_line_type(
viv_frame_tf,
None if viv_damping is None else tuple(viv_damping),
None if viv_stochastic is None else tuple(viv_stochastic),
viv_frame_method,
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -3117,15 +3125,31 @@ def _viv_diam_table(self) -> tuple[str, str, list[list[str]]]:

def _viv_frame_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
with_method = any(
item.viv_frame_tf is not None and item.viv_frame_method is not None
for item in self._line_types
)
for item in self._line_types:
if item.viv_frame_tf is None:
if item.viv_frame_method is not None:
raise ValueError(
f"line type {item.name!r}: viv_frame_method needs viv_frame_tf"
)
continue
what = f"line type {item.name!r}"
if item.wake_cl0 is None and not (item.cl is not None and item.cl > 0.0):
raise ValueError(
f"{what}: viv_frame_tf sets the frame of its VIV model, set cl > 0 or wake_cl0"
)
rows.append([_text(item.name, what), _num(item.viv_frame_tf, what)])
row = [_text(item.name, what), _num(item.viv_frame_tf, what)]
if with_method:
method = (item.viv_frame_method or "filter").lower()
if method not in ("filter", "cycle"):
raise ValueError(f"{what}: viv_frame_method must be 'filter' or 'cycle'")
row.append(method)
rows.append(row)
if with_method:
return "Name Tf Method", "(-) (s) (-)", rows
return "Name Tf", "(-) (s)", rows

def _viv_sto_table(self) -> tuple[str, str, list[list[str]]]:
Expand Down Expand Up @@ -3373,6 +3397,8 @@ def load(self) -> None:
for row in self.rows("VIV FRAME"):
t = row.tokens
model.line_types[t[0]].viv_frame_tf = _f(t[1])
if len(t) > 2:
model.line_types[t[0]].viv_frame_method = t[2].lower()
for row in self.rows("VIV STOCHASTIC"):
t = row.tokens
model.line_types[t[0]].viv_stochastic = tuple(_f(v) for v in t[1:])
Expand Down
55 changes: 45 additions & 10 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3393,22 +3393,40 @@ 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, frame_type_names: set[str]) -> None:
"""Native ``apply_type_viv_frame`` for the VIV FRAME section.
def _check_viv_frame_section(
self,
frame_type_names: set[str],
lift_type_names: set[str] | None = None,
section_types_by_line: dict[str, list[str]] | None = None,
) -> None:
"""Native ``apply_type_viv_frame`` and ``deck_line_frame_cycle`` for the VIV FRAME section.

A row ``TypeName Tf`` sets the flow frame of a line type's VIV model: with the filter
A row ``TypeName Tf [Method]`` sets the flow frame of a line type's VIV model: with the
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, or on the synchronisation model the motion of the phases, the
amplitude estimate and the VIV DAMPING split, so the type needs LINE TYPES ``Cl > 0`` or
a WAKE OSCILLATOR row with ``CL0 > 0`` (``frame_type_names``); a type takes one row.
low-pass filtered over ``Tf`` (``Method filter``, the default) or its lag-free mean over
the window ``Tf`` (``Method cycle``, synchronisation types only, ``Tf > 0``); 0 is the
ambient flow, at most 1e15. It sets the wake oscillator's frequency, or on the
synchronisation model the motion of the phases, the amplitude estimate and the VIV
DAMPING split, so the type needs LINE TYPES ``Cl > 0`` (``lift_type_names``) or a WAKE
OSCILLATOR row with ``CL0 > 0`` (``frame_type_names``); a type takes one row, and a line
whose framed lift types mix the two methods fails.
"""
types = {row.tokens[0].lower(): row.tokens[0] for row in self.line_types}
named: set[str] = set()
cycle_types: set[str] = set()
filter_types: 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")
if len(row.tokens) not in (2, 3):
raise DeckFormatError(f"{where}: VIV FRAME rows must be: TypeName Tf [Method]")
cyc = False
if len(row.tokens) == 3:
method = row.tokens[2].lower()
if method not in ("filter", "cycle"):
raise DeckFormatError(
f'{where}: VIV FRAME Method must be filter or cycle, got "{row.tokens[2]}"'
)
cyc = method == "cycle"
name = row.tokens[0].lower()
if name not in types:
raise DeckFormatError(
Expand All @@ -3431,6 +3449,21 @@ def _check_viv_frame_section(self, frame_type_names: set[str]) -> None:
f'{where}: VIV FRAME of LINE TYPE "{types[name]}" sets the flow frame of its '
"VIV model: give the type LINE TYPES Cl > 0 or a WAKE OSCILLATOR row"
)
lifting = lift_type_names is None or name in lift_type_names
if cyc and not (lifting and value > 0.0):
raise DeckFormatError(
f'{where}: VIV FRAME Method cycle of LINE TYPE "{types[name]}" acts on the '
"synchronisation model (LINE TYPES Cl > 0) with a window Tf > 0"
)
if lifting and value > 0.0:
(cycle_types if cyc else filter_types).add(name)
for line_id, section_types in (section_types_by_line or {}).items():
used = {t.lower() for t in section_types}
if used & cycle_types and used & filter_types:
raise DeckFormatError(
f"{self._label}: line {line_id}: its VIV FRAME rows mix the methods filter and "
"cycle; a line takes one method"
)

def _check_viv_sto_section(self, viv_type_names: set[str], wake_type_names: set[str]) -> None:
"""Native ``apply_type_viv_sto`` for the VIV STOCHASTIC section.
Expand Down Expand Up @@ -4905,7 +4938,9 @@ 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(viv_type_names | wake_type_names)
self._check_viv_frame_section(
viv_type_names | wake_type_names, viv_type_names, section_types_by_line
)
self._check_viv_sto_section(viv_type_names, wake_type_names)
damp_type_names = self._check_viv_damp_section(amp_type_names)
amp_lines = {
Expand Down
25 changes: 24 additions & 1 deletion python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -5012,7 +5012,9 @@ def test_viv_frame_rows_are_read_and_kept(tmp_path):
@pytest.mark.parametrize(
"wake, rows, message",
[
(True, ("chain 8 1",), "rows must be: TypeName Tf"),
(True, ("chain 8 cycle 1",), "rows must be: TypeName Tf [Method]"),
(True, ("chain 8 1",), 'Method must be filter or cycle, got "1"'),
(True, ("chain 8 cycle",), "acts on the synchronisation model"),
(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"),
Expand All @@ -5033,6 +5035,27 @@ def test_viv_frame_rows_follow_the_native_checks(wake, rows, message):
)


def test_viv_frame_method_cycle_is_read_kept_and_checked(tmp_path):
from cabledyn import DeckModel

lift_only = _edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8"))
text = _with_section(lift_only, "VIV FRAME", "TypeName Tf Method", "chain 0.4 cycle")
DeckFile.from_text(text)
path = tmp_path / "cycle.dat"
path.write_text(text, encoding="utf-8")
model = DeckModel.load(path)
assert model.line_types["chain"].viv_frame_tf == 0.4
assert model.line_types["chain"].viv_frame_method == "cycle"
saved = tmp_path / "saved.dat"
model.save(saved)
again = DeckModel.load(saved)
assert again.line_types["chain"].viv_frame_method == "cycle"
assert again.line_types["chain"].viv_frame_tf == 0.4
DeckFile.from_text(_with_section(lift_only, "VIV FRAME", "chain 8 filter"))
with pytest.raises(DeckFormatError, match=re.escape("with a window Tf > 0")):
DeckFile.from_text(_with_section(lift_only, "VIV FRAME", "chain 0 cycle"))


def test_viv_frame_takes_a_synchronisation_type():
# the phases of the lift alone, and with a table its estimate and damping split, take it
lift_only = _edit(_DYNAMIC, (_LIFT_ROW, _LIFT_ROW + " 0.8"))
Expand Down
Loading
Loading