Skip to content

feat: bending damping of finite-EI cables (EI|Bb, EI|-zeta|f) - #144

Merged
SMI-Lab-Inha merged 4 commits into
devfrom
feat/bending-damping
Nov 11, 2026
Merged

SMI-Lab-Inha merged 4 commits into
devfrom
feat/bending-damping

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

Finite-EI cables had axial (BA) and torsional (GJ|K|Bt) Kelvin-Voigt damping but no
transverse structural damping, the damping that OrcaFlex, RIFLEX and SHEAR7 users set for every
dynamic or VIV run. This adds a bending damping to the cubic-Hermite cable.

  • Input. The LINE TYPES EI column takes EI|Bb (Bb in N m^2 s) or EI|-zeta|f, the
    damping ratio of a pure bending mode of frequency f [Hz], resolved once per line type as
    Bb = zeta EI/(pi f) (mesh independent). EI|0 is the plain EI. Bending damping on an
    EI = 0 type, a negative Bb without its frequency, a ratio outside (0, 1), a non-positive
    frequency and a four-part column are refused by name, in the native reader and the Python deck
    reader alike; the Python builder writes and reads ei=(EI, Bb) and ei=(EI, -zeta, f).
  • Model. The dissipation function psi = int 1/2 Bb |kdot|^2 ds with
    kdot = (I - t t^T) dkappa/dt, kappa = (a x b)/|a|^3 the curvature vector of the elastic energy.
    Since kappa is normal to t, kdot is the curvature rate in the frame carried with the
    tangent by the smallest rotation: zero for a rigid motion whose rotation is normal to the
    tangent, equal to dkappa/dt in planar bending. The damping force dpsi/dv comes with exact
    position and velocity Jacobians (CD_HermiteCable_Bending_Damping).
  • March. One helper (structural_damping_element) returns the axial and bending damping
    loads and tangents together, used by the serial and element-private assembly, the end-force
    recovery and the node recovery. Without bending damping it returns the axial kernel's output as
    before, bit for bit (the node recovery keeps its fixed-length axial form). It reaches every
    route that builds the cable (standalone, OpenFAST, FAST.Farm, the C API); linearisation picks it
    up through the residual it differences, and it carries no state for the checkpoint.
  • Effect. It is stiffness-proportional in EI alone, so a mode is damped in its bending share:
    zeta = omega Bb/(2 EI) * EI k^2/(EI k^2 + T) for a uniform cable of wavenumber k under
    tension T. A tension-dominated mode is damped much less than a bending one.
  • Docs. driver_format.md (EI column), theory.rst (new Bending damping section),
    capabilities.rst, CHANGELOG.

Tests

  • hermite_bending_damping (new, kernel): Kq and Kv against central differences of the force
    on a stretched 3D element and on a straight one (relative 1e-10); linear in the rates and
    dissipative; zero for a rigid translation and for a rigid rotation normal to the tangents
    (5e-16); the planar closed form v . f = Bb kdot^2 L; refusals.
  • hermite_bending_damping_dynamic (new): free decay of the first mode of a weightless, pinned,
    tensioned cable at rho_inf = 1. Bending share 0.96: zeta 1.9217e-2 against 1.9221e-2; share
    0.20: 3.9561e-3 against 3.9582e-3; without damping 4e-10; refusals of the setter.
  • bending_damping_deck (new, through the deck driver): EI|-zeta|f and the EI|Bb it resolves to
    give identical outputs; EI|0 is the undamped deck exactly; the damping lowers the hang-off
    curvature range in a sea; refusals.
  • Python: test_deck_native_parity (accepted forms and every refusal) and test_builder (round
    trips of both tuple forms, tuple-length check).
  • Full ctest under the default and the Prescott OpenBLAS kernels, Debug -fcheck=all, and the
    example fallback scan: see the PR comments.

Checklist

  • pre-commit run --all-files passes
  • ctest --test-dir build --output-on-failure passes
  • python -m pytest tests python/tests passes (if Python or validation records changed)
  • VALIDATION.md updated if a validation result changed (no validation result changed)
  • CHANGELOG.md updated under [Unreleased] (heading added if missing) for user-visible changes
  • Documentation in doc/ updated for changed inputs, options, or outputs
  • Conventional Commit title (feat:, fix:, docs:, ...)
  • Commits are signed off (git commit -s) under the
    Developer Certificate of Origin

Finite-EI cables had axial (BA) and torsional (GJ|K|Bt) Kelvin-Voigt
damping but no transverse structural damping, the damping a dynamic or
VIV analysis sets as its baseline. The LINE TYPES EI column now takes
EI|Bb, a damping moment Bb [N m^2 s] times the curvature rate, or
EI|-zeta|f, the damping ratio of a pure bending mode of frequency f,
resolved once per line type as Bb = zeta EI/(pi f).

The element dissipation function is the integral of 1/2 Bb |kdot|^2
with kdot = (I - t t^T) dkappa/dt, the curvature rate in the frame
carried with the tangent by the smallest rotation: zero for a rigid
motion whose rotation is normal to the tangent, dkappa/dt in planar
bending. The force and its position and velocity Jacobians are exact
(CD_HermiteCable_Bending_Damping). A mode is damped in its bending
share, zeta = omega Bb/(2 EI) * EI k^2/(EI k^2 + T).

One helper returns the axial and bending damping loads and tangents
for the serial and element-private assembly, the end-force and the
node recovery; without bending damping it returns the axial kernel's
output as before, bit for bit. The native and Python deck readers
refuse the malformed forms by name, and the Python builder writes and
reads ei=(EI, Bb) and ei=(EI, -zeta, f).

Tests: kernel Jacobians against central differences, rigid motions and
the planar closed form; free decay of a pinned cable against the
bending-share damping ratio to 0.05 %; the deck route (EI|-zeta|f is
the EI|Bb it resolves to, EI|0 is the undamped deck, refusals); Python
parity and builder round trips.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 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-10T22:53:55.079086Z 017ced9 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.

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

Local checks on the pushed commit (gfortran, Windows):

  • Full ctest, Release, default OpenBLAS kernel: 409/409 passed.
  • Full ctest, Release, OPENBLAS_CORETYPE=Prescott: 409/409 passed.
  • Debug (-fcheck=all), the hermite, damping, control, torsion and VIV tests with their own timeouts: 65/65 passed; the new bending_damping_deck takes 109 s in Debug.
  • Example scan, every shipped deck on the Release driver under Prescott and Haswell: 61 decks, no non-zero exit, no fallback, stall or relaxed-tolerance note.
  • pre-commit run --all-files clean; python -m pytest python/tests/test_deck_native_parity.py python/tests/test_builder.py: 398 passed.
  • Without bending damping the structural-damping helper returns the axial kernel's output unchanged, so runs without EI|Bb are unchanged.

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@read-the-docs-community

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

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35798677 | 📁 Comparing 017ced9 against latest (789cb6d)

  🔍 Preview build  

4 files changed
± capabilities.html
± changelog.html
± driver_format.html
± theory.html

@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: b89afcece7

ℹ️ 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_DeckDriver.f90 Resolved
EI|-zeta|f resolves to Bb = zeta EI/(pi f), which is 0 on an EI = 0
type, so the finite-EI check on Bb > 0 let 0|-0.05|0.5 through and the
line ran undamped without a word. The check now refuses any requested
bending damping, the ratio form or a positive Bb, on EI <= 0, in the
native and the Python deck readers alike, with the row in both tests.

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

ℹ️ 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_HermiteCableDynamic.f90 Resolved
Under active line control an element's unstretched length L changes,
and the Hermite shape functions depend on it: a = p/L + g and
b = P/L^2 + G/L, with p, P the end-position parts and g, G the tangent
handle parts. At fixed DOFs the curvature therefore still changes, and
the damping took its rate from the DOF rates alone, so payout and
haul-in were not damped (or damped wrongly) in bending.

The kernel takes l0_dot: the rates of a and b gain -(L'/L) a_pos and
-(L'/L)(2 b_pos + b_tan), and their dependence on the DOFs joins Kq;
Kv is unchanged. The structural-damping helper passes l0_dot as it
does for the axial strain rate (the node recovery keeps its fixed-
length form). The kernel test checks the force against d psi/d v of the
dissipation function built from the public curvature with its rate by
central differences in the DOFs and the length (1.6e-8), that a length
change alone is damped, and the Jacobians with a length rate (1e-10).

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: 0ece6a2cc7

ℹ️ 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_HermiteCableDynamic.f90 Resolved
The node recovery reads the section moment from the tangent rows of the
element end residual and turns it into curvature over EI. With bending
damping that residual also held the viscous moment Bb kdot, so a cable
bending at a rate reported a rate-dependent curvature and elastic
moment: a straight cable moving in its first mode read 1.5e-4 1/m.

The structural-damping helper now also returns the bending part of its
load, and the recovery residual leaves out its tangent rows; its
position rows, the shear the viscous moment carries, stay in the
section forces, and the end force (its own path) keeps the full
damping. Test B5: a straight cable in its first bending mode at zero
acceleration recovers zero curvature with the damping on, and its end
force differs from the undamped one.

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. Already looking forward to the next diff.

Reviewed commit: 017ced968b

ℹ️ 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 8a62231 into dev Nov 11, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/bending-damping branch November 11, 2026 05:12
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