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
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.
- Cross-flow VIV of finite-EI cables in the standalone driver: the same LINE TYPES columns on an
`EI > 0` type give a distributed lift, Gauss-integrated over each cubic-Hermite element with
exact tangents, and a shedding phase at each node driven along the node's own tangent. A taut
line with `EI` near zero reproduces the `EI = 0` lock-in to three digits, at any `dtM` from
5e-4 to 1e-2 s without smoothing; a bending-stiff line matches the string of equal first-mode
frequency in mode-1 lock-in and stays in mode 1 where that string jumps to mode 2. A finite-EI
line with two moving ends, or beside bodies, rods or free points, refuses `Cl > 0`.
- 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
15 changes: 14 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1175,6 +1175,11 @@ 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_hermite_viv tests/test_hermite_viv.f90)
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_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 @@ -1627,9 +1632,17 @@ if(Python3_Interpreter_FOUND)
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_viv_lockin.py
--exe $<TARGET_FILE:cabledyn>
--output ${CMAKE_BINARY_DIR}/viv_lockin)
# eight benchmark runs, four at a time (PROCESSORS reserves them, so no other test shares
# the cores); a checked Debug build is about ten times slower than Release
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
set(_viv_lockin_timeout 2400)
else()
set(_viv_lockin_timeout 600)
endif()
set_tests_properties(viv_lockin PROPERTIES
LABELS "python;integration;dynamic;viv;validation"
TIMEOUT 600
PROCESSORS 4
TIMEOUT ${_viv_lockin_timeout}
ENVIRONMENT "${_cabledyn_python_test_environment}")
else()
message(STATUS "viv_lockin: skipped (numpy not importable in ${Python3_EXECUTABLE})")
Expand Down
1 change: 1 addition & 0 deletions VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ article's methods, are compared in
| **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 |
| **L2-VIV-EI** | Cross-flow VIV of a finite-EI cable: the L2-VIV line with EI = 1 N m², and a bending-stiff line (EA 5e9 N, EI 5e7 N m², β = π²EI/(TL²) ≈ 1, neutrally buoyant) against the EI = 0 string of equal first-mode frequency, U = 0.10–0.36 m/s | CableDyn `EI = 0` line (verification) | EI = 1: mid/quarter A/D 0.662/0.421 against 0.663/0.421, same frequency, at `dtM` 5e-4 to 1e-2 s; stiff line: mode-1 lock-in A/D within 2.5% of the string's at the same frequency for U ≤ 0.24 m/s; for U ≥ 0.27 m/s the string jumps to mode 2 while the stiff line stays in mode 1 (bending raises f₂/f₁ to 3.15) | EI = 1: A/D within 1% at `dtM` 0.01 and 0.002 s (5e-4 s run once over 200 s); stiff line at U 0.21 m/s: A/D within 3%; frequency within one spectral bin; at U 0.30 m/s stiff line A/D > 0.6, string < 0.15 (`viv_lockin`, `hermite_viv`) | Pass |
| **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 @@ -115,9 +115,11 @@ Line and constitutive capability
torsion is rejected
* - 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
- MoorDyn v2's synchronisation model on ``EI = 0`` lines and, as a distributed lift, on
finite-EI cables of the Hermite march (:ref:`theory-viv`); in-line VIV is not provided;
the coupled OpenFAST and FAST.Farm routes, mixed ``EI = 0`` / finite-EI decks, finite-EI
lines with two moving ends and finite-EI lines beside bodies, rods or free points refuse
``Cl > 0`` by name

Loads and environment
---------------------
Expand Down
5 changes: 3 additions & 2 deletions doc/migrating.rst
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,9 @@ Keyword map
- 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
- same columns and the same synchronisation model in the standalone driver, on ``EI = 0``
types and as a distributed lift on finite-EI types (: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``
Expand Down
3 changes: 2 additions & 1 deletion doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -683,7 +683,8 @@ Ambient fluid and prescribed motion
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``
- standalone lines (``EI = 0``, or finite-EI on the Hermite march) with a LINE TYPES
``Cl > 0``
- ``0.25 VIVrmsWindow``
* - ``motionFile``
- path, or ``0``/``none``
Expand Down
30 changes: 26 additions & 4 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -720,10 +720,10 @@ The fluid acceleration is the local (Eulerian) acceleration of the wave field.
Cross-flow vortex-induced vibration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``EI = 0`` lines can carry the cross-flow lift of the synchronisation model of
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
:doc:`file_formats`). On an ``EI = 0`` line, 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

