Skip to content

feat: VIV FRAME method cycle, a lag-free frame velocity - #188

Merged
SMI-Lab-Inha merged 4 commits into
devfrom
feat/viv-frame-cycle-mean
Nov 20, 2026
Merged

SMI-Lab-Inha merged 4 commits into
devfrom
feat/viv-frame-cycle-mean

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

VIV FRAME gets an optional third column, Method, with the values filter (the default: the existing first-order filter, unchanged to the bit) and cycle. With cycle, a synchronisation type's frame velocity is the lag-free cycle mean of the node velocity over the window Tf:

$$ \bar{\mathbf v}(t) = \frac{1}{T_f}\int_{t-T_f}^{t}\mathbf v,dt' + \tfrac12\left[\mathbf v(t) - \mathbf v(t - T_f)\right] $$

--------------------- VIV FRAME ----------------------------------------
TypeName   Tf     Method
(-)        (s)    (-)
cable      0.373  cycle

Why

The first-order filter lags a slow motion at $\omega_m$ by $\arctan\omega_m T_f$. A decelerating tow or floater motion therefore leaves the frame faster than the cable, and an accelerating one leaves it slower. The frame speed then differs between the two half-cycles at the same flow speed, which is a hysteresis source of the filter's own.

The cycle mean removes that lag:

  • A component of period $T_f$ and its harmonics drop out of both terms: the cross-flow VIV at $f = 1/T_f$, and the in-line VIV at $2f$.
  • A velocity linear in time passes unchanged.
  • A velocity quadratic in time is off by $T_f^2/12$ times its second derivative.

Limitation

Tf must be one period of the response. Off that period, the VIV velocity passes into the frame by about $|\sin\pi\delta|$ for $fT_f = 1 + \delta$.

On the taut cable of the deck gate, which responds at 0.29 Hz, the cable locks in at:

