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

### Added

- Cross-flow vortex-induced vibration of `EI = 0` lines in the standalone driver: MoorDyn v2's
LINE TYPES columns `Cl` or `Cl dF cF` switch on the synchronisation model of Thorsen et al.,
with the same phase start and running-RMS window (`VIVrmsWindow`, default 500 steps of
`dtM`). On a taut 100 m line in a uniform current it follows MoorDyn-F's lock-in amplitude
and frequency to two to three digits through mode-1 and mode-3 lock-in, at any `dtM` from
5e-4 to 1e-2 s. The Python deck tools read and keep the columns. The coupled and mixed
routes refuse `Cl > 0` by name.
- Bend stiffeners (`STIFFENERS` table): a tapered polyurethane sleeve over an end of a finite-EI
line, given as conical segments from the root outward (outer diameters, bore, modulus,
density). Each element it covers takes the compliance average of the cable-plus-sleeve
Expand Down
21 changes: 21 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,7 @@ add_library(cabledyn_obj OBJECT
src/CableDyn_Damping.f90
src/CableDyn_Viscoelastic.f90
src/CableDyn_Syrope.f90
src/CableDyn_VIV.f90
src/CableDyn_Dynamic.f90
src/CableDyn_Model.f90
src/CableDyn_Modal.f90
Expand Down Expand Up @@ -1169,6 +1170,11 @@ add_test(NAME flagship_compression_note
COMMAND test_flagship_compression_note ${CMAKE_SOURCE_DIR}/examples/iea15mw_umaine_mixed_cabledyn.dat)
set_tests_properties(flagship_compression_note PROPERTIES LABELS "fortran;integration;static;contact")

add_executable(test_viv_kernels tests/test_viv_kernels.f90)
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")

add_executable(test_hfmf_mirror tests/test_hfmf_mirror.f90)
target_link_libraries(test_hfmf_mirror PRIVATE cabledyn_core)
add_test(NAME hfmf_mirror COMMAND test_hfmf_mirror WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
Expand Down Expand Up @@ -1614,6 +1620,21 @@ if(Python3_Interpreter_FOUND)
message(STATUS "anchor_uplift_channels: skipped (numpy not importable in ${Python3_EXECUTABLE})")
endif()

# Cross-flow VIV lock-in of a taut line against MoorDyn-F, at a coarse and a zig-zag-resolving
# dtM (needs numpy).
if(_range_tdp_numpy_rc EQUAL 0)
add_test(NAME viv_lockin
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_viv_lockin.py
--exe $<TARGET_FILE:cabledyn>
--output ${CMAKE_BINARY_DIR}/viv_lockin)
set_tests_properties(viv_lockin PROPERTIES
LABELS "python;integration;dynamic;viv;validation"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")
else()
message(STATUS "viv_lockin: skipped (numpy not importable in ${Python3_EXECUTABLE})")
endif()

# Node channels on a refined finite-EI line name deck nodes: the static profile's DeckNode
# column, the standalone static and dynamic cubic-Hermite routes, the mixed route (the OpenFAST
# aggregate evaluator) and the C API on the coarse lazy-wave deck the static solve refines
Expand Down
1 change: 1 addition & 0 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ article's methods, are compared in
| **L2-V** | VolturnUS-S anchor tension | closed-form catenary | 0.77% | <3% | Pass |
| **L2-80** | Lozon 80 m all-chain mooring | catenary (H) / MoorDyn-F (fairlead) | 0.03% / 1.8% | <2% / <5% | Pass |
| **L2-arb** | Closed-form catenary reference check | OrcaFlex VolturnUS-S ref | 0.69% | <2% | Pass |
| **L2-VIV** | Cross-flow VIV lock-in of a taut 100 m line, U = 0.06–0.42 m/s | MoorDyn-F (OpenFAST v5 `moordyn_driver`, `dtM` 5e-4 s) | mode-1 and mode-3 lock-in (U ≤ 0.18 and ≥ 0.36 m/s): mid-span A/D within 1.2%, frequency within one spectral bin; same response at `dtM` 5e-4 to 1e-2 s; at 0.21–0.33 m/s the codes settle on different modes (MoorDyn-F mode 1, CableDyn mode 2) | A/D <3%, frequency within one spectral bin (`viv_lockin`) | Pass scoped |
| **L3-1** | WD0050 static | OrcaFlex | 0.15 / 0.85% | <2% | Pass |
| **L3-2** | Regular-wave dynamic | OrcaFlex (pinned, dt-converged) | mean 0.30%, swing 8.4% | <2% / <15% | Pass |
| **L3-3** | Current-deflected static | OrcaFlex | 0.07–0.67% | <2% | Pass |
Expand Down
8 changes: 5 additions & 3 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -113,9 +113,11 @@ Line and constitutive capability
- natural frequencies and mode shapes of each line about its static equilibrium (all
``EI = 0`` lines, or all finite-EI lines on the Hermite route; flat seabed); a deck with
torsion is rejected
* - VIV (``compVIV``)
- Not implemented
- use another validated model; CableDyn rejects the request
* - Cross-flow VIV (LINE TYPES ``Cl``, ``dF``, ``cF``)
- Standalone only
- MoorDyn v2's synchronisation model on ``EI = 0`` lines (:ref:`theory-viv`); in-line VIV
and finite-EI cables are not provided; the coupled OpenFAST and FAST.Farm routes and
mixed ``EI = 0`` / finite-EI decks refuse ``Cl > 0`` by name

Loads and environment
---------------------
Expand Down
3 changes: 2 additions & 1 deletion doc/cli.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1016,7 +1016,8 @@ native reader's rules.
- ``LINE TYPES`` row ``NAME``; fields ``name``, ``diam``, ``mass``, ``ea``, ``ba``,
``ei`` followed by ``cdn``, ``cdt``, ``can``, ``cat`` (CableDyn columns), ``cd``,
``ca``, ``cdax``, ``caax`` (MoorDyn-style columns), or ``gas``, ``gj``, ``irt``,
``irn``, ``cdn``, ``cdt``, ``can``, ``cat`` (14-column rows).
``irn``, ``cdn``, ``cdt``, ``can``, ``cat`` (14-column rows); an 11- or 13-column row
adds ``cl`` or ``cl``, ``df``, ``cf`` (VIV).
* - ``section.LINE.OCCURRENCE.FIELD``
- The ``OCCURRENCE``-th section (1-based, End A to End B) of line ``LINE``; fields
``lineid``, ``linetype``, ``length``, ``numsegs``. A 7-column ``LINES`` row counts as a
Expand Down
4 changes: 3 additions & 1 deletion doc/concepts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,9 @@ A ``LINE TYPES`` row is the reusable material a section refers to by name: diame
metre, axial stiffness ``EA``, axial damping ``BA``, bending stiffness ``EI``, and the four Morison
coefficients (``Cd_n``, ``Cd_t``, ``Ca_n``, ``Ca_t``). ``EI`` is the switch between the two solver paths
(next section). Axial response can be linear ``EA`` or a stateful constitutive model
(viscoelastic, Syrope) — see :doc:`theory`.
(viscoelastic, Syrope) — see :doc:`theory`. An ``EI = 0`` row may end with MoorDyn's cross-flow
VIV columns ``Cl`` or ``Cl dF cF`` (lift coefficient and synchronisation band; see
:ref:`theory-viv`).

Two solver paths, selected by ``EI``
------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion doc/coupling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ solve is mathematically incorrect; changing ``NumCrctn`` does not change that de
``current`` except as a steady current on a single-turbine, pure ``EI = 0`` deck without
Rigid6 bodies or rods in a SeaState without waves or current (a WaterKin ``CurrentMod 1``
table remains available),
- VIV (``compVIV``), and
- cross-flow VIV (a LINE TYPES ``Cl > 0``), which runs in the standalone driver only, and
- fluid-source combinations that the nodewise SeaState field cannot separate without double
counting.

Expand Down
4 changes: 4 additions & 0 deletions doc/migrating.rst
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,10 @@ Keyword map
* - ``LINE TYPES`` ``Name Diam MassDen EA BA/-zeta EI Cd Ca CdAx CaAx``
- same row; the native order is ``Cd_n Cd_t Ca_n Ca_t`` and the header decides which is
meant. ``EI > 0`` switches the line to the bending element.
* - ``LINE TYPES`` VIV columns ``Cl`` or ``Cl dF cF``
- same columns and the same synchronisation model on ``EI = 0`` types in the standalone
driver (:ref:`theory-viv`); the running-RMS window is ``VIVrmsWindow`` seconds, by default
500 steps of ``dtM`` as MoorDyn's
* - ``ElasticMod 2/3`` viscoelastic ``EA``/``BA``
- ``Es|Ed`` / ``Es|alphaMBL|vbeta`` in ``EA`` and ``BA_s|BA_d`` in ``BA``
* - Syrope line type and ``SYROPE IC``
Expand Down
9 changes: 9 additions & 0 deletions doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -676,6 +676,15 @@ Ambient fluid and prescribed motion
shape; one to two peak periods is typical
- standalone ``waves``, ``wavetrain``, and WaterKin ``WaveKinMod 1`` waves
- ``20.0 rampTime``
* - ``VIVrmsWindow`` / ``viv_rms_window``
- real, s
- ``0``
- finite, ≥ 0; the averaging time of the running RMS cross-flow velocity and acceleration
of the VIV synchronisation model (:ref:`theory-viv`). ``0`` takes MoorDyn's 500 steps of
``dtM`` (of the first step when the deck has no ``dtM``); set it to compare runs at
different ``dtM`` with the same averaging time
- standalone ``EI = 0`` lines with a LINE TYPES ``Cl > 0``
- ``0.25 VIVrmsWindow``
* - ``motionFile``
- path, or ``0``/``none``
- absent
Expand Down
12 changes: 12 additions & 0 deletions doc/references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,18 @@ Time integration and nonlinear solution
Hydrodynamics and ocean environment
-----------------------------------

.. _ref-thorsen2014:

- **Thorsen, M. J., Sævik, S. & Larsen, C. M. (2014).** A simplified method for time domain
simulation of cross-flow vortex-induced vibrations. *Journal of Fluids and Structures*
**49**, 135–148. https://doi.org/10.1016/j.jfluidstructs.2014.04.006

.. _ref-thorsen2016:

- **Thorsen, M. J., Sævik, S. & Larsen, C. M. (2016).** Time domain simulation of
vortex-induced vibrations in stationary and oscillating flows. *Journal of Fluids and
Structures* **61**, 1–19. https://doi.org/10.1016/j.jfluidstructs.2015.11.006

.. _ref-morison1950:

- **Morison, J. R., O'Brien, M. P., Johnson, J. W. & Schaaf, S. A. (1950).** The force
Expand Down
45 changes: 45 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -715,6 +715,51 @@ fluid acceleration :math:`\dot{\mathbf{u}}_f = \dot{\mathbf{u}}_{f,n} + \dot{\ma

The fluid acceleration is the local (Eulerian) acceleration of the wave field.

.. _theory-viv:

Cross-flow vortex-induced vibration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``EI = 0`` lines can carry the cross-flow lift of the synchronisation model of
:ref:`Thorsen et al. (2014) <ref-thorsen2014>` and :ref:`(2016) <ref-thorsen2016>` in the form
MoorDyn v2 implements it: a LINE TYPES row with a lift coefficient :math:`C_L > 0` (see
:doc:`file_formats`). At an interior node with unit tangent :math:`\mathbf{q}` (the chord of its
neighbours) and normal relative flow :math:`\mathbf{v}_n` of speed :math:`U = \lvert\mathbf{v}_n\rvert`,
each node carries a vortex-shedding phase :math:`\phi` and the lift

.. math::

\mathbf{F}_L = \tfrac{1}{4}\rho\,d\,C_L\,(l_{i} + l_{i+1})\,U\cos\phi\;\mathbf{q}\times\mathbf{v}_n ,

the per-length :math:`\tfrac{1}{2}\rho d C_L U^2\cos\phi` over the node's half elements (wetted
fraction included). The phase follows the cross-flow motion
:math:`\dot y = \dot{\mathbf{r}}\cdot\mathbf{e}`, :math:`\ddot y = \ddot{\mathbf{r}}\cdot\mathbf{e}`
along :math:`\mathbf{e} = \mathbf{q}\times\mathbf{v}_n/U`:

.. math::

\dot\phi = 2\pi\,\hat f\,\frac{U}{d}, \qquad
\hat f = c_F + d_F \sin(\phi_{\dot y} - \phi), \qquad
\phi_{\dot y} = \operatorname{atan2}\!\left(-\frac{\ddot y}{\ddot y_\text{rms}},\,
\frac{\dot y}{\dot y_\text{rms}}\right),

so the shedding frequency locks onto the cross-flow motion inside the band
:math:`c_F \pm d_F` (MoorDyn's defaults 0.18 and 0.08). The running RMS values average over
``VIVrmsWindow`` seconds, by default 500 steps of ``dtM`` as in MoorDyn, and the phases start at
:math:`2\pi i/N` along the line from End A. The static equilibrium carries no lift.

In the implicit step the phase is explicit: the step's lift takes the phase predicted at
:math:`t_{n+1}` from the step-start rate (the generalised-α level under the configuration blend),
and the committed phase is the trapezoidal (Heun) update with the rate at the converged end
state. The lift's position and velocity derivatives enter the tangent. The cross-flow motion of
the phase and the velocity in the lift are the node values averaged with the neighbours,
:math:`(\mathbf{x}_{i-1} + 2\mathbf{x}_i + \mathbf{x}_{i+1})/4`. That keeps a resolved mode of
wavenumber :math:`k` to :math:`\cos^2(k l_0/2)` and removes the mesh-scale zig-zag mode exactly.
With the node's own kinematics, a step that resolves the zig-zag mode lets the synchronisation
loop pump it until the line loses lock-in; a coarse step only hides this behind the
integrator's numerical damping. VIV runs in the standalone driver; the coupled and mixed
aggregate routes refuse a deck with :math:`C_L > 0`.

Buoyancy and wetting
~~~~~~~~~~~~~~~~~~~~

Expand Down
5 changes: 3 additions & 2 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -838,8 +838,9 @@ aborts with a CableDyn fatal error, check whether the deck uses one of these com
- linearise a pinned-hang-off, uncontrolled variant of the deck; time-domain runs support both
* - a ``Rigid`` end-connection direction reversed by exactly 180 degrees in one host update
- drive the platform through intermediate orientations
* - VIV (``compVIV``)
- use a solver with a separately validated VIV model
* - VIV on the coupled or mixed route (``VIV (LINE TYPES Cl > 0) runs in the standalone driver
of an EI = 0 deck``)
- run the VIV study on a standalone ``EI = 0`` deck, or set ``Cl = 0`` for the coupled run
* - a host/file fluid combination named as inseparable
- select host wave/current and file wave/current independently as documented, or place the
whole field in SeaState
Expand Down
33 changes: 31 additions & 2 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,11 @@ class LineType:
Optional finite-EI columns (shear and torsional stiffness, rotary
inertias). All four set writes the 14-column row; all ``None`` writes
the 10-column row.
cl, df, cf : float | None
Optional cross-flow VIV columns of an ``EI = 0`` type (MoorDyn's lift
coefficient and the half-range and centre of the synchronisation band
in non-dimensional frequency). ``cl`` set writes the 13-column row, with
MoorDyn's ``df = 0.08`` and ``cf = 0.18`` where they are ``None``.
"""

name: str
Expand All @@ -209,6 +214,9 @@ class LineType:
gj: float | None = None
irt: float | None = None
irn: float | None = None
cl: float | None = None
df: float | None = None
cf: float | None = None


@dataclass(eq=False)
Expand Down Expand Up @@ -1622,6 +1630,9 @@ def add_line_type(
gj: float | None = None,
irt: float | None = None,
irn: float | None = None,
cl: float | None = None,
df: float | None = None,
cf: float | None = None,
) -> LineType:
"""Add a ``LINE TYPES`` row; see :class:`LineType` for the fields.

Expand All @@ -1637,7 +1648,9 @@ def add_line_type(
"""
_text(name, "line-type name")
self._check_new_key(self.line_types, name)
item = LineType(name, diam, mass, ea, ba, ei, cdn, cdt, can, cat, gas, gj, irt, irn)
item = LineType(
name, diam, mass, ea, ba, ei, cdn, cdt, can, cat, gas, gj, irt, irn, cl, df, cf
)
self._line_types.append(item)
return item

Expand Down Expand Up @@ -2631,7 +2644,7 @@ def save(

def _line_type_table(self) -> tuple[str, str, list[list[str]]]:
rows: list[list[str]] = []
wide = False
wide = viv = False
for item in self._line_types:
what = f"line type {item.name!r}"
row = [_text(item.name, what), _num(item.diam, what), _num(item.mass, what)]
Expand All @@ -2649,10 +2662,23 @@ def _line_type_table(self) -> tuple[str, str, list[list[str]]]:
elif any(value is not None for value in extra):
raise ValueError(f"{what}: give all of gas, gj, irt, irn or none")
row += [_num(v, what) for v in (item.cdn, item.cdt, item.can, item.cat)]
if item.cl is not None:
if all(value is not None for value in extra):
# a LINE TYPES row has 10, 11, 13 or 14 columns: no VIV on the wide row
raise ValueError(f"{what}: cl, df and cf do not combine with gas, gj, irt, irn")
viv = True
df = 0.08 if item.df is None else item.df
cf = 0.18 if item.cf is None else item.cf
row += [_num(v, what) for v in (item.cl, df, cf)]
elif item.df is not None or item.cf is not None:
raise ValueError(f"{what}: df and cf need the VIV lift coefficient cl")
rows.append(row)
if wide:
header = "Name Diam Mass EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t"
units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (N) (N-m^2) (kg-m) (kg-m) (-) (-) (-) (-)"
elif viv:
header = "Name Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t Cl dF cF"
units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (-) (-) (-) (-) (-) (-) (-)"
else:
header = "Name Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t"
units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (-) (-) (-) (-)"
Expand Down Expand Up @@ -3142,6 +3168,9 @@ def line_type(self, row: DeckRecord) -> None:
gj=_f(values["gj"]) if wide else None,
irt=_f(values["irt"]) if wide else None,
irn=_f(values["irn"]) if wide else None,
cl=_f(values["cl"]) if "cl" in values else None,
df=_f(values["df"]) if "df" in values else None,
cf=_f(values["cf"]) if "cf" in values else None,
)

def body(self, row: DeckRecord) -> None:
Expand Down
Loading
Loading