Skip to content

feat(viv): cross-flow vortex-induced vibration of EI = 0 lines - #55

Merged
SMI-Lab-Inha merged 11 commits into
devfrom
feat/viv
Oct 26, 2026
Merged

SMI-Lab-Inha merged 11 commits into
devfrom
feat/viv

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

MoorDyn v2's optional LINE TYPES columns Cl or Cl dF cF now switch on cross-flow
vortex-induced vibration of EI = 0 lines in the standalone driver: the synchronisation model of
Thorsen et al. (2014, 2016) in the form MoorDyn implements it.

Model. Each interior node carries a shedding phase phi and the lift
1/4 rho d Cl (l_i + l_i+1) U cos(phi) q x v_n (wetted fraction included). The phase rate is
2 pi (cF + dF sin(phi_y - phi)) U/d, with phi_y the phase of the node's cross-flow motion from
its running-RMS velocity and acceleration. The RMS window is VIVrmsWindow seconds, by default
500 steps of dtM as in MoorDyn, and the phases start at 2 pi i/N from End A. The static
equilibrium carries no lift.

In the implicit step the phase is explicit. The step's lift takes the phase predicted at
t_n+1 from the step-start rate (the generalised-alpha level under the configuration blend), and
the commit is the Heun update with the rate at the converged end state. The lift's position and
velocity derivatives enter the tangent. The phase sample and the lift use the node kinematics
averaged with the neighbours, (x_i-1 + 2 x_i + x_i+1)/4. With the node's own kinematics, a step
that resolves the mesh zig-zag mode (dtM 2e-3 s or less on the benchmark) let the synchronisation
loop pump that mode until the line lost lock-in; the average removes the zig-zag mode exactly
and keeps a resolved mode of wavenumber k to cos^2(k l0/2).

Validation against MoorDyn-F (OpenFAST v5 moordyn_driver, dtM 5e-4 s) on a taut 100 m line
in a uniform cross current, U = 0.06-0.42 m/s:

  • mode-1 and mode-3 lock-in (U <= 0.18 and >= 0.36 m/s): mid-span A/D within 1.2 % and the
    response frequency within one spectral bin, e.g. U 0.15 m/s: 0.662 against 0.663 at 0.293 Hz;
  • the same response at every dtM from 5e-4 to 1e-2 s;
  • at U 0.21-0.33 m/s the two codes settle on different modes (MoorDyn-F mode 1, CableDyn
    mode 2). Each is robust to the initial state, the step and the phase origin in its own code.
    VALIDATION.md records this as a scoped result.

