Skip to content

feat: amplitude-dependent VIV coefficients (VIV AMPLITUDE section) - #155

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

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

Conversation

@SMI-Lab-Inha

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

Copy link
Copy Markdown
Owner

Summary

Adds amplitude-dependent VIV coefficients. A new optional VIV AMPLITUDE section gives a line type a table over the cross-flow amplitude ratio A/D:

  • Cv, which replaces the type's Cl. This is the amplitude-dependent excitation of Thorsen et al. (2016), who fit a curve C_v(y₀/D) to riser tests.
  • An optional CdAmp, which multiplies the type's normal drag coefficient, for drag amplification laws such as Chaplin et al. (2005, Eq. 4).
--------------------- VIV AMPLITUDE ------------------------------------
TypeName   AD     Cv     CdAmp
(-)        (-)    (-)    (-)
riser      0.0    0.8    1.0
riser      0.3    0.9    1.5
riser      0.6    0.0    2.0

The table is linear between rows and held beyond the end ones. A type takes 2 to 32 rows with A/D strictly increasing, and it needs the synchronisation lift (Cl > 0). It works on EI = 0 lines and finite-EI cables, standalone and coupled. A new channel, VIVAmp<L>N<J>, writes the smoothed amplitude estimate [m].

Amplitude estimate

Each node estimates its amplitude as Thorsen et al. do (their Eq. 8 and 9):

$$y_0 = \frac{1}{2}\int_{t_1}^{t_2} |\dot y|\,\mathrm{d}t, \qquad \frac{\mathrm{d}y_0^*}{\mathrm{d}t} = k_a\,(y_0 - y_0^*), \quad k_a = \frac{0.1}{\Delta t}$$

Here $t_1, t_2$ are the last two zero crossings of $\dot y$.

  • The travel is integrated by the trapezoidal rule. A crossing inside a step is placed by linear interpolation.
  • The travel is carried signed, $\int \dot y\,\mathrm{d}t$ since the last crossing, so a reversal through a sample at exactly zero (+1, 0, −1) ends the half cycle there, while a touch (+1, 0, +1) ends none.
  • $\dot y$ is the node velocity across the ambient flow normal to the line, $\dot{\mathbf r}\cdot(\mathbf t\times\mathbf u_n)/|\mathbf u_n|$, as in their Fig. 1 (y across the incoming flow). The phase's cross-flow axis, across the relative flow, turns with the node's own velocity. At A/D 0.68 that axis read the amplitude 16 % low; the ambient axis reads it within 0.03 %.
  • An element reads its table at the mean $y_0^*$ of its free nodes over its diameter (the one free node next to a fixed end). It uses the committed estimate, so the Jacobians only scale.

State and checkpoints

The estimate is four more rows of the per-node VIV motion statistics viv_ms:

Line Rows of viv_ms Checkpoint
Without a table CD_VIV_NMS = 2 (the mean squares) unchanged, bit for bit
With a table CD_VIV_NMS_AMP = 6 (the mean squares, then s, y₀, y₀*, last ẏ) the line VIV block grows by 4 nn

The rows travel through the existing step-recovery, snapshot, system-rewind, checkpoint and OpenFAST-mirror paths. Two paths needed changes:

  • The system snapshot buffers now size the VIV block per line, instead of using the q-sized slot. A snapshot taken after a line gains tables resizes the buffer; restoring a snapshot taken before that change is refused, with nothing restored.
  • The automatic sub-stepping slots of an EI = 0 line now check both dimensions of the statistics, so a line that gains tables after it has stepped reallocates them.
  • The checkpoint and mirror sign checks skip the two signed rows (the travel and the last velocity).
  • The table lookup stays inside the table for a NaN amplitude (a diverged run).

Verification

Test Check Result
test_viv_amplitude_kernel Harmonic velocity Amplitude within the trapezoidal $(\omega\Delta t)^2/12$ = 1.95e-6; halving the step quarters it
Smoothing; touch of zero; growing oscillation Eq. 9 step by step; no half cycle ended; mean amplitude of each half cycle within 0.1 %
Tables Interpolate, hold at the ends, NaN stays inside, bad tables refused by name
test_viv_amplitude_deck (taut gate line, EI = 0 and finite-EI) Cv = Cl, CdAmp 1 Identical to the deck without the section, bit for bit
VIVAmp vs steady mid-span response Within 0.03 % (A/D 0.68)
Cv falling to 0 at A/D 0.3 Response held at A/D 0.28
Cv 0, CdAmp 2 Settles at the static offset of Cd 2.4 to six digits
Refusals 13
test_viv_coupled Tables on both lines Checkpoint blocks +4 nn; restart bit for bit; rebuild without the VIV state differs; rewound step repeats
test_viv_amplitude_kernel Reversal through a zero sample A triangular velocity sampled on its zeros ends each of its nine half cycles at y₀ = 1 exactly
test_model Tables set on a sub-stepped line after stepping Slots take six rows; 100 more steps converge (the old guard stops on an array-bound mismatch)
test_system Line gains tables after a snapshot New snapshot resized and restores; restoring the old one is refused, state untouched
Python Reader, builder, parity Rows read, kept and refused as natively; six native/Python parity decks agree

Run before opening:

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