Tf A/D
3.5 s 0.79 (the ambient flow's 0.79)
1 s 0.55

So the method suits a response at one known frequency. A response that moves between modes keeps the filter. The docs say this.

Implementation

  • Kernel (CableDyn_VIV: CD_VIV_Cycle_Init, CD_VIV_Cycle_Update, CD_VIV_Cycle_Valid):
    • The velocity's integral is sampled every $T_f/64$, exactly for the velocity linear over a step and for any step length.
    • The samples sit in a ring of 66 per node, held relative to the integral at the committed time, so their values stay of the order of the velocity however long the run.
    • $I(t - T_f)$ and $\mathbf v(t - T_f)$ come from the quadratic through the three samples around $t - T_f$.
  • State: $2 + 3\times 66$ rows of the node's motion statistics, after the frame rows 7–9. This holds on EI = 0 lines (CD_Set_Model_VIV tf_cycle) and on finite-EI cables (CD_HermiteCable_Dyn_Set_VIV tf_cycle).
    • Step recovery, snapshots, rollback and checkpoints carry the state with no further code.
    • Every node holds a valid state, the ends included.
    • A restored state with a sample time outside $[0, 1]$, or a slot off the ring, fails closed (CD_Set_Model_VIV_State, CD_HFMF_UnpackMirror).
    • The update starts from the committed state, so a repeated end-of-step pass gives the same result.
  • Deck:
    • Rows are TypeName Tf [Method].
    • cycle needs Cl > 0 and Tf > 0, so the wake oscillator keeps the filter.
    • A line takes one method; a line whose types mix the two is refused.
  • Docs: driver_format.md (VIV FRAME), theory.rst (flow frame, Cycle mean), capabilities.rst, and CHANGELOG.md.

Tests

  • New viv_cycle_frame (kernel):
    • A period-$T$ component and its second harmonic drop out within 0.25 % of their amplitude.
    • A ramp passes to round-off (1e-14).
    • A quadratic gives the $T^2/12$ error within $c h^2$.
    • The same holds with steps of 1.7 sample intervals.
    • Invalid states are rejected.
  • hermite_viv_frame F5:
    • The moving and the held pipe agree with the cycle mean (peak 0.854 / 0.849 D, RMS 0.455 / 0.454 D).
    • The frame velocity follows the imposed velocity within 0.17 % of its amplitude, against 1.7 % for the filter.
    • A snapshot restored mid-run replays bit for bit, the ring included.
  • hfmf_mirror (6): the checkpoint block carries the ring, round-trips bit-identically, and a fractional slot fails closed.
  • viv_coupled: checkpoint restart and rewind with Tf 3.4 cycle on the EI = 0 riser and the finite-EI cable, bit for bit.
  • viv_frame_deck G5–G7:
    • Method filter is the row without the column, bit for bit, on both cores.
    • With Method cycle, the towed cable responds as the held one (A/D 0.7931 against 0.7922).
    • In the current, the response is that of the ambient flow (0.7930 / 0.7922 finite-EI, 0.4617 / 0.4625 EI = 0).
    • Refusals by name.

Full ctest, slow tier included: 434/434 pass (gfortran 16.2 Release, Windows, 3 jobs); python 2505 passed. The docs build is left to CI.

Effect on L3-O (published sets; not a change to the record)

These runs use the SJTU moving cylinder, with the window $T_f = 1/f_1$ = 0.373 s against the record's filter (Tf 0.2 s). The column shows the mean gap between the deceleration and acceleration paths.

Set, $U_{R,max}$ filter (record) cycle measured
uls19, 6.5 0.426 0.413 0.089
uls19, 7.9 0.498 0.599 0.123
b1, 6.5 0.364 0.320 0.089
b1, 7.9 0.380 0.267 0.123

The method removes the filter's lag from the frame. It does not remove these sets' deceleration hold, so the record keeps the filter. Defaults are unchanged.

The VIV FRAME section takes an optional third column, rows TypeName Tf
[Method]: filter (the default, the first-order filter as before) or cycle.
With cycle the frame velocity of a synchronisation type is the mean of the
node velocity over the window Tf plus half its change over it,

  vbar(t) = (1/Tf) int_{t-Tf}^{t} v dt' + (v(t) - v(t-Tf))/2,

which drops a component of period Tf and its harmonics (the cross-flow VIV
and the in-line VIV at twice its frequency) and passes the slow motion of a
towed or floater-driven cable without the filter's lag; Tf is then one
period of the response. The filter's lag leaves the frame faster than the
cable on a decelerating motion and slower on an accelerating one.

The kernel (CD_VIV_Cycle_Init, CD_VIV_Cycle_Update, CD_VIV_Cycle_Valid)
samples the velocity's integral every Tf/64, exactly for the velocity linear
over a step, in a ring of 66 samples held relative to the integral at the
committed time; I(t - Tf) and v(t - Tf) come from the quadratic through the
three samples around t - Tf. Its state, 2 + 3 x 66 rows per node, sits in
the motion statistics after the frame rows on EI = 0 lines and finite-EI
cables, so step recovery, snapshots and checkpoints carry it, and a
restored state with a sample time off [0, 1] or a slot off the ring fails
closed. A line takes one method; rows without the column are unchanged to
the bit.

Tests: viv_cycle_frame (a period-Tf component and its second harmonic drop
out within 0.25 %, a ramp passes to round-off, a quadratic gives the
T^2/12 error, long steps); hermite_viv_frame F5 (moving and fixed pipe
agree, the frame follows the imposed velocity within 0.17 % against 1.7 %
for the filter, snapshot replay bit for bit); hfmf_mirror (6) checkpoint
round-trip and an invalid slot failing closed; viv_coupled (checkpoint
restart and rewind with the ring on both line kinds); viv_frame_deck G5-G7
(Method filter is the row without it to the bit, Method cycle towed and
held, refusals); viv_wake_deck W7 (the four-column row, an unknown Method
and Method cycle on a wake-oscillator type refused by name). The Python
deck checker and builder follow (viv_frame_method).

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 20, 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-20T07:09:10.888554Z 683694e 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 20, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #36034597 | 📁 Comparing 683694e against latest (789cb6d)

  🔍 Preview build  

16 files changed · ± 16 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: ce56b5c6e7

ℹ️ 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
A sample landing on the step end (window 1 s, steps of 0.01 s) could round
the time since the latest sample a few ulps below 0, a valid simulation
state that CD_VIV_Cycle_Valid then refused on a checkpoint restore. The
update now clamps it to [0, h]; viv_cycle_frame C5 runs 10000 such steps and
checks the state stays valid.

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. You're on a roll.

Reviewed commit: cafdc22b5c

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

mypy (Python 3.10 target) wants dict[str, list[str]] for the map of a line's
section types that the line-wide method check takes.

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 them coming!

Reviewed commit: 67b03cbca5

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

fprettify (the CI format gate, line length 120) re-indented them; the calls
are split instead.

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. What shall we delve into next?

Reviewed commit: 683694e0c9

ℹ️ 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 3e5638d into dev Nov 20, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-frame-cycle-mean branch November 20, 2026 08:07
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