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 @@ -10,6 +10,16 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Added

- Stochastic VIV band centre: an optional `VIV STOCHASTIC` section, rows `TypeName sigma c
[Nf [seed]]`, makes the centre `cF` of a line type's synchronisation band the slowly varying
random process of Ulveseter et al. (2017): `Nf` (default 100) sinusoids of a flat spectrum up to
`c` times `cF` with standard deviation `sigma`, each advancing at its non-dimensional frequency
times `U/D` as the shedding phase does, from start phases the seed fixes per node and line (the
nodes independent). On `EI = 0` lines and finite-EI cables, standalone and coupled, with or
without in-line VIV. The node's travelled distance `integral U/D dt` is the one new state (step
recovery, snapshots, checkpoints); a run repeats its realisation, `sigma` 0 leaves runs unchanged
to the bit. With the article's NDP values the process has the mean `cF` to 2e-6 and the standard
deviation `sigma` to four digits.
- Rayleigh damping of finite-EI cables: the LINE TYPES EI column takes `EI|-zeta|f1|f2`, the
damping ratio `zeta` at the two frequencies `f1` and `f2` [Hz]. Beside the bending damping
`Bb = zeta EI/(pi (f1 + f2))` it adds a mass-proportional transverse damping
Expand Down
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1379,6 +1379,13 @@ add_executable(test_viv_frame_deck tests/test_viv_frame_deck.f90)
target_link_libraries(test_viv_frame_deck PRIVATE cabledyn_core)
add_test(NAME viv_frame_deck COMMAND test_viv_frame_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_frame_deck PROPERTIES LABELS "fortran;integration;dynamic;viv;driver")
# The VIV STOCHASTIC section (the stochastic band centre of Ulveseter et al. 2017): the process's
# mean, standard deviation, near-Gaussian shape and seeded phases; a sigma 0 row bit-identical to
# none, a seeded run repeatable and locked in, on both cores; and the refusals.
add_executable(test_viv_stochastic tests/test_viv_stochastic.f90)
target_link_libraries(test_viv_stochastic PRIVATE cabledyn_core)
add_test(NAME viv_stochastic COMMAND test_viv_stochastic WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_stochastic 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
Expand Down
5 changes: 5 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,11 @@ Line and constitutive capability
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`)
* - 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``
lines and finite-EI cables wherever the cross-flow lift runs, seeded and repeatable
(:ref:`theory-viv-stochastic`), its state in the checkpoint
* - In-line VIV (``VIV`` section ``ClX``, ``alpha``)
- Standalone and coupled
- the in-line shedding force of Ulveseter et al. (2018) at twice the cross-flow frequency, and
Expand Down
43 changes: 42 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,8 @@ 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 / VIV FRAME / FAILURE / CONTROL → OPTIONS → OUTPUTS
VIV AMPLITUDE / VIV DIAMETER / VIV DAMPING / VIV FRAME / VIV STOCHASTIC / 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 @@ -216,6 +217,7 @@ are collapsed. It must match one of the spellings below; any other name fails wi
| VIV DIAMETER | `VIV DIAMETER`, `VIV DIAMETERS` |
| VIV DAMPING | `VIV DAMPING` |
| VIV FRAME | `VIV FRAME`, `VIV FRAMES` |
| VIV STOCHASTIC | `VIV STOCHASTIC` |
| FAILURE | `FAILURE`, `FAILURES` |
| CONTROL | `CONTROL`, `CONTROLS` |
| TURBINES | `TURBINES`, `TURBINE` |
Expand Down Expand Up @@ -1424,6 +1426,45 @@ Behaviour:
named type or one without VIV (neither LINE TYPES `Cl > 0` nor a WAKE OSCILLATOR row), or holds
a value out of range.

### VIV STOCHASTIC (optional)

The stochastic synchronisation of Ulveseter et al. (2017): the centre `cF` of a line type's
synchronisation band becomes a slowly varying random process, so the response can wander between
modes as in long risers in shear (see [Stochastic band centre](theory.rst)).

```text
--------------------- VIV STOCHASTIC -----------------------------------
TypeName sigma c Nf seed
riser 0.016 0.07 100 1
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive) with `Cl > 0` and no WAKE OSCILLATOR row, at most one row each |
| `sigma` | standard deviation of the band centre, 0 to 1e3 (0: the constant `cF`) |
| `c` | top of the centre's flat spectrum as a fraction of `cF`, 0 < `c` <= 1 |
| `Nf` | number of frequency components, an integer from 1 to 1000 (optional, default 100) |
| `seed` | seed of the components' start phases, an integer from 0 to 2147483646 (optional, default 0) |

