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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ All notable changes to CableDyn are recorded in this file. The format follows
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.
- The higher-harmonic VIV force of Ulveseter et al. (2019): a fourth `VIV` section column `Chh`
adds `1/2 rho D Chh cos(phi + phi_x) U (t x v_n)`, the lift's form at the sum of the cross-flow
and in-line phases, on `EI = 0` lines and finite-EI cables. On the in-line example `Chh` 1.0
raises the quarter-span in-line response at four times the cross-flow frequency fourfold. The
Python deck reader and builder take the column.
- Load power channels `VIVPow<L>`, `DragPow<L>` and `DampPow<L>` [W], and `<name><L>N<J>` per
unit length about a node [W/m]: the power the VIV loads, the drag and the structural damping
(`BA`, `Bb`) deliver to a line at the committed state, on `EI = 0` lines and finite-EI cables,
Expand Down
3 changes: 2 additions & 1 deletion doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,8 @@ Line and constitutive capability
host's fluid field on the coupled routes and its state in the checkpoint
* - 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
- the in-line shedding force of Ulveseter et al. (2018) at twice the cross-flow frequency, and
the optional higher-harmonic force of Ulveseter et al. (2019) (``Chh``), on
``EI = 0`` lines and finite-EI cables wherever the cross-flow lift runs
(:ref:`theory-viv-inline`), its state in the checkpoint

