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

### Added

- 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
`alpha = 4 pi zeta f1 f2/(f1 + f2)` [1/s], the force `alpha m` on the velocity normal to the
tangent, so a mode has `zeta(omega) = alpha/(2 omega) + omega Bb/(2 EI)` times its bending share
for `Bb`: `zeta` at `f1` and `f2` and less between them. Free decays of modes 1 to 3 of a pinned
cable match this to 0.06 %. The velocity is absolute, so rigid transverse and pendulum motion is
damped as well (more below `f1`). No new state; exact Jacobians; the work is in `DampPow`; the
Python deck reader and builder take the form. Existing decks give bit-identical outputs.
- A finite-EI line may end on a `Free` point: the line's free End B, its position free in the
static equilibrium and the dynamics, with the point's Mass/Vol/CdA/Ca acting on the end node as
an attachment (a free-hanging cable or riser with a clump). The static solve holds the end on
Expand Down
12 changes: 11 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -774,7 +774,15 @@ add_executable(test_hermite_bending_damping_dynamic tests/test_hermite_bending_d
target_link_libraries(test_hermite_bending_damping_dynamic PRIVATE cabledyn_core)
add_test(NAME hermite_bending_damping_dynamic COMMAND test_hermite_bending_damping_dynamic)
set_tests_properties(hermite_bending_damping_dynamic PROPERTIES LABELS "fortran;unit;dynamic;damping")
# Bending damping on a deck (EI|Bb, EI|-zeta|f): resolution, effect and refusals end to end.
add_executable(test_hermite_mass_damping tests/test_hermite_mass_damping.f90)
target_link_libraries(test_hermite_mass_damping PRIVATE cabledyn_core)
add_test(NAME hermite_mass_damping COMMAND test_hermite_mass_damping)
set_tests_properties(hermite_mass_damping PROPERTIES LABELS "fortran;unit;damping")
add_executable(test_hermite_mass_damping_dynamic tests/test_hermite_mass_damping_dynamic.f90)
target_link_libraries(test_hermite_mass_damping_dynamic PRIVATE cabledyn_core)
add_test(NAME hermite_mass_damping_dynamic COMMAND test_hermite_mass_damping_dynamic)
set_tests_properties(hermite_mass_damping_dynamic PROPERTIES LABELS "fortran;unit;dynamic;damping")
# Bending damping on a deck (EI|Bb, EI|-zeta|f, EI|-zeta|f1|f2): resolution, effect and refusals end to end.
add_executable(test_bending_damping_deck tests/test_bending_damping_deck.f90)
target_link_libraries(test_bending_damping_deck PRIVATE cabledyn_core)
add_test(NAME bending_damping_deck COMMAND test_bending_damping_deck)
Expand Down Expand Up @@ -3554,6 +3562,8 @@ if(CABLEDYN_ENABLE_COVERAGE)
test_hermite_axial_damping
test_hermite_bending_damping
test_hermite_bending_damping_dynamic
test_hermite_mass_damping
test_hermite_mass_damping_dynamic
test_bending_damping_deck
test_hermite_cable_control
test_control_torsion
Expand Down
5 changes: 5 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,11 @@ Line and constitutive capability
- a bending Kelvin–Voigt damping on the curvature rate (stiffness-proportional in ``EI``;
a mode is damped in its bending share), on every dynamic route that carries the cable,
beside the axial (``BA``) and torsional (``GJ|K|Bt``) damping (:doc:`theory`)
* - Rayleigh damping of finite-EI cables (``EI|-zeta|f1|f2``)
- Supported
- the bending damping plus a mass-proportional transverse damping ``alpha m`` on the
velocity normal to the tangent, holding a damping ratio at two frequencies; absolute
velocity, so rigid transverse and pendulum motion is damped too (:doc:`theory`)
* - Hockling loops, nonlinear cross-section laws
- Not provided
- the buckling onset and the post-buckled shape are computed, but a loop that closes on
Expand Down
15 changes: 13 additions & 2 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ Inside OUTPUTS, a row whose first token is `END` also closes the channel list.
| `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): 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²]; `EI|Bb` or `EI|-zeta|f` adds bending damping (below) | finite and ≥ 0; see [EI routing](#ei-routing) |
| `EI` | bending stiffness [N·m²]; `EI|Bb` or `EI|-zeta|f` adds bending damping, `EI|-zeta|f1|f2` Rayleigh damping (below) | 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 @@ -295,6 +295,17 @@ 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).

**Rayleigh damping.** `EI|-zeta|f1|f2` gives the ratio `0 < ζ < 1` at two frequencies `f1` and `f2`
[Hz]: beside the bending damping `Bb = ζ EI/(π (f1 + f2))` it adds a mass-proportional transverse
damping `α = 4π ζ f1 f2/(f1 + f2)` [1/s], the force `α m` (`m` the line's mass per metre) on the
velocity normal to the cable's tangent (see [Mass-proportional damping](theory.rst)). A mode then
has `ζ(ω) = α/(2ω) + ω Bb/(2 EI) · EI k²/(EI k² + T)`: `ζ` at `f1` and `f2` for a mode whose
stiffness is all bending, less between them and more outside. In water the `α` share falls with
the added mass, `m/(m + m_a)`. The velocity is absolute, so the term also damps the rigid
transverse motion and pendulum swing of a span, increasingly below `f1` (`α/(2ω)`): set `f1` at
the lowest frequency of interest. It needs `EI > 0`, is set once per line type and acts in the
dynamics only.

**Cross-flow VIV columns (MoorDyn v2).** A 10-column row may end with `Cl` (11 columns) or
`Cl dF cF` (13 columns), and a 14-column row likewise (15 or 17 columns, so a line restrained in
torsion can carry VIV): the lift coefficient of the vortex-shedding synchronisation model and
Expand Down Expand Up @@ -1924,7 +1935,7 @@ bending moment. None of these channels is mandatory.
| `Twist<L>` | line L total twist `Phi − Theta = M C`, end-spring windup included; on a line free at one end the twist of its elements, the free end's turn. Only on a line solved in torsion | deg |
| `VIVPow<L>` | line L power of the VIV loads (cross-flow lift, and the in-line force of a `VIV` section row) at the committed state, positive into the line ([Outputs](outputs.rst)); 0 in static runs | W |
| `DragPow<L>` | line L power of the Morison drag (and, on a finite-EI line, its ATTACHMENTS' drag) | W |
| `DampPow<L>` | line L power of the structural damping (`BA`, and `EI|Bb` on a finite-EI line); never positive | W |
| `DampPow<L>` | line L power of the structural damping (`BA`, and `EI|Bb` and the mass-proportional part of `EI|-zeta|f1|f2` on a finite-EI line); never positive | W |
| `VIVPow<L>N<J>`, `DragPow<L>N<J>`, `DampPow<L>N<J>` | the same per unit unstretched length about node J (node J's share: half of each of its elements' power and its own node loads', over half their unstretched length) | W/m |
| `VIVAmp<L>N<J>` | line L smoothed cross-flow amplitude estimate at node J (Thorsen et al. 2016, Eq. 9), which a [VIV AMPLITUDE](#viv-amplitude-optional) table reads; only on a line with such a table; 0 at a node without VIV | m |

Expand Down
3 changes: 2 additions & 1 deletion doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -890,7 +890,8 @@ committed state, positive when the load puts energy into the line:
- W
* - ``DampPow<L>``
- power of the structural damping: the axial dashpot ``BA`` and, on a finite-EI line, the
bending dashpot (``EI|Bb``); never positive
bending dashpot (``EI|Bb``) and the mass-proportional damping (``EI|-zeta|f1|f2``); never
positive
- W
* - ``VIVPow<L>N<J>``, ``DragPow<L>N<J>``, ``DampPow<L>N<J>``
- the same per unit unstretched length about node ``J``
Expand Down
72 changes: 72 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -916,6 +916,78 @@ pinned cable reproduces this ratio to 0.05 % in the bending- and tension-dominat
(``test_hermite_bending_damping_dynamic``). The force joins the axial damping as the structural
damping load (it is in the reported end forces, not in the elastic ``BendMom`` output).

.. _theory-mass-damping:

Mass-proportional (Rayleigh) damping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The bending damping alone gives :math:`\zeta \propto \omega`: a ratio set at one frequency is too
low below it and too high above it, so a broad VIV band cannot hold one :math:`\zeta`. The form
``EI|-zeta|f1|f2`` (LINE TYPES) adds a mass-proportional term, which makes the pair a Rayleigh
damping :math:`\alpha\,\mathbf M + \beta\,\mathbf K_b` with :math:`\beta = B_b/EI`. With
:math:`\mathbf v = \dot{\mathbf r}` the velocity interpolated by the shape functions of the
consistent mass and :math:`m` the line's mass per unstretched length (``MassDenInAir``, with a
stiffener sleeve's where ``STIFFENERS`` adds one), the
element's dissipation function is

.. math::

\psi_\alpha = \int_0^{L_0} \tfrac{1}{2}\,\alpha\,m\,
\lvert(\mathbf{I} - \mathbf{t}\mathbf{t}^\mathsf{T})\,\mathbf v\rvert^2\,\mathrm{d}s ,

and the damping force is :math:`\mathbf f_\alpha = \partial\psi_\alpha/\partial\dot{\mathbf q} =
\int_0^{L_0} \alpha\,m\,\mathbf N^\mathsf{T}(\mathbf I - \mathbf t\mathbf t^\mathsf{T})\,\mathbf v\,\mathrm ds`
(:math:`\mathbf N` the cubic-Hermite position shape functions, four-point Gauss rule as the mass).
Its velocity Jacobian :math:`\int \alpha m\,\mathbf N^\mathsf{T}(\mathbf I - \mathbf t\mathbf t^\mathsf{T})
\mathbf N\,\mathrm ds` is symmetric; its position Jacobian follows from
:math:`\partial\mathbf t/\partial\mathbf r' = (\mathbf I - \mathbf t\mathbf t^\mathsf{T})/\lvert\mathbf r'\rvert`,

.. math::

\frac{\partial \mathbf f_\alpha}{\partial \mathbf q} = -\int_0^{L_0} \frac{\alpha\,m}{\lvert\mathbf r'\rvert}\,
\mathbf N^\mathsf{T}\Big[(\mathbf I - \mathbf t\mathbf t^\mathsf{T})(\mathbf t\cdot\mathbf v)
+ \mathbf t\,\big((\mathbf I - \mathbf t\mathbf t^\mathsf{T})\mathbf v\big)^\mathsf{T}\Big]\,
\mathbf N_{,s}\,\mathrm ds ,

so the Newton tangent stays exact. On a straight span the force is :math:`\alpha\,\mathbf M\,\mathbf v`
in the two transverse directions and zero along the axis: axial motion is left to ``BA``. A
transverse mode whose modal mass is the line's own is damped at :math:`\alpha/(2\omega)`, and with
the bending damping the ratio is

.. math::

\zeta(\omega) = \frac{\alpha}{2\,\omega} + \frac{\omega\,B_b}{2\,EI}\;\frac{EI\,k^2}{EI\,k^2 + T} .

``EI|-zeta|f1|f2`` sets

.. math::

B_b = \frac{\zeta\,EI}{\pi\,(f_1 + f_2)}, \qquad \alpha = \frac{4\pi\,\zeta\,f_1 f_2}{f_1 + f_2} ,

so a mode whose stiffness is all bending has the ratio :math:`\zeta` at :math:`f_1` and
:math:`f_2`, less between them (at least :math:`2\zeta\sqrt{f_1 f_2}/(f_1 + f_2)`, at
:math:`\sqrt{f_1 f_2}`) and more outside. Free decays of modes 1, 2 and 3 of a pinned cable
reproduce :math:`\zeta(\omega)` for :math:`\alpha` alone, :math:`B_b` alone and both to 0.06 %, and
the target at :math:`f_1` and :math:`f_2` to 0.03 % (``test_hermite_mass_damping_dynamic``).
The
ratio is lower in two cases: :math:`B_b` damps a mode with tension in its bending share only, and
:math:`\alpha` damps a mode in water in the share :math:`m/(m + m_a)` of its modal mass, since the
added mass :math:`m_a` (and an attachment's mass) is not in :math:`\alpha\,\mathbf M`.

The velocity is absolute (the earth frame), as in the usual Rayleigh model. The term therefore
damps a rigid transverse translation and the pendulum swing of a span, and it opposes the
transverse motion a moving fairlead imposes, as a linear drag :math:`\alpha m\,\mathbf v_n` would in
still water. Its ratio :math:`\alpha/(2\omega)` grows as the frequency falls, so motions well below
:math:`f_1` (slow drift, a moored line's pendulum and the low-frequency response of a coupled
floater) are damped more than the target; set :math:`f_1` at the lowest frequency the analysis
must resolve and compare the low-frequency response against the run without the pair. A velocity
relative to the cable's filtered motion (the frame :ref:`theory-viv-frame` uses) would exempt
slow motions, but it adds a filter state, lags the damping and replaces :math:`\alpha/(2\omega)`
by a factor that depends on the filter, so the pair would no longer hold :math:`\zeta` at
:math:`f_1`; CableDyn keeps the absolute velocity and no state. The force joins the structural
damping load beside ``BA`` and :math:`B_b` (the end forces and ``DampPow`` carry it). ``EI = 0``
lines have no counterpart: the form needs a finite-EI cable, as the bending damping does.

Viscoelastic rope (MoorDyn ``ElasticMod`` 2 and 3)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
10 changes: 7 additions & 3 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,9 @@ class LineType:
Bending stiffness, in N m^2; ``(EI, Bb)`` adds the bending damping
``Bb`` in N m^2 s (written ``EI|Bb``), and ``(EI, -zeta, f)`` gives it
as the damping ratio ``zeta`` of a bending mode of frequency ``f`` in Hz
(written ``EI|-zeta|f``; ``Bb = zeta EI / (pi f)``).
(written ``EI|-zeta|f``; ``Bb = zeta EI / (pi f)``); ``(EI, -zeta, f1, f2)``
adds the mass-proportional damping ``alpha`` beside ``Bb``, the Rayleigh
pair that holds ``zeta`` at ``f1`` and ``f2`` (written ``EI|-zeta|f1|f2``).
cdn, cdt, can, cat : float
Normal and tangential drag and added-mass coefficients.
gas, gj, irt, irn : float | None
Expand Down Expand Up @@ -2768,8 +2770,10 @@ def _line_type_table(self) -> tuple[str, str, list[list[str]]]:
row.append(f'"{_render(ea)}"')
else:
row.append(_multi(item.ea, what))
if isinstance(item.ei, tuple) and len(item.ei) not in (2, 3):
raise ValueError(f"{what}: ei is EI, (EI, Bb) or (EI, -zeta, f)")
if isinstance(item.ei, tuple) and len(item.ei) not in (2, 3, 4):
raise ValueError(
f"{what}: ei is EI, (EI, Bb), (EI, -zeta, f) or (EI, -zeta, f1, f2)"
)
row += [_multi(item.ba, what), _multi(item.ei, what)]
extra = (item.gas, item.gj, item.irt, item.irn)
if all(value is not None for value in extra):
Expand Down
30 changes: 23 additions & 7 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -4195,7 +4195,7 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
if len(row.tokens) >= 14 and index == 7:
continue # the GJ column, GJ, GJ|K or GJ|K|Bt, is read below
if index == 5:
continue # the EI column, EI, EI|Bb or EI|-zeta|f, is read below
continue # the EI column (EI, EI|Bb, EI|-zeta|f, EI|-zeta|f1|f2) is read below
numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}")
ea_parts = row.tokens[3].split("|")
ba_parts = row.tokens[4].split("|")
Expand Down Expand Up @@ -4257,12 +4257,13 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
f"{self._at(row)}: LINE TYPES drag and added-mass coefficients "
"(Cd_n Cd_t Ca_n Ca_t) must be non-negative"
)
# native parse_ei_column: EI, EI|Bb (bending damping, N m^2 s) or EI|-zeta|f
# native parse_ei_column: EI, EI|Bb (bending damping, N m^2 s), EI|-zeta|f or
# EI|-zeta|f1|f2 (the Rayleigh pair of Bb and the mass-proportional alpha)
ei_parts = row.tokens[5].split("|")
if len(ei_parts) > 3:
if len(ei_parts) > 4:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}" takes EI, EI|Bb '
"or EI|-zeta|f"
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}" takes EI, EI|Bb, '
"EI|-zeta|f or EI|-zeta|f1|f2"
)
ei = numeric(ei_parts[0], row, "EI")
bend_damping = 0.0
Expand All @@ -4287,9 +4288,24 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
"of EI|-zeta|f must be positive [Hz]"
)
bend_damping = -ratio * ei / (math.pi * frequency)
# a damping asked for (the ratio form, or Bb > 0) needs a finite EI: on EI = 0 the
elif len(ei_parts) == 4:
ratio = numeric(ei_parts[1], row, "EI|-zeta|f1|f2 ratio")
f_one = numeric(ei_parts[2], row, "EI|-zeta|f1|f2 frequency f1")
f_two = numeric(ei_parts[3], row, "EI|-zeta|f1|f2 frequency f2")
if not -1.0 < ratio < 0.0:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}": '
"EI|-zeta|f1|f2 takes a damping ratio 0 < zeta < 1, written negative"
)
if not (f_one > 0.0 and f_two > 0.0):
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}": the '
"frequencies f1 and f2 of EI|-zeta|f1|f2 must be positive [Hz]"
)
bend_damping = -ratio * ei / (math.pi * (f_one + f_two))
# a damping asked for (a ratio form, or Bb > 0) needs a finite EI: on EI = 0 the
# ratio form resolves to Bb = 0 and would pass unnoticed
if (len(ei_parts) == 3 or bend_damping > 0.0) and not ei > 0.0:
if (len(ei_parts) >= 3 or bend_damping > 0.0) and not ei > 0.0:
raise DeckFormatError(
f"{self._at(row)}: LINE TYPES {row.tokens[0]}: bending damping (EI|Bb) needs "
"a finite-EI cable (EI > 0)"
Expand Down
8 changes: 5 additions & 3 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -1155,7 +1155,7 @@ def test_torsional_damping_round_trips_in_the_gj_column(tmp_path: Path) -> None:
assert next(t for t in loaded.line_types if t.name == "cable").gj == (1.0e4, 0.0, -0.02)


@pytest.mark.parametrize("ei", [(1.0e4, 250.0), (1.0e4, -0.02, 1.5)])
@pytest.mark.parametrize("ei", [(1.0e4, 250.0), (1.0e4, -0.02, 1.5), (1.0e4, -0.02, 0.5, 2.0)])
def test_bending_damping_round_trips_in_the_ei_column(
tmp_path: Path, ei: tuple[float, ...]
) -> None:
Expand Down Expand Up @@ -1232,8 +1232,10 @@ def test_no_viv_section_without_inline_viv(tmp_path: Path) -> None:

def test_bending_damping_ei_tuple_length_is_checked(tmp_path: Path) -> None:
model = _chain_model(tmp_path)
model.add_line_type("cable", diam=0.2, mass=40.0, ea=5.0e8, ei=(1.0e4, 1.0, 2.0, 3.0))
with pytest.raises(ValueError, match=r"ei is EI, \(EI, Bb\) or \(EI, -zeta, f\)"):
model.add_line_type("cable", diam=0.2, mass=40.0, ea=5.0e8, ei=(1.0e4, -0.02, 1.0, 2.0, 3.0))
with pytest.raises(
ValueError, match=r"ei is EI, \(EI, Bb\), \(EI, -zeta, f\) or \(EI, -zeta, f1, f2\)"
):
model.to_text()


Expand Down
Loading
Loading