Repository navigation
feat(capi): host rotations, torsion through the C API - #70
Conversation
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>
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Codex Review: Didn't find any major issues. Keep it up! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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>
|
@codex review |
|
Codex Review: Didn't find any major issues. Can't wait for the next one! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
…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>
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(orInitDeckwithn_q0 = 0) whosehandle takes the host's rotations and passes them, as orientation and angular velocity and
acceleration, with every
UpdateStatesandStepon the aggregate route, as the coupledOpenFAST 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, theglobal-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/RestoreStatecarry them with the model.CableDyn_GetCoupledMoments: the moment each block applies to the host about the coupledpoint (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 referencesection), 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 torsionline of
test_coupled_torsion:InitDeckrefuses it namingCableDyn_InitDeckRotating; a20 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.pymirrors them. Full suitepasses; examples unchanged (no code path of a deck run changed).