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

## [Unreleased]

### Added

- Bending damping of finite-EI cables: the LINE TYPES EI column takes `EI|Bb`, a Kelvin-Voigt
damping moment `Bb` [N m^2 s] times the curvature rate (in the frame carried with the tangent),
or `EI|-zeta|f`, the damping ratio of a pure bending mode of frequency `f` (Bb = zeta EI/(pi f)).
A mode is damped in its bending share, `omega Bb/(2 EI) * EI k^2/(EI k^2 + T)`; free decays of a
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.

## [0.4.2] - 2026-11-09

### Added
Expand Down
16 changes: 16 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -766,6 +766,19 @@ add_executable(test_hermite_axial_damping tests/test_hermite_axial_damping.f90)
target_link_libraries(test_hermite_axial_damping PRIVATE cabledyn_core)
add_test(NAME hermite_axial_damping COMMAND test_hermite_axial_damping)
set_tests_properties(hermite_axial_damping PROPERTIES LABELS "fortran;unit;dynamic;damping")
add_executable(test_hermite_bending_damping tests/test_hermite_bending_damping.f90)
target_link_libraries(test_hermite_bending_damping PRIVATE cabledyn_core)
add_test(NAME hermite_bending_damping COMMAND test_hermite_bending_damping)
set_tests_properties(hermite_bending_damping PROPERTIES LABELS "fortran;unit;damping")
add_executable(test_hermite_bending_damping_dynamic tests/test_hermite_bending_damping_dynamic.f90)
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_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)
set_tests_properties(bending_damping_deck PROPERTIES LABELS "fortran;driver;integration;dynamic;damping")

# Active line control of a finite-EI cable: the length update rebuilds the caches a fresh
# build carries (bit for bit), is atomic and rewinds exactly; hanging, taut and paid-out
Expand Down Expand Up @@ -3436,6 +3449,9 @@ if(CABLEDYN_ENABLE_COVERAGE)
test_hermite_cable_dynamic
test_hermite_drag_dynamics
test_hermite_axial_damping
test_hermite_bending_damping
test_hermite_bending_damping_dynamic
test_bending_damping_deck
test_hermite_cable_control
test_control_torsion
test_hermite_added_mass
Expand Down
5 changes: 5 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,11 @@ Line and constitutive capability
``Coupled``/``Vessel`` rods, bodies other than Rigid6 and ``False alpha_force_blend``.
Modal analysis carries the twist angle of every node. Not modelled: seabed friction
against twist, anisotropic sections, self-contact of a loop (see :ref:`theory-torsion`)
* - Bending damping of finite-EI cables (``EI|Bb``, ``EI|-zeta|f``)
- Supported
- 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`)
* - 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
13 changes: 12 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,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²] | finite and ≥ 0; see [EI routing](#ei-routing) |
| `EI` | bending stiffness [N·m²]; `EI|Bb` or `EI|-zeta|f` adds bending 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 @@ -278,6 +278,17 @@ cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`; see
active line control changes keeps its `ζ`). It needs a finite-EI type; `GJ|0|Bt` is damping
without coupling.

**Bending damping.** The `EI` column may be written `EI|Bb`, with `Bb` [N·m²·s] the bending
Kelvin–Voigt damping of a finite-EI cable: a damping moment `Bb` times the rate of the curvature
vector, taken in the frame carried with the cable's tangent (see [Bending damping](theory.rst)). It
is stiffness-proportional: a bending mode of frequency `ω` whose strain energy is all bending has
the damping ratio `ω Bb/(2 EI)`, and a mode that tension also stiffens is damped only in its
bending share, `ω Bb/(2 EI) · EI k²/(EI k² + T)` for a uniform cable of wavenumber `k` under
tension `T`. `EI|-zeta|f` gives it as the damping ratio `0 < ζ < 1` of a pure bending mode of
frequency `f` [Hz], `Bb = ζ EI/(π f)`, set once per line type (it does not depend on the mesh).
`EI|0` is the plain `EI`. It needs `EI > 0` and acts in the dynamics only (a static solve has no
rates).

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

Expand Down
43 changes: 43 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -837,6 +837,49 @@ viscoelastic or Syrope section has no single ``EA`` that sets the first mode, so
and a negative ``BA`` is refused under this option; ``BA`` in N·s is used as given under both
conventions.

Bending damping
~~~~~~~~~~~~~~~

A finite-EI cable can carry a bending Kelvin–Voigt damping (``EI|Bb`` or ``EI|-zeta|f`` in
LINE TYPES, see :doc:`file_formats`). With :math:`\mathbf{a} = \mathbf{r}_{,s}`,
:math:`\mathbf{b} = \mathbf{r}_{,ss}` and the curvature vector of the elastic energy
:math:`\boldsymbol{\kappa} = \mathbf{a}\times\mathbf{b}/\lvert\mathbf{a}\rvert^3`, the element's
dissipation function is

.. math::

\psi = \int_0^{L_0} \tfrac{1}{2}\,B_b\,\lvert\mathring{\boldsymbol{\kappa}}\rvert^2\,\mathrm{d}s,
\qquad
\mathring{\boldsymbol{\kappa}} = (\mathbf{I} - \mathbf{t}\mathbf{t}^\mathsf{T})\,\dot{\boldsymbol{\kappa}},
\qquad \mathbf{t} = \mathbf{a}/\lvert\mathbf{a}\rvert ,

and the damping force is :math:`\partial\psi/\partial\mathbf{v}`, with exact position and velocity
Jacobians. Under active line control (``CONTROL``) the curvature rate also carries the change of
the element's unstretched length, on which the shape functions depend, as the axial strain rate
does. Because :math:`\boldsymbol{\kappa}` is normal to :math:`\mathbf{t}`,
:math:`\mathring{\boldsymbol{\kappa}} = \dot{\boldsymbol{\kappa}} - (\mathbf{t}\times\dot{\mathbf{t}})
\times\boldsymbol{\kappa}`: the curvature rate in the frame carried with the tangent by the smallest
rotation. It vanishes for a rigid motion whose rotation
is normal to the tangent and equals :math:`\dot{\boldsymbol{\kappa}}` in planar bending. Without a
twist state, a curvature that turns about the centreline cannot be told from a whirl and is damped
as one; for a rigid rotation about the tangent of a curved span (the out-of-plane swing of a
catenary) the force is of order :math:`B_b\kappa^2` and negligible against the span's inertia.

The damping is stiffness-proportional in the bending stiffness alone. A uniform cable of tension
:math:`T` vibrating in a mode of wavenumber :math:`k` and frequency :math:`\omega` has the damping
ratio

.. math::

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

the pure-bending ratio times the bending share of the modal stiffness: a tension-dominated mode is
damped much less than a bending one. ``EI|-zeta|f`` sets :math:`B_b = \zeta\,EI/(\pi f)`, the ratio
:math:`\zeta` of a pure bending mode of frequency :math:`f`. The free decay of the first mode of a
pinned cable reproduces this ratio to 0.05 % in the bending- and tension-dominated limits
(``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).

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

