Skip to content

fix: the coupled VIV response converges at second order in the time step - #171

Merged
SMI-Lab-Inha merged 4 commits into
devfrom
fix/viv-coupled-order
Nov 16, 2026
Merged

SMI-Lab-Inha merged 4 commits into
devfrom
fix/viv-coupled-order

Conversation

@SMI-Lab-Inha

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

Copy link
Copy Markdown
Owner

Summary

The coupled VIV response converged at first order or worse in the time step. Under prescribed motion, the same phase update was second order. The cause is that the synchronisation model read the line's acceleration from the generalised-α committed value $a_n$, and that is not the line's acceleration. The phase now advances on the step's mid-point motion, and every coupled VIV variant converges at second order. The limits at $\rho_\infty$ 1, 0.8 and 0.4 agree to 1e-9.

This is a deliberate change to the VIV time discretisation, not a round-off change. Only the two VIV example decks change, and both move toward their fine-step results.

How it was found

A taut line locked in by the synchronisation model (the long-run VIV checks) changed its lock-in frequency by 0.74 %, 0.41 % and 0.27 % per halving of the step, from 25 to 200 steps per cycle.

Cause

The phase sampled $a_n$ for its cross-flow phase, and the wake oscillator used it for its forcing.

  • At $\rho_\infty < 1$: $a_n$ is the line's acceleration at $t_n + (\alpha_m - \alpha_f)\Delta t$, a first-order error. The errors were $0.06/n$ at $\rho_\infty$ 0.8 and $0.25/n$ at 0.4, with $n$ steps per response period.
  • At $\rho_\infty = 1$: $a_n$ carries an undamped alternating mode of the integrator. On the 20 m line, the mid-span $a_n$ alternated by ±11 m/s² against a physical 1.3 m/s². The lock-in converged to a frequency 3.4 % low: 3.940 rad/s at 3200 steps per cycle, against 4.0797.

Prescribed motion imposes the exact acceleration, which is why it did not show there.

Candidates switched off one at a time on that line, from 25 to 3200 steps per cycle, over 400 cycles:

Candidate Result
Second-order running mean square no change
Fixed normalisation instead of the RMS still first order
Newton tolerance 1e-12 no change
Lift at a fixed shedding rate (no phase feedback) second order (ratios 3.8–4.0)
Acceleration recomputed from the equations of motion each step limit moves to 4.0797 rad/s
Phase on the mid-step motion, acceleration from the converged velocities second order at $\rho_\infty$ 1 and 0.8
The same, with the lift's phase predicted from $a_n$ first order again at $\rho_\infty = 1$

No amplitude table, flow frame or in-line VIV is involved in that case.

Fix

  • Phase: the implicit mid-point rule with one fixed-point pass. It uses the node's cross-flow motion at the step's mid-point:

    • the mean position;
    • the velocity $(q_{n+1}-q_n)/\Delta t$;
    • the acceleration $(v_{n+1}-v_n)/\Delta t$.

    This pair is second order at every $\rho_\infty$, free of the lag and the alternating mode, and keeps the phase of a harmonic motion exactly.

  • Lift predictor: the step's lift takes the phase predicted with the previous step's mid-point rate.

    • That rate is a new row of the VIV motion statistics (two rows with in-line VIV).
    • Step recovery, sub-step slots, snapshots, checkpoints and the OpenFAST mirrors carry it, so a restart stays bit-identical.
    • A newly installed VIV model seeds it from the present state.
  • Other updates:

    • Running mean squares: the mid-point rule, weight $1-e^{-\Delta t/T_w}$ on the mid-point sample.
    • In-line phase: the same rule, slaved to the mid-point cross-flow rate.
    • Flow-frame and wake filters: exact for a velocity linear over the step.
    • Wake oscillator: driven by the mid-point acceleration at the mean of the start and end wake frequencies. That acceleration is its predictor (row 2 of its statistics).
  • Validators: the FMF and model restore checks accept the signed predictor rows.

  • Docs: the scheme, the measured error constants and the recommended steps per period are in doc/theory.rst, with a CHANGELOG "Fixed" entry.

Results

Ratio of successive changes per halving of the step (4 is second order), from 25 to 3200 steps per cycle:

Case Before After
Frequency, $\rho_\infty = 1$ limit 3.4 % low 3.6–4.9
Frequency, $\rho_\infty$ 0.8 / 0.4 2.0–3.4 / 1.5–3.2 3.6–4.8 / 3.8–4.5
Mid-span A/D, in-line VIV 2.2–2.3 2.6–4.3
Frequency, flow frame 1.6–2.0 3.1–4.5
Frequency, amplitude table 1.9–2.3 3.0–4.5
Wake oscillator, frequency 2.0–2.5 3.8–4.0
Finite-EI cable, frequency 1.7–2.3 3.1–4.1

Error constants at $n$ steps per response period:

  • Frequency: about $2.2/n^2$ ($\rho_\infty$ 1 and 0.8) and $3.4/n^2$ (0.4); $3.5/n^2$ on the finite-EI cable.
  • Mid-span A/D: $1.6/n^2$ and $3.4/n^2$.
  • Recommendation: 100 steps per response period keeps both within 0.04 %, and 30 within 0.4 %.

Long-run check under prescribed motion:

  • Phase error: after 400 cycles at 100 steps per cycle it is 0.0167 rad, against 0.0334 before, still second order (3.99).
  • Energy closure: 2.0e-4 of the VIV work against 8.3e-5 before, also second order (ratio 4.0). The lift's predicted phase now takes the rate of the previous step's mid-point, half a step behind the old step-start rate.

Example decks

Both VIV example decks are at their default dtM 0.02 s (about 170 steps per response period, rhoInf 0.4). Each value is the error against the same deck at dtM 0.00125 s:

Deck, quantity Before After
viv_taut_line_crossflow, mid-span RMS +0.31 % −0.02 %
viv_taut_line_crossflow, lock-in frequency −0.15 % −0.018 %
viv_taut_line_crossflow, fairlead tension RMS +0.29 % −0.027 %
viv_taut_cable_inline, quarter-span in-line RMS −1.56 % −0.34 %
viv_taut_cable_inline, cross-flow frequency +0.10 % +0.022 %
viv_taut_cable_inline, largest fairlead tension +0.70 % −0.23 %

Over the 90 s the phase moves, so the time series differ pointwise by up to 12 % (crossflow, fairlead tension) and 36 % (inline, quarter-span y) of the channel's range.

Delta Flume validation case (L3-D) rerun

The nine cases and every sensitivity run were rerun on this update; the recorded results, README, provenance.json, VALIDATION.md and the changelog entry follow.

Against the measurements:

Metric Before After
Dominant mode right / within one 5 / 9 of 9 5 / 9 of 9
Mean in-line displacement within ±17 % 7 of 9 (−25 % to +34 %) 7 of 9 (−25 % to +34 %)
Cross-flow amplitude vs maxima (vs envelopes) −44 % to +4 % (−40 % to +16 %) −45 % to +4 % (−40 % to +18 %)
Cross-flow curvature std −39 % to +26 % −39 % to +26 %
In-line curvature std −53 % to +110 % −53 % to +111 %

Convergence (half the time step, 128 elements, 80 s runs):

Cases Before After
1–4, 7, 8: peak amplitude / in-line curvature at half the step ≤ 4.5 % / ≤ 10 % ≤ 2.7 % / ≤ 1.2 %
5 beat in the window: peak amplitude −17 % and −20 % peak amplitude ≤ 0.6 %; in-line curvature +22 % and +25 %
6 with cases 1–4, 7, 8 peak amplitude −11 % at half the step (kept over 80 s) and −13 % with 128 elements; other metrics ≤ 2 %, in-line curvature ≤ 12 %
9 mode 7 at half the step, mode 8 otherwise unchanged

The 80 s runs of cases 6 and 8 at both steps are new; provenance.json records them.

Wang SCR case (L3-W) rerun and every quoted VIV number rechecked

  • L3-W: rerun with its two sensitivity runs. Every printed number and sentence still holds at its precision:

    • largest r.m.s. strain / measured: 1.0729 → 1.0733;
    • r.m.s. log error: 0.3386 → 0.3385;
    • frequency unchanged at 0.992 Hz.

    summary.json, the comparison CSV and provenance.json are updated.

  • Quoted numbers: every number in the docs, VALIDATION.md, CHANGELOG, example comments and test headers that comes from coupled VIV was recomputed from the deck, window and output it describes. The ones that moved at their printed precision are updated:

    • outputs.rst: the VIV power balance, 8.52 → 8.45 W;
    • python_postprocessing.rst: the travelling-wave index, 0.05 → 0.04;
    • theory.rst: the wake lock-in, the amplitude-estimate tracking, Thorsen's damping, and the frame pipe and tow tables;
    • driver_format.md;
    • the L2-VIV and L2-VIV-EI rows.
  • Claims already wrong on dev, now corrected:

    • the frame section's "the RMS agrees within 0.2 %" is 0.6 % (0.46 % on dev);
    • the L2-VIV band row's "mode-1 and mode-3 lock-in within 1.2 %" does not hold at U 0.36. There MoorDyn-F settles in mode 2 and CableDyn in mode 3, with the dev build too. The row now states the measured agreement: mode 1 within 0.2 %, mode 3 at 0.39–0.42 m/s within 1.4 %. Its acceptance rests on the viv_lockin gates and is unchanged.

