Skip to content

feat: VIV FRAME section, wake frequency relative to the cable's filtered motion - #165

Merged
SMI-Lab-Inha merged 1 commit into
devfrom
feat/wake-relative-frequency
Nov 15, 2026
Merged

SMI-Lab-Inha merged 1 commit into
devfrom
feat/wake-relative-frequency

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Problem

The wake oscillator took its frequency $\omega_f = 2\pi,\mathrm{St},U_a/D$ from the ambient flow normal to the line. A cable moved through still water, by a tow or by its floater, therefore had $U_a = 0$ and never shed. The model could not represent floater-driven VIV of a dynamic cable.

Change

A new optional VIV FRAME section sets the flow frame of a line type's VIV model, one row TypeName Tf per type. With $T_f > 0$ [s] the free stream is the ambient flow relative to the node's velocity, low-pass filtered over $T_f$:

$$ U_a = \bigl|(\mathbf u - \bar{\mathbf v})_n\bigr|,\qquad \bar{\mathbf v}_{n+1} = \bar{\mathbf v}_n + \bigl(1 - e^{-\delta t/T_f}\bigr)(\mathbf v_{n+1} - \bar{\mathbf v}_n) $$

This is the exact first-order filter of the converged end velocity held over the step, started at the node's initial velocity. The slow motion counts as flow; the VIV velocity, much faster than $T_f$, is filtered out. With Tf 0 or no row, runs are unchanged to the bit.

--------------------- WAKE OSCILLATOR ------------------
TypeName   CL0    St     eps    A
cable      0.3    0.2    0.3    12
--------------------- VIV FRAME ------------------------
TypeName   Tf
(-)        (s)
cable      10

In this PR the frame sets the wake oscillator's frequency, so a row needs a WAKE OSCILLATOR row. The frame is a section of its own, not a wake column, so that the synchronisation model's ambient-frame quantities can take the same frame later without changing the input. Those quantities are the amplitude estimate (VIV AMPLITUDE) and the cross-flow damping split (VIV DAMPING); for a cylinder moved through still water both are currently inactive.

Line kind Where the filtered velocity lives
Finite-EI cable wo_s grows from 2 to 5 rows per node when a node has $T_f > 0$. The recovery, snapshot and checkpoint copies carry the rows; the checkpoint mirror packs SIZE(wo_s).
EI = 0 line Rows 3–5 of the VIV motion statistics (CD_VIV_NMS_AMP rows; a wake line has no amplitude table). The state get/set, rollback and checkpoint already carry them.

The core setters take wake(4, ne) = $T_f$ as an optional fourth row. The deck reader, Python reader and builder (viv_frame_tf), the input format, theory and capability docs, and the CHANGELOG are updated.

Results

A taut cable (100 m, D 0.1 m, 50 kN; first mode locks in at 0.28 Hz):

Case A/D f [Hz]
Held, 0.15 m/s current, ambient flow (reference) 0.5850 0.282
Towed at 0.15 m/s through still water, Tf 10 s 0.5881 0.283
Towed at 0.15 m/s through still water, no frame 0.0421 –
Held, 0.15 m/s current, Tf 10 s (finite-EI) 0.5848 0.282
Held, 0.15 m/s current, Tf 10 s (EI = 0) 0.5854 0.282

Tests

  • test_viv_wake_deck
    • W6: the tow results above.
      • Towed with Tf, the cable locks in as the held cable in the current: A/D within 5 %, frequency within 0.003 Hz (measured 0.5 %, 0.001 Hz).
      • Towed without the frame, A/D is below a tenth of that.
      • On the held cable, Tf changes A/D by less than 2 % on both cores (measured 0.03 %), and the cores agree within 3 % (measured 0.1 %).
    • W7: VIV FRAME refusals by name: a malformed row, an unknown or repeated type, a negative Tf, and a type without a wake oscillator.
  • test_viv_coupled: with a VIV FRAME (Tf 5 s) the checkpoint blocks grow by the filtered velocity. The restarted run continues bit for bit, a rebuild without the VIV state does not, and a rewound step repeats.
  • Python: the reader keeps the section through load and save; the builder writes it and refuses it without wake_cl0; the native-parity cases accept Tf 8 and 0 and refuse a negative value, three columns, or a synchronisation-model type.

Checks

  • ctest 424/424 under both BLAS kernels (default and Prescott).
  • Debug subset (Hermite, surface, waves, added mass, VIV): 49/49.
  • pytest: 3204 passed, 47 skipped, with the native driver.
  • ruff and ruff format: clean.
  • mypy: only the two local missing-stub errors (pandas), the same as on dev.
  • Sphinx -W and pre-commit: clean.

…red motion

The wake oscillator took its frequency from the ambient flow normal to
the line. A cable moved through still water, by a tow or by its floater,
therefore never shed, and the model could not drive floater-induced VIV.

A new optional section VIV FRAME, rows `TypeName Tf`, sets the flow
frame of a line type's VIV model. With Tf > 0 [s] the free stream is the
ambient flow relative to the node's velocity, low-pass filtered over Tf:

  U_a = |(u - vbar)_n|,
  vbar_{n+1} = vbar_n + (1 - exp(-dt/Tf)) (v_{n+1} - vbar_n)

This is the exact first-order filter of the converged end velocity held
over the step, started at the node's initial velocity. The slow motion
counts as flow, and the VIV velocity, much faster than Tf, is filtered
out.

In this commit the frame sets the wake oscillator's frequency, and a row
needs a WAKE OSCILLATOR row. The synchronisation model's ambient-frame
quantities (the amplitude estimate, the cross-flow damping split) can
take the same frame later without changing the input. With Tf 0 or no
row, runs are unchanged to the bit.

- Finite-EI cables: wo_s grows from 2 to 5 rows per node when a node has
  Tf > 0. The recovery, snapshot and checkpoint copies carry the new
  rows, and the mirror packs SIZE(wo_s).
- EI = 0 lines: the filtered velocity takes rows 3-5 of the VIV motion
  statistics (CD_VIV_NMS_AMP rows; a wake line has no amplitude table),
  so the state get/set, rollback and checkpoint already carry it.
- The core setters take wake(4, ne) = Tf as an optional fourth row.
- Deck reader, Python reader and builder (viv_frame_tf), docs and
  CHANGELOG.

Gates:
- test_viv_wake_deck W6: a finite-EI taut cable towed at 0.15 m/s
  through still water, with Tf 10 s, locks in at A/D 0.588, 0.283 Hz.
  The same cable held in a 0.15 m/s current gives 0.585, 0.282 Hz.
  Without Tf the towed cable reaches A/D 0.042.
  On the held cable Tf changes A/D by 0.03 % on both cores, and the
  cores agree within 0.1 %.
- test_viv_wake_deck W7: VIV FRAME refusals by name (malformed row,
  unknown or repeated type, negative Tf, a type without a wake
  oscillator).
- test_viv_coupled: with a VIV FRAME the checkpoint blocks grow by the
  filtered velocity; the restarted run continues bit for bit, a rebuild
  without the VIV state does not, and a rewound step repeats.
- Python reader, builder and native-parity cases for the section.

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 15, 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-15T03:03:02.886129Z 3fa4ace 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

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35899997 | 📁 Comparing 3fa4ace against latest (789cb6d)

  🔍 Preview build  

14 files changed · ± 14 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 3fa4ace895

ℹ️ 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 7d3998f into dev Nov 15, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/wake-relative-frequency branch November 15, 2026 05:31
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