Expand Down
30 changes: 24 additions & 6 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1154,33 +1154,51 @@ relative flow, the direction of the drag, at twice the cross-flow frequency (Ulv

```text
--------------------- VIV ----------------------------------------------
TypeName ClX alpha
(-) (-) (-)
cable 0.85 0.15
TypeName ClX alpha Chh
(-) (-) (-) (-)
cable 0.85 0.15 0.5
```

| Column | Meaning |
|--------|---------|
| `TypeName` | an existing LINE TYPES name (case-insensitive), at most one row each |
| `ClX` | in-line shedding coefficient `C_x` >= 0, at most 1e15; `0` is no in-line VIV |
| `alpha` | optional frequency band of the in-line phase about twice the cross-flow one, `0 <= alpha < 1` (default 0.15) |
| `Chh` | optional higher-harmonic coefficient `C_hh` >= 0, at most 1e15 (default 0, none); `Chh > 0` needs `ClX > 0` |

Behaviour:

- Per unit length the force is `1/2 rho D ClX cos(phi_x) U v_n`, with `v_n` the relative normal
flow and `U` its speed; its phase follows `dphi_x/dt = 2 (dphi/dt) [1 + alpha sin(phi_xd - phi_x)]`,
`phi` the cross-flow phase and `phi_xd` the phase of the in-line motion. Ulveseter et al. take
`ClX = 0.85` and `alpha = 0.15` with `Cl = 0.65`.
- `Chh` adds the higher-harmonic force of Ulveseter et al. (2019), the lift's form
`1/2 rho D Chh cos(phi + phi_x) U (t x v_n)` at the sum of the two phases: across the flow at
three times the cross-flow frequency (and once and five times, through the in-line motion),
along it at twice and four times. It needs no state of its own. Ulveseter et al. use `Chh`
from 0 to 1.5.
- 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 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.
coupled. A row fails if it is not `TypeName ClX [alpha [Chh]]`,
names an undefined or already named type, or holds a value out of range; `ClX > 0` fails
on a type without the cross-flow lift, and `Chh > 0` with `ClX = 0`.
- See `examples/viv_taut_cable_inline.dat`.

**Published coefficient sets.** The synchronisation band of the LINE TYPES columns is the
`f0 +/- df` of the papers (`cF` = `f0`, `dF` = `df`), and their Morison inertia coefficient
`C_M` is `1 + Ca`. Two published sets, as LINE TYPES and VIV columns:

| Source | `Cd` | `Ca` | `Cl` | `dF` | `cF` | `ClX` | `alpha` | `Chh` |
|--------|------|------|------|------|------|-------|---------|-------|
| Ulveseter et al. (2018), Table 3: a 10 m riser model in current and in current and waves | 1.2 | 1.0 | 0.65 | 0.08 | 0.18 | 0.85 | 0.15 | 0 |
| Ulveseter et al. (2019), Table 1 and Section 4: the NDP high-mode riser in uniform current | 1.2 | 1.0 | 0.85 | 0.064 | 0.144 | 0.75 | 0.15 | 1.5 |

Each was fitted to its experiments by the authors and is a starting point, not a universal set;
MoorDyn's band defaults (`dF` 0.08, `cF` 0.18) are those of the first.

### FAILURE (optional, EI = 0 decks)

A FAILURE row detaches line ends from a point during a dynamic run, with MoorDyn's trigger rules.
Expand Down
6 changes: 6 additions & 0 deletions doc/references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ Hydrodynamics and ocean environment
simulation of riser VIV in current and irregular waves. *Marine Structures* **60**, 241–260.
https://doi.org/10.1016/j.marstruc.2018.04.001

.. _ref-ulveseter2019:

- **Ulveseter, J. V., Thorsen, M. J., Sævik, S. & Larsen, C. M. (2019).** Simulating fundamental
and higher harmonic VIV of slender structures. *Applied Ocean Research* **90**, 101856.
https://doi.org/10.1016/j.apor.2019.101856

.. _ref-feeny2008:

- **Feeny, B. F. (2008).** A complex orthogonal decomposition for wave motion analysis.
Expand Down
18 changes: 18 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1214,6 +1214,24 @@ run exactly as without the row. On the taut line of ``viv_taut_cable_inline.dat`
span moves in line at twice the cross-flow frequency, A/D 0.19 against 0.03 with the cross-flow
lift alone, and the same line as an ``EI = 0`` line gives the cable's amplitudes within 1 %.

A fourth column ``Chh`` adds the higher-harmonic force of
:ref:`Ulveseter et al. (2019) <ref-ulveseter2019>`, the lift's form at the sum of the two phases,

.. math::

\mathbf{f}_{hh} = \tfrac{1}{2}\rho\,d\,C_{hh}\cos(\phi + \phi_x)\;U\,
(\mathbf{t}\times\mathbf{v}_n) .

With the cross-flow phase at the frequency :math:`\omega` and the in-line one at :math:`2\omega`
it acts across the flow at :math:`3\omega`, and, through the turn of the relative flow by the
motion, at :math:`\omega` and :math:`5\omega` across and :math:`2\omega` and :math:`4\omega` along the flow. It takes no
state of its own: on a finite-EI cable it adds :math:`k_{hh}\cos(\phi + \phi_x)` to the node
values of the lift scale the element integrates, on an ``EI = 0`` line it is a second node lift
at the phase sum, and its derivatives enter the tangent with the lift's. Ulveseter et al. use
:math:`C_{hh}` from 0 to 1.5 (with :math:`C_{v,y}` 0.85 and :math:`C_{v,x}` 0.75). On the
in-line example with ``Chh`` 1.0 the quarter-span in-line response at four times the cross-flow
frequency grows from A/D 0.002 to 0.007, the same on an ``EI = 0`` line.

.. _theory-dry-buoyancy:

Buoyancy and wetting
Expand Down
20 changes: 16 additions & 4 deletions python/cabledyn/builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,10 @@ class LineType:
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
the row (the solver takes 0.15).
chh : float | None
Optional higher-harmonic coefficient of the ``VIV`` row (``Name ClX alpha
Chh``, Ulveseter et al. 2019; it needs ``clx``); ``None`` leaves it out
(0). With ``chh`` set and ``il_alpha`` ``None`` the row writes alpha 0.15.
"""

name: str
Expand All @@ -235,6 +239,7 @@ class LineType:
cf: float | None = None
clx: float | None = None
il_alpha: float | None = None
chh: float | None = None


@dataclass(eq=False)
Expand Down Expand Up @@ -1653,6 +1658,7 @@ def add_line_type(
cf: float | None = None,
clx: float | None = None,
il_alpha: float | None = None,
chh: float | None = None,
) -> LineType:
"""Add a ``LINE TYPES`` row; see :class:`LineType` for the fields.

Expand Down Expand Up @@ -1688,6 +1694,7 @@ def add_line_type(
cf,
clx,
il_alpha,
chh,
)
self._line_types.append(item)
return item
Expand Down Expand Up @@ -2949,12 +2956,16 @@ def _viv_table(self) -> tuple[str, str, list[list[str]]]:
if item.clx is None:
if item.il_alpha is not None:
raise ValueError(f"{what}: il_alpha needs the in-line VIV coefficient clx")
if item.chh is not None:
raise ValueError(f"{what}: chh needs the in-line VIV coefficient clx")
continue
row = [_text(item.name, what), _num(item.clx, what)]
if item.il_alpha is not None:
row.append(_num(item.il_alpha, what))
if item.il_alpha is not None or item.chh is not None:
row.append(_num(0.15 if item.il_alpha is None else item.il_alpha, what))
if item.chh is not None:
row.append(_num(item.chh, what))
rows.append(row)
return "Name ClX alpha", "(-) (-) (-)", rows
return "Name ClX alpha Chh", "(-) (-) (-) (-)", rows

def _syrope_table(self) -> tuple[str, str, list[list[str]]]:
rows = [
Expand Down Expand Up @@ -3158,7 +3169,8 @@ def load(self) -> None:
t = row.tokens
item = model.line_types[t[0]]
item.clx = _f(t[1])
item.il_alpha = _f(t[2]) if len(t) == 3 else None
item.il_alpha = _f(t[2]) if len(t) >= 3 else None
item.chh = _f(t[3]) if len(t) == 4 else None
for row in self.rows("ATTACHMENTS"):
t = row.tokens
arc: float | tuple[float, float, float]
Expand Down
34 changes: 24 additions & 10 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3201,16 +3201,17 @@ def _check_viv_section(
) -> None:
"""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.
A row ``TypeName ClX [alpha [Chh]]`` 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``; and the higher-harmonic coefficient ``Chh >= 0`` (default 0),
which needs ``ClX > 0``. A type takes one row.
"""
named: set[str] = set()
for row in self._rows("VIV"):
where = self._at(row)
if len(row.tokens) not in (2, 3):
raise DeckFormatError(f"{where}: VIV rows must be: TypeName ClX [alpha]")
if len(row.tokens) not in (2, 3, 4):
raise DeckFormatError(f"{where}: VIV rows must be: TypeName ClX [alpha [Chh]]")
name = row.tokens[0].lower()
if name not in line_type_meta:
raise DeckFormatError(
Expand All @@ -3221,11 +3222,14 @@ def _check_viv_section(
named.add(name)
try:
clx = _native_float(row.tokens[1])
alpha = _native_float(row.tokens[2]) if len(row.tokens) == 3 else 0.15
alpha = _native_float(row.tokens[2]) if len(row.tokens) >= 3 else 0.15
chh = _native_float(row.tokens[3]) if len(row.tokens) == 4 else 0.0
except ValueError as exc:
raise DeckFormatError(f"{where}: VIV ClX and alpha must be plain numbers") from exc
if not (math.isfinite(clx) and math.isfinite(alpha)):
raise DeckFormatError(f"{where}: VIV ClX and alpha must be finite")
raise DeckFormatError(
f"{where}: VIV ClX, alpha and Chh must be plain numbers"
) from exc
if not (math.isfinite(clx) and math.isfinite(alpha) and math.isfinite(chh)):
raise DeckFormatError(f"{where}: VIV ClX, alpha and Chh must be finite")
if clx < 0.0 or clx > _NATIVE_MAX_COEFFICIENT:
raise DeckFormatError(
f"{where}: VIV in-line coefficient ClX must be non-negative (0 = in-line VIV "
Expand All @@ -3235,6 +3239,16 @@ def _check_viv_section(
raise DeckFormatError(
f"{where}: VIV in-line frequency band alpha must satisfy 0 <= alpha < 1"
)
if chh < 0.0 or chh > _NATIVE_MAX_COEFFICIENT:
raise DeckFormatError(
f"{where}: VIV higher-harmonic coefficient Chh must be non-negative (0 = off) "
"and at most 1e15"
)
if chh > 0.0 and not clx > 0.0:
raise DeckFormatError(
f'{where}: VIV higher-harmonic force of LINE TYPE "{row.tokens[0]}" needs its '
"in-line VIV (ClX > 0): it runs at the cross-flow plus in-line phase"
)
if clx > 0.0 and name not in lift_type_names:
raise DeckFormatError(
f'{where}: VIV in-line VIV of LINE TYPE "{row.tokens[0]}" needs its '
Expand Down
30 changes: 30 additions & 0 deletions python/tests/test_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -1037,6 +1037,36 @@ def test_inline_viv_round_trips_in_the_viv_section(
assert (loaded.clx, loaded.il_alpha) == (clx, il_alpha)


@pytest.mark.parametrize(("il_alpha", "written_alpha"), [(0.2, 0.2), (None, 0.15)])
def test_higher_harmonic_viv_round_trips(
tmp_path: Path, il_alpha: float | None, written_alpha: float
) -> None:
model = _chain_model(tmp_path)
model.add_line_type(
"cable",
diam=0.2,
mass=40.0,
ea=5.0e8,
ei=1.0e4,
cl=0.8,
clx=0.85,
il_alpha=il_alpha,
chh=1.2,
)
target = model.save(tmp_path / "higher_harmonic.dat")
row = next(r for r in DeckFile.read(target)._rows("VIV") if r.tokens[0] == "cable")
assert [float(v) for v in row.tokens[1:]] == [0.85, written_alpha, 1.2]
loaded = next(t for t in DeckModel.load(target).line_types if t.name == "cable")
assert (loaded.clx, loaded.il_alpha, loaded.chh) == (0.85, written_alpha, 1.2)


def test_higher_harmonic_needs_the_inline_coefficient(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, cl=0.8, chh=1.0)
with pytest.raises(ValueError, match="chh needs the in-line VIV coefficient clx"):
model.to_text()


def test_inline_viv_alpha_needs_the_coefficient(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, cl=0.8, il_alpha=0.15)
Expand Down
17 changes: 14 additions & 3 deletions python/tests/test_deck_native_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -989,7 +989,15 @@ def test_bending_damping_rows_are_native(ei, message):


@pytest.mark.parametrize(
"rows", [("riser 0.85 0.15",), ("riser 0.85",), ("riser 0",), ("RISER 0.5 0.0",)]
"rows",
[
("riser 0.85 0.15",),
("riser 0.85",),
("riser 0",),
("RISER 0.5 0.0",),
("riser 0.85 0.15 1.0",),
("riser 0 0.15 0",),
],
)
def test_inline_viv_rows_are_accepted(rows):
DeckFile.from_text(_section(_VIV_CABLE, "VIV", "TypeName ClX alpha", "(-) (-) (-)", *rows))
Expand All @@ -998,10 +1006,13 @@ def test_inline_viv_rows_are_accepted(rows):
@pytest.mark.parametrize(
("rows", "message"),
[
(("riser 0.85 0.15 7",), "VIV rows must be: TypeName ClX [alpha]"),
(("riser 0.85 0.15 7 1",), "VIV rows must be: TypeName ClX [alpha [Chh]]"),
(("cable 0.85",), 'VIV row names undefined LINE TYPE "cable"'),
(("riser 0.85", "riser 0.5"), 'VIV names LINE TYPE "riser" twice'),
(("riser 0.85 x",), "VIV ClX and alpha must be plain numbers"),
(("riser 0.85 x",), "VIV ClX, alpha and Chh must be plain numbers"),
(("riser 0.85 0.15 y",), "VIV ClX, alpha and Chh must be plain numbers"),
(("riser 0.85 0.15 -1",), "Chh must be non-negative"),
(("riser 0 0.15 1",), "needs its in-line VIV (ClX > 0)"),
(("riser -0.1",), "ClX must be non-negative"),
(("riser 2.0e15",), "ClX must be non-negative"),
(("riser 0.85 1.0",), "alpha must satisfy 0 <= alpha < 1"),
Expand Down
Loading
Loading