Test

tests/test_viv_step_order.f90 (ctest viv_step_order, 30 s):

Check After Before
Lock-in frequency, 100–400 steps per cycle, ratio at $\rho_\infty = 1$ 3.99 2.44
The same at $\rho_\infty = 0.4$ 3.67 2.27
Difference between the two $\rho_\infty$ 4.3e-5 3.1 %
Wake oscillator's crossing frequency, ratio 3.90 2.18
Finite-EI cable, 200–800 steps per cycle, ratio 4.39 2.76

The VIV state layouts in test_model, test_system, test_viv_coupled, test_hermite_viv_frame and test_hfmf_mirror carry the predictor rows.

The tangent-predictor test of #169 at $\rho_\infty = 1$ and 25 steps per cycle

On top of #169, one cell of hermite_tangent_predictor changes. It is the lifted line at $\rho_\infty = 1$ and 25 steps per cycle, seeded with unit tangents. Every step still converges (G1) within the iteration budget (G4). But its largest mid-span displacement is 4.7 % above the converged value (limit 2 %), and its strain energy is 1.51 times the reference (limit 1.5).

Cause. With no numerical damping, the seed's undamped tangent-stretch ringing leaves a near-Nyquist velocity of about 27 % of the VIV velocity at 21 steps per response period. Both the old and the new update feed it into the phase.

What that cell measures. It measures how an update treats that spurious velocity, not the predictor. Four equally consistent second-order variants (different filters of the sign-flipping component) land +0.8 % to +10 % from the converged z max/D of 0.5639, and the deviation is insensitive to the Newton tolerance and to a seed tilt.

z max/D over 20 cycles; the converged value is 0.5639:

Steps per cycle New, unit seed New, balanced seed Old, unit seed Old, balanced seed
25 0.5903 (+4.7 %) 0.5641 0.5683 (+0.8 %) 0.5654
50 0.5632 0.5631 0.5677 0.5635
200 0.5639 0.5640 0.5653 0.5631
800 0.5639 0.5639 0.5652 0.5633
  • New update: reaches the converged value from 50 steps per cycle with either seed.
  • Old update: never reaches it at $\rho_\infty = 1$.
  • Test change:
    • that cell keeps G1 and G4 and skips G2 and G3, with the reason in the test;
    • new gate G7: the same unit-seed run at 50 steps per cycle within 0.5 % of the converged value (measured −0.12 %).
  • Docs: doc/theory.rst and the CHANGELOG state that at $\rho_\infty = 1$ from an unbalanced seed the VIV response is resolution-sensitive below about 50 steps per cycle. Keep rhoInf ≤ 0.95, as doc/options.rst already advises, or seed the tangents at the stretch.

Checks

