Skip to content

feat(capi): host rotations, torsion through the C API - #70

Merged
SMI-Lab-Inha merged 2 commits into
devfrom
feat/capi-torsion
Oct 30, 2026
Merged

SMI-Lab-Inha merged 2 commits into
devfrom
feat/capi-torsion

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

The C API moved line ends by translation only, so it refused every deck with a line
restrained in torsion and held a Rigid end connection on its deck direction. A host that turns
the bodies its Coupled points are fixed to now passes their rotations (C ABI 1 minor
extension 3, additive):

  • CableDyn_InitDeckRotating: CableDyn_InitDeckAt (or InitDeck with n_q0 = 0) whose
    handle takes the host's rotations and passes them, as orientation and angular velocity and
    acceleration, with every UpdateStates and Step on the aggregate route, as the coupled
    OpenFAST shell does. It accepts torsion decks; the rotations start at identity (the deck's
    axes at the static start).
  • CableDyn_UpdateRotations(dcm, omega, alpha, n_block): per coupled block, the
    global-to-body DCM (row-major, the OpenFAST mesh orientation) and the angular velocity and
    acceleration in global axes, kept until the next call. All or nothing: a handle without
    rotations, a wrong block count, a null pointer, a non-finite value or a DCM that is not
    proper orthogonal to 1e-8 is refused with the rotations unchanged. SaveState /
    RestoreState carry them with the model.
  • CableDyn_GetCoupledMoments: the moment each block applies to the host about the coupled
    point (a finite-EI line's torsional and bending reaction; zero for EI = 0 lines and the point
    route), on any initialised handle.

Python: CableDyn.init_deck_rotating, update_rotations, coupled_moments
(HOST_ROTATION_ABI_MINOR = 3). Docs: the C API reference (new guide step and reference
section), the Python API, and the pages that said the C API refuses torsion; the guard
message names the new call.

Gates: c_api_host_rotation (C, through the shared library) on the straight neutral torsion
line of test_coupled_torsion: InitDeck refuses it naming CableDyn_InitDeckRotating; a
20 deg feedthrough roll twists the end element alone (Twist1 = -20 deg, the coupled moment
GJ phi / l_e about the line axis, resisting the roll); a 60 deg/s roll gives Twist1 = -phi
(2e-15 deg) and the quasi-static torque GJ phi / L at both ends and as the coupled moment
(3e-6 N m); a restore after other rotations steps bit-identically; the rejections leave the
handle stepping bit-identically to one that never saw them; the point route takes rotations
and returns zero moments. python/tests/test_host_rotation.py mirrors them. Full suite
passes; examples unchanged (no code path of a deck run changed).

The C API moved line ends by translation only, so it refused every deck
with a line restrained in torsion and held a Rigid end connection on its
deck direction. C ABI 1 minor extension 3 adds a host that turns its
coupled points:

- CableDyn_InitDeckRotating: InitDeckAt whose handle passes the host's
  rotations with every update and step on the aggregate route, as the
  coupled OpenFAST shell does; it accepts torsion decks.
- CableDyn_UpdateRotations: per coupled block the global-to-body DCM and
  the angular velocity and acceleration, kept until the next call and
  carried by SaveState/RestoreState; all or nothing.
- CableDyn_GetCoupledMoments: the moment each block applies to the host.

Python: CableDyn.init_deck_rotating, update_rotations, coupled_moments.

New gate c_api_host_rotation (and python test_host_rotation): on a
straight torsion line a 60 deg/s roll gives Twist1 = -phi and the
quasi-static torque GJ phi / L as the coupled moment (3e-6 N m), a 20 deg
feedthrough roll twists the end element alone, a restore steps
bit-identically, rejected rotations leave the handle unchanged.

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-30T07:02:05.500235Z 0c458f2 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 Oct 30, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35517398 | 📁 Comparing 0c458f2 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. Keep it up!

Reviewed commit: 96b93f8adc

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

Use the cabledyn import and wrap a long line in test_host_rotation.

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. Can't wait for the next one!

Reviewed commit: 0c458f217a

ℹ️ 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 27b7738 into dev Oct 30, 2026
21 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/capi-torsion branch October 30, 2026 08:05
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>
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