Repository navigation
feat(torsion): OpenFAST linearisation, active line control and modal analysis of lines restrained in torsion - #73
Conversation
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>
|
@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. Breezy! 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". |
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>
|
@codex review |
|
Codex Review: Didn't find any major issues. Swish! 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". |
…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>
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>
…, 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>
Squash title:
feat(torsion): OpenFAST linearisation, active line control and modal analysis of lines restrained in torsionWhat 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 frameof the host-driven end,
CD_HFMF_Set_Twist_Frame_Ratesgives that frame the point's angularvelocity and acceleration (so the torsional damping and the held end section's inertia get
their
BandDcolumns), and the fairlead moment carries the torque. Under linearisation thecoupled-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
Linearizekeeps 0.1 rad. ARigidbending 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/landBt/l, the torque–tension coupling(K/GJ)(l − l0), the lumped polarinertia
Irn l0/2, and a-ζtorsional damping, which now keeps itsζand is re-resolved atthe 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 committedtorque, 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.outaddsPolarShareand
dTwistwhen a line carries twist.Gates
lin_torsion(the shell'slin_evalrecipe on the aggregate) andvalidation/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 thelumped 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)isGJ/Lto 1.5e-14, against thefeedthrough
GJ/l_ealone (50 times stiffer); a 90° twisted lazy wave matches the deck'sstatic 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 carriesGJ Φ/L(t) + K (H − L)/Lto1.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
CONTROLdeck on the aggregate) are bit-identical.modal_torsion,modal_torsion_deck: clamped 10 m line, torsional modes are the lumpedchain'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/Lmatch the clamped Greenhill cable to3.2e-7; eliminating the angles gives back the condensed static tangent to 1.4e-16.
Changed results
END CONNECTIONSorATTACHMENTSandnModes(no shippedexample): a clamped lazy wave's first twelve frequencies rise by 0.1 to 3.8 %, those of
lazy_wave_buoyancy_modules.datwithnModesdrop by 13 to 29 % (the ends and the modules'masses were ignored).
Linearize = Truethe rotation columns of a deck with a hang-off spring move by up to0.17 % (the 1e-4 rad rotation step).
(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 deckdriver's torsion stage, where #71 renamed the stage's meshes (
ld,lf) and control added thekept
ζof a-ζdamping: the merged stage resolves the damping onlf. The control branch'sextra 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 arethe 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.pyis dev's(the identity-based handle-release test of #72); the control fix's
gc.collect()variant isdropped, so that commit's message still names a change it no longer makes.
Checks
pytest python/tests tests(2124 passed, 114 skipped; thenative parity tests with
CABLEDYN_TEST_DRIVER: 212 passed); ruff check/format clean;pre-commit clean; the docs build with
-Wclean.