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 @@ -17,6 +17,13 @@ All notable changes to CableDyn are recorded in this file. The format follows
pinned cable match this to 0.05 %. It acts on every dynamic route beside the axial (`BA`) and
torsional (`GJ|K|Bt`) damping, with exact Jacobians; the Python deck reader and builder take the
same forms.
- In-line VIV of finite-EI cables: an optional `VIV` section row `TypeName ClX [alpha]` adds the
in-line vortex-shedding force of Ulveseter et al. (2018), `1/2 rho D ClX cos(phi_x) U v_n` along
the relative flow, with its phase slaved to twice the cross-flow one in a band `alpha` (default
0.15). On the taut line of `examples/viv_taut_cable_inline.dat` the in-line response runs at
twice the cross-flow frequency, A/D 0.19 against 0.03 with the lift alone. Exact Jacobians; the
phase is in the step-recovery, snapshot and checkpoint state; the Python deck reader and
builder take the section. `EI = 0` lines refuse it for now.

## [0.4.2] - 2026-11-09

Expand Down
12 changes: 11 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1321,6 +1321,16 @@ target_link_libraries(test_hermite_viv PRIVATE cabledyn_core)
add_test(NAME hermite_viv COMMAND test_hermite_viv)
set_tests_properties(hermite_viv PROPERTIES LABELS "fortran;dynamic;viv")

add_executable(test_hermite_viv_inline tests/test_hermite_viv_inline.f90)
target_link_libraries(test_hermite_viv_inline PRIVATE cabledyn_core)
add_test(NAME hermite_viv_inline COMMAND test_hermite_viv_inline)
set_tests_properties(hermite_viv_inline PROPERTIES LABELS "fortran;dynamic;viv")

add_executable(test_viv_inline_deck tests/test_viv_inline_deck.f90)
target_link_libraries(test_viv_inline_deck PRIVATE cabledyn_core)
add_test(NAME viv_inline_deck COMMAND test_viv_inline_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_inline_deck PROPERTIES LABELS "fortran;integration;dynamic;viv;driver")

