Skip to content

feat: cabledyn.viv_response, the VIV response of a line - #148

Merged
SMI-Lab-Inha merged 6 commits into
devfrom
feat/viv-diagnostics
Nov 11, 2026
Merged

SMI-Lab-Inha merged 6 commits into
devfrom
feat/viv-diagnostics

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

A VIV study describes a response by its cross-flow and in-line
amplitude along the span, the response frequencies against the flow,
the excited modes, how far it is a travelling wave and its orbits.
viv_response computes them from a line's node positions (a per-line
.p.out file, a MoorDyn-F line file, or the LNp channels of a
main output) over a window.

Each node's motion about its mean position is resolved into its local
flow frame: the mean tangent t from End A towards End B, the in-line
axis along the flow normal to t, and the cross-flow axis t x in-line;
a node whose tangent lies along the flow has no frame (nan). The
VIVResponse gives:

  • RMS and half peak-to-peak displacement over D, for either direction;
  • each node's and the line's dominant frequency (Hann periodogram,
    parabolic peak) and f D/U_n against the synchronisation band;
  • modal weights at every sample, on the sines of a taut line with
    fixed ends or on given shapes, with the dominant mode and the
    unexplained share;
  • the complex Fourier shape at a frequency and its travelling-wave
    index (the travelling index of Feeny's complex orthogonal
    decomposition, J. Sound Vib. 310, 2008, 77-90);
  • orbits and the in-line/cross-flow phase difference;
  • a CSV export and envelope and orbit plots.

Checks: synthetic standing and travelling waves with known amplitudes,
frequencies, modes, phases and index (python/tests/test_viv.py); the
end-to-end run of examples/viv_taut_cable_inline.dat reproduces the
deck's A/D 0.82 cross-flow and 0.19 in-line at twice the frequency,
modes 1 and 2, f D/U_n inside the band, a standing wave. Full pytest,
ruff, mypy strict, Sphinx -W.

A VIV study describes a response by its cross-flow and in-line
amplitude along the span, the response frequencies against the flow,
the excited modes, how far it is a travelling wave and its orbits.
viv_response computes them from a line's node positions (a per-line
.p.out file, a MoorDyn-F line file, or the L<L>N<J>p channels of a
main output) over a window.

Each node's motion about its mean position is resolved into its local
flow frame: the mean tangent t from End A towards End B, the in-line
axis along the flow normal to t, and the cross-flow axis t x in-line;
a node whose tangent lies along the flow has no frame (nan). The
VIVResponse gives:
- RMS and half peak-to-peak displacement over D, for either direction;
- each node's and the line's dominant frequency (Hann periodogram,
  parabolic peak) and f D/U_n against the synchronisation band;
- modal weights at every sample, on the sines of a taut line with
  fixed ends or on given shapes, with the dominant mode and the
  unexplained share;
- the complex Fourier shape at a frequency and its travelling-wave
  index (the travelling index of Feeny's complex orthogonal
  decomposition, J. Sound Vib. 310, 2008, 77-90);
- orbits and the in-line/cross-flow phase difference;
- a CSV export and envelope and orbit plots.

Checks: synthetic standing and travelling waves with known amplitudes,
frequencies, modes, phases and index (python/tests/test_viv.py); the
end-to-end run of examples/viv_taut_cable_inline.dat reproduces the
deck's A/D 0.82 cross-flow and 0.19 in-line at twice the frequency,
modes 1 and 2, f D/U_n inside the band, a standing wave. Full pytest,
ruff, mypy strict, Sphinx -W.

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 11, 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-11T14:15:10.529832Z 78e5a82 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 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: 38d1687dd2

ℹ️ 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 python/cabledyn/viv.py Resolved
Comment thread python/cabledyn/viv.py Resolved
@read-the-docs-community

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

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35814324 | 📁 Comparing 78e5a82 against latest (789cb6d)

  🔍 Preview build  

11 files changed · ± 11 modified

± Modified

Two review findings on cabledyn.viv_response:

