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: 5 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,14 @@ 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 VIV: 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.
twice the cross-flow frequency, A/D 0.19 against 0.03 with the lift alone, on `EI = 0` lines and
finite-EI cables alike (within 1 % of each other). Exact Jacobians; the phase is in the
step-recovery, snapshot and checkpoint state; the Python deck reader and builder take the
section.

## [0.4.2] - 2026-11-09

Expand Down
4 changes: 2 additions & 2 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@ Line and constitutive capability
* - 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
``EI = 0`` lines and finite-EI cables wherever the cross-flow lift runs
(:ref:`theory-viv-inline`), its state in the checkpoint

Loads and environment
---------------------
Expand Down
2 changes: 1 addition & 1 deletion doc/concepts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ coefficients (``Cd_n``, ``Cd_t``, ``Ca_n``, ``Ca_t``). ``EI`` is the switch betw
(next section). Axial response can be linear ``EA`` or a stateful constitutive model
(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`), and a ``VIV`` section row adds the in-line force of a finite-EI type
:ref:`theory-viv`), and a ``VIV`` section row adds the in-line force of a type
(:ref:`theory-viv-inline`).

Two solver paths, selected by ``EI``
Expand Down
9 changes: 5 additions & 4 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,7 @@ the half-range and centre of its band in non-dimensional frequency (MoorDyn's `d
`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.
in-line force of a type is a [VIV](#viv-optional) section row.

**Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept
bar-separated parts:
Expand Down Expand Up @@ -1145,7 +1145,7 @@ 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)
### VIV (optional)

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.
Expand Down Expand Up @@ -1174,8 +1174,9 @@ Behaviour:
- 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]`,
- It acts wherever the cross-flow lift does: on `EI = 0` lines (a node force over the node's
half elements, as the lift) and on finite-EI cables (integrated with the lift), standalone and
coupled. 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`.
Expand Down
4 changes: 2 additions & 2 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -340,8 +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, and a type with in-line VIV (the ``VIV`` section) adds
its in-line force. Zero on a line without VIV (``Cl = 0``)
the lift of their half-elements. On both, 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
18 changes: 13 additions & 5 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1174,7 +1174,7 @@ them with the rest of the state.
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
A 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
Expand All @@ -1197,14 +1197,22 @@ with the running RMS values of the cross-flow phase (:math:`\phi_{\dot x} = 0` a
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,
needs the type's cross-flow :math:`C_L > 0`. On an ``EI = 0`` line it is a node force like the
lift,

.. math::

\mathbf{F}_x = \tfrac{1}{4}\rho\,d\,C_x\,(l_{i} + l_{i+1})\,U\cos\phi_x\;\mathbf{v}_n ,

with the lift's wetted fractions, node tangent and neighbour-averaged kinematics (for the phase
and in the force). On a finite-EI cable it is integrated with the lift at the same Gauss points,
:math:`\cos\phi_x` interpolated between the element's end nodes. Its exact position and velocity
derivatives enter the tangent on both. 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.
lift alone, and the same line as an ``EI = 0`` line gives the cable's amplitudes within 1 %.

.. _theory-dry-buoyancy:

Expand Down
2 changes: 1 addition & 1 deletion examples/viv_taut_cable_inline.dat
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ LineID LineType Length NumSegs
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.
-- cross-flow Cl > 0) and the band alpha (0 <= alpha < 1, default 0.15). EI = 0 lines take it too.
TypeName ClX alpha
(-) (-) (-)
riser 0.85 0.15
Expand Down
2 changes: 1 addition & 1 deletion python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ class LineType:
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``.
clx, il_alpha : float | None
Optional in-line VIV of a finite-EI type, a ``VIV`` section row
Optional in-line VIV of a type, a ``VIV`` section row
``Name ClX [alpha]``: the in-line shedding coefficient (it needs ``cl``,
the in-line phase running at twice the cross-flow one) and the frequency
band of that phase, ``0 <= il_alpha < 1``; ``None`` leaves alpha out of
Expand Down
19 changes: 3 additions & 16 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3180,20 +3180,17 @@ def _check_stiffeners(

def _check_viv_section(
self,
line_ids: set[str],
section_types_by_line: dict[str, list[str]],
line_type_meta: dict[str, tuple[float, float, float, float]],
lift_type_names: set[str],
) -> None:
"""Native ``apply_type_viv`` and its finalize check for the VIV section.
"""Native ``apply_type_viv`` for the VIV section.

A row ``TypeName ClX [alpha]`` gives a line type in-line VIV: the in-line shedding
coefficient ``ClX >= 0`` (0 = off) and the band ``0 <= alpha < 1`` (default 0.15) of
its phase about twice the cross-flow one, so ``ClX > 0`` needs the type's LINE TYPES
lift ``Cl > 0``. A type takes one row; the in-line force acts on finite-EI lines.
lift ``Cl > 0``. A type takes one row.
"""
named: set[str] = set()
inline_types: set[str] = set()
for row in self._rows("VIV"):
where = self._at(row)
if len(row.tokens) not in (2, 3):
Expand Down Expand Up @@ -3228,16 +3225,6 @@ def _check_viv_section(
"cross-flow lift (LINE TYPES Cl > 0): the in-line phase runs at twice the "
"cross-flow one"
)
if clx > 0.0:
inline_types.add(name)
for line_id in sorted(line_ids, key=int):
names = section_types_by_line.get(line_id, [])
finite = any(line_type_meta[name][3] > 0.0 for name in names if name in line_type_meta)
if not finite and inline_types & set(names):
raise DeckFormatError(
f"{self._label}: line {line_id} is an EI = 0 line of a type with in-line VIV "
"(VIV ClX > 0): in-line VIV acts on finite-EI lines (EI > 0)"
)

def _legacy_rod_type_columns(self, record: DeckRecord) -> bool:
"""Return whether ``record`` sits under a legacy CableDyn ROD TYPES header.
Expand Down Expand Up @@ -4409,7 +4396,7 @@ def end_key(token: str) -> str:
)

self._check_stiffeners(line_ids, section_types_by_line, line_type_meta, line_lengths)
self._check_viv_section(line_ids, section_types_by_line, line_type_meta, viv_type_names)
self._check_viv_section(line_type_meta, viv_type_names)
self._check_attachments(line_ids, section_types_by_line, line_type_meta, line_lengths)

assigned_end_connections: set[tuple[str, str]] = set()
Expand Down
8 changes: 3 additions & 5 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -1020,11 +1020,9 @@ def test_inline_viv_needs_the_crossflow_lift():
)


def test_inline_viv_needs_a_finite_ei_line():
text = _section(_example("viv_taut_line_crossflow.dat"), "VIV", "riser 0.85")
_rejects(text, re.escape("in-line VIV acts on finite-EI lines (EI > 0)"))
# a zero in-line coefficient is no in-line VIV, which the EI = 0 line takes
DeckFile.from_text(_section(_example("viv_taut_line_crossflow.dat"), "VIV", "riser 0.0"))
@pytest.mark.parametrize("row", ["riser 0.85", "riser 0.0"])
def test_inline_viv_acts_on_an_ei0_line(row):
DeckFile.from_text(_section(_example("viv_taut_line_crossflow.dat"), "VIV", row))


def test_stiffener_needs_a_finite_ei_line():
Expand Down
44 changes: 17 additions & 27 deletions src/CableDyn_DeckDriver.f90
Original file line number Diff line number Diff line change
Expand Up @@ -10367,7 +10367,7 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er
REAL(wp), ALLOCATABLE :: ba(:), fluid_velocity(:, :), fluid_acceleration(:, :), drag_waterline(:)
REAL(wp), ALLOCATABLE :: hydro_diam(:), hydro_cdn(:), hydro_cdt(:), hydro_can(:), hydro_cat(:)
REAL(wp), ALLOCATABLE :: ve_ead(:), ve_bas(:), ve_bad(:), ve_ambl(:), ve_vbet(:)
REAL(wp), ALLOCATABLE :: viv_cl(:), viv_cf(:), viv_df(:)
REAL(wp), ALLOCATABLE :: viv_cl(:), viv_cf(:), viv_df(:), viv_clx(:), viv_al(:)
LOGICAL, ALLOCATABLE :: syr_el(:)
REAL(wp) :: anchor(3), fairlead(3), mode1_omega
REAL(wp), PARAMETER :: factors(4) = [0.25_wp, 0.5_wp, 0.75_wp, CD_ONE]
Expand Down Expand Up @@ -10406,10 +10406,12 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er
ALLOCATE (ba(SIZE(l0)), hydro_diam(SIZE(l0)), hydro_cdn(SIZE(l0)), hydro_cdt(SIZE(l0)), &
hydro_can(SIZE(l0)), hydro_cat(SIZE(l0)), ve_ead(SIZE(l0)), ve_bas(SIZE(l0)), &
ve_bad(SIZE(l0)), ve_ambl(SIZE(l0)), ve_vbet(SIZE(l0)), viv_cl(SIZE(l0)), viv_cf(SIZE(l0)), &
viv_df(SIZE(l0)), syr_el(SIZE(l0)))
viv_df(SIZE(l0)), syr_el(SIZE(l0)), viv_clx(SIZE(l0)), viv_al(SIZE(l0)))
viv_cl = CD_ZERO
viv_cf = CD_ZERO
viv_df = CD_ZERO
viv_clx = CD_ZERO
viv_al = CD_ZERO
ve_ead = CD_ZERO
ve_bas = CD_ZERO
ve_bad = CD_ZERO
Expand Down Expand Up @@ -10468,13 +10470,17 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er
viv_cl(e) = types(line_section_type(sections, ln%id, i))%cl
viv_cf(e) = types(line_section_type(sections, ln%id, i))%viv_cf
viv_df(e) = types(line_section_type(sections, ln%id, i))%viv_df
viv_clx(e) = types(line_section_type(sections, ln%id, i))%clx
viv_al(e) = types(line_section_type(sections, ln%id, i))%il_alpha
syr_el(e) = types(line_section_type(sections, ln%id, i))%is_syrope
END DO
END DO
syr_el = syr_el(SIZE(syr_el):1:-1)
viv_cl = viv_cl(SIZE(viv_cl):1:-1)
viv_cf = viv_cf(SIZE(viv_cf):1:-1)
viv_df = viv_df(SIZE(viv_df):1:-1)
viv_clx = viv_clx(SIZE(viv_clx):1:-1)
viv_al = viv_al(SIZE(viv_al):1:-1)
ba = ba(SIZE(ba):1:-1)
ve_ead = ve_ead(SIZE(ve_ead):1:-1)
ve_bas = ve_bas(SIZE(ve_bas):1:-1)
Expand Down Expand Up @@ -10764,8 +10770,15 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er
BLOCK
REAL(wp) :: seed(model%n_dof/3)
CALL CD_Deck_VIV_Phase_Seed(model%l0, ln%ends_swapped, seed, zero=opts%viv_phase_zero)
CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, &
phase_seed=seed, tangent_reversed=.NOT. ln%ends_swapped)
! with the in-line VIV of the VIV section where a type has ClX > 0
IF (ANY(viv_clx > CD_ZERO)) THEN
CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, &
phase_seed=seed, tangent_reversed=.NOT. ln%ends_swapped, clx=viv_clx, &
il_alpha=viv_al)
ELSE
CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, &
phase_seed=seed, tangent_reversed=.NOT. ln%ends_swapped)
END IF
END BLOCK
IF (es == CD_MODEL_OK) CALL CD_Recompute_Model_Acceleration(model, es, em)
IF (es /= CD_MODEL_OK) THEN
Expand Down Expand Up @@ -11602,20 +11615,6 @@ SUBROUTINE finite_viv_arrays(ln, sections, types, cl, cf, df, clx, il_alpha)
il_alpha = il_alpha(SIZE(il_alpha):1:-1)
END SUBROUTINE finite_viv_arrays

LOGICAL FUNCTION line_has_viv_il(ln, types, sections) RESULT(has)
!! Whether a section of the line uses a line type with in-line VIV (VIV ClX > 0).
TYPE(DeckLine), INTENT(IN) :: ln
TYPE(DeckLineType), INTENT(IN) :: types(:)
TYPE(DeckSection), INTENT(IN) :: sections(:)
INTEGER :: j
has = .FALSE.
DO j = 1, SIZE(sections)
IF (sections(j)%line_id /= ln%id) CYCLE
IF (sections(j)%ltype < 1 .OR. sections(j)%ltype > SIZE(types)) CYCLE
IF (types(sections(j)%ltype)%clx > CD_ZERO) has = .TRUE.
END DO
END FUNCTION line_has_viv_il

LOGICAL FUNCTION line_has_viv(ln, types, sections) RESULT(has)
!! Whether a section of the line uses a line type with a VIV lift coefficient Cl > 0.
TYPE(DeckLine), INTENT(IN) :: ln
Expand Down Expand Up @@ -19783,15 +19782,6 @@ SUBROUTINE finalize_checks(types, bodies, rod_types, rods, points, lines, sectio
END IF
END DO

! VIV in-line rows: the in-line force acts on finite-EI lines
DO j = 1, SIZE(lines)
IF (line_is_finite_ei(lines(j), types, sections)) CYCLE
IF (.NOT. line_has_viv_il(lines(j), types, sections)) CYCLE
at_line = lines(j)%deck_line
CALL fail(ErrStat, ErrMsg, 'line '//TRIM(int_to_str(lines(j)%id))//' is an EI = 0 line of a type with '// &
'in-line VIV (VIV ClX > 0): in-line VIV acts on finite-EI lines (EI > 0)'); RETURN
END DO

! STIFFENERS: bend stiffeners sleeving the ends of a finite-EI line
DO j = 1, SIZE(lines)
IF (.NOT. ALLOCATED(lines(j)%stf)) CYCLE
Expand Down
Loading
Loading