Skip to content

feat(damping): mesh-independent axial damping ratio; static balance and as-laid fixes - #112

Merged
SMI-Lab-Inha merged 5 commits into
devfrom
fix/axial-damping-ratio
Nov 8, 2026
Merged

SMI-Lab-Inha merged 5 commits into
devfrom
fix/axial-damping-ratio

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

This PR has three commits, one per item.

1. Negative BA (feat(damping), plus one fix)

A negative LINE TYPES BA is MoorDyn's damping ratio per segment, BA = ζ L0 √(EA m). On N elements it damps a line's first axial mode at about ζπ/(2N), so the result depends on the mesh. The free axial decay of a taut line confirms this: 3.140 / 1.570 / 0.785 % at N = 50 / 100 / 200, against 3.142 / 1.571 / 0.785 % predicted.

  • New axialDampingRatio (axial_damping_ratio) option. segment is the default and is unchanged. mode1 makes a negative BA the damping ratio of the line's first axial mode on any mesh: BA = 2ζ EA/ω₁, which is stiffness-proportional.
    • ω₁: the exact first mode of the line held at both ends, computed from its sections on a fixed internal mesh, so composite lines are covered. Composite lines measure 2.000 %; a series-stiffness estimate would give 2.2–3.0 %.
    • Routes: EI = 0 and finite-EI lines on every route that builds lines from a deck.
    • Refusal: a line with a negative BA and a viscoelastic or Syrope section is refused by name.
    • Python: the deck validator mirrors the option.
  • New initialisation note. Every line with a per-segment negative BA gets a note giving its first-mode damping ratio on its final mesh and its element count. The note reaches the driver report, CableDyn_GetInitNotes and the OpenFAST console.
  • Fix. On EI = 0 lines, a negative BA was resolved with the length, EA and mass of the element at the mirrored position from the other end. On an asymmetric composite line the sections therefore exchanged their damping (4.033 % against 3.174 %, +27 %). Of the examples, only composite_chain_syrope_chain.dat changes: 619 N at most, 6.6e-4 of the value.

2. Static force balance of a finite-EI cable in current (test(statics))

Across 88 cases (pinned or clamped ends, suspended or touchdown, 0.5–2 m/s, four headings, 100 or 25 elements), end reactions + weight + drag balance to 2.3e-8 of the end force with the solver's own quadrature. That is the static tolerance.

An independent check that integrates the drag on straight chords sees an O(h²) difference: 2.8e-5 / 1.1e-4 / 4.5e-4 at 1.25 / 2.5 / 5 m elements. That is the size reported earlier as "1 N in 11.8 kN", so it is not a solver defect. The new test static_current_balance gates the balance, and theory.rst states the length measure the drag is integrated over on each route. No code changes.

3. As-laid seabed friction reference (fix(friction))

A finite-EI section on a seabed shallower than its radius is partly dry. The solver gives back the dry part's buoyancy, but the as-laid reference still sank each node under the full submerged weight.

The reference now sinks each node under the load the solver applies, including the dry part, by Newton's method with its exact derivative.

  • A 0.5 m cable on a 0.1 m deep, 5°-sloped bed rested 7.75e-4 m off its laid path before the fix, and 4.4e-6 m after.
  • Results are bit-identical wherever the line lies more than a radius below the surface.

Tests

  • Release: 367/367 on the default and Prescott kernels.
  • Debug: 367/367, no warnings.
  • Python: pytest 2879 passed.
  • Lint and docs: ruff, fprettify and Sphinx -W are clean.
  • New or widened tests in Debug: they take 17 %, 21 % and 2.5 % of their timeouts.
  • Examples: 53 of the 54 are bit-identical; the exception is the composite Syrope deck (item 1).

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 8, 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-08T16:49:45.331556Z 2aa53b0 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 8, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35736128 | 📁 Comparing 2aa53b0 against latest (e8f88f5)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 2decd3607b

ℹ️ 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 force-pushed the fix/axial-damping-ratio branch from 2decd36 to 6de62cd Compare November 8, 2026 09:17
@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: 6de62cdee9

ℹ️ 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_HermiteCableStatic.f90 Resolved
@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: 3d99c95bd8

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

…mode

A negative LINE TYPES BA is MoorDyn's damping ratio per segment,
BA = zeta L0 sqrt(EA m) on each element, so the first axial mode of a
line is damped at about zeta pi/(2N) on N elements and less on a finer
mesh.

- OPTION axialDampingRatio (axial_damping_ratio): segment (the default,
  unchanged) or mode1. Under mode1 a negative BA is the damping ratio of
  the line's first axial mode, the same on any mesh:
  BA = 2 zeta EA / omega_1 on every element, a damping proportional to
  the stiffness, with omega_1 the first axial frequency of the line with
  both ends held from its sections (CD_Axial_Mode1_Omega, a fixed
  internal mesh), so a composite line is damped at zeta too. It applies
  on every route that builds lines from a deck (EI = 0 and finite-EI
  lines); a line with a negative BA and a viscoelastic or Syrope section
  is refused by name. The Python deck validator accepts the same values.