Behaviour:

- At a lifting node the centre is `cF + sum_i a sin(p_i + 2 pi f_i theta)`, `theta` the
integral of `U/D` over time (`U` the shedding speed of the phase rate), with `Nf` components
at the mid-points `f_i = (i - 1/2) c cF/Nf` of a flat spectrum over `(0, c cF]` and amplitude
`a = sigma sqrt(2/Nf)`, so its standard deviation is `sigma`. Each component advances at its
non-dimensional frequency times `U/D`, as the shedding phase does, so the centre is slow
against the VIV for `c` well below 1 (Ulveseter et al. take `c` 0.07). The band half-width `dF`
stays constant.
- The start phases are uniform in `[0, 2 pi)`, drawn for each node from the seed, the node and
the line, so the nodes are independent (no spanwise correlation, as in the article), a run
repeats its realisation and two lines of one type differ. A different seed is another
realisation; report statistics over several.
- `theta` is part of the step-recovery, snapshot and checkpoint state (one value per node). A
row with `sigma = 0` leaves the run exactly as without it. It acts on `EI = 0` lines and
finite-EI cables, standalone and coupled, with or without in-line VIV.
- A row fails if it is not `TypeName sigma c [Nf [seed]]`, names an undefined or already named
type, one without `Cl > 0` or one with 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
6 changes: 6 additions & 0 deletions doc/references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ Hydrodynamics and ocean environment
cross-flow vortex-induced vibrations. *Marine Structures* **51**, 134–151.
https://doi.org/10.1016/j.marstruc.2016.10.007

.. _ref-ulveseter2017:

- **Ulveseter, J. V., Thorsen, M. J., Sævik, S. & Larsen, C. M. (2017).** Stochastic modelling of
cross-flow vortex-induced vibrations. *Marine Structures* **56**, 260–280.
https://doi.org/10.1016/j.marstruc.2017.08.001

.. _ref-ulveseter2018:

- **Ulveseter, J. V., Thorsen, M. J., Sævik, S. & Larsen, C. M. (2018).** Time domain
Expand Down
41 changes: 41 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1682,6 +1682,47 @@ 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.

.. _theory-viv-stochastic:

Stochastic band centre
~~~~~~~~~~~~~~~~~~~~~~

The synchronisation band of :ref:`theory-viv` has a constant centre :math:`\hat f_0` (``cF``), so
a long cable in a steady current settles on one response. Measured high-mode responses wander in
amplitude and frequency. Ulveseter et al. (2017, Eq. 6) make the centre a slowly varying random
process; a ``VIV STOCHASTIC`` row gives a line type this centre:

.. math::

\hat F_0(t) = \hat f_0 + \sum_{i=1}^{N_f} a\,\sin\bigl(p_i + 2\pi \hat f_i\,\theta(t)\bigr),
\qquad \theta(t) = \int_0^t \frac{U}{D}\,\mathrm d t ,

with :math:`U` the shedding speed of the phase rate. The spectrum is flat over
:math:`(0, c\,\hat f_0]` (their Fig. 4); its :math:`N_f` components sit at the mid-points
:math:`\hat f_i = (i - 1/2)\,c\,\hat f_0/N_f` of equal intervals with the amplitude
:math:`a = \sigma\sqrt{2/N_f}`, so :math:`\hat F_0` has the mean :math:`\hat f_0` and the standard
deviation :math:`\sigma`, and for many components it is close to Gaussian. Each component advances
at its non-dimensional frequency times :math:`U/D`, as the shedding phase does, which keeps the
process free of the fluctuation of :math:`U` that a time-based phase would carry (their Fig. 5);
for :math:`c \ll 1` it is slow against the VIV, so the response has time to build up before the band
moves. The half-width :math:`\Delta\hat f` (``dF``) stays constant. The start phases
:math:`p_i` are uniform on :math:`[0, 2\pi)` and independent between nodes, as in the article (no
spanwise correlation). Ulveseter et al. take :math:`N_f` 100, :math:`c` 0.07 and :math:`\sigma`
0.016 for the NDP riser, and 0.040 as an upper case.

