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
16 changes: 16 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1290,6 +1290,13 @@ add_executable(test_end_tangent_channels tests/test_end_tangent_channels.f90)
target_link_libraries(test_end_tangent_channels PRIVATE cabledyn_core)
add_test(NAME end_tangent_channels COMMAND test_end_tangent_channels WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(end_tangent_channels PROPERTIES LABELS "fortran;integration;static;outputs" TIMEOUT 600)
# The end reactions of a finite-EI cable at rest in a uniform current, pinned or clamped,
# suspended or touching down, balance its weight and its Morison drag integrated independently.
add_executable(test_static_current_balance tests/test_static_current_balance.f90)
target_link_libraries(test_static_current_balance PRIVATE cabledyn_core)
add_test(NAME static_current_balance COMMAND test_static_current_balance
WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(static_current_balance PROPERTIES LABELS "fortran;integration;static;hydro" TIMEOUT 600)

add_executable(test_viv_kernels tests/test_viv_kernels.f90)
target_link_libraries(test_viv_kernels PRIVATE cabledyn_core)
Expand Down Expand Up @@ -2831,6 +2838,15 @@ if(Python3_Interpreter_FOUND)
LABELS "python;driver;integration;static;outputs"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")
# A negative BA damps the first axial mode of a line at zeta pi/(2N) per segment (the
# default), and at zeta on every mesh under axialDampingRatio mode1, uniform and composite.
add_test(NAME driver_axial_damping_ratio
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_axial_damping_ratio.py
$<TARGET_FILE:cabledyn>)
set_tests_properties(driver_axial_damping_ratio PROPERTIES
LABELS "python;driver;integration;dynamic;validation"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")
endif()
# The scan of the round-off CI job: it must flag a fallback note, a failed run and a forced
# BLAS kernel that did not take effect, or a clean scan would prove nothing.
Expand Down
3 changes: 2 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ Inside OUTPUTS, a row whose first token is `END` also closes the channel list.
| `Diam` | hydrodynamic / volume-equivalent diameter [m] | used for submerged weight, drag, and added mass; at least 1e-6 and at most 1e3 where used |
| `MassDenInAir` | dry mass per unstretched metre [kg/m] | submerged weight = (m − ρ_w·πd²/4)·g; its magnitude at most 1e6 where used |
| `EA` | axial stiffness [N] | linear (T = EA·ε); at least 1e-3 and at most 1e15 where used; see the viscoelastic and Syrope forms below |
| `BA/-zeta` | axial damping: ≥ 0 is BA [N·s], < 0 is −ζ (damping ratio) | active in EI = 0 and finite-EI dynamics; ignored in a static-only run |
| `BA/-zeta` | axial damping: ≥ 0 is BA [N·s], < 0 is −ζ (damping ratio): by default (MoorDyn's convention) of each segment, BA = ζ L0 √(EA m) per element, which damps the line's first axial mode at about ζ π/(2N) on N elements and so depends on the mesh (a run notes the ratio); under `mode1 axialDampingRatio` of the line's first axial mode, on any mesh (see the OPTIONS table) | active in EI = 0 and finite-EI dynamics; ignored in a static-only run |
| `EI` | bending stiffness [N·m²] | finite and ≥ 0; see [EI routing](#ei-routing) |
| `Cd_n`, `Cd_t` | normal / tangential drag coefficients | used by EI = 0 dynamic current and Airy-wave runs |
| `Ca_n`, `Ca_t` | normal / tangential added-mass coefficients | used by EI = 0 dynamic Froude–Krylov and added-mass runs |
Expand Down Expand Up @@ -1272,6 +1272,7 @@ syntax form. The most frequently edited keywords are:
| `cable_load_feedback` | coupled finite-EI cable reaction switch. `True` returns cable force and moment to the host. `False` marches the cable with the same moving boundary and host fluid field and keeps its output channels, but returns zero force and moment; use it for a one-way comparison, not as a physical model | `True` |
| `adaptive_mesh` | `True`/`False`; allow finite-EI mesh refinement when the static resolution check is fragile | `False` |
| `cable_statics` | `continuation` or `sequenced`: which finite-EI static route runs first (the other is its fallback); both results are audited | `continuation` |
| `axialDampingRatio` / `axial_damping_ratio` | `segment` or `mode1`: what a negative `BA` is the damping ratio ζ of. `segment` (MoorDyn's convention): of each segment, BA = ζ L0 √(EA m) per element, so the line's first axial mode is damped at about ζ π/(2N) on N elements and less on a finer mesh; a dynamic run notes that ratio. `mode1`: of the line's first axial mode (both ends held, dry mass, from its sections, so the same on any mesh): BA = 2 ζ EA / ω1 on every element, a damping proportional to the stiffness, so the axial mode n is damped at ζ ωn/ω1. A line with a negative `BA` and a viscoelastic or Syrope section is refused under `mode1` | `segment` |
| `OutputRecovery` / `output_recovery` | `equilibrium` or `element`: definition of the finite-EI node tension, curvature, bend moment and segment tension. `equilibrium` recovers them from nodal equilibrium (the effective tension F·t, the moment the neighbouring elements carry, curvature = moment / EI); `element` reports the length-weighted element-mean axial force EA(\|r'\| − 1), the larger one-sided exact curvature, and the element-midpoint axial resultant as segment tension. End forces, positions and TDP channels are the same under both | `equilibrium` |
| `alpha_force_blend` | `True`/`False`; generalised-α blend of the finite-EI and `EI = 0` dynamics: forces (`True`) or the configuration `q_αf` (`False`), which biases the mean tension of a rotating finite-EI line at large `dtM` and lets `EI = 0` segments that go slack report spurious tension spikes | `True` |
| `tensile_safety` | `False`, `warn`, or `True`; audits the element-mean axial force (three-point Gauss mean of the signed axial resultant, averaged over an element and its two neighbours). `True` rejects. `warn` commits the state, counts accepted-step events, and reports the worst force, threshold, element and time (the printed `xi` is always 0.5, the element centre) | `False` |
Expand Down
16 changes: 16 additions & 0 deletions doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -502,6 +502,22 @@ Finite-EI cable controls
same under both
- both (finite-EI lines)
- ``element OutputRecovery``
* - ``axialDampingRatio`` / ``axial_damping_ratio``
- mode
- ``segment``
- what a negative ``LINE TYPES`` ``BA`` is the damping ratio :math:`\zeta` of.
``segment`` (MoorDyn's convention): of each segment,
:math:`BA = \zeta L_0 \sqrt{EA\,m}` per element, which damps the line's first axial mode
at about :math:`\zeta\pi/(2N)` on :math:`N` elements, so the axial damping depends on
the mesh; a dynamic run notes the ratio for each such line. ``mode1``: of the line's
first axial mode, both ends held, from its sections' lengths, ``EA`` and dry mass, so
the same on any mesh: :math:`BA = 2\zeta EA/\omega_1` on every element, a damping
proportional to the stiffness, under which the axial mode :math:`n` is damped at
:math:`\zeta\,\omega_n/\omega_1` (see :doc:`theory`). A positive ``BA`` is used as given
under both. Under ``mode1`` a line with a negative ``BA`` and a viscoelastic
(``ElasticMod`` 2 or 3) or Syrope section is refused by name
- both (``EI = 0`` and finite-EI lines)
- ``mode1 axialDampingRatio``
* - ``axial_quadrature_order`` / ``axialquadratureorder`` / ``axial_quadrature``
- integer, –
- ``4``
Expand Down
52 changes: 47 additions & 5 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -811,9 +811,31 @@ so the element-scale modes (:math:`n \approx N`) are damped at up to :math:`(\pi
``BA``), while the line's global axial modes are damped much less, and less again on a finer
mesh: ``BA = -1`` on 100 elements gives the first axial mode 1.6 %, and 0.8 % on 200 elements.
Results that depend on the axial damping (tension peaks of snatch loads, the decay of axial
oscillations) therefore change with the mesh. For mesh-independent damping give ``BA`` in N·s:
a material damping ratio :math:`\zeta_1` of the first axial mode of a line of length :math:`L` is
:math:`BA = 2\,\zeta_1\,EA/\omega_1` with :math:`\omega_1 = (\pi/L)\sqrt{EA/\rho_A}`.
oscillations) therefore change with the mesh. The initialisation of a dynamic run notes, for every
line with a negative ``BA``, the damping ratio this gives its first axial mode on its final mesh:
the Rayleigh quotient :math:`\zeta_1 = \mathbf u^\mathsf T\mathbf C\mathbf u /
(2\,\omega_1\,\mathbf u^\mathsf T\mathbf M\mathbf u)` of the first mode :math:`\mathbf u` of the
line's axial chain with both ends held (element stiffness :math:`EA/L_0`, damping
:math:`BA/L_0`, the dry mass lumped at the nodes), which is :math:`\zeta\sin(\pi/(2N))` on a
uniform line and holds for a composite one.

**First-mode damping ratio** (``mode1 axialDampingRatio``, :doc:`options`). A negative ``BA`` is
then the damping ratio of the line's first axial mode, the same on any mesh:

.. math::

BA = \frac{2\,\zeta\,EA}{\omega_1}

on every element, with :math:`\omega_1` the first axial natural frequency of the line with both
ends held, from its sections' unstretched lengths, ``EA`` and dry mass per length (the first mode
of the axial chain on a fixed internal mesh of 2048 elements, so independent of the line's mesh;
:math:`\omega_1 = (\pi/L)\sqrt{EA/\rho_A}` on a uniform line, to 1e-7). The damping is then
proportional to the stiffness, :math:`\mathbf C = (2\zeta/\omega_1)\,\mathbf K`, so the first
axial mode of a composite line is damped at :math:`\zeta` too and the mode :math:`n` at
:math:`\zeta\,\omega_n/\omega_1`. Added mass and the tension are left out of :math:`\omega_1`. A
viscoelastic or Syrope section has no single ``EA`` that sets the first mode, so a line with one
and a negative ``BA`` is refused under this option; ``BA`` in N·s is used as given under both
conventions.

Viscoelastic rope (MoorDyn ``ElasticMod`` 2 and 3)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -988,7 +1010,17 @@ With the relative velocity :math:`\mathbf{u}_r = \mathbf{u}_f - \mathbf{v}` spli
+ \tfrac{1}{2}\rho\,\pi d\,C_{d,t}\,\lvert\mathbf{u}_{r,t}\rvert\,\mathbf{u}_{r,t}.

Its derivatives with respect to position (through :math:`\mathbf{t}`) and velocity enter the
implicit tangent exactly.
implicit tangent exactly. The length is the element's unstretched length :math:`L_0` on the
``EI = 0`` path (with the chord tangent and the wet-weighted relative velocity) and
the deformed length :math:`\lvert\mathbf r_{,\xi}\rvert\,\mathrm{d}\xi` of the cubic centreline
on the Hermite path (three Gauss points per element). At rest in a current the end reactions
(``FairTen``/``AnchTen``, ``Point<P>F``) balance the weight and this drag to the static
tolerance, about :math:`10^{-8}` of the end force, pinned or clamped ends alike. A check of the
balance must integrate the drag the same way: on straight chords between the nodes of a
finite-EI line it misses by a share that falls with the square of the element length
(:math:`3\times10^{-5}` of the end force on 1.25 m elements of a cable in a 1 m/s current,
:math:`4.5\times10^{-4}` on 5 m elements), and per unstretched length by about the axial strain
times the drag.

Added mass and fluid inertia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -1079,6 +1111,8 @@ 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-dry-buoyancy:

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

Expand Down Expand Up @@ -1406,7 +1440,15 @@ laid node sinks into the penalty seabed along its normal by its static penetrati
slope moves it horizontally by :math:`w_i\,(z_{,x}, z_{,y})/k_i`, with :math:`w_i` its nodal
load: its share of the line's submerged weight, plus the net weight of a discrete attachment
lumped at it (the finite-EI solve first smears an attachment over the two elements at its
node, then rebuilds the reference for the discrete loads before it polishes to them). Where
node, then rebuilds the reference for the discrete loads before it polishes to them). It is the
normal load the solver applies to the node resting at its laid position: a finite-EI section
that lies within its radius of the still-water level there (a seabed shallower than the cable
radius) carries the buoyancy of its dry part, as in the static solve and the dynamics
(:ref:`buoyancy recovery <theory-dry-buoyancy>`), at the height the node sinks to under that
load, :math:`z_f - w_i s^2/k_i`, and an attachment above the level its dry weight. The seabed
lies below the still-water level everywhere (a positive ``WtrDpth`` and positive bathymetry
depths), so a grounded node with its attachment stays submerged; an ``EI = 0`` line, whose
submergence follows its node heights, is wholly submerged where it is grounded. Where
the slope varies, the laid tension turns at every node and adds
:math:`-T_\text{laid}\,(\mathbf{t}_{i}^{+} - \mathbf{t}_{i}^{-})\cdot\mathbf{n}_i` to the
normal load (it presses the line into a crest and lifts it from a hollow), with
Expand Down
2 changes: 2 additions & 0 deletions examples/cabledyn_options_reference.dat
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ none waves - Wave model and parameters (m, s, deg) {none; airy;
-- 0.5 frictionMuAxial - Seabed friction along the line axis {>=0} [default: frictionMu]
-- 0.5 frictionMuLateral - Seabed friction across the line axis {>=0} [default: frictionMu]
-- asLaid staticsFriction - Statics seabed friction policy {none; asLaid} [default: none]
-- mode1 axialDampingRatio - A negative BA is the damping ratio of {segment=each segment; mode1=the first axial mode} [default: segment]
-- 0.0 layAzimuth - Lay azimuth of every line from +x toward +y (deg) [default: anchor -> fairlead]
-- 225.0 layAzimuth2 - Lay azimuth of line 2 alone (deg) [default: layAzimuth]
-- 0.0 asLaidTension - As-laid effective tension of every line (N) [default: 0]
Expand All @@ -108,6 +109,7 @@ none waves - Wave model and parameters (m, s, deg) {none; airy;
-- layAzimuth = lay_azimuth; asLaidTension = as_laid_tension
-- dtM = dt; rhoInf = rho_inf; modified_newton = modifiedNewton; adaptive_mesh = adaptiveMesh
-- cable_statics = cableStatics; alpha_force_blend = alphaForceBlend; OutputRecovery = output_recovery
-- axialDampingRatio = axial_damping_ratio
-- maxStrain = max_strain; WaveSeed = wave_seed; rampTime = ramp_time = tRamp
-- RangeStart = range_start
-- cable_load_feedback = cableLoadFeedback; tensile_safety = tensileSafety
Expand Down
9 changes: 9 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,8 @@
"as_laid_tension": "as_laid_tension",
"outputrecovery": "output_recovery",
"output_recovery": "output_recovery",
"axialdampingratio": "axial_damping_ratio",
"axial_damping_ratio": "axial_damping_ratio",
}
# Per-line static friction rows (native apply_option): ``layAzimuth<ID>`` and ``asLaidTension<ID>``
# with the LINE id appended; the id is a plain decimal suffix, and leading zeros name the same line.
Expand Down Expand Up @@ -1338,6 +1340,13 @@ def _scalar_option_value_error(keyword: str, value: str) -> str | None:
if value.lower() in {"continuation", "sequenced"}
else "must be continuation or sequenced"
)
if key == "axial_damping_ratio":
# native: the value is dequoted and compared case-insensitively
return (
None
if _strip_quotes(value).lower() in {"segment", "mode1"}
else "must be segment or mode1"
)
if key == "output_recovery":
return (
None
Expand Down
5 changes: 5 additions & 0 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -673,6 +673,8 @@ def test_unknown_scalar_option_keyword_fails_closed(tmp_path):
("maybe", "alpha_force_blend", "native boolean"),
("relaxed", "cable_statics", "continuation or sequenced"),
("nodal", "OutputRecovery", "equilibrium or element"),
("mode2", "axialDampingRatio", "segment or mode1"),
("element", "axial_damping_ratio", "segment or mode1"),
("on", "ei0_substeps", "auto or off"),
("0", "ei0_substep_angle", r"\(0, 90\] deg"),
("91", "ei0SubstepAngle", r"\(0, 90\] deg"),
Expand Down Expand Up @@ -758,6 +760,9 @@ def test_zero_e_exponent_waterkin_mode_is_accepted(tmp_path):
"sequenced cableStatics",
"equilibrium OutputRecovery",
"element output_recovery",
"segment axialDampingRatio",
"mode1 axial_damping_ratio",
"MODE1 AXIALDAMPINGRATIO",
"auto ei0_substeps",
"off ei0Substeps",
"0.5 ei0_substep_angle",
Expand Down
16 changes: 16 additions & 0 deletions python/tests/test_init_notes.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

from __future__ import annotations

import math
import os
import re
import subprocess
Expand Down Expand Up @@ -119,6 +120,21 @@ def test_the_notes_of_a_deck_on_both_routes(tmp_path):
assert "LINE 1: dtM = 0.1000 s resolves its axial period" in notes


@pytest.mark.parametrize("ei", [0.0, 1.0e6], ids=["point", "aggregate"])
def test_the_axial_damping_note_reaches_an_in_process_host(tmp_path, ei):
# BA = -1 is a damping ratio per segment: the note gives the first-mode ratio of the mesh
with CableDyn(_deck(tmp_path, ei=ei)) as model:
notes = [note for note in model.init_notes if "damping ratio per segment" in note]
assert len(notes) == 1
match = re.search(r"at ([0-9.]+) % of critical on its ([0-9]+) elements", notes[0])
assert match is not None, notes[0]
# zeta pi/(2N) on the uniform chain, N its final mesh
expected = 100.0 * math.pi / (2 * int(match.group(2)))
assert float(match.group(1)) == pytest.approx(expected, rel=1e-3)
with CableDyn(_deck(tmp_path, "mode1 axialDampingRatio", ei=ei, name="mode1.dat")) as model:
assert not [note for note in model.init_notes if "damping ratio per segment" in note]


def test_a_note_of_the_parse_is_kept_once(tmp_path):
# the deck is read twice, to find its route and to build it
(tmp_path / "current_profile_dynamic.txt").write_text(CONSTANT_GRID, encoding="utf-8")
Expand Down
Loading
Loading