- An initialisation note for every line with a negative BA per segment:
  the damping ratio of its first axial mode on its final mesh, from the
  resolved BA (CD_Axial_Mode1_Damping, the Rayleigh quotient of the
  axial chain), and the element count. It reaches the driver report,
  CableDyn_GetInitNotes and the OpenFAST console.
- Fix: a negative BA of an EI = 0 line was resolved with the length, EA
  and mass of the element at the mirrored position from the other end,
  so the sections of an asymmetric composite line exchanged their axial
  damping. Of the examples, composite_chain_syrope_chain.dat changes
  (the largest difference 619 N, 6.6e-4 of the value); the others are
  bit-identical.

driver_axial_damping_ratio fits the free decay of a taut line's first
axial mode: zeta pi/(2N) at N = 50, 100 and 200 within 0.1 % under the
segment form, with the note; 2 % on every mesh under mode1, uniform and
composite, EI = 0 and finite-EI; and the composite segment form at the
ratio of its own elements' damping (27 % off before the fix).

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

The end reactions of a finite-EI cable at rest in a uniform current
(CD_HermiteCable_Dyn_End_Force: FairTen/AnchTen, Point<P>F) balance its
submerged weight and its Morison drag to the static tolerance, about
2e-8 of the end force, with pinned (bending-free) and clamped ends,
suspended and touching down, in currents of 0.5 to 2 m/s at headings
0 to 180 deg across the plane of the ends, on 25- and 100-element meshes.
static_current_balance integrates the documented drag law independently
on the converged cubic-Hermite centreline: with the solver's 3-point rule
the balance closes to 2.3e-8; a 10-point rule differs by the drag
quadrature, 7.4e-8 on 100 elements and 2.0e-6 on 25.

An imbalance near 1e-4 comes from the check, not the equilibrium:
integrated on straight chords between the nodes the drag misses by a
share that falls with the square of the element length (2.8e-5 on
1.25 m elements in a 1 m/s current, 1.1e-4 on 2.5 m, 4.5e-4 on 5 m), and
per unstretched length by the axial strain times the drag (7e-5 here).
theory.rst now states the length each path takes the drag over
(unstretched on EI = 0 lines, the deformed centreline on finite-EI
lines) and how a check must integrate it.

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

With staticsFriction asLaid on a bathymetry, the friction reference of
a node moves with its sink into the penalty seabed, which on a slope
shifts it horizontally by its load over its seabed stiffness. The load
was the submerged weight of the line and the net in-water weight of an
attachment wherever the node lay. The static solve and the dynamics
give back the buoyancy of the dry part of a finite-EI section within its
radius of the still-water level, and an attachment above the surface
carries its dry weight. On a seabed shallower than a cable's radius the
reference therefore sank less than the node, and the run rested off its
laid path across the slope, held there by a spurious friction force.

CD_HermiteCable_As_Laid_Offsets now sinks each node under the normal
load the solver applies at its laid position: the line laid without its
sink, each node at the height its load sinks it to, and the dry part's
load there (CD_HermiteCable_Dry_Buoyancy, the solver's own law) solved
by Newton's method with its exact height derivative; attachments above
the surface add their buoyancy back. The section diameter travels with
the friction reference by reference arc, so the reference rebuilt on a
refined mesh uses it too. Where the line lies below the surface by more
than its radius nothing changes, bit for bit.

The seabed lies below the still-water level everywhere (WtrDpth and
bathymetry depths must be positive), so a grounded node with an
attachment stays submerged and an EI = 0 line, whose submergence
follows its node heights, is wholly submerged where it is grounded: the
attachment case cannot arise and is handled by the same rule.

static_friction_as_laid gains shallow_cross: a 0.5 m cable laid on a
seabed 0.1 m deep with a 5 degree cross slope. Its run lay 7.75e-4 m off
its laid path (7.72e-4 m predicted from the two sinks); it now rests
4.4e-6 m off it, and a march from the static state stays at rest. Every
example is bit-identical.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The [Unreleased] entries of the open changes are added together in one
change, so that they do not conflict with each other.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@SMI-Lab-Inha
SMI-Lab-Inha force-pushed the fix/axial-damping-ratio branch from 3d99c95 to 1c6bf8e Compare November 8, 2026 13:30
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 1c6bf8e5c3

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

…residual

The as-laid reference's dry-part load is solved by Newton's method. On a
net-buoyant cable over a seabed shallower than its radius, a node held off
the floor is wholly dry and one sunk under that load wholly wet, so the
full step cycled between the two (about -208 and 728 N/m for a 0.5 m cable
of 180 kg/m on a bed 0.01 m deep with kBot = 1000) and initialisation
failed with "the dry-part load of the laid line did not converge".

A step that does not reduce the residual's 2-norm (Armijo, slope 1e-4) is
now halved from the last accepted loads, down to 2^-30, and the iteration
budget is 200. The case converges at the 70.3 N/m root, and a march from
its static state stays at rest (drift 1.5e-8). static_friction_as_laid
gains buoyant_shallow, which failed before. Full CTest 370/370 on both
BLAS kernels.

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. Bravo.

Reviewed commit: 2aa53b013d

ℹ️ 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 30a4d0a into dev Nov 8, 2026
22 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the fix/axial-damping-ratio branch November 9, 2026 08:55
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