Docs

  • doc/driver_format.md: the section and the VIVAmp channel.
  • doc/theory.rst: the Amplitude-dependent coefficients subsection.
  • doc/outputs.rst, doc/capabilities.rst, CHANGELOG.md.

Thorsen et al. (2016) and Chaplin et al. (2005) are already in doc/references.rst.

Thorsen, Saevik and Larsen (J. Fluids Struct. 61, 2016) make the
cross-flow excitation coefficient of the synchronisation model a
function of the vibration amplitude, C_v(y0/D), fitted to riser tests;
drag amplification laws of vibrating cylinders (Chaplin et al. 2005,
Eq. 4) are functions of the same amplitude.

An optional VIV AMPLITUDE section, rows TypeName AD Cv [CdAmp], gives a
line type a table over the amplitude ratio A/D of the coefficient Cv
that replaces its LINE TYPES Cl and a factor CdAmp (default 1) of its
normal drag coefficient, linear between rows and held beyond the end
ones (2 to 32 rows, A/D strictly increasing, the type with Cl > 0).

Each node estimates its amplitude as Thorsen et al. do (Eq. 8 and 9):
half the travel between two zero crossings of the cross-flow velocity
(trapezoidal, crossings placed by linear interpolation), smoothed by a
tenth of the difference per step (k_a = 0.1/dt). The velocity is taken
across the ambient flow normal to the line, their incoming flow: the
phase's axis across the relative flow turns with the node's own
velocity and read the amplitude 16 % low at A/D 0.68. An element reads
its table at the mean of its free nodes over its diameter, at the
committed estimate, so the Jacobians only scale. The estimate is
updated at the end of each converged step from the committed one.

The estimate is four more rows of the per-node VIV motion statistics
(viv_ms, CD_VIV_NMS_AMP rows with a table, CD_VIV_NMS without, so a
deck without a table runs and checkpoints exactly as before), carried
by the step-recovery, snapshot and system rewind paths (the system
snapshot follows a line that gains tables, a restore across that change
is refused) and appended to the line VIV checkpoint blocks (4 nn
values). VIVAmp<L>N<J> writes the smoothed estimate [m] on a line with
a table. The Python deck reader
mirrors the section and channel checks; the builder writes the table
(LineType.viv_amplitude).

Checks:
- tests/test_viv_amplitude_kernel.f90: a harmonic velocity gives the
  amplitude within the trapezoidal (om dt)^2/12 (1.95e-6; halving the
  step quarters it), the smoothing is Eq. 9 step by step, a touch of
  zero ends no half cycle, a growing oscillation gives each half
  cycle's mean amplitude within 0.1 %, tables interpolate and hold,
  a NaN amplitude stays inside a table, and bad tables are refused by
  name;
- tests/test_viv_amplitude_deck.f90, on the taut gate line as an EI = 0
  line and a finite-EI cable: Cv = Cl with CdAmp 1 is the deck without
  the section bit for bit; VIVAmp follows the steady mid-span response
  within 0.03 % (A/D 0.68); a Cv falling to zero at A/D 0.3 holds the
  response at 0.28; Cv 0 with CdAmp 2 settles at the static offset of
  Cd 2.4 to six digits; thirteen refusals;
- tests/test_viv_coupled.f90: with tables on both lines the checkpoint
  blocks grow by 4 nn, the restarted run continues bit for bit, a
  rebuild without the VIV state does not, and a rewound step repeats;
- tests/test_system.f90: a snapshot after a line gains tables is resized
  and restores, a restore of one taken before is refused untouched;
- Python: rows read, kept and refused as natively, the builder writes
  them, six native/Python parity decks agree.
Full ctest under both BLAS kernels, Debug -fcheck=all on the new and
changed 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-13T06:50:08.400913Z 9fd0716 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 #35860300 | 📁 Comparing 9fd0716 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: ec9a00720a

ℹ️ 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
Comment thread src/CableDyn_Model.f90 Resolved
…he VIV rows

Two review findings on the amplitude tables.

A cross-flow velocity reversing exactly on a step boundary (+1, 0, -1)
ended no half cycle: the zero sample overwrote the last velocity, so the
following negative one saw no sign change and the travel ran on across
half cycles. The travel is now carried signed, int y' dt since the last
crossing (+-int |y'| dt, as y' keeps its sign between crossings), and a
crossing is a change of sign from that of the running half cycle: the
last velocity, or after zero samples the sign of the travel. A touch
(+1, 0, +1) still ends none. For nonzero samples the amplitudes are
bit-identical to before. The travel row joins the last velocity as a
signed row in the checkpoint and mirror checks.

An EI = 0 line that had stepped with automatic sub-stepping and then
had amplitude tables set kept its two-row sub-step VIV slots, as their
reuse checked the node count only; the next sub-stepped step copied six
rows into two. The slots now follow both dimensions.

Checks: tests/test_viv_amplitude_kernel.f90 K2, a triangular velocity
sampled on its zeros ends each of its nine half cycles at y0 = 1 exactly,
and the touch and reversal through one zero sample; tests/test_model.f90,
tables set on the sub-stepped VIV line after 60 steps, 20 more
sub-stepped steps converge with six-row slots.

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. 🎉

Reviewed commit: 9fd0716f72

ℹ️ 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 3a2753f into dev Nov 13, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-amplitude branch November 13, 2026 08:43
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