Skip to content

feat: wake-oscillator VIV on finite-EI cables (WAKE OSCILLATOR section) - #154

Merged
SMI-Lab-Inha merged 2 commits into
devfrom
feat/viv-wake-oscillator
Nov 13, 2026
Merged

SMI-Lab-Inha merged 2 commits into
devfrom
feat/viv-wake-oscillator

Conversation

@SMI-Lab-Inha

@SMI-Lab-Inha SMI-Lab-Inha commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds the wake oscillator as a second VIV model for finite-EI cables, next to the synchronisation model of the Cl column. A new optional WAKE OSCILLATOR section gives a line type the van der Pol wake oscillator of Facchinetti, de Langre & Biolley (2004) with acceleration coupling, distributed along the line as in Violette et al. (2010).

--------------------- WAKE OSCILLATOR ----------------------------------
TypeName   CL0    St     eps    A
(-)        (-)    (-)    (-)    (-)
cable      0.3    0.2    0.3    12

St, eps and A are optional. Their defaults (0.2, 0.3, 12) are the values Facchinetti et al. fit to forced-wake data. The type keeps Cl = 0, and a line uses one VIV model.

Model

At each node a van der Pol oscillator in the reduced lift coefficient $q = 2C_L/C_{L0}$ is forced by the node's cross-flow acceleration:

$$\ddot q + \varepsilon\,\omega_f\,(q^2 - 1)\,\dot q + \omega_f^2\,q = \frac{A}{D}\,\ddot y, \qquad \omega_f = 2\pi\,\mathrm{St}\,\frac{U_a}{D}$$

The lift per unit length acts across the relative normal flow, in the same direction as the synchronisation lift:

$$\mathbf f = \tfrac{1}{4}\,\rho\,D\,C_{L0}\,q\,U\,(\mathbf t\times\mathbf v_n)$$
Symbol Meaning
$U_a$ Ambient flow speed normal to the line (the paper's free stream). The cable's own cross-flow velocity does not modulate the wake frequency.
$U$, $\mathbf v_n$ Speed and vector of the relative normal flow, as for the synchronisation lift
$\ddot y$ Node acceleration along the cross-flow axis $\mathbf t\times\mathbf v_n/U$

The paper's fluid damping, $\gamma\,\omega_f\,\rho D^2\dot y$ with $\gamma = C_D/(4\pi\,\mathrm{St})$, is the linearised Morison drag, and CableDyn already applies that drag in full. The wake therefore contributes the lift only.

Implementation

  • Configuration: the wake oscillator is a mode of the cable's VIV configuration. Set_VIV takes the per-element (St, eps, A). The element lift uses $q$ at its end nodes where the synchronisation model uses $\cos\phi$, with exact position and velocity Jacobians at fixed $q$.
  • Time integration: the per-node state $(q,\dot q)$ is integrated beside the cable, like the synchronisation phase.
    • At the start of a step, a predictor advances it under the step-start acceleration to give the $q$ for the step's lift.
    • After convergence, a corrector advances it from the committed state with the acceleration linear to the converged end value.
    • Both use classical RK4 in sub-steps with $\omega_f\max(1, \varepsilon q^2)\,\delta t \le 0.1$, so a large $\varepsilon$ stays stable; an interval whose rate grows on the way is redone with twice the sub-steps (CD_VIV_Wake_Advance).
  • Start state: $q$ starts on its limit cycle at the node's VIV phase seed, $q = 2\cos\phi_0$.
  • Saved state: $(q,\dot q)$ is part of the step-recovery, snapshot and checkpoint state. In the OpenFAST mirror it adds 2*nn values after the in-line block.
  • Python: the deck reader applies the native checks. The builder writes the section through LineType.wake_cl0, wake_st, wake_eps and wake_a.
  • Scope: finite-EI cables, cross-flow only. Each of these is refused by name: an EI = 0 line with the wake oscillator, a line mixing the two models, and CL0 > 0 on a type with Cl > 0.

Verification

Test Check Result
test_viv_wake_kernel Free oscillator Settles on $q = 2.001$ at the period shifted by $\varepsilon^2/16$
Forced at its own frequency vs Facchinetti Eq. 17 0.2 % at $y_0 = 0.05$, 1.9 % at $y_0 = 0.5$ (the third harmonic the one-harmonic balance omits)
Sub-stepped advance Fourth-order convergence
test_viv_wake_deck Taut cable of the in-line VIV gate, Cl 0, CL0 0.3 Locks in at 0.282 Hz (cable 0.300 Hz), steady mid-span A/D 0.585
Uncoupled, A = 0 0.298 Hz, A/D 0.099
Power balance over the lock-in Drag and damping remove the wake lift's 2.84 W to within 0.21 %
CL0 = 0 Identical to the deck without the section, to the printed digits
Refusals 11
test_viv_coupled Coupled route Checkpoint block grows by 2*nn. A restart continues bit for bit; a rebuild without the VIV state does not; a rewound step repeats
Python Reader, builder, parity Rows read, kept and refused as natively; five native/Python parity decks agree

Run before opening:

  • full ctest under the default and OPENBLAS_CORETYPE=Prescott kernels;
  • Debug -fcheck=all on the new tests;
  • pytest, ruff, mypy, Sphinx -W, pre-commit.

Docs

The wake oscillator on EI = 0 lines is left for a follow-up, as was done for in-line VIV (#145 → #146).

CableDyn's VIV follows the synchronisation model of Thorsen et al. The
other model class in common use is the wake oscillator: a van der Pol
oscillator stands for the near wake and drives the lift. A model-form
comparison needs both on the same line.

An optional WAKE OSCILLATOR section row TypeName CL0 [St [eps [A]]]
gives a line type the wake oscillator of Facchinetti, de Langre and
Biolley (J. Fluids Struct. 19, 2004), distributed along the line as in
Violette et al. (2010):

  q'' + eps om (q^2 - 1) q' + om^2 q = (A/D) y'',  om = 2 pi St U_a/D,
  lift per unit length 1/4 rho D CL0 q U^2 across the relative flow,

with y'' the node's cross-flow acceleration (their acceleration
coupling), U_a the ambient flow speed normal to the line (their free
stream, so the cable's own cross-flow velocity does not modulate the
wake frequency), U the relative normal flow speed of the lift (as the
synchronisation lift), and the defaults St 0.2, eps 0.3, A 12 they fix from
forced-wake data (checked in the PDF). Their fluid damping
gamma om rho D^2 y', gamma = Cd/(4 pi St), is the linearised Morison
drag CableDyn applies in full, so the wake adds the lift only. It
replaces the synchronisation lift of the type, which keeps Cl 0; a line
takes one VIV model.

It is a mode of the cable's VIV configuration: Set_VIV takes the
per-element (St, eps, A), the lift scale is 1/4 rho D CL0, and the
element lift takes q at its end nodes in place of cos(phi), with the
exact Jacobians at fixed q. The state (q, q') per node is advanced
beside the cable like the phase: a predictor under the step-start
acceleration for the step's lift, then from the committed state with
the acceleration linear to the converged end one, at the step-start
wake frequency (classical Runge-Kutta in sub-steps of om dt <= 0.1,
CD_VIV_Wake_Advance). q starts on its limit cycle at the VIV phase
seed, q = 2 cos(phi_0). The state is in the step-recovery, snapshot and
checkpoint state and the OpenFAST mirror (2 nn values after the
in-line block). Finite-EI cables only for now; an EI = 0 line with the
wake oscillator is refused by name, as is a line mixing the models.

The Python deck reader takes the section with the native checks, the
builder writes it (LineType.wake_cl0, wake_st, wake_eps, wake_a).

Checks:
- tests/test_viv_wake_kernel.f90: the free oscillator settles on q = 2
  at its period (the van der Pol shift eps^2/16); forced at its own
  frequency it follows the lift magnification of Facchinetti's Eq. 17
  within 0.2 % at y0 = 0.05 and 1.9 % at 0.5 (the third harmonic their
  one-harmonic balance leaves out; halving the step changes K by
  2e-5), and the sub-stepped advance converges at fourth order;
- tests/test_viv_wake_deck.f90: on the taut cable of the in-line VIV
  gate with Cl 0 and CL0 0.3 the wake locks the cable in at 0.282 Hz,
  below its own 0.300 Hz, at a steady A/D 0.585; uncoupled (A 0) it
  drives the cable at 0.298 Hz at A/D 0.099; over the lock-in the drag
  and damping take out the wake lift's 2.84 W within 0.21 %; CL0 0 is
  the deck without the section to the printed digits; eleven refusals;
- tests/test_viv_coupled.f90: on the coupled route the cable's
  checkpoint block grows by 2 nn, the restarted run continues bit for
  bit, a rebuild without the VIV state does not, and a rewound step
  repeats;
- Python: rows read, kept and refused as natively; the builder writes
  the values given; five native/Python parity decks agree.
Full ctest under both BLAS kernels, Debug -fcheck=all on the new
tests, pytest, ruff, mypy, Sphinx -W, pre-commit.

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 Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T03:00:44.212239Z 4941e4c 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 Nov 13, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35856854 | 📁 Comparing 4941e4c against latest (789cb6d)

  🔍 Preview build  

13 files changed · ± 13 modified

± Modified

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0193895c53

ℹ️ 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".

Comment thread src/CableDyn_VIV.f90 Resolved
CD_VIV_Wake_Advance chose its RK4 sub-steps from om dt <= 0.1 alone. The
van der Pol damping eps om (q^2 - 1) is a faster rate for a large eps,
which the deck accepts: with eps 20 and om 1 the unforced oscillator
from (2, 0) went non-finite within 0.5 s in 0.1 s calls.

The sub-steps now satisfy r dt <= 0.1 with r = om max(1, eps q^2) at
the start of the interval, and the interval is redone from its start
with twice the sub-steps should the rate exceed 0.2/dt on the way or
the result not be finite (up to 1e6 sub-steps). For the default eps 0.3
the count is unchanged until |q| > 1.83, so one call still equals two
half calls to round-off; every documented wake result is unchanged at
its printed digits.

tests/test_viv_wake_kernel.f90 K4: eps 20 from (2, 0) in 0.1 s calls
stays finite and matches 1 ms calls within 1e-13 at t = 1 s
((1.967, -0.034)). The theory text gives the new rule.

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. Another round soon, please!

Reviewed commit: 4941e4ce5d

ℹ️ 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 0c73735 into dev Nov 13, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-wake-oscillator branch November 13, 2026 04:44
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