add_executable(test_viv_coupled tests/test_viv_coupled.f90)
target_link_libraries(test_viv_coupled PRIVATE cabledyn_core)
add_test(NAME viv_coupled COMMAND test_viv_coupled WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
Expand Down Expand Up @@ -3568,7 +3578,7 @@ foreach(_feature_example IN ITEMS
airy_wave_shallow_chain laid_cable_cross_current chain_modes lazy_wave_modes buoy_clamped_cable
moordynC_wavekin/chain_wavekin7_currents1 spar_pinned_rods mixed_body_rods_points
als_volturnus_line_break_time als_volturnus_line_break_tension
viv_taut_line_crossflow composite_axial_damping_mode1 composite_ve_syrope_jonswap
viv_taut_line_crossflow viv_taut_cable_inline composite_axial_damping_mode1 composite_ve_syrope_jonswap
composite_chain_poly_chain_modes shared_cable_two_floaters lazy_wave_modules_stiffener
chain_sloped_bathymetry_friction torsion_free_end_armoured_cable
moordynC_currents/chain_wavekin3_currents2 moordynC_currents/chain_currents5_grid)
Expand Down
8 changes: 6 additions & 2 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -143,8 +143,12 @@ Line and constitutive capability
- Standalone and coupled
- MoorDyn v2's synchronisation model on ``EI = 0`` lines and, as a distributed lift, on
finite-EI cables of the Hermite and multibody marches (:ref:`theory-viv`), with the
host's fluid field on the coupled routes and its state in the checkpoint; in-line VIV is
not provided
host's fluid field on the coupled routes and 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, on
finite-EI cables of the Hermite and multibody marches (:ref:`theory-viv-inline`), its state
in the checkpoint; not on ``EI = 0`` lines yet

Loads and environment
---------------------
Expand Down
5 changes: 3 additions & 2 deletions doc/concepts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,10 @@ 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`. An ``EI = 0`` row may end with MoorDyn's cross-flow
(viscoelastic, Syrope) — see :doc:`theory`. A 10-column row may end with MoorDyn's cross-flow
VIV columns ``Cl`` or ``Cl dF cF`` (lift coefficient and synchronisation band; see
:ref:`theory-viv`).
:ref:`theory-viv`), and a ``VIV`` section row adds the in-line force of a finite-EI type
(:ref:`theory-viv-inline`).

Two solver paths, selected by ``EI``
------------------------------------
Expand Down
48 changes: 46 additions & 2 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,8 +133,8 @@ except that `SYROPE IC` must come **after** `LINES`, because its rows name lines
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 / FAILURE / CONTROL →
OPTIONS → OUTPUTS
SECTIONS → END CONNECTIONS / EQUIVALENT BUOYANCY / ATTACHMENTS / STIFFENERS / VIV / 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 @@ -210,6 +210,7 @@ are collapsed. It must match one of the spellings below; any other name fails wi
| EQUIVALENT BUOYANCY | `EQUIVALENT BUOYANCY`, `EQUIVALENT SECTIONS`, `BUOYANCY SECTIONS` |
| ATTACHMENTS | `ATTACHMENTS`, `LINE ATTACHMENTS`, `CLUMPS` |
| STIFFENERS | `STIFFENERS`, `STIFFENER`, `BEND STIFFENERS`, `BEND STIFFENER` |
| VIV | `VIV`, `VORTEX-INDUCED VIBRATION`, `VORTEX INDUCED VIBRATION` |
| FAILURE | `FAILURE`, `FAILURES` |
| CONTROL | `CONTROL`, `CONTROLS` |
| TURBINES | `TURBINES`, `TURBINE` |
Expand Down Expand Up @@ -289,6 +290,14 @@ frequency `f` [Hz], `Bb = ζ EI/(π f)`, set once per line type (it does not dep
`EI|0` is the plain `EI`. It needs `EI > 0` and acts in the dynamics only (a static solve has no
rates).

**Cross-flow VIV columns (MoorDyn v2).** A 10-column row may end with `Cl` (11 columns) or
`Cl dF cF` (13 columns): the lift coefficient of the vortex-shedding synchronisation model and
the half-range and centre of its band in non-dimensional frequency (MoorDyn's `dF = 0.08` and
`cF = 0.18` when only `Cl` is given). `Cl = 0` is no VIV; `Cl > 0` needs `cF > 0` and
`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 14-column row has no VIV columns. The
in-line force of a finite-EI type is a [VIV](#viv-optional-finite-ei-lines) section row.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:

Expand Down Expand Up @@ -1136,6 +1145,41 @@ Behaviour:
`NodeA`) the `End` column follows the written row, so the stiffener stays on the same physical
end. Stiffeners run wherever the cubic-Hermite cable does, standalone and coupled.

### VIV (optional, finite-EI lines)

In-line vortex-induced vibration of a line type: a second vortex-shedding force along the
relative flow, the direction of the drag, at twice the cross-flow frequency (Ulveseter et al.
2018; see [In-line VIV](theory.rst)). One row per line type, which must carry the cross-flow lift
(`Cl > 0` in LINE TYPES), since the in-line phase runs at twice the cross-flow one.

```text
--------------------- VIV ----------------------------------------------
TypeName ClX alpha
(-) (-) (-)
cable 0.85 0.15
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive), at most one row each |
| `ClX` | in-line shedding coefficient `C_x` >= 0, at most 1e15; `0` is no in-line VIV |
| `alpha` | optional frequency band of the in-line phase about twice the cross-flow one, `0 <= alpha < 1` (default 0.15) |

Behaviour:

- Per unit length the force is `1/2 rho D ClX cos(phi_x) U v_n`, with `v_n` the relative normal
flow and `U` its speed; its phase follows `dphi_x/dt = 2 (dphi/dt) [1 + alpha sin(phi_xd - phi_x)]`,
`phi` the cross-flow phase and `phi_xd` the phase of the in-line motion. Ulveseter et al. take
`ClX = 0.85` and `alpha = 0.15` with `Cl = 0.65`.
- The Outputs flag `V` file carries the in-line force with the lift, and the phase is part of
the step-recovery, snapshot and checkpoint state. A row with `ClX = 0` leaves the run exactly as
without it.
- It acts on finite-EI lines (`EI > 0`) on every route the cubic-Hermite cable runs; an `EI = 0`
line of a type with `ClX > 0` stops by name. A row fails if it is not `TypeName ClX [alpha]`,
names an undefined or already named type, or holds a value out of range, and `ClX > 0` fails
on a type without the cross-flow lift.
- See `examples/viv_taut_cable_inline.dat`.

### 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
6 changes: 6 additions & 0 deletions doc/examples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,12 @@ Dynamic environment
:ref:`theory-viv`
- cable, dynamic
- ~2 s
* - ``viv_taut_cable_inline.dat``
- in-line VIV (the ``VIV`` section, ``ClX`` and ``alpha``): the same line as a finite-EI
cable; the quarter span moves in line at twice the cross-flow frequency, A/D 0.19 against
0.03 with the cross-flow lift alone — :ref:`theory-viv`
- cable, dynamic
- ~2 s

Points, buoys, bodies, and rods
-------------------------------
Expand Down
3 changes: 2 additions & 1 deletion doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -340,7 +340,8 @@ write. Any other letter is a parse error. Mixed ``EI = 0`` + finite-EI decks rej
flag ``V``; a static run carries no lift and writes no file). On an ``EI = 0`` line the
end nodes carry none, as in MoorDyn; on a finite-EI line each element's lift is lumped to
its two nodes (the translational part of its consistent load), so the end nodes carry
the lift of their half-elements. Zero on a line without VIV (``Cl = 0``)
the lift of their half-elements, and a type with in-line VIV (the ``VIV`` section) adds
its in-line force. Zero on a line without VIV (``Cl = 0``)
* - ``r``
- ``<out_root>.Line<L>.range.out``
- range graph: minimum, maximum and mean over the run of the node tension, curvature, bend
Expand Down
6 changes: 6 additions & 0 deletions doc/references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@ Hydrodynamics and ocean environment
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-ulveseter2018:

- **Ulveseter, J. V., Thorsen, M. J., Sævik, S. & Larsen, C. M. (2018).** Time domain
simulation of riser VIV in current and irregular waves. *Marine Structures* **60**, 241–260.
https://doi.org/10.1016/j.marstruc.2018.04.001

.. _ref-morison1950:

- **Morison, J. R., O'Brien, M. P., Johnson, J. W. & Schaaf, S. A. (1950).** The force
Expand Down
37 changes: 37 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1169,6 +1169,43 @@ phases, the running mean squares and the averaging time are part of the checkpoi
restart continues the uninterrupted run bit for bit. The OpenFAST correction iterations rewind
them with the rest of the state.

.. _theory-viv-inline:

In-line vortex-induced vibration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A finite-EI line type can add the in-line shedding force of the combined cross-flow and in-line
model of :ref:`Ulveseter et al. (2018) <ref-ulveseter2018>`, a ``VIV`` section row
``TypeName ClX [alpha]`` (see :doc:`file_formats`). A second phase :math:`\phi_x` per node drives
a force along the relative normal flow, per unit deformed length

.. math::

\mathbf{f}_x = \tfrac{1}{2}\rho\,d\,C_{x}\cos\phi_x\;U\,\mathbf{v}_n ,

the direction of the drag, at twice the cross-flow frequency. Its phase is slaved to the
cross-flow shedding phase :math:`\phi`, with a band :math:`\alpha` in which it locks onto the
in-line motion :math:`\dot x = \dot{\mathbf{r}}\cdot\mathbf{v}_n/U`:

.. math::

\dot\phi_x = 2\,\dot\phi\,\bigl[1 + \alpha\sin(\phi_{\dot x} - \phi_x)\bigr], \qquad
\phi_{\dot x} = \operatorname{atan2}\!\left(-\frac{\ddot x}{\ddot x_\text{rms}},\,
\frac{\dot x}{\dot x_\text{rms}}\right),

with the running RMS values of the cross-flow phase (:math:`\phi_{\dot x} = 0` at a node with no
in-line motion). Ulveseter et al. take :math:`C_x = 0.85` and :math:`\alpha = 0.15` (the default
here) with a cross-flow :math:`C_L` of 0.65. The in-line phase starts at twice the cross-flow
one, so the two start locked. The in-line rate is twice the cross-flow one, so ``ClX > 0``
needs the type's cross-flow :math:`C_L > 0`. The force is integrated with the lift at the same
Gauss points, :math:`\cos\phi_x` interpolated between the element's end nodes, and its exact
position and velocity derivatives enter the tangent. The phase is explicit with the Heun commit,
its end-state rate taken from the end-state cross-flow rate. The phase and the two mean squares
are part of the step-recovery, snapshot and checkpoint state, and a ``ClX`` of zero leaves the
run exactly as without the row. On the taut line of ``viv_taut_cable_inline.dat`` the quarter
span moves in line at twice the cross-flow frequency, A/D 0.19 against 0.03 with the cross-flow
lift alone. ``EI = 0`` lines do not take in-line VIV yet.

.. _theory-dry-buoyancy:

Buoyancy and wetting
Expand Down
60 changes: 60 additions & 0 deletions examples/viv_taut_cable_inline.dat
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
--------------------- CableDyn Input File ------------------------------------
CableDyn driver deck -- cross-flow and in-line VIV of a taut cable in a uniform current, 90 s
-- The taut line of viv_taut_line_crossflow.dat as a finite-EI cable (EI 1 N m^2, a string to
-- within 1e-6 of its geometric stiffness): 100 m, D 0.1 m, 10 kg/m, EA 5e7 N, about 50 kN, held
-- at both ends 50 m below the surface in a 0.15 m/s current along +Y. The LINE TYPES columns
-- Cl dF cF give the cross-flow lift (0.8 in MoorDyn's band), which locks the first vertical mode
-- in across the flow (Z). The VIV section adds the in-line shedding force of Ulveseter et al.
-- (Mar. Struct. 60, 2018) along the flow (Y): ClX 0.85 and the band alpha 0.15 of its phase
-- about twice the cross-flow one. Over 60-90 s the quarter span (L1N13py) moves in line at A/D
-- 0.19, at twice the 0.29 Hz cross-flow frequency of the mid span (L1N26pz, A/D 0.82); with the
-- cross-flow lift alone (drop the VIV section) they are 0.03 and 0.66. The Outputs flag V writes
-- the VIV force, lift and in-line, at every node to <root>.Line1.V.out.
--------------------- LINE TYPES ---------------------------------------
TypeName Diam MassDenInAir EA BA/-zeta EI Cd_n Cd_t Ca_n Ca_t Cl dF cF
(-) (m) (kg/m) (N) (N-s/-) (N-m^2) (-) (-) (-) (-) (-) (-) (-)
riser 0.10 10.0 5.0e7 -0.8 1.0 1.2 0.0 1.0 0.0 0.8 0.08 0.18
--------------------- POINTS -------------------------------------------
ID Type X Y Z Mass Vol CdA Ca
(-) (-) (m) (m) (m) (kg) (m^3) (m^2) (-)
1 Coupled 0.0 0.0 -50.0 0 0 0 0
2 Fixed 100.0 0.0 -50.0 0 0 0 0
--------------------- LINES --------------------------------------------
ID NodeA NodeB Outputs
(-) (-) (-) (-)
1 1 2 V
--------------------- SECTIONS -----------------------------------------
-- 99.9 m unstretched: 50 kN stretches it to the 100 m span (EA 5e7 N, strain 0.1 %).
LineID LineType Length NumSegs
(-) (-) (m) (-)
1 riser 99.9001 50
--------------------- VIV ----------------------------------------------
-- In-line VIV of a line type: the in-line shedding coefficient ClX (0 = off; it needs the type's
-- cross-flow Cl > 0) and the band alpha (0 <= alpha < 1, default 0.15). Finite-EI lines only.
TypeName ClX alpha
(-) (-) (-)
riser 0.85 0.15
--------------------- OPTIONS ------------------------------------------
9.80665 g - Gravitational acceleration (m/s^2) [default: 9.80665]
1025.0 rhoW - Water density (kg/m^3) [default: 1025]
100.0 WtrDpth - Water depth (m) [default: absent standalone; host-owned OpenFAST]
1.0e5 kBot - Seabed penalty stiffness base (Pa/m) [default: 1.0e5]
1.0e4 cBot - Seabed normal damping base (Pa-s/m) [default: 1.0e4]
0.02 dtM - CableDyn internal time step (s) [default: omitted standalone; the glue DT in OpenFAST]
90.0 TMax - Standalone simulation duration (s) [default: omitted standalone; host-owned OpenFAST]
0.25 VIVrmsWindow - Averaging time of the VIV running RMS motion (s) {0=500 steps of dtM} [default: 0]
spread VIVphaseSeed - Initial VIV phases {spread=2 pi i/N, MoorDyn-C; zero=MoorDyn-F} [default: spread]
uniform 0.0 0.15 0.0 current - Current model and X/Y/Z velocity (m/s) {none; uniform; profile} [default: none]
none waves - Wave model, height, period, and direction (m, s, deg) {none; airy; jonswap} [default: none]
0 WaterKin - Water-kinematics source {0/none; 3; 7; file; SEASTATE coupled only} [default: no policy]
0.4 rhoInf - Generalised-alpha spectral radius {0<=rhoInf<=1} [default: 0.4]
False modified_newton - Tangent-reuse mode {False=full Newton; True=guarded reuse} [default: False]
False adaptive_mesh - Automatic finite-EI refinement {False; True} [default: False]
dynamic_solver 1.0e-8 1.0e-14 30 12 - Relative tolerance, absolute tolerance, max iterations, backtracks [defaults shown]
none frictionMu - Seabed friction coefficient {none; value>=0} [default: none]
-- Complete option/default reference: cabledyn_options_reference.dat and doc/options.rst.
--------------------- OUTPUTS ------------------------------------------
"FairTen1"
"L1N26pz"
"L1N13py"
--------------------- need this line -----------------------------------
Loading
Loading