Scope. The coupled OpenFAST and FAST.Farm routes and mixed EI = 0 / finite-EI decks refuse
Cl > 0 by name (they neither checkpoint the phase nor feed it the host's fluid field yet), as
do finite-EI and Syrope line types, and an EI = 0 deck without water (the lift acts with
the line's Morison drag). In-line VIV is not modelled.

State. The phases and running mean squares are part of the committed line state
(commit_state_copy): the rotation-resolved sub-steps, the recovery rungs, the line-system
rollback and the snapshots save and restore them with the kinematics.

Python. DeckFile reads the 11- and 13-column rows with MoorDyn's checks and DeckModel
keeps cl, df and cf through load and save. DeckFile refuses Cl > 0 where the
native code does, and the builder refuses VIV columns on a 14-column finite-EI row.

Tests: viv_kernels (lift, phase rate, RMS update, Jacobians against central differences),
viv_lockin (the benchmark at dtM 0.01 and 0.002 s against the MoorDyn-F reference), a
test_model case that forces sub-steps on a VIV line (a repeated sub-stepped pass and the
fallback to the plain step stay bit-identical), and the deck-file and builder tests. Full suite
on this branch: 304/304 ctest, 2081 pytest; the examples are unchanged.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
At steps that resolve the mesh-scale zig-zag mode (dtM <= 2e-3 s on a
100 m, 50-segment taut line) the VIV lock-in broke down after ~70 s:
the zig-zag (14.9 Hz, neighbours opposite, corr -1.00) grew without
bound in the cross-flow acceleration. Through the phase and the lift's
dependence on the node's own velocity, the synchronisation loop pumped
it (dF = 0 does not grow; tolerance, blend form and rhoInf do not
matter). Larger steps hid it by damping the mode numerically.

The phase sample and the lift now take the node kinematics averaged
with the neighbours, (x_{i-1} + 2 x_i + x_{i+1})/4, which removes the
zig-zag mode exactly and keeps resolved modes to cos^2(k l0/2); the lift
Jacobian is distributed accordingly. Under the force blend the in-step
phase is the explicit phase at t_{n+1}. The benchmark now locks at A/D
0.66, 0.29 Hz for dtM 5e-4 to 1e-2 s, as MoorDyn-F does at 5e-4 s.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn's lift formula and its geometry, the lift Jacobians against
central differences, the cross-flow projection, the phase rate at lock
and a quarter period ahead, MoorDyn's running mean square, phase
wrapping and the coinciding-neighbour failure.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn starts the phase at 2 pi i/N with node i counted from End A; the
EI = 0 model numbers its nodes from End B, so the distribution ran
mirrored. Steady lock-in states of the benchmark sweep are unchanged.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
DeckFile accepts the 11- and 13-field LINE TYPES rows (Cl, or Cl dF cF,
after the ten standard columns) with the native checks: Cl >= 0, and with
Cl > 0 a band cF > 0, 0 <= dF < cF on an EI = 0, non-Syrope type; the
drag and added-mass columns are columns 7-10 of those rows. VIVrmsWindow
is a non-negative option. LineType carries cl, df, cf, so DeckModel no
longer drops the VIV columns on save.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The coupled OpenFAST and FAST.Farm routes and mixed EI = 0 / finite-EI
decks neither checkpoint the shedding phase nor give it the host's fluid
field yet: a LINE TYPES row with Cl > 0 now stops their initialisation
with a message that names the standalone EI = 0 driver.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Theory section on the synchronisation model, its discretisation (explicit
phase, Heun commit, neighbour-averaged node kinematics) and its route
limits; the LINE TYPES VIV columns in concepts, MoorDyn migration and the
CLI field list; the VIVrmsWindow option; capabilities, coupling and
troubleshooting rows; Thorsen et al. (2014, 2016) in the references.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
… dtM

A taut 100 m line in a uniform 0.15 m/s cross current locks in on its
first mode: at dtM 0.01 s the mid-span A/D is within 3 % of MoorDyn-F's
0.662 and the frequency within one spectral bin of 0.293 Hz, and at
dtM 0.002 s (the step at which the zig-zag mode used to break lock-in)
the amplitude stays within 2 %.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…e refusals in Python

The rotation-resolved sub-stepping of an EI = 0 line saved and restored
only the kinematics and the law states: a sub-stepped interval advanced
the shedding phase again from the plain step's committed phase, and a
failing sub-step left its phase and mean squares behind. The phases and
mean squares now belong to commit_state_copy, so the sub-step slots and
the recovery snapshot carry them alike. A test forces sub-steps on a VIV
line: a repeated sub-stepped pass and the fallback to the plain step are
bit-identical (both failed before).

DeckFile now refuses Cl > 0 on the coupled and mixed routes and on an
EI = 0 deck without water, as the native code does, and the builder
refuses VIV columns on a 14-column finite-EI row. The unused VIV state
and lift queries are removed until a route uses them.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-26T16:32:55.345073Z e8ef6db Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@read-the-docs-community

read-the-docs-community Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35418789 | 📁 Comparing e8ef6db against latest (fd1936d)

  🔍 Preview build  

18 files changed · ± 18 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: bccd33309c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: e8ef6db96c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@SMI-Lab-Inha
SMI-Lab-Inha merged commit 1554411 into dev Oct 26, 2026
21 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv branch October 26, 2026 17:58
SMI-Lab-Inha added a commit that referenced this pull request Oct 27, 2026
The cross-flow VIV synchronisation model of #55 now runs on finite-EI (cubic-Hermite) cables in
the standalone driver: the same LINE TYPES columns `Cl` or `Cl dF cF` on an `EI > 0` type.

Model. The lift is a distributed load per unit deformed length,
f = 1/2 rho d Cl cos(phi) U (t x v_r), with t the unit tangent of the centreline, v_r the
relative flow and cos(phi) interpolated linearly between the element's end nodes. It is
integrated against the Hermite shape functions at the drag element's three Gauss points (a
point above the surface carries none), with its exact position and velocity Jacobians in the
tangent (the residual path and the parallel tangent-only path). Each node carries a phase,
driven by the node's cross-flow motion along its own tangent, the slope degrees of freedom;
d, cF and dF at a node are the length-weighted averages over its lifting elements, and the
phases start at 2 pi i/N from End A. As on EI = 0 lines the phase is explicit: the step's
evaluations take the phase predicted from the step-start rate (at t_n+1 under the force blend,
whose committed force F_n keeps phi_n; at the generalised-alpha level under the configuration
blend), and the commit is the Heun update. With VIV the converged force is not cached as the
next step's F_n (it took the predicted phase).

No smoothing is needed: the Hermite tangent and the integrated lift leave no mesh-scale mode
for the synchronisation loop to pump.

State. The phases and running mean squares are saved and restored with the kinematics by the
recovering step, the snapshot and the deallocation; every evaluation outside a step (end
forces, node recovery, the held-field update, the committed acceleration) takes the committed
phase. The phase commit cannot fail, so a step is never left half committed: a node whose end
tangent is degenerate takes the step-start rate over the step. Installing or removing VIV
refreshes the committed acceleration with the lift (the previous VIV state and acceleration come
back if that solve fails), and a later drag reconfiguration carries the lift scale and the
shedding diameter with it. An internal wave family (Set_Waves) is refused on a VIV cable; deck
waves and current reach the standalone Hermite march as its held fluid field, which the phase
follows.

Routes. `build_one_hermite_cable` installs VIV only for the standalone finite-EI march. A
finite-EI line with two moving ends (compatibility route), a finite-EI line beside bodies, rods
or free points (multibody march), the single-cable `CD_Init_Deck_HermiteCable` entry and the
aggregate (coupled, mixed) route refuse `Cl > 0` by name; `DeckFile` mirrors the refusals.

Validation (VALIDATION.md L2-VIV-EI, gated in `viv_lockin` and `hermite_viv`):

- the #55 benchmark line as a finite-EI cable with EI = 1 N m^2: mid/quarter-span A/D
  0.662/0.421 against the EI = 0 line's 0.663/0.421 at the same frequency, unchanged at dtM
  1e-2, 2e-3 and 5e-4 s;
- a bending-stiff, neutrally buoyant cable (EA 5e9 N, EI 5e7 N m^2, beta = pi^2 EI/(T L^2) ~ 1)
  against the EI = 0 string of equal first-mode frequency, tension T(1 + beta): the same
  mode-1 lock-in (A/D within 2.5 %, same frequency) for U <= 0.24 m/s; for U >= 0.27 m/s the
  string jumps to mode 2 while the cable stays in mode 1, its bending having raised f2/f1 to
  about 3.15;
- a lazy-wave power cable (examples/lazy_wave_buoyancy_smeared.dat with Cl 0.8, 0.5 m/s
  current) shows out-of-plane VIV at 0.47 Hz with the fairlead tension oscillating at twice
  that frequency, and stays still without the lift.

Tests: `hermite_viv` (the setter's refusals, the acceleration refresh, the drag
reconfiguration, the lock-in with and without lift, a mid-run
snapshot replaying the state and phase bit for bit, the recovering step equal to the plain
step), `viv_kernels` section 7 (the per-length lift and its flow and tangent Jacobians against
central differences), `viv_lockin` (the two comparisons above, the EI = 1 cable at dtM 0.01 and
0.002 s), and the deck-file tests. Full suite: 305/305 ctest, 2082 pytest; every shipped
example's output is byte-identical to dev.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant