Skip to content

feat: cross-flow damping on finite-EI cables (VIV DAMPING section) - #157

Merged
SMI-Lab-Inha merged 1 commit into
devfrom
feat/viv-cf-damping
Nov 13, 2026
Merged

SMI-Lab-Inha merged 1 commit into
devfrom
feat/viv-cf-damping

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

An optional VIV DAMPING section gives a finite-EI line type a drag split in the frame of the ambient normal flow: Morison's drag in line, and the cross-flow hydrodynamic damping of Thorsen, Sævik and Larsen (J. Fluids Struct. 61, 2016, Eq. 1) across it.

--------------------- VIV DAMPING ---------------------
TypeName   a      b      c
(-)        (-)    (-)    (-)
riser      0      0      1

Model

With $\mathbf t$ the tangent, $\mathbf u_n$ the ambient flow normal to it, $\mathbf e_x = \mathbf u_n/|\mathbf u_n|$ and $\mathbf e_y = \mathbf t\times\mathbf e_x$, the relative normal velocity $\mathbf w$ splits into $w_x$ and $w_y$:

$$\mathbf f_n = \tfrac12\rho D\left[C_{dn}A_d\,|\mathbf w|\,w_x\,\mathbf e_x + \left(C_{dy}|w_y| + c\,C_{dn}|\mathbf w|\right)w_y\,\mathbf e_y\right], \qquad C_{dy} = a + b\,\frac{y_0^*}{D}$$
  • $A_d$ is the drag factor of the type's VIV AMPLITUDE table and $y_0^*$ its amplitude estimate.
  • 0.31 0.89 0 is the published fit (still-water decay tests, $y_0/D \le 0.6$).
  • 0 0 1 is Morison's drag with the drag factor on the in-line part only, so an amplified drag no longer damps the cross-flow VIV motion twice.
  • Below $u_{ref} = 0.01$ m/s the axes are undefined, and the force blends to Morison's as $\beta\mathbf f_s + (1-\beta)\mathbf f_M$ with $\beta = U^2/(U^2+u_{ref}^2)$.
  • Thorsen's quadratic form drops the linear $\tfrac12\rho D C_{dn} U\dot y$ part of Morison's cross-flow damping. It suits cross-flow-only VIV; with an in-line force an undamped low-frequency cross-flow motion can grow. The theory page says so.

Changes

Area Change
CableDyn_Hydro CD_Morison_Drag_Split_Per_Length_Jac: the split force, exact Jacobians in the relative velocity and the tangent
CableDyn_HermiteCableDynamic Set_VIV cdy (2 or 3, n_elem) with checks and rollback; the drag element takes cdy/cdy_lin in the residual, the tangent and the element drag load
CableDyn_DeckDriver VIV DAMPING section (TypeName a b [c]), needs Cl > 0 and a VIV AMPLITUDE table, refused on EI = 0 lines
Python deck reader check, LineType.viv_damping in the builder and loader
Docs driver_format.md, theory.rst (cross-flow damping), capabilities.rst, CHANGELOG

Statics is unchanged: at rest in the flow the split force is Morison's.

Tests

Test Checks
test_viv_cf_damping_kernel Morison at rest and in still water; the cross-flow law and the blend; Jacobians against central differences (with $U \sim u_{ref}$ and the $c$ term); refusals
test_viv_cf_damping_deck 0 0 1 with factor 1 is the line without the row to 1.5e-8; with $C_v = 0$ and factor 2 the static in-line offset of Cd 2.4; Thorsen's form raises $A/D$ 0.68 to 1.02; drag, damping and VIV powers balance within 0.2 %; six refusals
Python read/keep and native-check parity in test_deck_file, builder rows, end-to-end reader parity (7 decks)

Local gates: full CTest under the default and Prescott BLAS kernels, Debug -fcheck=all on the VIV, drag, checkpoint and restart tests, pytest, ruff, Sphinx -W, pre-commit.

An optional VIV DAMPING section row "TypeName a b [c]" splits the normal
drag of a finite-EI line type in the frame of the ambient normal flow:
Morison's drag in line (with the VIV AMPLITUDE drag factor) and, across
it, 1/2 rho D [C_dy |w_y| + c Cdn |w|] w_y with C_dy = a + b y0/D, the
cross-flow hydrodynamic damping of Thorsen et al. (2016, Eq. 1; 0.31
0.89 is their fit) at the amplitude estimate y0. Below an ambient
normal flow of 0.01 m/s the force blends to Morison's, where the axes
are undefined.

CD_Morison_Drag_Split_Per_Length_Jac computes the split force with
exact Jacobians in the relative velocity and the tangent. The dynamic
finite-EI drag element takes it in the residual, the tangent and the
element drag load. Statics is unchanged: at rest in the flow the split
force is Morison's. Set_VIV takes cdy (2 or 3, n_elem), checks it and
rolls it back with the rest of the VIV state.

"0 0 1" is Morison's drag with the drag factor on the in-line part
alone, so an amplified drag no longer damps the cross-flow VIV motion
twice. Thorsen's quadratic form drops the linear U y' part of
Morison's cross-flow damping and suits cross-flow-only VIV.

The section needs Cl > 0 and a VIV AMPLITUDE table; EI = 0 lines are
refused. The Python deck reader and builder take the section, with
parity tests against the native reader.

Tests: test_viv_cf_damping_kernel (Morison limits, the cross-flow
law, the blend, Jacobians against central differences, refusals) and
test_viv_cf_damping_deck (0 0 1 equals the line without the row to
1.5e-8, the in-line-only factor gives the Cd 2.4 static offset,
Thorsen's form raises A/D 0.68 to 1.02, power balance within 0.2 %,
six refusals).

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 13, 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-13T12:24:01.685557Z 17f6715 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 #35867064 | 📁 Comparing 17f6715 against latest (789cb6d)

  🔍 Preview build  

13 files changed · ± 13 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

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

Reviewed commit: 17f6715332

ℹ️ 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 281b021 into dev Nov 13, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/viv-cf-damping branch November 13, 2026 15: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