All on the branch rebased on dev 4b94321 (#169, #170):

  • Example A/B: of the 134 example and test-data decks, only the two VIV decks differ. Every other output file and console log is bit-identical.
  • Full test suite: 430/430 on the default and on the Prescott OpenBLAS kernel.
  • Fallbacks: the 66 example decks run with no fallback note on both kernels.
  • pre-commit.

A taut line locked in by the synchronisation model changed its
lock-in frequency by 0.74 %, 0.41 % and 0.27 % per halving of the
step from 25 to 200 steps per cycle (the long-run VIV checks), worse
than first order, while the same phase update under prescribed
motion was second order. The phase sampled the committed
generalised-alpha acceleration a_n for its cross-flow phase (and the
wake oscillator for its forcing). That acceleration is the line's at
t_n + (alpha_m - alpha_f) dt only, a first-order error at rho_inf <
1, and at rho_inf = 1 it carries an undamped alternating mode of the
integrator: on the 20 m line the mid-span a_n alternated by +-11 m/s^2
against a physical acceleration of about 1.3 m/s^2. The lock-in at
rho_inf = 1 therefore converged to a frequency 3.4 % low (3.940 at
3200 steps per cycle against 4.0797 rad/s), and at rho_inf 0.8 and
0.4 it was first order (0.06/n and 0.25/n at n steps per response
period). Prescribed motion imposes the exact acceleration, which is
why it did not show there.

Candidates switched off one at a time on that line, 25 to 3200 steps
per cycle: a second-order running mean square (exact exponential with
trapezoidal samples) changed nothing; a fixed normalisation in place
of the RMS left it first order; a tighter Newton tolerance changed
nothing; the lift at a fixed shedding rate (no phase feedback) was
second order (ratios 3.8 to 4.0); the acceleration recomputed from
the equations of motion after every step moved the limit to 4.0797
rad/s; and the phase on the step's mid-point motion with the
acceleration from the converged velocities restored second order
(ratios 3.6 to 5.0, then 4.01 to 4.04 from 400 steps on) at rho_inf 1
and 0.8 alike. No amplitude table, flow frame or in-line VIV is
involved in that case.

The phase now advances by the implicit mid-point rule, one
fixed-point pass, on the node's cross-flow motion at the step's
mid-point: the mean position, the velocity (q_n+1 - q_n)/dt and the
acceleration (v_n+1 - v_n)/dt, the step means of the velocity and of
its derivative (second order at every rho_inf, free of the committed
acceleration's lag and alternating mode, and keeping the phase of a
harmonic motion exactly). The step's lift takes the phase predicted
with the rate of the previous step's mid-point, a new row of the VIV
motion statistics (two with in-line VIV), so the step recovery,
sub-step slots, snapshots and checkpoints carry it and a restart stays
bit-identical; a newly installed VIV model seeds it from the present
state. The running mean squares advance by the mid-point rule
(1 - exp(-dt/T_w) on the mid-point sample), the in-line phase in the
same way slaved to the mid-point cross-flow rate, the flow frame's and
the wake filter's filtered velocities exactly for the velocity linear
over the step, and the wake oscillator under the mid-point
acceleration (held over the step, its integral exact) at the mean of
the start and end wake frequencies, that acceleration being its
predictor (row 2 of its statistics). The time discretisation of the
VIV phase therefore changes on purpose; this is not a round-off
change.

Measured on the same line from 25 to 3200 steps per cycle (EI = 0
line and rho_inf 0.8 unless noted), the ratio of successive changes
per halving of the step, before and after:

  frequency, rho_inf 1:          limit 3.4 % low;  3.6-4.9
  frequency, rho_inf 0.8 / 0.4:  2.0-3.4 / 1.5-3.2;  3.6-4.8 / 3.8-4.5
  mid-span A/D, in-line VIV:     2.2-2.3;  2.6-4.3
  frequency, flow frame:         1.6-2.0;  3.1-4.5
  frequency, amplitude table:    1.9-2.3;  3.0-4.5
  wake oscillator, frequency:    2.0-2.5;  3.8-4.0
  finite-EI cable, frequency:    1.7-2.3;  3.1-4.1

The Richardson limits at rho_inf 1, 0.8 and 0.4 agree to 1e-9 (4.0797304
rad/s), and the errors are about 2.2/n^2 (rho_inf 1, 0.8) and 3.4/n^2
(0.4) in frequency and 1.6/n^2 and 3.4/n^2 in mid-span A/D at n steps
per response period, 3.5/n^2 on the finite-EI cable. With the cable
seeded at its static stretch, rho_inf 1 reaches the rho_inf 0.8 limit;
from unit tangents the undamped tangent-stretch mode rings and moves
it at fine steps (the seed, not the VIV update). Under prescribed
motion the phase error of the long-run check after 400 cycles at 100
steps per cycle is 0.0167 rad against 0.0334 before, still second
order (3.99). The energy closure of that check at 100 steps per cycle
is 2.0e-4 of the VIV work against 8.3e-5 before, second order (ratio
4.0): the lift's predicted phase now takes the rate of the previous
step's mid-point, half a step behind the old step-start rate.

The two VIV example decks change at their default dtM 0.02 s (about
170 steps per response period, rhoInf 0.4) and move toward their
results at dtM 0.00125 s. viv_taut_line_crossflow, against dtM
0.00125 s: the mid-span RMS 0.31 % high before, 0.02 % low after; the
lock-in frequency 0.15 % low before, 0.018 % after; the fairlead
tension RMS 0.29 % high before, 0.027 % low after. viv_taut_cable_inline:
the quarter-span in-line RMS 1.56 % low before, 0.34 % after; the
cross-flow frequency 0.10 % high before, 0.022 % after; the largest
fairlead tension 0.70 % high before, 0.23 % low after; the mid-span RMS
0.21 % and 0.20 % low. Over the 90 s the phase moves, so the time series
differ pointwise by up to 12 % (crossflow, fairlead tension) and 36 %
(inline, quarter-span y) of the channel's range. Every other example
and test-data deck (132 decks) gives bit-identical output files and
console logs. The full test suite (427 tests) passes on the default
and the Prescott OpenBLAS kernel, and the 66 example decks run with no
fallback note on both.

Test: viv_step_order, the lock-in frequency of the line second order
from 100 to 400 steps per cycle at rho_inf 1 (ratio 3.99) and 0.4
(3.67) and within 1e-4 of each other (4.3e-5), the wake oscillator's
crossing frequency (3.90) and the finite-EI cable from 200 to 800
steps per cycle (4.39); on the previous code every check fails (ratios
2.44, 2.27, 2.18 and 2.76, the two rho_inf 3.1 % apart). The VIV
state layouts in test_model, test_system, test_viv_coupled,
test_hermite_viv_frame and test_hfmf_mirror carry the predictor rows.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…the VIV update

With the mid-point VIV update the predictor check of the lifted
taut line fails one cell, rho_inf 1 at 25 steps per cycle (21 per
response period): from the unit-tangent seed z max/D 0.5903 against
the balanced seed's 0.5641 (+4.6 %) and Es max 1.51 times it. Every
step converges (6.15 iterations on average, at most 21).

At rho_inf 1 nothing damps the unit seed's stretch ringing, and at
that resolution it leaves a near-Nyquist velocity in the trajectory:
the mid-node (v_n+1 - v_n)/dt alternates by 4.8 m/s^2 against a VIV
acceleration of 3.2 m/s^2 (a velocity of about 0.09 m/s, 27 % of the
VIV velocity; the committed a_n alternates by 32 against 17, 19
against 10.5 on the old update), 10 to 20 times less at 50 steps per
cycle. The response then depends on how the VIV update treats that
velocity: four equally consistent variants (the last two mid-point
accelerations averaged, a three-point second-order Nyquist-free
acceleration, an averaged predictor rate, both of the latter) give
z max/D 0.623, 0.579, 0.589 and 0.578, +0.8 % to +10 % from the
converged 0.5639 with the old update's +0.8 % among them. That value
is the fine-step one (200 to 800 steps per cycle), the same at
rho_inf 0.8 with either seed and at rho_inf 1 with the balanced seed.
The new update reaches it from 50 steps per cycle with either seed
(unit seed 0.5632 at 50, 0.5641 at 100, 0.5639 from 200 on), while
the old update settled at rho_inf 1 0.23 % high from the unit seed and
0.1 % low from the balanced one. The result is deterministic (Newton
tolerance 1e-6 to 1e-10 and a 1e-7 seed tilt change it by under
0.03 %).

So that cell measures the VIV update's treatment of an unresolved
spurious velocity, not the predictor. It keeps G1 (every step
converges) and G4 (iterations) and skips G2 and G3, and a new gate G7
holds the convergence claim: the unit seed at rho_inf 1 and 50 steps
per cycle within 0.5 % of the converged z max/D 0.5639 (measured
0.5632). The other cells keep G2 and G3 (measured at most 1.07 times
and 0.09 %). doc/theory.rst and the CHANGELOG note that at rho_inf 1
from an unbalanced seed the VIV response is resolution-sensitive below
about 50 steps per cycle: keep rhoInf at or below 0.95 or seed the
tangents at the stretch.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…phase

The nine cases and their sensitivity runs (half the time step, 128
elements, 80 s for cases 5, 6, 8 and 9, the 38.1 kN/m top spring) rerun
on the second-order VIV phase update. The counts are unchanged: the
dominant mode right in 5 of 9 and within one in all, the mean in-line
displacement within 17 % in 7 of 9 (-25 % to +34 %). The cross-flow
amplitude is -45 % to +4 % against the maxima (-40 % to +18 % against
the envelopes; within the 12 % measurement scatter in cases 2, 4, 6 and
7), the cross-flow curvature -39 % to +26 %, the in-line curvature
-53 % to +111 %.

Half the time step now changes the peak amplitude of cases 1-4, 7 and 8
by at most 2.7 % (4.5 % before) and their in-line curvature by at most
1.2 % (10 % before). Case 5 keeps its peak amplitude within 0.6 % (it
moved by up to 20 % before) while its in-line curvature moves by up to
25 %. The peak amplitude of case 6 now depends on the step and the mesh:
-11 % at half the time step, kept over an 80 s run, and -13 % with 128
elements, its other metrics within 2 % (in-line curvature 12 %). Case 9
still settles in mode 7 at half the time step. README, provenance.json
(new 80 s runs of cases 6 and 8 at both steps), summary.json,
response_comparison.csv, VALIDATION.md and the changelog entry follow.

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 16, 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-16T07:37:11.538108Z b990080 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 16, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35919680 | 📁 Comparing b990080 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. Keep it up!

Reviewed commit: a379c3f040

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

…int phase

The mid-point VIV phase update changes every coupled-VIV result, so
the validation case L3-W and the numbers the documents quote from
coupled VIV runs are recomputed with it, each as its text describes
(deck, options, window, output flag).

L3-W (validation/experiments/wang_scr), rerun as its README says, and
its two sensitivity runs: the largest r.m.s. strain over the measured
largest 1.0729 -> 1.0733, the station mean 1.0362 -> 1.0361, the
r.m.s. log error 0.339 -> 0.338, the dominant frequency 0.992 Hz
(unchanged), 7 r.m.s. peaks along the span (unchanged); 400 elements
1.0753 -> 1.0759 and half the time step 1.0742 -> 1.0747 (0.24 % and
0.13 % from the base run). Every number and sentence of the README,
VALIDATION.md and the CHANGELOG still holds at its printed precision;
summary.json, the comparison CSV and provenance.json (commit, date,
sensitivity) are updated.

Numbers changed:

- doc/outputs.rst, examples/viv_taut_cable_inline.dat: the VIV loads'
  power over 60-90 s 8.52 -> 8.45 W, the drag (and damping) 8.56 ->
  8.48 W (balance within 0.5 %, unchanged).
- doc/python_postprocessing.rst: the travelling-wave index 0.05 -> 0.04.
- doc/theory.rst: the EI = 0 wake-oscillator line locks in at 0.283 Hz
  (was "the same 0.282 Hz"); the amplitude estimate within 0.04 % (0.1 %
  on the EI = 0 line; was 0.03 %); Thorsen's damping A/D 1.02 -> 1.01;
  the moving/held pipe table (peak 0.819/0.819 -> 0.811/0.818, RMS
  0.446/0.447 -> 0.446/0.446; without the row 0.711/0.850 ->
  0.700/0.851 and 0.349/0.450 -> 0.345/0.450; Cl alone 0.713/0.714 ->
  0.713/0.712 and 0.372/0.371 -> 0.372/0.370; without 0.711/0.736 ->
  0.700/0.733 and 0.349/0.375 -> 0.345/0.374), the RMS agreement
  within 0.2 % -> 0.6 % (0.02 % with the table); the towed cable 0.7905
  / 0.7906 -> 0.7902 / 0.7903, 0.665 -> 0.663, 0.6764 / 0.6764 ->
  0.6758 / 0.6758, Tf on the held cable at most 0.23 % -> 0.24 %.
- doc/driver_format.md: towed within 0.01 % -> 0.02 %, at most 0.23 %
  -> 0.24 %.
- VALIDATION.md: L2-VIV zero seed 0.701 -> 0.699 against 0.699;
  L2-VIV-EI 0.662/0.421 against 0.663/0.421 -> 0.661/0.420 against
  0.661/0.420; the coupled VIV row 0.6645 / 0.6646 -> 0.6631 / 0.6625
  (standalone 0.665 -> 0.663). The L2-VIV band against MoorDyn-F,
  rerun over 150-300 s at U 0.06-0.42 m/s: mode 1 at 0.09-0.18 m/s
  within 0.2 %, mode 3 at 0.39-0.42 m/s within 1.4 %, and at 0.36 m/s
  MoorDyn-F settles in mode 2 and CableDyn in mode 3 (the earlier phase
  update gives the same branches, its A/D within 0.5 % of the new one at
  every speed, so the discrepancy predates this change); the row said
  "mode 3 at U >= 0.36 m/s within 1.2 %".
- CHANGELOG.md: the wake entry's EI = 0 frequency, the amplitude
  estimate 0.03 % -> 0.04 %, the frame entry's pipe and tow numbers as
  in the theory, and the #169 entry's largest A/D within 0.75 % ->
  0.1 % except at rho_inf 1 and 25 steps per cycle.
- tests/test_viv_frame_deck.f90 and tests/test_hermite_viv_frame.f90
  (header comments only): the measured values of their gates.

Every other quoted coupled-VIV number still holds at its precision
(the example decks' A/D 0.66, 0.82, 0.19 and 0.03, their frequencies,
the in-line and higher-harmonic gates, the wake, diameter and Thorsen
gates, the riser case). The Delta Flume case was rerun before; the
NDP case is on another branch.

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: b990080b99

ℹ️ 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 f4c9958 into dev Nov 16, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the fix/viv-coupled-order branch November 16, 2026 10:16
SMI-Lab-Inha added a commit that referenced this pull request Nov 16, 2026
…r and bending-damping speed-ups (#173)

viv_long_run runs the synchronisation model for 400 cycles. Prescribed
motion: every node of a finite-EI cable moves across a 0.3 m/s flow as a
rigid body, so the shedding phase obeys Adler's equation,
d psi/dt = a - b sin(psi), solved in closed form. Outside the band
(5.5 rad/s) the error grows linearly in time (T/(T/2) 2.014 and 1.988 at
50 and 100 steps per cycle) and is second order (4.01 from 50 to 100
steps): 0.0167 rad after 400 cycles at 100 steps per cycle. Inside the
band the lag holds within 3.0e-5 rad of psi*, the averaging-ripple
floor, and the mean rate is the motion's within 5.8e-12.

Lock-in, finite-EI and EI = 0 (taut 20 m line, rho_inf = 1, no added
mass, 100 and 200 steps per cycle): the load powers close E(t) - E(0) to
2.0e-4 / 1.8e-4 of the VIV work, second order (3.98 / 3.67) and
stationary (T against T/2 1.00). On the mid-point phase update of #171
the lift takes the phase predicted from the previous step's mid-point
rate, half a step behind, so the bound is 3e-4. The halves agree in RMS
A/D within 7.3e-4, VIV power within 1.8e-3 and lock-in frequency within
1.9e-4; the frequency changes by 1.6e-4 / 1.9e-4 from 100 to 200 steps
per cycle. Every tolerance and its measured value is in the test header.
57 s Release; label slow, TIMEOUT 1200.

run_study with jobs > 1 runs every case with OMP_NUM_THREADS=1 unless the
environment sets it, and study.json records omp_num_threads. On a 24-core
workstation (gfortran Release) 96 finite-EI VIV cases scale 13.3x at 24
jobs and 15.1x at 48; on the 1024-element lazy-wave example 24 jobs take
16.7 s with one thread each, 17.9 s with four and 19.1 s with the OpenMP
default. The Python manual gives the table and the recommended settings.

Speed-ups, outputs bit-identical:
- a row evaluates a line's node powers once for all its power channels
  (VIVPow, DragPow, DampPow; 19 % of a VIV run) on the Hermite, EI = 0
  and system routes; any failure still goes through the
  channel-at-a-time path. viv_taut_cable_inline.dat 2.39 s to 2.14 s;
- the bending damping force no longer computes the second derivatives
  of the curvature, which only the position Jacobian uses (32 % of the
  Delta Flume case 9 run): 73.2 s to 58.6 s.
load_power_deck P6 checks that a power channel read alone equals the
same channel among its line's other power channels, on all three routes.

Checked: 431/431 tests on the default and the Prescott OpenBLAS kernel;
the 134 example and test-data decks bit-identical to the reference
build; the NDP validation runs of #172 reproduce their committed rows.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
SMI-Lab-Inha added a commit that referenced this pull request Nov 17, 2026
The OD 48 mm research cable of the FLOTANT tests at MARIN (de Wilde,
Heijnsdijk & de Ridder 2021, Deliverable D5.5, MARIN report
30995-53-DWB): 6.4 m hanging from the carriage with a 200 kg clump,
towed at the 40 speeds of 0.025-1.0 m/s. It tests cross-flow and in-line
VIV of a real cable section against three published coefficient sets,
none fitted to these tests, on a structure identified only from the
specimen's forced-oscillation RAOs.

validation/experiments/flotant/flotant_viv.py writes a deck per case,
runs them in parallel (reused when deck and executable are unchanged)
and compares:
- tow: A/D_rms = sigma/OD at 1/2L, 3/4L and L, cross-flow and in line,
  at the same test speed, the model's displacement processed as the
  report's accelerometer motions (the g theta/omega^2 tilt term, the
  3.5 rad/s high-pass); Ur with f1 1.77 Hz as Appendix 3; 60 s runs,
  statistics after 20 s, dt 2 ms;
- rao: the in-air (5 and 10 mm) and in-water (5 mm) RAOs of
  Appendices 1 and 2, the structural check.

The line follows the report's FEM tables node by node, in fresh water
(Table 2-2 implies 1000 kg/m^3), with the clump or counterweight as a
20 kN/m axial spring in series. What the tests leave open is identified
from the RAOs: cable EI 1650 N m^2 and bending damping 130 N m^2 s from
the in-air resonance (the tables' EI 3000 needs MARIN's empirical factor
1.10), and in water a link chain bending with EI 100 N m^2 and the clump
held laterally by 32.5 kN/m and 20 N s/m, which give the measured split
of the first in-water mode (r.m.s. log error 0.46 in surge against 1.19
for MARIN's fixed clump and 1.17 for a free one).

Sets, checked against the articles:
- uls19, Ulveseter et al. (2019), Table 1 (Cl 0.85, cF 0.144, dF 0.064,
  ClX 0.75, alpha 0.15, Chh 1.5), fitted to the NDP riser: blind here;
- b1, the generic set of the Delta Flume case (Cl 0.8, cF 0.18, dF 0.08,
  ClX 0.85, alpha 0.15, Chaplin's drag amplification, VIV DAMPING
  0 0 1): blind;
- wake, Facchinetti et al. (2004) (CL0 0.3, St 0.2, eps 0.3, A 12):
  blind.

Result on the second-order VIV phase update (#171) (cross-flow r.m.s.
log error over the three stations, Ur >= 3):
- uls19 0.731: the first peak at 1/2L is 0.755 at Ur 5.30 against 0.776
  at 5.58, but the rise starts at a lower speed (0.42 against 0.18 at
  Ur 3.53), the lock-in releases at Ur 7.06 against 5.88 (1.2 Ur late)
  and the upper branch stays at 0.64-0.71 above Ur 9 where the test
  falls to 0.18-0.44;
- b1 0.594: 38 % low at the peak (0.483), releases at the measured Ur;
- wake 1.208: 62 % low (0.296).
With MARIN's fixed clump or a free clump (End B Free) uls19 scores
0.721 and 0.692 but releases at Ur 8.83 and 9.12 and misses the RAOs.

extract_d55.py reads the data from the report's PDF (FEM tables from the
text, the RAO charts from the vector graphics, Appendix 3 from the raster
images calibrated on the grid lines; every point maps to a tested speed
within 0.0085 m/s). The caveats of the data are stated: the Ur basis
(1.77 Hz against the 1.3 Hz first in-water mode of Sec. 5.3), the bottom
tension (1436 N in Table 6-1 against about 1700 N in the FEM table) and
the towing direction alternating with speed.

Half the time step, two elements per table element and 120 s runs change
no A/D_rms by more than 0.006 at five speeds; the RAO scores move by at
most 0.001. The default command run into a new work directory reproduces
the committed record byte for byte.

Added to VALIDATION.md as L3-F, to the experiments index, the changelog
and the references (de Wilde et al. 2021, from the report's PDF; no DOI);
the top-level README now names the seven published experiments.

flotant_viv.py and ndp_riser_viv.py now remove a folder's result, executable
stamp and output before writing new inputs, so a rerun that fails or is
interrupted cannot leave the previous model's result to be reused; a tow
selection entirely below Ur 3 prints n/a for its scores instead of failing
before the comparison files are written.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
SMI-Lab-Inha added a commit that referenced this pull request Nov 17, 2026
…17) (#179)

An optional VIV STOCHASTIC section, rows TypeName sigma c [Nf [seed]],
makes the centre cF of a line type's synchronisation band the slowly
varying random process of Ulveseter, Thorsen, Saevik & Larsen (2017,
Eq. 6 and Fig. 4):

  F0 = cF + sum_i a sin(p_i + 2 pi f_i theta),  theta = integral U/D dt,

Nf components (default 100) at the mid-points f_i = (i - 1/2) c cF/Nf of
a flat spectrum over (0, c cF], amplitude a = sigma sqrt(2/Nf), so F0
has the mean cF and the standard deviation sigma. Each component
advances at its non-dimensional frequency times U/D, as the shedding
phase does (U the shedding speed of the phase rate). The start phases
are uniform on [0, 2 pi), drawn per node from a minimal-standard stream
that the seed, the node and the line select: the nodes are independent,
as in the article, a run repeats its realisation and two lines of one
type differ. The band half-width dF stays constant.

theta is the one new state: one more row of each node's VIV motion
statistics, so step recovery, snapshots, rollback and checkpoints
(standalone and the OpenFAST mirror) carry it; the phases are rebuilt
from the seed. The step advances theta by dt U/D at the mid-point and
takes F0 at theta + dt U/(2D), the mid-point rule of the phase (#171).
On EI = 0 lines and finite-EI cables, standalone and coupled, with or
without in-line VIV; refused on a type without Cl > 0 or with a WAKE
OSCILLATOR row.

Checks (test_viv_stochastic, test_viv_coupled):
- the process with the article's NDP values (cF 0.144, sigma 0.016,
  c 0.07, 100 components) over theta 0-4e6 has the mean cF to 2e-6, the
  standard deviation sigma to four digits and an excess kurtosis of
  -0.18; the phases repeat per seed and node and differ between them;
- a sigma 0 row is the deck without it, bit for bit, on both cores;
- with sigma 0.02 a run repeats bit for bit, another seed differs, and
  the taut cable stays locked in (A/D within 1 % of the constant centre's
  over 50-80 s on both cores);
- the coupled checkpoint restart continues bit for bit with theta in
  both VIV blocks (one more value per node), a rebuild without the VIV
  state does not, and a rewound step repeats;
- refusals: no Cl, a wake-oscillator type, c out of (0, 1], a
  non-integer Nf, a seed out of range.

The EI = 0 model's explicit copy and move routines and its VIV row
count (CD_Model_VIV_NMS) carry the new fields. Python reader and
builder: the section, its native checks and a round trip. Driver
format, theory (Stochastic band centre), capabilities, changelog and
the reference (from the article's first page).

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
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