**Implementation.** Each lifting node carries :math:`\theta` as one more row of its motion
statistics. The step advances it by :math:`\Delta t\,U/D` with :math:`U` at the step's mid-point,
and the phase rate takes :math:`\hat F_0` at :math:`\theta + \Delta t\,U/(2D)`, so the centre follows
the mid-point rule of the phase (:ref:`theory-viv`). The phases :math:`p_i` come from a
minimal-standard generator seeded by the row's seed, the line and the node, so a run repeats its
realisation and needs no stored phases: :math:`\theta` alone is part of the step-recovery,
snapshot and checkpoint state. The process over :math:`\theta` = 0 to :math:`4\times 10^6` (about
200 periods of the lowest component) with the NDP values has the mean :math:`\hat f_0` to
:math:`2\times 10^{-6}`, the standard deviation :math:`\sigma` to four digits and an excess kurtosis of
-0.18. A row with :math:`\sigma` = 0 leaves the run unchanged to the bit; with :math:`\sigma` 0.02 the
taut cable of the flow-frame gates stays locked in (A/D within 1 % of the constant centre's over
50-80 s on both line kinds). A seed is one realisation: statistics of a response need several.

.. _theory-viv-coefficients:

Published coefficient sets
Expand Down
34 changes: 34 additions & 0 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,14 @@ 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_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
``(sigma, c)``, ``(sigma, c, Nf)`` or ``(sigma, c, Nf, seed)``
(Ulveseter et al. 2017): the standard deviation of the centre, the top
of its flat spectrum as a fraction of ``cF``, the number of components
(default 100) and the seed of their start phases (default 0). It needs
``cl > 0`` and no ``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 @@ -288,6 +296,7 @@ class LineType:
viv_diameter: float | None = None
viv_frame_tf: float | None = None
viv_damping: tuple[float, ...] | None = None
viv_stochastic: tuple[float, ...] | None = None


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

Expand Down Expand Up @@ -1759,6 +1769,7 @@ def add_line_type(
viv_diameter,
viv_frame_tf,
None if viv_damping is None else tuple(viv_damping),
None if viv_stochastic is None else tuple(viv_stochastic),
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2654,6 +2665,7 @@ def to_text(self, *, validate: bool = True) -> str:
_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 STOCHASTIC", *self._viv_sto_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 @@ -3116,6 +3128,25 @@ def _viv_frame_table(self) -> tuple[str, str, list[list[str]]]:
rows.append([_text(item.name, what), _num(item.viv_frame_tf, what)])
return "Name Tf", "(-) (s)", rows

def _viv_sto_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
for item in self._line_types:
if item.viv_stochastic is None:
continue
what = f"line type {item.name!r}"
if item.wake_cl0 is not None or not (item.cl is not None and item.cl > 0.0):
raise ValueError(
f"{what}: viv_stochastic varies the band centre of its synchronisation "
"model, set cl > 0 and no wake_cl0"
)
if not 2 <= len(item.viv_stochastic) <= 4:
raise ValueError(f"{what}: viv_stochastic is (sigma, c[, Nf[, seed]])")
rows.append([_text(item.name, what)] + [_num(v, what) for v in item.viv_stochastic])
width = max((len(r) for r in rows), default=3)
names = ["Name", "sigma", "c", "Nf", "seed"][:width]
units = ["(-)", "(-)", "(-)", "(-)", "(-)"][:width]
return " ".join(names), " ".join(units), 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 @@ -3342,6 +3373,9 @@ 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])
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:])
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
61 changes: 61 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@
"VIV DAMPING": "VIV DAMPING",
"VIV FRAME": "VIV FRAME",
"VIV FRAMES": "VIV FRAME",
"VIV STOCHASTIC": "VIV STOCHASTIC",
}
# 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 @@ -123,6 +124,7 @@
"VIV DIAMETER",
"VIV DAMPING",
"VIV FRAME",
"VIV STOCHASTIC",
}
)
_TABLE_SECTIONS = _LIST_DIRECTED_SECTIONS | _WHITESPACE_TABLE_SECTIONS
Expand Down Expand Up @@ -3426,6 +3428,64 @@ def _check_viv_frame_section(self, frame_type_names: set[str]) -> None:
"VIV model: give the type LINE TYPES Cl > 0 or a WAKE OSCILLATOR row"
)

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.