Expand Down Expand Up @@ -757,8 +757,30 @@ the phase and the velocity in the lift are the node values averaged with the nei
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`.
integrator's numerical damping.

On a finite-EI (cubic-Hermite) cable the lift is a distributed load per unit deformed length,

.. math::

\mathbf{f}_L = \tfrac{1}{2}\rho\,d\,C_L\cos\phi\;U\;\mathbf{t}\times\mathbf{v}_r ,

with :math:`\mathbf{t}` the unit tangent of the centreline, :math:`\mathbf{v}_r` the relative flow
(its normal part has speed :math:`U`) and :math:`\cos\phi` interpolated linearly between the
element's end nodes. It is integrated against the Hermite shape functions at the three Gauss
points of the drag (a point above the surface carries none), and its exact position and
velocity derivatives enter the tangent. Each node carries a phase, driven as above by the
node's cross-flow motion along its own tangent, the slope degrees of freedom; :math:`d`,
:math:`c_F` and :math:`d_F` at a node are the length-weighted averages over its lifting
elements. The phase is explicit with the Heun commit as on ``EI = 0`` lines, and no smoothing is
needed: the Hermite tangent and the integrated lift leave no mesh-scale mode for the loop to
pump, and the response is the same from ``dtM`` 5e-4 to 1e-2 s. A finite-EI line with
:math:`EI \to 0` reproduces the ``EI = 0`` line's lock-in. The standalone Hermite march
carries it, including deck waves and current through its held fluid field; a finite-EI line
with two moving ends, or beside bodies, rods or free points, refuses :math:`C_L > 0`.

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
8 changes: 6 additions & 2 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -839,8 +839,12 @@ aborts with a CableDyn fatal error, check whether the deck uses one of these com
* - a ``Rigid`` end-connection direction reversed by exactly 180 degrees in one host update
- drive the platform through intermediate orientations
* - 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
of an EI = 0 or finite-EI deck``)
- run the VIV study on a standalone ``EI = 0`` or finite-EI deck, or set ``Cl = 0`` for the
coupled run
* - VIV on a finite-EI line with two moving ends (``needs its End B fixed``) or beside
bodies, rods or free points (``does not run with bodies, rods or free points yet``)
- fix End B of the line, or set ``Cl = 0`` for its line type
* - 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
2 changes: 1 addition & 1 deletion python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ class LineType:
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
Optional cross-flow VIV columns of a 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``.
Expand Down
23 changes: 17 additions & 6 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -2615,6 +2615,7 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
# (native init_one_model, which needs the line's Morison drag in water)
has_viv = False
has_viv_ei0 = False
viv_type_names: set[str] = set()
for row in self.line_types:
for index in (1, 2, *range(5, len(row.tokens))):
numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}")
Expand Down Expand Up @@ -2697,17 +2698,15 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
f"{self._at(row)}: LINE TYPES VIV synchronisation band needs cF > 0 "
"and 0 <= dF < cF"
)
if cl > 0.0 and ei > 0.0:
raise DeckFormatError(
f"{self._at(row)}: VIV (Cl > 0) is implemented for EI = 0 line types only"
)
if cl > 0.0 and is_syrope:
raise DeckFormatError(
f"{self._at(row)}: VIV (Cl > 0) does not combine with the Syrope "
"working-curve model"
)
has_viv = has_viv or cl > 0.0
has_viv_ei0 = has_viv_ei0 or (cl > 0.0 and not ei > 0.0)
if cl > 0.0:
viv_type_names.add(row.tokens[0].lower())
if ei > 0.0 and (is_syrope or len(ea_parts) > 1):
model = "Syrope" if is_syrope else "viscoelastic stiffness"
raise DeckFormatError(f"{self._at(row)}: {model} is not supported with EI > 0")
Expand Down Expand Up @@ -3494,8 +3493,8 @@ def end_key(token: str) -> str:
if has_viv:
raise DeckFormatError(
f"{self._label}: VIV (LINE TYPES Cl > 0) runs in the standalone driver of an "
"EI = 0 deck; the coupled OpenFAST and FAST.Farm routes and mixed EI = 0 / "
"finite-EI decks do not carry it yet. Set Cl = 0 for this run"
"EI = 0 or finite-EI deck; the coupled OpenFAST and FAST.Farm routes and mixed "
"EI = 0 / finite-EI decks do not carry it yet. Set Cl = 0 for this run"
)
if self.caller_driven:
# native CD_Init_Deck_Aggregate: nothing on the coupled route evaluates deck
Expand Down Expand Up @@ -3600,6 +3599,18 @@ def is_body_kind(kind: str, pinned: bool) -> bool:
)
elif has_rigid6:
needs_multibody = non_rigid6_points
if deck_driver_route and viv_type_names:
# native run_deck_driver: the finite-EI lift runs on the cubic-Hermite march, which
# builds no bodies, rods or Free/Connect points (a moving End B is refused above)
for line_id in finite_line_ids:
if not viv_type_names.intersection(section_types_by_line[line_id]):
continue
if needs_multibody:
raise DeckFormatError(
f"{self._label}: VIV (LINE TYPES Cl > 0) of a finite-EI line does not run "
"with bodies, rods or free points yet; set Cl = 0 for the finite-EI lines "
"of this deck"
)
if failures and deck_driver_route:
# native CD_Run_Deck_Driver: FAILURE runs on the point-system object graph only
if not has_dtm:
Expand Down
18 changes: 15 additions & 3 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -4591,11 +4591,16 @@ def test_line_type_viv_columns_follow_the_native_checks(columns, message):
DeckFile.from_text(_edit(_STATIC, (_VIV_ROW, _VIV_ROW + columns)))


def test_line_type_viv_needs_an_ei0_line_type():
def test_line_type_viv_is_accepted_on_a_finite_ei_line_type(tmp_path):
from cabledyn import DeckModel

row = "chain 0.252 390.0 1.674e9 -1.0 1.0e4 1.37 0.64 1.0 0.0"
text = _edit(_DYNAMIC, (row, row + " 0.8"))
with pytest.raises(DeckFormatError, match="implemented for EI = 0 line types only"):
DeckFile.from_text(text)
DeckFile.from_text(text)
path = tmp_path / "viv_ei.dat"
path.write_text(text, encoding="utf-8")
line_type = DeckModel.load(path).line_types["chain"]
assert (line_type.ei, line_type.cl) == (1.0e4, 0.8)


def test_viv_is_refused_on_the_coupled_route():
Expand All @@ -4613,6 +4618,13 @@ def test_viv_needs_water_on_an_ei0_line():
DeckFile.from_text(_edit(_STATIC, ("50.0 WtrDpth\n", "")))


def test_finite_ei_viv_is_refused_beside_free_points():
row = "chain 0.252 390.0 1.674e9 -1.0 1.0e4 1.37 0.64 1.0 0.0"
base = _edit(_DYNAMIC, ("2 Coupled 0.0 0.0 0.0 0 0 0 0", "2 Free 0.0 0.0 0.0 1000 0 0 0"))
with pytest.raises(DeckFormatError, match="does not run with bodies, rods or free points"):
DeckFile.from_text(_edit(base, (row, row + " 0.8")))


def test_viv_rms_window_option_is_non_negative():
base = _edit(_STATIC, (_VIV_ROW, _VIV_ROW + " 0.8"))
DeckFile.from_text(_edit(base, ("50.0 WtrDpth\n", "50.0 WtrDpth\n0.25 VIVrmsWindow\n")))
Expand Down
Loading
Loading