Skip to content

feat(torsion): ATTACHMENTS on a line restrained in torsion - #71

Merged
SMI-Lab-Inha merged 1 commit into
devfrom
feat/torsion-attachments
Oct 30, 2026
Merged

SMI-Lab-Inha merged 1 commit into
devfrom
feat/torsion-attachments

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

A finite-EI line restrained in torsion refused discrete ATTACHMENTS ("torsion is not combined
with ATTACHMENTS in this build"), which ruled out the usual lazy-wave power cable with buoyancy
modules. The static start of an attachment line solves the smeared equilibrium, then carries it
to the lumped loads by a homotopy (the attachment polish); the torsion stage ran on the smeared
state before the polish, whose untwisted solves would have unwound it.

  • A line with ATTACHMENTS takes its torsion stage after the polish, on the discrete
    equilibrium: torsion_stage runs on the final mesh with the modules' net weights
    -(m - rho V) g (and, in a deck current, their drag) as nodal loads
    (hermite_static_torsion passes f_nodal to the static solve). The drag depends on the
    node's depth and tangent, so the stage repeats with the drag of the last twisted state until
    the nodes move by less than 1e-9 m, as the polish does.
  • Every drag pass starts from the polished, untwisted state, so a writhe a buckling descent
    left cannot put the next pass on another branch.
  • The twisted discrete start gets the mesh safety diagnosis (attachment_mesh_checks, the
    kink limit away from the attachment nodes and, under tensile_safety True, no compression
    with the torque-tension coupling force added), which the smeared-state diagnosis cannot give
    it; the verdict of a polish fallback shares the same checks. The untwisted state's lateral
    hand-off note is not written for a torsion line (the torsion stage tests the twisted start's
    stability).
  • The torsion notes moved to torsion_note, written once for the accepted stage.
  • The deck rule and its Python mirror are removed; docs (driver format, capabilities,
    troubleshooting) say the modules add no polar inertia to the twist.

Gates, new torsion_attachments:

  • neutral modules (m = rho V, no drag) on the straight taut twisted line of
    test_torsion_deck: torque and twist equal the bare line's, GJ Phi / L and 720 deg;
  • tests/data/lazy_wave_torsion_attachments.dat (25 modules, one turn of pretwist, Irn 1 kg m:
    the nodal twist): a still 10 s run keeps the fairlead tension, both end torques and the
    twist of the static start to the output precision (spread 0 of 8 digits), in still water and
    in a cross-flow current of (0.2, 0.3) m/s. With the torsion stage on the smeared state
    (before the polish) the start is untwisted by the polish and the run rings by 3.4e-3 (End A)
    and 6.7e-3 (End B) of the torque.
  • a coupled line (GJ|K, Phi = -45 deg) whose coupling force compresses it, with one neutral
    module, is refused under tensile_safety True as the bare line is (the smeared-state
    diagnosis alone let it start with -2142 N).
    torsion_deck and the Python parity test now accept the deck they refused. Full suite passes;
    examples unchanged.

A finite-EI line restrained in torsion refused discrete ATTACHMENTS. The
static start of an attachment line solves the smeared equilibrium and
carries it to the lumped loads by the attachment polish; the torsion stage
ran before the polish, whose untwisted solves would unwind it.

A line with ATTACHMENTS now takes its torsion stage after the polish, on
the discrete equilibrium, with the modules' net weights and current drag
as nodal loads (the drag to a fixed point of the twisted state, every
pass from the polished untwisted state). The twisted start gets the mesh
safety diagnosis (kink limit away from the modules; under tensile_safety
no compression with the coupling force added). The deck rule and its
Python mirror are removed.

New gate torsion_attachments: neutral modules reproduce the bare twisted
line (GJ Phi / L, 720 deg); a lazy wave with 25 modules and one turn of
pretwist keeps tension, torque and twist over a still 10 s run in still
water and in a cross-flow current (the torsion stage before the polish
rang by 3.4e-3 of the torque); a coupling-compressed twisted line with a
neutral module is refused under tensile_safety as the bare line is.

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-30T08:22:38.924467Z 52f74c7 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 #35518524 | 📁 Comparing 52f74c7 against latest (fd1936d)

  🔍 Preview build  

28 files changed · ± 28 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 52f74c7975

ℹ️ 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 6195432 into dev Oct 30, 2026
21 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/torsion-attachments branch October 30, 2026 09:58
SMI-Lab-Inha added a commit that referenced this pull request Oct 30, 2026
…scoelastic segments, MoorDyn-C Currents 2 and 5 (#72)

Three MoorDyn features CableDyn refused or lacked, for 0.4.0, in one PR. Each is kept as its own commits (bodies, line control, currents), followed by a gate where they meet.

## 1. CoupledPinned bodies in OpenFAST

Every deck refused MoorDyn-F's `CoupledPinned`/`VesselPinned` bodies. They now run on the coupled route (`CompMooring = 5`) as MoorDyn-F's coupled pinned body.

- The body reference point is a node of the coupling mesh that takes the platform position only; the body turns about it with its own three rotations (`M_rr alpha = M - m [c]x a_p - w x (I_p w)`), and the node returns the body's net load less its inertia, with no moment. The 24-real body mirror carries the state (restarts and correction rewinds are bit-identical); `PtfmInit` moves and turns the body before the static solve, which balances the moment about the node.
- 14-, 15- and 18-column BODIES rows; aliases `CpldPin`/`VesselPinned`/`VesPin`. Standalone, in the C API, without inertias and under the linearisation probe the body is refused by name, and the Python deck validator mirrors the rules.
- MoorDyn-F's `inertialF` is accepted as `1` (CableDyn always returns the inertia of coupled bodies and rods); `0` and `2` are refused by name; `inertialF_rampT` is parsed and ignored.
- Start accelerations in OpenFAST (a result change, under Fixed): the module restores its state mirror after the output call at `t = 0`, which marked the accelerations of Free Rigid6 bodies and Free, Pinned and CoupledPinned rods as committed before they were solved, so their first step started from zero acceleration. The aggregate now solves them when it initialises and at a committed step-start transfer before the first step. An object in its static equilibrium changes at round-off (1e-12 m, 1e-6 deg over 10 s); one released out of balance (`bodyIC deck`) changes by the first step's velocity error, 0.02 m/s and 0.05 deg for a hanging Pinned rod, up to 0.6 m/s far from balance. The standalone driver is unchanged.

Gates, new `openfast_pinned_body`: a dry compound pendulum keeps the elliptic-integral period to 1.6e-4 at `dt = T/100` and the analytic pin reaction to 4e-16 of m g; under a constant node acceleration it swings about `-atan(a/g)` with the effective-gravity period; a body with a CoupledPinned rod's mass and inertia follows the rod to 2e-12; a symmetric mooring does not turn the body; snapshot/probe/restart are bit-identical; `PtfmInit` with the static start balances the moment to 3e-13; the shell's order (mirror Get/Set before the first step) against the direct order for pinned and free bodies and rods: identical now, up to 87 apart within 1 s before. Against the MoorDyn-F driver (`inertialF 1`) a pendulum with its line at the node agrees to 0.09 deg over a 120 deg swing (0.15 deg with the node surging).

## 2. CONTROL on Syrope and viscoelastic segments

Active line control (`CONTROL`, OpenFAST `CableDeltaL`/`CableDeltaLdot`) of a Syrope or a viscoelastic segment (`Es|Ed`, `Es|alphaMBL|vbeta`) stopped at initialisation. MoorDyn-F and MoorDyn-C keep each segment's slow-branch stretch as its state and read it at the new length; CableDyn now does the same (the committed slow strain is read at the present length; the running maximum of a Syrope segment is kept). An uncontrolled element reads its state as before, so no other deck changes.

- Syrope state solve (a result change, under Fixed): a line held at its running maximum under `False alpha_force_blend` stopped with "Syrope backward-Euler state solve did not converge" (the Newton difference quotient straddled the kink next to the top sample of the working curve), and a light rope (BA_s|BA_d = 1e4|1e3) failed where its residual changes sign between two adjacent reals. The solve now finishes by bisection there and returns the end with the smaller residual when the bracket cannot be split. Over 440,000 fuzzed states every solve that converged before is bit-identical; the 26 that failed now converge.

Gates, new `syrope_control` and `viscoelastic_control`, on a taut 100 m line with the fairlead segment paid out 0.5 m, hauled in to -1 m and paid back: the tension follows the rest curve of its load history to 2.5e-4 of T0 along the ramps and 6e-7 at rest (Syrope; working curve, OWC with the ratchet, then the working curve of the new maximum) and the static law `Es (D/L - 1)` to 1.7e-4 and 4e-9 (viscoelastic); after a 5 cm pay-out or 4 cm haul-in step the tension is MoorDyn's at the carried stretch to 6e-16 (carrying the strain instead is off by 0.4 to 4.6 % and fails); restarts in the ramp continue bit for bit; a Syrope segment paid out inside sub-steps matches plain steps of dt/4 to 9.5e-14 of the fairlead load. `syrope` gains the 26 fuzzed states and the stalled solve (they fail on the previous kernel).

## 3. MoorDyn-C Currents 2 and 5

The standalone routes read MoorDyn-C's time-varying depth profile (`Currents 2`, `current_profile_dynamic.txt`) and its grid in x, y, z and time (`Currents 5`, `current_profile_4d.txt`) as MoorDyn-C v2.7.1 does: resampled at the smallest time interval, repeating past the last sample, trilinear in space and held beyond the grid, no fluid acceleration. `deck_current_velocity` now takes the position and time, so every current consumer (EI = 0 lines, finite-EI cables, points, rods, bodies at their reference point, attachments) samples the field where and when it evaluates the fluid; the static start takes it at `t = 0`, the finite-EI solver through its turned and translated solve frame. The coupled and mixed aggregate routes refuse the files by name (the host supplies the water kinematics), and the point-system shells of the C API and OpenFAST, which have no clock, refuse a table that varies in time and apply a constant one.

- EI = 0 static current (a result change, under Fixed): the static start of an `EI = 0` line decided from the current sampled on the straight chord whether to carry it, so a current zero along the chord but not where the line sags (a depth profile, a grid) was left out; the start was solved in still water and the march drifted (192 N in 4 s on a 70 m rope with its ends at z = -20 m in 0.8 m/s below z = -32 m). The decision now looks at the field, and the static tangent takes the current's gradient along the line (without it that start did not converge). A later `current` row also discards the levels of an earlier profile row.

Gates, new `mdc_currents` and `mdc_currents_runs`: the current at 739 points and times is identical to MoorDyn-C v2.7.1's and within 4.4e-16 m/s of an independent Python evaluation; a constant Currents 2 table equals Currents 1 and a grid uniform in x and y equals Currents 2; on a 70 m rope across the flow the tension change of a time-varying and of a sheared current is within 0.8 % and 0.9 % of MoorDyn-C's; the static start in a sheared grid is an equilibrium of the march on the EI = 0, finite-EI and point-connected routes (1.4e-7 of the change the current makes); the off-chord decks hold their start to 0 N (EI = 0) and 1e-4 N (finite-EI) over 4 s, within 0.14 % of each other; `step_allocations_current_grid`: 20,000 grid velocity and gradient evaluations make no heap allocation.

## 4. Where the features meet

New gate `parity_integration`:
- A CoupledPinned body in a Currents 2 or 5 deck is refused on the coupled aggregate (with and without the host fluid field) for its current files, "the MoorDyn-C WaveKin 3/7 and Currents 1/2/5 files are not supported on the aggregate route (coupled runs take water kinematics from the host; ...)"; the deck without them initialises; the standalone driver refuses it for the body ("CoupledPinned/VesselPinned BODY requires a coupled host").
- CONTROL in the host's cross-flow (fields at every node, its steady current for the static start): a still 10 s run at a zero command keeps the start (node drift 1.4e-14 m viscoelastic, 6.0e-12 m Syrope); after a 0.3 m pay-out (viscoelastic) or a 0.2 m haul-in (Syrope) and a 40 s hold the line rests at the static start of the deck with that segment changed, to 1.1e-12 m and 3.8e-12 of the tension (viscoelastic) and 5.0e-7 m and 7.1e-7 (Syrope), with cross-flow deflections of 0.39 m and 0.08 m.
- ATTACHMENTS on a line restrained in torsion (#71) in a Currents 5 grid: the lazy wave with 25 modules and one turn of pretwist, turned by 30 deg and moved off the origin, in a grid sheared in x, y and z. The attachment drag fixed point after the polish samples the grid at the modules' global positions, and a still 10 s run keeps the start to 8.6e-8 of the fairlead tension and 0 in torque and twist (the grid moves the start by 4.5e-3 and 2.0e-2). Sampling at x = y = 0 or at the unturned solve-frame position instead leaves spreads of 1.6e-4 to 1.5e-3. A grid in depth only gives the start of the same Currents 1 profile to the output precision.

## Checks

Full ctest 328/328; pytest (`python/tests`, `tests`) 2124 passed, 114 skipped; ruff check and format clean; pre-commit clean; docs build with `-W` clean. Every example deck (53 of 53) is byte-identical to dev's. The result changes are the three named above: Free bodies and rods start from their solved accelerations in OpenFAST, the `EI = 0` static start carries an off-chord current, and the Syrope state solve converges where it stopped.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
SMI-Lab-Inha added a commit that referenced this pull request Oct 30, 2026
…analysis of lines restrained in torsion (#73)

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

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
…n a Fixed rod end, the routes combined (#74)

Squash title: `feat(torsion): torsion on the mixed deck, at one restrained end and on a Fixed rod end, the routes combined`

## What changed

Three more torsion route limits are lifted, then the torsion routes of 0.4.0 are combined. This
PR sits on the linearisation / control / modal PR; each of the first three features was built
and reviewed on its own branch from dev 66e3e83.

### Prescribed motion and torsion on the standalone mixed deck

A standalone deck that mixes `EI = 0` and finite-EI lines between `Fixed`/`Coupled`/`Vessel`
points runs on the coupled aggregate. It held its coupled ends and refused `motionFile`,
`vesselMotion` and every line restrained in torsion. The driver now marches the deck's
prescribed motion on the aggregate as the single-line cubic-Hermite route does (row 1 installed
before `t = 0`, a `TMax = 0` run writes the static state); a vessel turns the end-connection and
torsion frames of the cables on its points, and the `motionFile` roll column imposes the twist.
`vesselRAO` stays refused with the deck waves; `CableDyn_InitDeck`/`InitDeckAt` keep their
refusal.

### A line restrained in torsion at one end only

A finite-EI line whose `END CONNECTIONS` restrain its twist at one end only (the other end
`TorsStiffness Free`, or no row) was noted and solved as without the columns. Where its
`LINE TYPES` rows give `GJ` it is now solved in torsion: the free end carries no torque and
turns with the twist of the line, statically by `Twist<L> = −Σ (K/GJ)(l − L)` under `GJ|K`, and
in the dynamics with torsional waves that reflect at it. The `Torq`/`Twist` channels and range
columns work on such a line. A line that misses a rule (no `GJ`, two moving ends, the
configuration blend in a dynamic run, a restrained End A on a free, pinned or Coupled rod end or
a non-Rigid6 body) keeps the 6-column meaning, with a note naming the rule.

### A torsional END CONNECTION on a Fixed rod end

A line restrained in torsion may hang from an end of a `Fixed` rod (an I-tube or J-tube), whose
frame holds the End A torsion frame, with `Nx` in the rod's deck axes; the ends of a rod fixed to
a Rigid6 body roll with the body. `Rod<N>M` of a rod fixed to a body now includes the connection
moment of a cable clamped at its end (it read 0). Free, pinned and Coupled/Vessel rods refuse
the torsion by name, and so does `staggered bodyScheme` on a body or rod. A finite-EI line
written anchor first onto a rod end is turned around like the other anchor-first lines; a line
between two rods is refused as ending on a rod end.

### The routes combined

Each branch was built alone, so the one-end feature still left a line unsolved in torsion under
`ATTACHMENTS`, `CONTROL`, `nModes` and a rod End A. Those rules are lifted (natively and in the
Python validator):

- the torsion stage after the attachment polish (#71) handles a free end: it takes the stage's
  final mesh, which after the polish is `l0` (reading the pre-polish `l0_am`, which the polish
  has moved, crashed);
- the modal twist Hessian skips a free end, which it took for an elastic end of compliance 0 (a
  non-finite stiffness);
- a restrained End A may be on a `Fixed` rod end;
- the staggered body scheme refuses a torsional End A only when End A is restrained.

OpenFAST linearisation already took a line free at one end; its gate is added.
`ATTACHMENTS` on a line restrained at both ends already ran on the mixed route and on a rod end
(both build the cable through the same builder as the single-line route); their gates are added.

## Gates

Mixed deck (`mixed_route_torsion`, `step_allocations_motion_*`): vessel roll 20°, pitch 4°,
heave 1 m from rest on a sagging clamped line restrained in torsion, alone and beside a moving
chain: torque, twist and node positions agree to the printed digits (≤ 0.50 of a unit), end
tensions, inclination and End A bend moment within 6.6e-6 of their range; a 1 m surge with a 20°
roll column: ≤ 0.57 printed units, loads within 8.2e-6 (the Newton tolerance: with the
single-line controls every channel agrees to 0.36 printed units). A straight line rolled by 30°
gives `Twist1 = Pretwist − roll` to 5e-7° and `Torq = GJ Φ/L` to 4.7e-6 N·m. No heap allocation
per step.

One restrained end (`torsion_one_end`, `step_allocations_torsion_one_end`): a straight line held
rigidly at one end rings at the clamped–free frequencies `(2n − 1)π/(2L) √(GJ/Irn)` (3e-4, 3e-3);
a roll of the restrained end gives the continuum's free-end turn `A/cos kL` and reaction
`GJ A k tan kL` to 0.5 % below and above the first mode; deck statics with `GJ|K` give
`Twist1 = −(K/GJ) dl` to 8.5e-9 and the tension `(EA − K²/GJ) ε` to 4.6e-9; the same on the
coupled aggregate under a platform roll.

Rod end (`rod_end_torsion`): two turns on an inclined Fixed J-tube give `GJ Φ/L` to 1.1e-9, the
held Coupled point's torque to the printed digits, `Rod1M = M_t a` to 1.1e-8; on a rod fixed to a
rolling Rigid6 body the torque follows `GJ (Φ − θ)/L` to 4.1e-11 and `Rod1M` carries it to
2.0e-7.

Routes combined (VALIDATION T-17; each of the first five fails on the code before the last
commit):

| Gate | Oracle | Measured |
|------|--------|----------|
| `torsion_one_end` T1: vertical `GJ\|K` cable with two clumps and a buoy (net 14.6, −9.1, 5.8 kN), free at End A, then at End B | `Twist1 = −(K/GJ)(H − L0)`; tensions from the module weights; mid-line twist from the piecewise tension | 8.5e-9; 2.9e-9; 3.9e-4 (first order in the mesh: 1.9e-4, 9.6e-5 at 80, 160 elements); no torque |
| T2: neutral modules on the rolled line (`kL = π/8`) | the continuum's free-end twist and end torques | 9e-4 |
| `control_torsion` O: `CONTROL` deck on the aggregate, free at the fairlead, then at the anchor, paid out 0.2 m | `Twist1 = −(K/GJ)(H − L(t))`; no torque; mean held tension `(EA − K²/GJ) ε` | 3.7e-11; 8.2e-11 of `K ε`; 1.2e-4 |
| `modal_torsion_deck` 3: the clamped line free at End B, then End A | clamped–free chain `2 √(GJ/Irn)/l0 sin((2n − 1)π/(4N))`; quarter-wave within `1 − sin x/x`; first shape `sin(π s/(2L))`; other modes = `TorsStiffness Free` | 8e-10; 6.4e-5 (first); 5e-10; exact |
| `rod_end_torsion` 4: J-tube line with `GJ\|K`, free at End B, then at the rod end | `Twist1 = −(K/GJ) dl`; the held Coupled point's | 8.5e-9; identical |
| `lin_torsion` O (shell recipe) and `openfast_lin_torsion.py` 3 (OpenFAST): the straight line free at End B, then at End A | clamped–free chain; quarter-wave within `x²/6`; roll stiffness 0 | 2e-14 (shell), 2.5e-13 (OpenFAST); 4.1e-5 (first); 0 (End B free: `C A⁻¹ B` cancels the feedthrough `GJ/l_e`) |
| `rod_end_torsion` 4: two turns, two clumps and a buoy on the J-tube line | the held Coupled point's torque and twist | identical |
| `mixed_route_torsion` 7: three buoyancy modules on the roll-column line | the single-line route | 1.15 printed units; loads 2.1e-5 of range |

Ablations: lifting the rules without the mesh fix crashes T1 (SIGSEGV); without the Hessian fix
the modal deck stops ("the stiffness or mass matrix is not finite").

## Changed results

- Lines restrained at one end with a `GJ` row now carry the twist in their dynamics: on a swaying
  lazy-wave cable with `GJ|K` the tensions move by up to 1.5e-4 (7e-8 in a planar heave). A line
  restrained at End A on a Rigid6 body joins the static body balance; bending-pinned there its
  body's static moment now balances (on a buoy `Body1My` −103.9 N·m to 1e-6, `FairTen1` 126885 to
  126857 N, `Body1Ry` 0.3004 to 0.2984°; the march then differs by up to 2.6 % at `dtM` 0.05 s);
  clamped there, by about 1e-7. OpenFAST checkpoints of such decks written before do not reload.
- `Rod<N>M` of a rod fixed to a body includes the connection moment of a cable clamped at its end.

## Combining the branches

The six commits are cherry-picked in order (mixed route, one end, rod end; each with its review
fix), then one integration commit. Conflicts:

- documentation, VALIDATION and the CHANGELOG: every entry kept; the scope paragraphs of
  `doc/driver_format.md`, `doc/capabilities.rst`, `doc/openfast.rst` and
  `doc/troubleshooting.rst` rewritten to the combined state (the C API rotating entry of #70,
  linearisation, control, modal, mixed deck, one end, rod end); the stale "torsion has no
  inertia" and "no torque–tension coupling" sentences are gone; the mixed deck's VALIDATION entry
  is T-16;
- the torsion message `TORSION_NEEDS_ORIENTATION` and its Python mirror: the C API's
  `InitDeck`/`InitDeckAt` only (the mixed deck now turns the frames);
- the deck driver's torsion stage: #71 split the notes into `torsion_note`, which now returns for
  a line free at one end (its note is the one-end state's, and no twist stage set the tolerance
  it reports); the shared roll-column check of the mixed route (`check_motion_roll_lines`) and
  its roll-column map take the one-end rule (`line_torsion_at_a`: a free End A takes no roll);
- `normalize_stock_endpoint_order` takes the line types (rod end) and is followed by
  `resolve_one_end_torsion` (one end); `test_step_allocations` dispatches `free`,
  `motion_roll` and `motion_vessel`;
- the Python validator's torsion check: the mixed-deck refusal removed, the one-end rules and the
  rod rules kept, the both-end ATTACHMENTS refusal of the rod branch's base dropped (#71 lifted
  it).

On #72 (rebase): the mixed route's `CD_Init_Deck_Aggregate` counts the host bodies with #72's
`CoupledPinned` ones, the aggregate takes both #72's start accelerations and the deck's
prescribed motion, the mixed deck still refuses MoorDyn-C `Currents 1`/`2`/`5`, and
`test_step_allocations` dispatches `current_grid` beside the torsion and motion gates. Every
current sample in the torsion code goes through `deck_current_velocity(opts, position, time,
...)`. `python/tests/test_native_model.py` is dev's (the identity-based handle-release test of
#72); the `gc.collect()` variants of the mixed-route and rod-end fixes are dropped, so those
two commit messages still name a change they no longer make.

## Checks

- Full ctest suite (339) passes; `pytest python/tests tests` (2126 passed, 121 skipped; the
  native parity tests with `CABLEDYN_TEST_DRIVER`: 221 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).

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
…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>
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