A row ``TypeName sigma c [Nf [seed]]`` makes the band centre of a line type's
synchronisation model a slowly varying random process (Ulveseter et al. 2017): standard
deviation ``0 <= sigma <= 1e3``, the top ``0 < c <= 1`` of its flat spectrum as a fraction
of ``cF``, ``Nf`` components (an integer from 1 to 1000, default 100) and the seed of their
start phases (an integer from 0 to 2147483646, default 0). The type needs LINE TYPES
``Cl > 0`` (``viv_type_names``) and no WAKE OSCILLATOR row; 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 STOCHASTIC"):
where = self._at(row)
if not 3 <= len(row.tokens) <= 5:
raise DeckFormatError(
f"{where}: VIV STOCHASTIC rows must be: TypeName sigma c [Nf [seed]]"
)
name = row.tokens[0].lower()
if name not in types:
raise DeckFormatError(
f'{where}: VIV STOCHASTIC row names undefined LINE TYPE "{row.tokens[0]}"'
)
if name in named:
raise DeckFormatError(
f'{where}: VIV STOCHASTIC names LINE TYPE "{types[name]}" twice'
)
named.add(name)
values = [0.0, 0.0, 100.0, 0.0]
for k, token in enumerate(row.tokens[1:]):
try:
values[k] = _native_float(token)
except ValueError as exc:
raise DeckFormatError(
f"{where}: VIV STOCHASTIC sigma, c, Nf and seed must be plain numbers"
) from exc
sigma, c, nf, seed = values
if not (
all(math.isfinite(v) for v in values) and 0.0 <= sigma <= 1.0e3 and 0.0 < c <= 1.0
):
raise DeckFormatError(
f"{where}: VIV STOCHASTIC needs 0 <= sigma <= 1e3 and 0 < c <= 1"
)
if not (1.0 <= nf <= 1000.0 and nf == int(nf)):
raise DeckFormatError(
f"{where}: VIV STOCHASTIC Nf must be an integer from 1 to 1000"
)
if not (0.0 <= seed <= 2147483646.0 and seed == int(seed)):
raise DeckFormatError(
f"{where}: VIV STOCHASTIC seed must be an integer from 0 to 2147483646"
)
if name not in viv_type_names or name in wake_type_names:
raise DeckFormatError(
f'{where}: VIV STOCHASTIC of LINE TYPE "{types[name]}" varies the band '
"centre of its synchronisation model: give the type LINE TYPES Cl > 0 and "
"no 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 @@ -4842,6 +4902,7 @@ def end_key(token: str) -> str:
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_sto_section(viv_type_names, wake_type_names)
damp_type_names = self._check_viv_damp_section(amp_type_names)
amp_lines = {
line_id
Expand Down
14 changes: 14 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,20 @@ def test_viv_frame_rows_are_written(tmp_path: Path) -> None:
model.to_text(validate=False)


def test_viv_stochastic_rows_are_written(tmp_path: Path) -> None:
model = _chain_model(tmp_path)
model.add_line_type(
"riser", diam=0.1, mass=10.0, ea=5.0e7, cl=0.8, viv_stochastic=(0.016, 0.07, 100, 3)
)
deck = DeckFile.from_text(model.to_text(validate=False), path=tmp_path / "deck.dat")
assert [row.tokens for row in deck._rows("VIV STOCHASTIC")] == [
("riser", "0.016", "0.07", "100.0", "3.0")
]
model.add_line_type("plain", diam=0.1, mass=10.0, ea=5.0e7, viv_stochastic=(0.016, 0.07))
with pytest.raises(ValueError, match="set cl > 0 and no 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
Loading
Loading