Skip to content

feat(torsion): OpenFAST linearisation, active line control and modal analysis of lines restrained in torsion - #73

Merged
SMI-Lab-Inha merged 7 commits into
devfrom
feat/torsion-routes-a
Oct 30, 2026
Merged

SMI-Lab-Inha merged 7 commits into
devfrom
feat/torsion-routes-a

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Squash title: feat(torsion): OpenFAST linearisation, active line control and modal analysis of lines restrained in torsion

What changed

Three torsion route limits are lifted. Each one was built and reviewed on its own branch from
dev 66e3e83; here they are combined on dev (after #71 and #72).

OpenFAST linearisation (Linearize = True)

A finite-EI line restrained in torsion no longer fails closed under linearisation. Its nodal
twist joins the continuous states: the twist angle of every node the end frames do not hold,
after the cables' positions and tangents, and their rates after the velocities (Cable 1 node 2 twist, rad, ... twist rate, rad/s). The coupled point's orientation turns the torsion frame
of the host-driven end, CD_HFMF_Set_Twist_Frame_Rates gives that frame the point's angular
velocity and acceleration (so the torsional damping and the held end section's inertia get
their B and D columns), and the fairlead moment carries the torque. Under linearisation the
coupled-point rotation is stepped by 1e-4 rad instead of 0.1 rad, also in the input Jacobians of
the time march before the linearisation times; a run without Linearize keeps 0.1 rad. A
Rigid bending end connection still fails closed.

Active line control (CONTROL)

A controlled finite-EI line restrained in torsion is no longer refused. Every torsion term that
depends on the unstretched length follows the command: the condensed compliance, the nodal
twist's GJ/l and Bt/l, the torque–tension coupling (K/GJ)(l − l0), the lumped polar
inertia Irn l0/2, and a -ζ torsional damping, which now keeps its ζ and is re-resolved at
the new length. The torsional damping acts on the rate of the twist per length, as the axial
damping acts on the strain rate. The committed force keeps the committed lengths, so a ramp does
not lag at α_f > 0. The checkpoint mirror of a nodal-twist line gains one value, its committed
torque, so a reload brings it back as it was formed.

Modal analysis (nModes)

The modes of a line restrained in torsion carry the twist angle of every node, with the lumped
polar inertia as its mass and the second variation of the twist energy at the static torque.
The finite-EI modal route now also takes the end connections (finite springs; a rigid end's
tangent in its basis) and the attachments' masses from the model, which it ignored, and writes
the positions of a line with a heading in the deck's axes. <root>.modes.out adds PolarShare
and dTwist when a line carries twist.

Gates

  • lin_torsion (the shell's lin_eval recipe on the aggregate) and
    validation/scripts/openfast_lin_torsion.py (OpenFAST): on a straight taut 100 m line
    (GJ 5e4 N·m², Irn 2 kg·m, 50 elements) the first three torsional modes from eig(A) are the
    lumped chain's to 5e-14 and lie 1.6e-4, 6.6e-4 and 1.5e-3 below the continuum's
    nπ/L √(GJ/Irn); the roll stiffness −(D − C A⁻¹ B) is GJ/L to 1.5e-14, against the
    feedthrough GJ/l_e alone (50 times stiffer); a 90° twisted lazy wave matches the deck's
    static solutions for a rolled and a moved fairlead to 4.9e-4. Condensed torsion, an elastic
    end and the frame-rate columns (Bt/L, Irn l_e/2) are gated to 1e-6.
  • control_torsion: a taut line paid out and hauled in carries GJ Φ/L(t) + K (H − L)/L to
    1.5e-12 (a frozen compliance misses by 6.5e-3 and 0.23) and its tension to 3.6e-6; a constant
    pay-out carries the Kelvin–Voigt torque to 5.8e-6 N·m of its 0.642 N·m damping share; the
    length-rate damping matches central differences to 1.3e-10 and the torque tangent to 1.1e-9;
    a pay-out under a ringing twist balances the energy to 7.8e-5 of the work done; restarts
    mid-ramp (snapshot, checkpoint mirror, a CONTROL deck on the aggregate) are bit-identical.
  • modal_torsion, modal_torsion_deck: clamped 10 m line, torsional modes are the lumped
    chain's to 1e-16 and the continuum's within the chain's own error (2.6e-4 on the first);
    elastic torsional ends against the continuum to 1.5e-4; coupled axial–torsional modes to
    8.6e-4; lateral modes under a torque M = 4 EI/L match the clamped Greenhill cable to
    3.2e-7; eliminating the angles gives back the condensed static tangent to 1.4e-16.

Changed results

  • The modes of finite-EI decks with END CONNECTIONS or ATTACHMENTS and nModes (no shipped
    example): a clamped lazy wave's first twelve frequencies rise by 0.1 to 3.8 %, those of
    lazy_wave_buoyancy_modules.dat with nModes drop by 13 to 29 % (the ends and the modules'
    masses were ignored).
  • Under Linearize = True the rotation columns of a deck with a hang-off spring move by up to
    0.17 % (the 1e-4 rad rotation step).
  • OpenFAST checkpoints of decks with the nodal twist written before this change do not reload
    (the mirror gained the committed torque).

Combining the branches

The six commits are cherry-picked in order (lin, control, modal; each with its review fix) onto
#71 and then rebased onto #72. Conflicts were in the documentation and the CHANGELOG (every
entry kept; the OpenFAST coverage paragraph and the active-tensioning bullet merge #72's
viscoelastic and Syrope control with this PR's linearisation and torsion), the exact-real
compile options of the new tests in CMakeLists.txt (both kept), and in the deck
driver's torsion stage, where #71 renamed the stage's meshes (ld, lf) and control added the
kept ζ of a -ζ damping: the merged stage resolves the damping on lf. The control branch's
extra value in the nodal-twist mirror composes with the lin branch's slot arithmetic: the twist
slots are taken from the end of the mirror (MirrorSize − Twist_Mirror_Size) and the angles are
the first block of the twist tail, so the appended torque does not move them. The VALIDATION
entries are T-14 (control) and T-15 (modal). python/tests/test_native_model.py is dev's
(the identity-based handle-release test of #72); the control fix's gc.collect() variant is
dropped, so that commit's message still names a change it no longer makes.

Checks

  • Full ctest suite (333) passes; pytest python/tests tests (2124 passed, 114 skipped; the
    native parity tests with CABLEDYN_TEST_DRIVER: 212 passed); ruff check/format clean;
    pre-commit clean; the docs build with -W clean.
  • All 53 example decks are bit-identical to the reference driver (dev 0f53412).

With Linearize = True a finite-EI line restrained in torsion no longer
fails closed. Its nodal twist joins the line states: the twist angle of
every node its end frames do not hold (all but a torsionally rigid end)
after the cables' positions and tangents, and the angle rates after their
velocities ("Cable 1 node 2 twist, rad" / "twist rate, rad/s"). lin_eval
loads them into the mirror with the rest of the state, and the angles'
accelerations come from the same acceleration solve as the cable's, with
the lumped polar inertia Irn. CD_HFMF_Twist_Lin_Count/_Slots give the
slots in the cable's torsion tail.

The input mesh already carried the coupled point's orientation and
angular rates, and the output mesh the moment. The orientation turns the
parent-attached End A frame (SetCoupledKinematics), so the condensed
torque (Phi - Theta)/C and a nodal twist's end element see the turned
frame, and the fairlead moment carries the torque. New
CD_HFMF_Set_Twist_Frame_Rates gives that frame the point's angular
velocity and acceleration, which the march takes from the frame's turn
over a step: the torsional damping of the end element and the polar
inertia of the held end section now have their B and D columns. Under
linearisation the rotation is stepped by 1e-4 rad instead of 0.1 rad (a
rotation moves no node, so no contact or slack bounds it, and the turn of
an end frame or connection direction is nonlinear). This moves the
rotation columns of a deck with a hang-off spring by up to 0.17 %; on a
straight line with a 2e5 N m/rad hang-off spring the force per unit
rotation now matches static solutions to 4e-8 (6.8e-6 before). The
time-domain input Jacobian keeps 0.1 rad. A Rigid bending end connection
still fails closed.

Gates:
- openfast_lin_torsion.py (full OpenFAST linearisation, the case of
  openfast_lin_ab.py). A straight taut 100 m line, GJ 5e4 N m^2, Irn
  2 kg m, 50 elements, rigid in torsion at both ends: the first three
  torsional modes from the eigenvalues of A are the lumped chain's
  2 sqrt(GJ/Irn)/h sin(n pi/2N) to 5e-14 and lie -1.6e-4, -6.6e-4,
  -1.5e-3 below the continuum's n pi/L sqrt(GJ/Irn). The roll stiffness
  D - C A^-1 B is GJ/L = 500 N m/rad to 1.5e-14; D alone is the end
  element's GJ/l_e = 25000. The mixed deck's lazy-wave cable alone,
  twisted 90 deg (3470 states), matches the deck's static solutions to
  4.9e-4: the moment about the End A director per unit rotation about it
  (Pretwist(A) +-0.5 deg) is 82.4268 / 82.4263 N m/rad, then the forces
  and that moment per unit fairlead translation, and the forces per unit
  rotation against the reciprocal moment row.
- test_lin_torsion (ctest): the shell's lin_eval sequence on the
  aggregate. Twist modes against the lumped chain to 1e-14, twist block
  decoupled from the line states (exactly). Roll stiffness GJ/L for the
  nodal twist and the condensed torsion, 1/(L/GJ + 1/kt) with an elastic
  end. Bt/L per unit angular velocity (0 without the frame rates), and
  Irn l_e/2 per unit angular acceleration.
- The #66 gates are unchanged: the UMaine fairlead stiffness against
  MoorDyn-F to 0.10 % (H/X 0.29 %), the line modes to 0.30 %, the mixed
  deck's coupled points against their static solutions to 3.3e-4.

An executable without twist states refuses both decks at initialisation.
The full suite passes, and all 53 example decks are bit-identical to dev.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
- lin_eval reports a failure to set the torsion end-frame rates by its
  own name, no longer as the cable's acceleration.
- The comments and the CHANGELOG say that in a Linearize run every input
  Jacobian, those of the time march before the linearisation times
  included, steps the coupled-point rotation by 1e-4 rad; a run without
  Linearize keeps 0.1 rad.
- The angle-step comment states what is affine in the twist angles (the
  element twists, torques and their forces at a fixed configuration, also
  under GJ|K) and what is not (their coupling to the configuration).
- The .lin operating-point outputs come from CD_CalcOutput, which keeps
  the committed accelerations and the end-frame rates of the last step's
  turn, while the matrices difference lin_eval with the input's angular
  rates. At a settled operating point (the documented still-water start)
  the two agree; at a moving one they differ by the inertia terms and the
  torsional damping and held-section inertia of the fairlead moment. This
  is documented (lin_eval, doc/openfast.rst) rather than changed: making
  CD_CalcOutput evaluate like lin_eval would change the operating-point
  outputs of every linearised cable, not only of torsion.
- Docs: the turned frame is the coupled (host-driven) end's;
  doc/coupling.rst and doc/coupling_boundary.md no longer describe the
  zero-state quasi-static linearisation removed in #66.
- openfast_lin_torsion.py: ruff clean.

openfast_lin_torsion.py rerun on the rebuilt module: unchanged (twist
modes to the lumped chain 5e-14, GJ/L to 1.5e-14, twisted lazy wave
4.9e-4).

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Active line control (deck CONTROL, CD_HermiteCable_Dyn_Set_SegmentLength)
refused a finite-EI line restrained in torsion. It now takes it, and every
torsion quantity that depends on l0 follows the length change:

- read at evaluation, as before: the condensed compliance sum l0/GJ, the
  nodal twist's GJ/l0 and Bt/l0, the coupling term (K/GJ)(l - l0) and the
  element shape. The committed force keeps them at the committed lengths
  (enter/leave_committed_lengths), the step's force takes the new ones, as
  for the rest of the residual, so a ramp does not lag at alpha_f > 0.
- rebuilt with the length caches (new torsion_length_terms, also when the
  committed-state evaluation hands the present lengths back): the lumped
  polar inertia Irn l0/2 and a torsional damping given as -zeta, which the
  torsion now keeps (CD_HermiteTorsionType bt_zeta, set by the deck) and
  re-resolves as zeta l0 sqrt(GJ Irn) (CD_HermiteTorsion_Zeta_Damping, the
  deck's own formula); a direct Bt stays. The torsion query cache is
  dropped on a length change.
- the torsional damping takes the rate of the twist per length, as the
  axial damping takes the strain rate: M = (GJ/l0) tau + (Bt/l0)(tau_dot -
  tau l0_dot/l0), with tau_dot gaining (l0_dot/l0)(m . g_m - (K/GJ) l0)
  (the reference twist depends on m only through l0 m and m/|m|), and the
  matching tangent.
- the snapshot and the recovering step keep the committed torque as it
  was formed instead of re-deriving it with the present lengths.

No new restart state: the torsion terms are functions of the lengths,
which the shell re-applies before the mirror reload.

test_control_torsion:
- Q: a taut line paid out and hauled in carries GJ Phi/L(t) + K (H - L)/L
  (condensed 2.8e-16 and 9.6e-15 with K, nodal twist 1.5e-12; a frozen
  compliance misses by 6.5e-3 and 0.23) and the tension EA (H - L)/L +
  K Phi/L to 3.6e-6;
- D: a constant pay-out under GJ|K|Bt carries GJ chi + Bt chi_dot to
  5.8e-6 N m of a 0.642 N m damping share; without the rate 0.646;
- F: the length-rate damping on a bowed line equals Bt l0_dot
  d(tau/l0)/dl0 by central differences to 1.1e-10 (the straight-line value
  is 1.7 % off);
- Z: the inertia and damping a command rebuilds equal a fresh build bit
  for bit; a committed-state evaluation takes the committed lengths and
  leaves the present ones; saved control and a snapshot taken between a
  command and its step take it back, the committed torque included;
- E: a pay-out under a ringing twist (real Irn, rho_inf 1) changes the
  energy by the work of the length change to 7.8e-5 of it;
- L: a slow pay-out at rho_inf 0.4 follows rho_inf 0 to 1.4e-3 of the
  per-step torque change, also with the committed force evaluated afresh
  each step (at the new lengths it lags by alpha_f of the change, 0.29);
- R, S: restarts mid-ramp from a snapshot, a checkpoint mirror and a
  CONTROL deck on the coupled aggregate are bit-identical; the deck keeps
  and re-resolves its -zeta damping, and its Torq1N1 follows
  GJ Twist1/L(t) to 6e-11 (its torsional damping included).
Ablations of the rate term, the rebuilt terms, their hand-back, the
committed-length force and the snapshot torque each fail a gate.

Full suite passes; all 53 example decks are bit-identical.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Review follow-ups to the active line control of lines restrained in
torsion.

- The checkpoint mirror of a line with the nodal twist carries its
  committed torque (CD_HermiteCable_Dyn_Twist_Mirror_Size gains one
  value), so a reload brings it back as it was formed, as Restore does.
  A frame write or a re-derived committed state forms it as the summed
  twist over the compliance, which (Phi - Theta)/C reproduces only to
  round-off. The condensed torque is formed as (Phi - Theta)/C at every
  commit and frame write, so the reload keeps re-deriving it at the
  re-applied lengths.
- test_control_torsion F runs at interior elements, at both rigid
  torsional ends (End A the fairlead, the element OpenFAST controls)
  and with coupling K/GJ = 0.5: the length-rate damping torque matches
  central differences of Bt l0_dot d(tau/l0)/dl0 to 1.3e-10 (the
  straight-line value is up to a factor 5 off), and the torque tangent
  a step assembles, read back at the state of its last assembly,
  matches central differences of the torque to 1.1e-9, where the
  length-rate share is 1.6e-3 to 7.6e-3 of it.
- R: after a non-stepping frame write the snapshot and the mirror bring
  back the committed torque bit for bit; re-derived it would differ by
  1.8e-15 N m.
- The Set_SegmentLength header reflowed; VALIDATION T-14 gives the lag
  of a committed force at the new lengths as the expected alpha_f = 2/7
  (0.289 measured by ablation); doc/theory.rst names the tangent DOFs
  a_i apart from the reference twist m_e.

- test_native_model's handle-release gate collects garbage before it
  tracks close(): in the full Python run an unreachable model of an
  earlier test was finalised inside the failing constructor, through
  the tracker, and the gate read its close first.

Full suite passes; all 53 example decks are bit-identical.

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

OPTION nModes now runs on finite-EI lines restrained in torsion. The dynamics of
such a line carry a twist angle at every node (a deck's explicit GJ comes with
the polar inertia Irn), so its modes do too.

- CD_Modal_Hermite_Line and CD_Modal_Hermite_Line_Band assemble a line model's
  modal stiffness and mass on the DOFs its dynamics solves: [r, m, phi] per node
  (half-bandwidth 13) on a line with twist, the lumped polar inertia as the
  angles' mass and the second variation of the twist energy
  sum 1/2 (GJ/l0)(phi_{e+1} - phi_e + rho_e(q))^2 at the static torque
  (CD_HermiteCable_Dyn_Twist_Hessian): M_e d2rho/dq2 + (GJ/l0) g g^T on the
  cable, +-(GJ/l0) g against the angles, and the elastic end springs.
  Eliminating the angles gives back the condensed static tangent; its rank-one
  term is the Schur complement of the angle block. A model with the condensed
  torsion of no polar inertia is refused by name (no deck builds one).
- The finite-EI modal route now takes the end connections (a finite spring's
  Hessian; a rigid end's tangent in its basis with the two transverse
  components held) and the attachments' masses from the model, which it
  ignored, and writes the positions of a line with a heading in the deck's
  axes. Decks without them keep their modes table byte for byte.
- <root>.modes.out adds PolarShare (the polar share of each mode's kinetic
  energy) and dTwist (the section rotation about the End A -> End B tangent)
  when a line carries twist; a torsional mode is scaled to a unit largest
  twist.

Gates: test_modal_torsion on a 10 m clamped line: torsional modes against
n pi/L sqrt(GJ/Irn) within the lumped chain's own error (2.6e-4, 1.0e-3) and
the chain to 1e-16, bending and axial modes equal to the line without torsion;
elastic torsional ends against the continuum (1.5e-4); torque-tension coupled
axial-torsional modes (<= 8.6e-4); lateral modes under M = 4 EI/L against the
clamped Greenhill-cable determinant to 3.2e-7 (-5.5 % on the first); on a
bowed twisted line the Schur complement of the angles equals the condensed
static tangent to 1.4e-16 and the central differences of the condensed static
residual to 7.6e-10; finite end springs put the first lateral frequency
between pinned and clamped (3.6e-5 from the clamp at k = 1e5 EI/L).
test_modal_torsion_deck.py runs the same straight line
through the driver against TorsStiffness Free and turned 30 degrees, and the
lazy wave twisted two turns; on the old driver both fail with the refusal.
The old modal route without the twist finds no torsional mode and puts the
clamped line's first lateral frequency 41 % low.

Changed results: the modes of finite-EI decks with END CONNECTIONS or
ATTACHMENTS and nModes (none shipped): a clamped lazy wave's first twelve
frequencies rise by 0.1 to 3.8 %, those of lazy_wave_buoyancy_modules.dat with
nModes drop by 13 to 29 %.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
- doc/theory.rst: the modal stiffness of the nodal twist is written with the
  full element twist rho_e (the reference twist and the coupling's
  (K/GJ)(l_e - L0)), summed over the elements, so M_e (K/GJ) d2l_e/dq2 under
  GJ|K appears as the code assembles it; the cross term names the element's
  nodes consistently.
- modes.out: dTwist is a normalised shape value like dX dY dZ, now marked (-);
  doc/outputs.rst says what the normalisation means for a bending and for a
  torsional mode, and that End A is the reader's End A (the fairlead of a deck
  written anchor-first).
- examples/torsion_lazy_wave_hangoff_twist.dat: the comment no longer calls
  the torsion quasi-static. Comment lines only: the example's outputs are byte
  identical to the reference driver's.

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 Oct 30, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-30T19:35:50.909612Z fc840bf 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

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 519e47fecf

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

@read-the-docs-community

read-the-docs-community Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35532362 | 📁 Comparing fc840bf against latest (fd1936d)

  🔍 Preview build  

30 files changed · ± 30 modified

± Modified

Check R of control_torsion requires the snapshot and the mirror to bring
back the committed torque of a non-stepping frame write bit for bit,
which re-deriving it as (Phi - Theta)/C would not. The two values differ
only by the round-off of Phi - (Phi - summed twist), and the Linux
Release build makes that exact, so the "check resolves" requirement
failed there although the restore was right.

Where the two values are equal, the committed torque is now set one ulp
off the re-derived value before the snapshot and the mirror pack, so a
re-derivation can never reproduce it on any build. Forcing that branch
on Windows passes; the natural difference there stays 1.8e-15 N m.

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. Swish!

Reviewed commit: fc840bfa69

ℹ️ 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 ffc57c0 into dev Oct 30, 2026
20 of 21 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/torsion-routes-a branch October 30, 2026 22:18
SMI-Lab-Inha added a commit that referenced this pull request Oct 31, 2026
…rs or two objects, TURBINES rows turning both end frames (#75)

A finite-EI (cubic-Hermite) line may now have two moving ends: End B on a
Coupled/Vessel point (a cable shared by two floaters, a FAST.Farm shared
line), standalone, in OpenFAST, FAST.Farm and the C API, and End B on a
Rigid6 body point or a rod end on the standalone multibody march (a cable
between two objects). Both ends are driven, carry END CONNECTIONS and torsion,
and return their loads to their hosts or objects.

Base: dev e992e9f (#74); the series is rebased onto it from 6195432 (#71),
past #72, #73 and #74.

- HFMF boundary: a second driven end at internal node 1 (moving_b), with its
  own parent frame, end connection and torsion frame (the frames of both ends
  turn with their parents), its mirror block in the restart state, and a held
  End B (at rest, target equal to the committed position in either frame) that
  steps exactly as a Fixed End B.
- Standalone: motionFile, vesselMotion/vesselRAO, TURBINES rows and the roll
  column drive End B as End A; Phi = Pretwist(B) - Pretwist(A) - roll(A) -
  roll(B), the roll of an end free in torsion twisting nothing. TURBINES
  decks start each end's Ez/Nx in its turbine's PtfmInit axes and turn both
  frames with the rows' rotations, as FAST.Farm does.
- Aggregate, OpenFAST, FAST.Farm, C API: End B on a moving column of its own
  (cable_col_b), the turbine map, host orientations at both ends,
  CableDyn_GetCoupledLayout with the End B blocks; OpenFAST linearisation of
  such a cable fails closed (the linearisation of torsion from #73 stays for
  every other line). On the standalone mixed deck the roll columns of both
  ends twist the line.
- Multibody march: End B's attachment, frames and loads (cab_*_b); the
  monolithic step re-steps a cable between two objects at every outer
  iteration and couples both objects' junction coordinates through its
  finite-difference end-to-end stiffness in the one Newton matrix; the
  static passes balance both objects on the cubic-Hermite end loads,
  accelerated by Anderson mixing (a stiff EI 1e6 clamped cable between two
  unequal moored bodies, out of their plane: 8 passes either direction, where
  the plain passes diverged); the staggered scheme takes pinned ends. A
  pinned cable with one moving end is coupled at the predictor whichever end
  that is, and an end on a fixed rod's end is the Fixed end there, so the
  result does not depend on the line's direction. A partitioned coupling was
  measured and not taken: on a stiff taut cable (EA 1e8 N) between 200 kg
  bodies at dtM 0.05 s it needed 9.2 mean outer iterations and 300 step
  halvings over 100 steps, the joint form 3.9 and none. An End B on a
  Free/Connect point, a Point3 buoy or a Coupled/Vessel point stays refused
  there by name.
- Validation (native and the Python mirror): END CONNECTIONS and torsion
  admit those End B points; staticsFriction asLaid is refused on a moving
  End B.

Where it meets the torsion routes of #73/#74 (one restrained end, torsion on
Fixed and `Body<N>` rod ends, prescribed motion on the mixed deck):
- check_torsion_line is the union of both scopes. Two cases neither solves are
  refused by name, natively and in deck_file.py: torsion at an End B on a rod
  end, and a rod End A restrained in torsion with a moving End B. A bending
  END CONNECTION takes any End B that holds a frame (ROD_END_B_NOTE is gone).
- The restrained end decides, not any torsion on the line
  (line_torsion_at_a/line_torsion_at_b): connected_end, cab_clamp_b, the End B
  staggered refusal, the static pass tolerance and pinned-end skip, the roll
  columns, and the torsion turn limit of both bodies (an end free in torsion
  is not limited). clamp_object_frame takes the Fixed-rod normal of the end it
  frames; `Rod<N>` connection moments include End B.
- Mixed deck: build_aggregate_motion now follows the two-ends moving-set order
  (End A columns, then End B columns) and cable_two_ends imposes
  Phi_0 - roll(A) - roll(B). Before, a deck whose End B point came first was
  refused and otherwise the roll did not twist the line (gate 8 below).
- test_cable_between_bodies D: a Fixed-to-rod-end line and its reversal now
  write one output, since #74 turns a Fixed-to-rod line around as dev turns a
  Fixed-to-body line.

Result changes:
- The finite-EI compatibility (Cosserat) deck route is retired. Only three
  test decks reached it, all refusals or a run-only smoke; on four
  shared-line decks it failed to converge (three) or reached a static
  FairTen of -6.1e8 N (one), and the Hermite route runs all four. Decks with
  a line between two moving points now run on the Hermite route.
- A torsion frame at a bending-pinned body or rod End A is refused on
  bodyScheme staggered (it ran with the frame held still and could spin the
  body through +-180 deg); the monolithic scheme turns it with the body.
- Standalone TURBINES decks: an end on a `Turbine<J>` point takes Ez and Nx in
  the turbine's axes (turned by PtfmInit) and its frames turn with the
  TURBINES rows. Decks whose turbines start rotated or whose rows rotate,
  with end connections or torsion, change: on a clamped line twisted 90 deg
  between turbines rolling 10 deg in opposite senses the end torque at 1 s is
  613.6 N m (788.1 N m before), tensions within 5e-7. No example uses
  TURBINES rows.

Gates:
- tests/test_two_moving_ends: a held Coupled End B writes the Fixed End B's
  files byte for byte (also at a 37 deg chord heading and in the modes); a
  symmetric cable whose ends move apart stays mirror-symmetric (4e-11 m); a
  rigid translation keeps the end loads (4e-5 N of 1.6e4 N); End B driven
  equals the reversed line driven at End A (1e-3 N; turning clamped End B
  2e-5 N, 4e-7 N m); equal rolls keep the torque (3e-6 N m), opposite rolls
  change it by GJ (2 phi)/L (5e-6 N m); restarts bit-identical; FAST.Farm
  aggregate vs standalone: shared line 7e-3 N of 1.9e4 N, yawed turbines with
  torsion 7.6e-9, rolling turbines 3.4e-8 in every channel.
- tests/test_cable_between_bodies: two mirrored bodies stay mirror images
  (monolithic clamped and staggered pinned, to the output precision); a body
  joined to a 1e15 kg body equals the body-to-Fixed line of the established
  route to 8e-9 (clamped, and twisted 90 deg); two free bodies with no
  external load keep the total linear momentum to 3e-5 and the energy to
  0.2 %; a 90 deg twist returns equal and opposite torques GJ Phi/L (sum
  below 2e-10 N m); a moored pair starts balanced and stays at rest, its
  connection moments turning it from the pinned pitch; the stiff unequal pair
  converges forward and reversed to one equilibrium the still dynamics hold,
  and with its passes limited fails closed naming the line; either direction
  of a Fixed-point-to-rod-end cable gives the same output, and an End B on a
  fixed rod's end is the Fixed End B; a body-to-rod-end cable runs; refusals
  name their cause (the staggered torsion End A included).
- tests/test_mixed_route_torsion gate 8: a line twisted 90 deg between two
  Coupled points beside a chain, both ends rolled by the roll column: rolled
  oppositely the twist stays 90 deg exactly (torque GJ Phi/L to 3.4e-6 N m);
  rolled equally 15 deg it is 90 - 2 roll to 5.0e-7 deg (4.7e-6 N m; the old
  code 30 deg and 262 N m); End B's point listed first gives the same figures
  (the old code refused the deck).
- tests/test_rod_end_torsion, python/tests/test_deck_native_parity: the End B
  rod-end refusal and the shared staggered message.
- Python validator: mirrors the march's End B refusals, the staggered refusal
  of a connected or torsional end at either end, and the two new torsion
  refusals.
- C API and Python: host rotations at both end frames, the coupled layout
  driven through the documented host recipe, the asLaid mirror.

Commits: the two-moving-ends commits rebased one by one, the three multibody
commits (a finite-EI line between two objects, its review fixes, the Python
mirror) as one with the torsion-route integration, then the Intel ifx #5151
continuation fix and the mixed-deck roll fix with gate 8.

Two fixes from the checked Debug CI job:
- `end_b_at_rest` no longer indexes `pdof_b` when End B is not driven
  (Fortran does not short-circuit `moving_b .AND. .NOT. end_b_at_rest(...)`;
  Release read a stray value it then discarded, Debug stopped on it).
- A rod numbered as a body is no longer one of the body's attachment points
  (also in 0.3.0): a `Rod<N>A/B` end point keeps its rod's id where a
  `Body<N>` point keeps its body's, and the body's point list took both. New
  gate `body_rod_numbering`: the same deck with the arm rod numbered 1 and 3
  now writes identical outputs; before, 200 of 203 rows differed (arm pitch
  172 deg, body pitch 1.06 deg, a leg tension 3.0 kN in 1 s).
The 25 tests the Debug job failed and the new gate pass on a local checked
Debug build.

Full ctest (341/341) and pytest (python/tests and tests with the native
driver: 2179 passed, 75 skipped) pass; ruff check/format and mypy clean (the
three numpy-stub notes dev already has aside), pre-commit clean, docs build
with warnings as errors, no symbol both in a PUBLIC list and declared PUBLIC.
A/B against the reference driver: 53 of 53 examples byte-identical.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
SMI-Lab-Inha added a commit that referenced this pull request Oct 31, 2026
GitHub retires the `macos-14` runner image on 2 November 2026, and its scheduled brownouts
already cancel the `wheels / macos` job (#73, #74, #75: "Cancelled after 1s", annotated as a
macOS 14 brownout, actions/runner-images#13518).

- `.github/workflows/wheels.yml`: the macOS wheel builds on `macos-15` with
  `MACOSX_DEPLOYMENT_TARGET=15.0`, the oldest macOS its Homebrew gfortran and OpenBLAS bottles
  support there, so delocate accepts the bundled libraries. The wheel tag becomes
  `macosx_15_0_arm64` (0.3.0: `macosx_14_0_arm64`).
- The installation page, the README and the CHANGELOG (`Changed`) say the macOS wheel needs
  macOS 15 or newer on Apple silicon; on macOS 14, build from source.

No code change. Docs build with warnings as errors locally; the `wheels / macos` job of this PR
is the build and smoke test of the new wheel.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
SMI-Lab-Inha added a commit that referenced this pull request Oct 31, 2026
…, on lines as long as their span and on bodies with pinned cables (#77)

## What changed

Six accuracy items from the open list, rebased onto dev (#73 torsion linearisation, control and modal analysis, #74 torsion on the mixed deck, at one end and on a rod end, #75 lines with two moving ends, #76), one commit that closes where they meet dev's newer routes, and four fixes from an independent review.

- **Dry weight of an `EI = 0` line above the surface.** With a seabed the march gives the part of a line above the still-water level its dry weight; the static start kept its buoyancy. `CD_Static_Line_Equilibrium` now carries the dry part as a fixed point on the wetted lengths. A chain hung from 5 m above the surface starts in the march's equilibrium (holds to 1e-10; before 1e-3 of its fairlead load in the first step), and the coupled and standalone starts agree to 1.4e-8 (before 2.4e-4).
- **The same dry weight in the force balance of `Connect`/`Free` points, bodies and rods** (`solve_body_equilibrium_core`, its warm and cold line solves, the new `CD_Static_Line_Dry_Load`). A 50 t `Connect` point hung by two chains from 10 m above the surface holds its position over 2 s (before it sank 1.1e-2 m). An `EI = 0` chain between two moving objects across the surface, a body point 5 m above it and a `Connect` clump, holds both (before 5.5e-3 m). In that balance a finite-EI line, carried without its bending stiffness, now takes its dry weight with or without a seabed, as its cubic-Hermite cable does: a body with a light pinned cable 5 m above the surface on a deck without a seabed holds its heave to 7e-6 m (before 2.8e-3 m).
- **`ATTACHMENTS` above the surface.** The march loads an attachment above the free surface with its weight alone, while the attachment polish and the torsion stage after it kept its buoyancy. Each solve now takes every attachment's load for the side of the surface its node is on, and the final solve is repeated until no attachment changes side. A 500 kg, 0.2 m³ module 3 m above the surface held the fairlead load over 1 s to the output's 8 digits, restrained in torsion as well (before it moved by up to 6.1e-2). An attachment carried above and below the surface on alternate solves (a net-buoyant module that would float, which a point attachment cannot represent) fails closed, and the message leads with that attachment's index, Mass and Volume.
- **A pinned cable with `ATTACHMENTS` in the body static balance.** The object solve left a bending-pinned End A free in torsion to its cable without bending stiffness, which carries no attachments. Such a line now takes the static passes of a connected end. On a moored body with a 2 t clump on a pinned cable the body holds its pose (before it drifted by up to 2.9e-2 m and 0.20 deg in 5 s).
- **Current gradient in the finite-EI static tangent.** A depth profile is sampled at the node elevations and a current grid at the node positions, so the drag moves with the nodes. The Newton tangent now carries that: the drag tangent matches central differences to 4e-10 to 1.7e-9 (before 5e-2 to 0.2), also at the twisted equilibrium of a line restrained in torsion with `GJ|K` (4.3e-10, before 5.4e-2). The equilibria do not change beyond the solver tolerance; Newton converges faster in strong shear (16 instead of 23 iterations).
- **Force-scale floor for a finite-EI line as long as its span.** The static start of a neutral line whose length equals its span failed with neutral or drag-area `ATTACHMENTS`: the polish stalled at the round-off of the axial forces. For a line whose chord is at least its length, the convergence scale now includes that floor over the tolerance, as on the `EI = 0` path. Such lines now start straight and unloaded, also between two moving ends, restrained in torsion at both ends or at End A only, and with a chord 1e-8 longer than the line (0.1 N to 2.2e-7 N). All of these failed on dev.
- Docs: the linearisation at an accelerating coupled point (`doc/openfast.rst`, `VALIDATION.md`), and the carry spin of a held end section, measured and left out (`doc/theory.rst`; the modal analysis and the OpenFAST linearisation of #73 leave it out as well).

## Review fixes

- **The attachment with no static side is named** (`attachment_static_polish`, `torsion_after_attachments`): a 200 kg, 2 m³ module 50 m along a slack cable stopped with only "the homotopy stopped at load fraction 0.625000"; every later failure now leads with the attachment that crossed the surface (`static_dry_weight` 9). On dev the same deck ran with the module 4.5 m above the surface and its buoyancy kept.
- **A pinned cable with `ATTACHMENTS` on a `Point3` buoy** is refused by the existing `Point3` message instead of an END CONNECTIONS message for a deck without that row (`line_attachments` 10).
- **The body passes of a pinned cable with `ATTACHMENTS` are Anderson-mixed**, as the passes of a line between two objects are: on a spar rod with a 1500 kg clump on a pinned cable the plain passes diverged (end-load change 2.9 of the force scale after 60) and the deck stopped; they now converge in 26 and the rod holds to 8 digits over 3 s (`line_attachments` 11).
- **Every bending-pinned finite-EI line on a Rigid6 body or a rod end takes the (mixed) passes**, with or without attachments: the stand-in without bending stiffness put a spar rod's start 5.7e-2 m off equilibrium (7e-2 m drift and a 2.3 % leg tension change in 3 s); it now holds to 8 digits after 4 passes (`line_attachments` 12; before 1.8e-4 m in 0.1 s). This changes the static start of user decks with a pinned finite-EI cable on a free body or rod by the bending share of the end force; no example deck has one.
- **Body passes that do not hinge on round-off** (after the Linux Release job failed `line_attachments` 11 with no convergence in 60 passes, where Windows took 26): the core solve's stand-in cable now carries the line's `ATTACHMENTS` smeared as net weight, as the Hermite statics smear them, so the passes correct only the lumped, surface-side, drag and bending differences (the whole 15 kN clump load before); a failed pass set is repeated once on the stand-in without attachments; and the Anderson column-drop bound is 1e-6 instead of 1e-10 (a pinned end's residual spans fewer directions than the history, so later columns were round-off with coefficients near 1e12). Gate 11 converges in 6 passes, geometrically. New gate 13: the same deck with a leg anchor moved 1 ulp either way gives the same rod pose to 1e-9 m in 6 passes each (before 26, no convergence after 60, 26). Across a 45-deck sweep of rod and body decks (clump mass, cable length, rod mass, start offsets, 1-ulp and 1e-14 m moves) 42 converge, 34 before; the two-object decks are unchanged. Gates 11 and 12 march at `dtM` 0.002 s, because the explicit coupling of a cable to a free rod on this branch is unstable at 0.01 s (fixed separately in the next PR).
- Known and left: the as-laid friction reference still takes an attachment's net in-water weight, which matters only where the seabed rises above `z = 0`.

## Rebase notes

- Conflicts were only in `CHANGELOG.md` (entries kept side by side), `doc/openfast.rst` (the torsion linearisation paragraph of #73 kept, and the zero-frequency paragraph replaced by this branch's operating-point version) and `doc/theory.rst` (the carry-spin paragraph placed before #74's free-end section). The source files merged cleanly. `cached_line_solve`, `prepare_line` and `warm_line_solve` sit on #75's two-ends object solve unchanged: the line cache already treats both ends alike.
- The carry-spin commit message no longer says the modal analysis refuses torsion.

## Gates

- `static_dry_weight` 1-8: gates 1-5 as before. Gate 6: a module above the surface, plain and restrained in torsion (0; before 6.1e-2), and a submerged module as guard. Gate 7: a pinned cable above the surface on a body without a seabed (7e-6 m; before 2.8e-3 m). Gate 8: an `EI = 0` chain between a body above the surface and a `Connect` point (0; before 5.5e-3 m).
- `line_attachments` 8 (continued) and 9: two moving ends, torsion at one or both ends, and a chord above the length, each of which failed on dev; the pinned cable with a clump on a moored body (1e-9 m; before 2.9e-2 m).
- `hermite_static_current_gradient` 1-5, `nodal_twist_dynamic` (carry spin).

## Checks

- Full ctest (Release): 344 of 344 pass (also after the review fixes; base now dev 1a8a606, #76 touched only CI and docs). On the checked Debug build (`-fcheck=all`) the added and touched tests and their neighbours pass, 12 of 12: `static_dry_weight`, `line_attachments`, `hermite_static_current_gradient`, `nodal_twist_dynamic`, `hermite_cable_static`, `hermite_torsion_static`, `torsion_attachments`, `torsion_one_end`, `rod_end_torsion`, `clamped_cable_ends`, `cable_between_bodies`, `bodies_rods`.
- pytest `python/tests` and `tests`, with the native parity tests on (`CABLEDYN_TEST_DRIVER`): 2179 passed, 75 skipped.
- ruff check and format are clean. Strict mypy shows only dev's 3 numpy-stub notes. pre-commit and Sphinx `-W` are clean, and no symbol is both in a `PUBLIC` list and declared `PUBLIC`.
- Example A/B against dev 357f9eb: 53 of 53 identical. No example has a line or attachment above the water, a finite-EI line in a profile or grid current, a line as long as its span, or a pinned cable with `ATTACHMENTS` on a body.

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