Skip to content

feat: VIV FRAME for the synchronisation model's amplitude estimate and damping split - #166

Merged
SMI-Lab-Inha merged 3 commits into
devfrom
feat/viv-frame-sync
Nov 15, 2026
Merged

SMI-Lab-Inha merged 3 commits into
devfrom
feat/viv-frame-sync

Conversation

@SMI-Lab-Inha

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

Copy link
Copy Markdown
Owner

Summary

#165 made the wake-oscillator frequency use the flow relative to the node velocity low-pass filtered over Tf (VIV FRAME). The synchronisation model still defined its ambient-frame features across the ambient flow only:

  • the amplitude estimate that feeds VIV AMPLITUDE (Cv(A/D) and the drag factor CdAmp);
  • the cross-flow/in-line axes and the blend to Morison of the VIV DAMPING split.

A cylinder moved through still water therefore got y0 = 0, Cv(0), CdAmp(0) and a pure Morison split, while the same problem in the cylinder's frame got the amplitude-dependent features. For a floater-driven cable (the hang-off moves at wave frequency) the result depended on the frame.

With a VIV FRAME row and Tf > 0, these features now use the flow relative to the filtered node velocity $\bar v$:

$$ \dot y' = (\mathbf v - \bar{\mathbf v})\cdot\mathbf e, \qquad \mathbf e = \frac{\mathbf t \times (\mathbf u - \bar{\mathbf v})_n}{\lVert(\mathbf u - \bar{\mathbf v})_n\rVert} $$

on finite-EI Hermite cables and EI = 0 lines. Without the row (or with Tf = 0) every result is bit-identical to dev.

Implementation

  • Filter state: the exact first-order filter of feat: VIV FRAME section, wake frequency relative to the cable's filtered motion #165, started at the node velocity. With a frame, viv_ms grows from 6 to 9 rows (rows 7-9 hold $\bar v$), so recovery, snapshot, checkpoint and the System pack/unpack carry it unchanged.
  • Damping split: an element takes the mean $\bar v$ of its end nodes, held at its step-start value so the Jacobians stay exact (new optional frame_v of the drag kernel).
  • Setters: CD_HermiteCable_Dyn_Set_VIV(tf=) and CD_Set_Model_VIV(tf=) take Tf per element.
  • Deck and Python: grammar, reader and builder (viv_frame_tf) follow the same rules.
  • Docs: new theory section theory-viv-frame, cross-references from the amplitude and damping sections, capabilities rows, driver_format.md, CHANGELOG.

Verification

Frame check: a 20 m finite-EI pipe with the displaced-water mass, moved at 0.6 m/s amplitude and 40 s period through still water, against the same pipe held in water moving the other way (Froude-Krylov included), Tf 0.6 s:

Pipe Frame Peak A/D moving / held RMS A/D moving / held
Amplitude table + VIV DAMPING Tf 0.6 s 0.8191 / 0.8189 0.4464 / 0.4470
Amplitude table + VIV DAMPING none 0.7108 / 0.8502 0.3486 / 0.4500
Cl alone Tf 0.6 s 0.7127 / 0.7136 0.3722 / 0.3710
Cl alone none 0.7108 / 0.7364 0.3486 / 0.3749
  • Gates: with the frame 1 % on peak and RMS (worst 0.67 % over Release, Debug and both BLAS kernels, the residual being the filter lag of the imposed motion, $\omega T_f = 0.094$).
  • Deck tow at 0.15 m/s, Tf 10 s: towed 0.7905 vs held 0.7906 (table + damping), 0.6764 vs 0.6764 (Cl alone).
  • The phase keeps the node's own acceleration: $\dot{\bar v} = (v-\bar v)/T_f$ would carry the VIV velocity.
  • The amplitude estimate scales the VIV velocity by $\omega T_f/\sqrt{1+\omega^2T_f^2}$ (0.9985 at 0.29 Hz with Tf 10 s); documented in the theory section.
  • Grammar: a VIV FRAME row needs Cl > 0 or a WAKE OSCILLATOR row; a type with neither is refused by name.
  • ctest: 426/426 on the default and the Prescott OpenBLAS kernels; Debug (-fcheck=all) VIV tests pass.
  • Bit-identity against dev 7d3998f: 10 decks, 26/26 output files byte-identical.
  • check_example_fallbacks.py: 66 decks, no fallback notes; pre-commit clean; Sphinx -W -n gives only the 3 warnings dev also gives.