Expand Down
17 changes: 11 additions & 6 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,11 @@ class LineType:
viscoelastic type, or a :class:`SyropeEA`.
ba : float | tuple[float, ...]
Axial damping in N s (negative: damping ratio), or ``(Bs, Bd)``.
ei : float
Bending stiffness, in N m^2.
ei : float | tuple[float, ...]
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)``).
cdn, cdt, can, cat : float
Normal and tangential drag and added-mass coefficients.
gas, gj, irt, irn : float | None
Expand All @@ -211,7 +214,7 @@ class LineType:
mass: float
ea: float | tuple[float, ...] | SyropeEA
ba: float | tuple[float, ...] = 0.0
ei: float = 0.0
ei: float | tuple[float, ...] = 0.0
cdn: float = 0.0
cdt: float = 0.0
can: float = 0.0
Expand Down Expand Up @@ -1627,7 +1630,7 @@ def add_line_type(
mass: float,
ea: float | tuple[float, ...] | SyropeEA,
ba: float | tuple[float, ...] = 0.0,
ei: float = 0.0,
ei: float | tuple[float, ...] = 0.0,
cdn: float = 0.0,
cdt: float = 0.0,
can: float = 0.0,
Expand Down Expand Up @@ -2661,7 +2664,9 @@ def _line_type_table(self) -> tuple[str, str, list[list[str]]]:
row.append(f'"{_render(ea)}"')
else:
row.append(_multi(item.ea, what))
row += [_multi(item.ba, what), _num(item.ei, 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)")
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):
wide = True
Expand Down Expand Up @@ -3171,7 +3176,7 @@ def line_type(self, row: DeckRecord) -> None:
mass=_f(values["mass"]),
ea=ea,
ba=_fmulti(values["ba"]),
ei=_f(values["ei"]),
ei=_fmulti(values["ei"]),
cdn=_f(values["cdn"]),
cdt=_f(values["cdt"]),
can=_f(values["can"]),
Expand Down
40 changes: 39 additions & 1 deletion python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3729,6 +3729,8 @@ def numeric(token: str, row: DeckRecord, field: str) -> float:
for index in (1, 2, *range(5, len(row.tokens))):
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
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 @@ -3790,7 +3792,43 @@ 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"
)
ei = numeric(row.tokens[5], row, "EI")
# native parse_ei_column: EI, EI|Bb (bending damping, N m^2 s) or EI|-zeta|f
ei_parts = row.tokens[5].split("|")
if len(ei_parts) > 3:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}" takes EI, EI|Bb '
"or EI|-zeta|f"
)
ei = numeric(ei_parts[0], row, "EI")
bend_damping = 0.0
if len(ei_parts) == 2:
bend_damping = numeric(ei_parts[1], row, "EI|Bb damping")
if bend_damping < 0.0:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}": a negative '
"bending damping is -zeta and needs the frequency it holds at, EI|-zeta|f"
)
elif len(ei_parts) == 3:
ratio = numeric(ei_parts[1], row, "EI|-zeta|f ratio")
frequency = numeric(ei_parts[2], row, "EI|-zeta|f frequency")
if not -1.0 < ratio < 0.0:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}": '
"EI|-zeta|f takes a damping ratio 0 < zeta < 1, written negative"
)
if not frequency > 0.0:
raise DeckFormatError(
f'{self._at(row)}: LINE TYPES EI column "{row.tokens[5]}": the frequency f '
"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
# 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:
raise DeckFormatError(
f"{self._at(row)}: LINE TYPES {row.tokens[0]}: bending damping (EI|Bb) needs "
"a finite-EI cable (EI > 0)"
)
if len(row.tokens) in (11, 13):
# Native check_viv_columns: MoorDyn's cross-flow VIV columns Cl [dF cF]
cl = numeric(row.tokens[10], row, "Cl")
Expand Down
22 changes: 22 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -994,6 +994,28 @@ 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)])
def test_bending_damping_round_trips_in_the_ei_column(
tmp_path: Path, ei: tuple[float, ...]
) -> None:
model = _chain_model(tmp_path)
cable = model.add_line_type("cable", diam=0.2, mass=40.0, ea=5.0e8, ei=ei)
assert cable.ei == ei
target = model.save(tmp_path / "bend_damped.dat")
deck = DeckFile.read(target)
row = next(r for r in deck.line_types if r.tokens[0] == "cable")
assert tuple(float(v) for v in row.tokens[5].split("|")) == ei
loaded = DeckModel.load(target)
assert next(t for t in loaded.line_types if t.name == "cable").ei == ei


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.to_text()


@pytest.mark.parametrize(
("gj", "ei", "message"),
[
Expand Down
30 changes: 30 additions & 0 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -953,6 +953,36 @@ def test_stiffener_rows_are_native(row, message):
_rejects(_example("lazy_wave_bend_stiffener.dat", (_STIFFENER_ROOT, row)), message)


_BARE_ROW = "bare 0.160 36.70 4.69e8 0.0 1.99e4 1.2 0.1 1.0 0.0"


@pytest.mark.parametrize(
"ei",
["1.99e4|250.0", "1.99e4|0", "1.99e4|-0.02|1.5"],
)
def test_bending_damping_forms_are_accepted(ei):
DeckFile.from_text(
_example("lazy_wave_bend_stiffener.dat", (_BARE_ROW, _BARE_ROW.replace("1.99e4", ei, 1)))
)


@pytest.mark.parametrize(
("ei", "message"),
[
("1.99e4|1|2|3", "takes EI, EI|Bb or EI|-zeta|f"),
("1.99e4|-250.0", "a negative bending damping is -zeta and needs the frequency"),
("1.99e4|0.02|1.5", "takes a damping ratio 0 < zeta < 1, written negative"),
("1.99e4|-1.5|1.5", "takes a damping ratio 0 < zeta < 1, written negative"),
("1.99e4|-0.02|0", "of EI|-zeta|f must be positive"),
("0.0|250.0", "bending damping (EI|Bb) needs a finite-EI cable"),
("0.0|-0.05|0.5", "bending damping (EI|Bb) needs a finite-EI cable"),
],
)
def test_bending_damping_rows_are_native(ei, message):
text = _example("lazy_wave_bend_stiffener.dat", (_BARE_ROW, _BARE_ROW.replace("1.99e4", ei, 1)))
_rejects(text, re.escape(message))


def test_stiffener_needs_a_finite_ei_line():
text = _section(_HELD, "STIFFENERS", "1 A 1.0 0.5 0.5 0.3 5.0e7 1150")
_rejects(text, "STIFFENERS name line 1, which is not a finite-EI line")
Expand Down
Loading
Loading