- The default modal shapes sin(n pi s/S) vanish at the line's ends, but
  a main output may hold only some of the line's nodes: the fit then
  took the first and last nodes held as the fixed ends and gave wrong
  weights even for a pure first mode. VIVResponse now records
  whole_line (True for a per-line file), and modal_amplitudes refuses
  the default shapes without the whole line, naming the per-line file
  or shapes at the nodes held as the way on; given shapes still fit.
- travelling_wave_index raised ValueError from complex_shape when the
  direction has no dominant frequency (no motion, or no node with a
  flow frame) instead of returning the documented nan; it now returns
  nan first.

Tests: interior nodes of a main output refuse the default shapes and
fit given ones exactly; a motionless line and a flow along the line
give nan. Full pytest, ruff, mypy strict, Sphinx -W.

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 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: 433ab79c74

ℹ️ 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 python/cabledyn/viv.py Resolved
A main output may hold only some of a line's L<L>N<J>p nodes, and
viv_response numbered them 1, 2, ... in its export and in the methods
that take a node: channels of nodes 5 and 10 came out as rows 1 and 2,
against the deck and other node results.

VIVResponse now records node_numbers, the CableDyn number of each node:
the J of the main-output channels, 1 .. N for a per-line file (MoorDyn's
node J being J + 1, as elsewhere). The CSV export writes them, and
orbit, phase_difference and plot_orbit take a node by its number,
naming the nodes held when given another.

Test: four interior nodes of a main output keep their numbers in the
export, give the whole line's orbit and phase difference at the same
node, and refuse a node not held. Full pytest, ruff, mypy strict,
Sphinx -W.

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

ℹ️ 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 python/cabledyn/viv.py Resolved
On a coarse output the shapes of a modal fit can be dependent at the
nodes held: on ten uniform nodes sin(9 pi s/S) vanishes at every node
and sin(10 pi s/S) is -sin(8 pi s/S). The fit passed the node-count
check, and the minimum-norm least squares then split a pure mode 8
between modes 8 and 10, halving its amplitude and inventing mode 10
with a near-zero residual.

modal_amplitudes now checks the rank of the least-squares fit and
refuses dependent shapes (default or given), naming the rank and the
ways on: fewer modes or a finer output.

Test: ten uniform nodes refuse ten modes (rank 8) and fit a pure mode 8
exactly with eight. Full pytest, ruff, mypy strict, Sphinx -W.

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 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: 1775664e1d

ℹ️ 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 python/cabledyn/viv.py Resolved
A node that does not move, at a coordinate with no exact binary form
(z = -50.1), keeps a round-off offset from its mean position; windowed,
that constant read as power at every nonzero frequency, so the still
node, a pinned end or a whole still line reported a frequency instead
of nan, in frequency, frequencies, the non-dimensional frequency and
the CSV export.

The periodogram now treats a node whose displacement range is below
1e-12 of its distance from the origin plus the diameter as still, with
no power.

Test: still lines at z = -50.1, -0.3 and -1234.567 have no frequency
and no travelling index, and the pinned ends of a moving line none,
while the line keeps its frequency; it fails without the fix. Full
pytest, ruff, mypy strict, Sphinx -W.

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 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: 2f96706714

ℹ️ 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 python/cabledyn/viv.py Resolved
The still-node rule of the periodogram did not reach complex_shape: a
line moving cross-flow only, at a lateral coordinate with no exact
binary form (y = -0.3), kept a round-off in-line residual whose Fourier
coefficient was small but nonzero, so phase_difference returned an
arbitrary phase for an orbit with no in-line motion instead of nan.

The rule now lives in one place, _moving_displacement, which sets still
nodes to exactly zero for both the periodogram and the complex shape.

Test: a cross-flow-only line at y = -0.3 has a zero in-line shape and no
orbit phase; it fails without the fix. Full pytest, ruff, mypy strict,
Sphinx -W.

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: 78e5a82e7f

ℹ️ 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 9bd50e4 into dev Nov 11, 2026
27 of 28 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-diagnostics branch November 11, 2026 23:28
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