…d damping split

The synchronisation model defined its ambient-frame quantities across
the ambient flow (current and held field) only. A cable moved through
still water, by a tow or by its floater, therefore kept y0 = 0, Cv(0)
and CdAmp(0), and its VIV DAMPING split blended to Morison's drag,
while the same problem in the cable's frame (the water moving past the
held cable) took the amplitude-dependent values.

A VIV FRAME row (TypeName Tf) now also acts on a type with a VIV
AMPLITUDE table. With Tf > 0 the ambient-frame quantities take the
ambient flow relative to the node velocity low-pass filtered over Tf,
the filter of #165:

  vbar_{n+1} = vbar_n + (1 - exp(-dt/Tf)) (v_{n+1} - vbar_n)

- Amplitude estimate: y' = (v - vbar) . t x (u - vbar)_n/|(u - vbar)_n|,
  and with it the table's Cv, the drag factor CdAmp and C_dy.
- VIV DAMPING split: the axes e_x, e_y and the blend beta take
  (u - vbar)_n, an element the mean vbar of its end nodes. vbar is the
  step-start value within a step, so the Jacobians are unchanged.
- The phase rate keeps the published form (U the relative normal
  speed), and the lift and drag the relative velocity.

For a frame at constant velocity (a steady tow) the quantities equal
those of the held cable exactly; the estimate loses the part of the VIV
velocity that passes the filter, a factor wTf/sqrt(1 + (wTf)^2).

- Finite-EI cables: Set_VIV takes tf(ne) for the synchronisation model
  (refused with the wake oscillator, which keeps wake(4, :), and where
  an element with tf > 0 has no amplitude table). viv_ms grows from 6
  to 9 rows (CD_VIV_NMS_FRAME), rows 7-9 the filtered velocity, so the
  recovery, snapshot, mirror and checkpoint copies carry it. The drag
  kernel takes the frame velocity as an optional frame_v.
- EI = 0 lines: CD_Set_Model_VIV takes tf(n_elem); rows 7-9 of the VIV
  motion statistics hold the filtered smoothed velocity, so the state
  get/set, rollback and checkpoint carry it (CD_Model_VIV_NMS 9).
- Deck reader: a VIV FRAME row needs a WAKE OSCILLATOR row or a VIV
  AMPLITUDE table; the Python reader and builder follow.
- Tf 0 or no row leaves runs unchanged to the bit.

Gates:
- test_hermite_viv_frame: a 20 m pipe of the displaced mass (so the
  in-line inertia of the two frames is the same; another mass differs
  by the Froude-Krylov term) with the amplitude table and Thorsen's
  damping, moved at 0.6 m/s amplitude and 40 s period through still
  water, against the same pipe held in the water moving the other way
  (held field with its acceleration). With Tf 0.6 s: peak A/D 0.838
  against 0.825 (0.834 Debug, 0.843 on the Prescott kernel; gate 5 %),
  RMS 0.415 against 0.445 (gate 12 %; the remainder is the phase input,
  see below). Without the frame: 0.711 against 0.850 peak, 0.349
  against 0.450 RMS. Refusals, an all-zero tf bit for bit, and a
  snapshot replay bit for bit.
- test_viv_frame_deck: a Tf 0 row is the deck without it, bit for bit,
  on both cores; a finite-EI cable towed at 0.15 m/s with Tf 10 s gives
  A/D 0.780 against 0.792 held in the current (0.665 without the
  frame); held in the current Tf changes A/D by 0.16 % (finite-EI) and
  less than 0.01 % (EI = 0); the refusal of a type without a table.
- test_viv_coupled: with a VIV FRAME on amplitude-table types (and VIV
  DAMPING on the cable) both checkpoint blocks grow by 3 per node, 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.

The phase input y' = r'.e, e across the relative flow, equals u.e and
so is zero in still water: the moving pipe's phase follows y'' alone.
It is left in the published form here; taking y' relative to the frame
closes the RMS gap of the pipe check to 0.1 %.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@read-the-docs-community

read-the-docs-community Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35906343 | 📁 Comparing e1b769b against latest (789cb6d)

  🔍 Preview build  

14 files changed · ± 14 modified

± Modified

… filtered motion

The synchronisation phase read the cross-flow velocity r'.e across the
relative flow, which is u.e and so zero in still water: a cable moved
through still water locked its phase on y'' alone, while the held cable
in the moving water did not. The in-line phase input x' = r'.v_n/U
carried the imposed motion along the flow.

With a VIV FRAME row and Tf > 0 the cross-flow and in-line phase inputs
now take the node's velocity relative to its filtered velocity vbar
(viv_node_motion on finite-EI cables; the smoothed velocity in the
phase step on EI = 0 lines). The relative flow, and so the axes and the
shedding speed U of the phase rate, are unchanged. The acceleration
stays the node's: vbar changes slowly, and its rate (v - vbar)/Tf would
carry the VIV velocity into y''.

The frame then acts on every synchronisation type, so a VIV FRAME row
now needs LINE TYPES Cl > 0 or a WAKE OSCILLATOR row, not a VIV
AMPLITUDE table; the setters take tf > 0 where cl > 0. Without a table
the 9 motion statistics keep rows 3-6 at 0 and vbar in rows 7-9. The
Python reader and builder follow. Without a row, or with Tf 0, runs
are unchanged to the bit.

Gates:
- test_hermite_viv_frame, the 20 m pipe of the displaced mass moved at
  0.6 m/s amplitude and 40 s period in still water against the same
  pipe held in the water moving the other way, Tf 0.6 s:

  | pipe              | frame | peak A/D moving / held | RMS A/D moving / held |
  |-------------------|-------|------------------------|-----------------------|
  | table and damping | Tf    | 0.8191 / 0.8189        | 0.4464 / 0.4470       |
  | table and damping | none  | 0.7108 / 0.8502        | 0.3486 / 0.4500       |
  | Cl alone          | Tf    | 0.7127 / 0.7136        | 0.3722 / 0.3710       |
  | Cl alone          | none  | 0.7108 / 0.7364        | 0.3486 / 0.3749       |

  Gate 1 % on peak and RMS with the frame (at most 0.7 % over the
  Release and Debug builds and both OpenBLAS kernels; the rest is the
  filter lag, omega Tf = 0.094); without it more than 10 % / 15 % with
  the table, more than 4 % RMS with Cl alone.
- test_viv_frame_deck: towed at 0.15 m/s with Tf 10 s, A/D 0.7905
  against 0.7906 held in the current with the same row (0.7924 without
  it) with the table and damping, 0.6764 against 0.6764 (0.6775) with
  Cl alone; gates 0.2 % and 1 %. Held, Tf changes A/D by at most
  0.23 % on both cores (gate 0.5 %). A Tf 0 row is bit-identical on
  both cores with and without the table. A row on a type without VIV
  is refused by name.
- test_viv_coupled: the frame on the lift alone, restart and rewind
  bit for bit with the 9-row VIV block on both lines.
- test_viv_wake_deck W7 and the Python cases follow the new rule.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@SMI-Lab-Inha
SMI-Lab-Inha marked this pull request as ready for review November 15, 2026 12:22
@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-15T13:23:29.581294Z e1b769b 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.

@chatgpt-codex-connector

Copy link
Copy Markdown

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

Reviewed commit: 3874a5aeab

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

On Linux with the Prescott OpenBLAS kernel the moving pipe's peak A/D was 0.8106 against 0.8189
held (1.01 %), above the 1 % gate, while the RMS agreed within 0.2 %. The peak is a single
extreme of the response and ranges 0.811-0.819 over builds, kernels and platforms; the RMS is
the robust measure. The theory section states the spread.

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. Hooray!

Reviewed commit: e1b769b579

ℹ️ 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 5114299 into dev Nov 15, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-frame-sync branch November 15, 2026 15:50
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