Repository navigation
CableDyn 0.4.0 - #86
Conversation
feat(stiffeners): model tapered bend stiffeners on finite-EI lines A STIFFENERS table describes a polyurethane bend stiffener over End A or End B of a finite-EI line as conical segments from the root outward (length, outer diameter at each side, bore, modulus, density). The sleeve bends with the cable: every element it covers takes the compliance average of EI_cable + E pi/64 (OD^4 - ID^4) over its length (an element of an EI = 0 section only when the sleeve covers it completely), the sleeve's mean mass, and one diameter, that of the displaced area of cable and solid sleeve, for its buoyancy, added mass and drag, as a line type has. Elements it does not reach keep their line type's values exactly, so decks without stiffeners are unchanged. The overlay sits in the two routines every finite-EI route builds its element properties from, so it applies standalone, on the OpenFAST aggregate, through the C API and in Python. Under a stiffener BendMom<L>N<J> (and the BendMoment columns) report the cable's own moment, the line type's EI times the curvature; the new StfMom<L>N<J> reports the sleeve's share. FairDefl<L>/AnchDefl<L> give the angle between the end force and the direction a held END CONNECTIONS row declares, the stiffener's load case with the end tension. Initialisation notes name a stiffener spanning fewer than 10 elements and one at a pinned end. The Python reader and builder mirror the native table and channel rules. On a hang-off clamped through a 5 m stiffener (16 times the cable's EI at the root), the curvature follows OrcaFlex 11.6d with its stiffener as a line attachment within 0.74 % of the root value, and an independent collocation solution of the planar extensible elastica within 0.74 % (cable moment), 0.18 % (section moment) and 0.003 deg (deflection). Example lazy_wave_bend_stiffener.dat.
* fix(statics): converge weightless taut finite-EI lines The Hermite static solve judges convergence by the residual relative to a force scale: the line's total submerged weight, with a 1 N floor. A weightless or near-neutral taut line (a neutrally buoyant cable, a tendon) carries tension far above its weight, and the round-off of its axial forces EA (|r'| - 1) then lies far above tol x scale: a neutrally buoyant 60 m cable at 61 kN stopped at ||R|| 1e-4 N against a 1e-6 N test and failed every static route, even lying straight along its chord. A taut line, its ends farther apart than its length L, carries at least (chord/L - 1) times its series axial stiffness whatever its weight; the force scale now includes that tension. A slack line (chord <= L) keeps its weight scale, so every such solve is unchanged: all 99 example output files are identical to dev. The weightless cable clamped 30 deg off its chord now converges and follows an independent solution of the planar elastica within 0.14 % (root moment) and 0.07 % (end tension). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(statics): use the chord tension only with both ends held The taut-chord tension is a lower bound on the line's tension only while the solve holds both end positions. With an end free to move (a cantilever) the seed's chord implies no tension at equilibrium, and an overstretched seed set a force scale that the solve never revised: a cantilever with EA 1e12 N seeded 1 % long took a 1e10 N scale and read its 1000 N weight as converged before bending. The bound now applies only when the end positions are both fixed; such a cantilever reaches the beam deflection w L^4/(8 EI) from either seed. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(statics): skip the chord tension with an EA = 0 element EA = 0 is a valid element input, and the series compliance sum(l0/EA) divided by zero on a held taut seed. An element without axial stiffness leaves the series stiffness, and so the tension bound, at zero: the bound is skipped. The static test checks that no division by zero is raised. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> --------- Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…rce (#52) A finite-EI end resting on the seabed left the downward part of its end force to the floor (force(3) = MAX(force(3), 0)), a rule from before bathymetry: on a flat floor that part is the end node's weight, but on a slope it also holds the line's own pull. A cable laid down a 10 deg slope from its anchor reported AnchTen 1.5 % low (cos 10 deg of the tension) and AnchFz = Point<P>Fz = 0 instead of -1.5 kN. The floor now takes the part of the end force pressing into it along its upward normal, the old rule on a flat floor, so the anchor keeps the line's along-floor pull. On a frictional seabed it also holds the along-floor part of the end node's own weight, up to mu times that normal load. On the 10 deg slope the anchor force runs 10.00 deg below horizontal and AnchTen continues the line tension to 0.1 N. Flat seabeds are unchanged: all 52 example decks write identical outputs. The cross-slope as-laid friction test now bounds the lateral anchor force in the plane of the floor (203 N, below the 415 N of a reference without the sink offset): the pull of the run sunk into the penalty seabed, along the slope's normal, goes to the floor instead of adding its lateral part. Found by the statics robustness campaign (sloped-seabed lazy wave, BALANCE 6 %). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
) OpenFAST's native <root>.CD.out wrote channel values as ES15.6E2. A value that needs a three-digit exponent, below 1e-99 or from 1e100 on, then fills the field with asterisks, and the round-off noise of a zero component reaches that range: on the IEA-15 mixed deck the y position and tangent azimuth channels of the finite-EI cable, which lies in the x-z plane, printed 30 such fields in 10 s (e.g. 2.9e-113, 2.9e-104), and a coupled campaign with the 0.3.0 release counted 28,818 in 31 runs. Every reader of the file failed or misread it. Channel values are now written with a three-digit exponent at the same field width, ES15.6E3, through two shared formats in CableDyn_Conventions: CD_NATIVE_CHANNEL_FMT for .CD.out and the OpenFAST module driver, CD_CHANNEL_FMT (ES15.7E3, as every other standalone writer) for the mixed EI = 0 + finite-EI .out. That writer, the module driver, the modal results and the static driver's mesh file stated no exponent width, so a three-digit exponent dropped its letter (1.0000000-120), which Python's float() rejects; they get E3 too. test_output_formats writes zero, 1e-120, -3e150, the 1e+-100 edges, a subnormal, HUGE and ordinary values through both formats: each field is TAB plus a fixed width with no asterisks, a mantissa, E, a sign and three digits, and reads back to its printed precision (zero exactly). With the old formats it fails on exactly the reported fields. On the mixed deck the .CD.out now has no asterisk field and numpy reads it whole. The outputs reference and the OpenFAST tutorial show the format. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…54) openfast -restart did not continue a run with a finite-EI cable bit for bit. The checkpoint rebuild moves each coupled end to the restored input mesh, the glue's input at the restart time, and the cable's mirror held only its free DOFs: its fairlead kept the restored mesh's bits instead of the boundary the uninterrupted run committed (with NumCrctn = 0 that run stepped with the extrapolated input). The EI=0 lines already reload their committed coupled motion. On the IEA-15 mixed deck restarted at 6 s, the lazy-wave cable's .CD.out channels drifted by up to 9.4e-7 (relative) within 4 s, while the chain-only deck stayed exact. The cable mirror gains a boundary block, reloaded after the move: [q; v; a] of the held DOFs (the held accelerations move here from the force-blend block, so the configuration blend restores them too), the end-connection directions and the parent frame (orientation, angular velocity and acceleration). Unpacking checks the orientation before it writes anything. The parent frame of a torsion cable now reloads as committed instead of being re-derived from its end frames. With the fix every .CD.out and OpenFAST row from 6 s to 10 s matches the uninterrupted run bit for bit at dtM = DT and 2 DT, NumCrctn 0 and 1, and with a rigid fairlead END CONNECTIONS row (before: 3 to 6 rows of the cable's channels differed in each). The mirror test covers the new layout, its round trip and the orientation check. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn v2's optional LINE TYPES columns `Cl` or `Cl dF cF` now switch on cross-flow vortex-induced vibration of `EI = 0` lines in the standalone driver: the synchronisation model of Thorsen et al. (2014, 2016) in the form MoorDyn implements it. Model. Each interior node carries a shedding phase phi and the lift 1/4 rho d Cl (l_i + l_i+1) U cos(phi) q x v_n (wetted fraction included). The phase rate is 2 pi (cF + dF sin(phi_y - phi)) U/d, with phi_y the phase of the node's cross-flow motion from its running-RMS velocity and acceleration. The RMS window is `VIVrmsWindow` seconds, by default 500 steps of `dtM` as in MoorDyn, and the phases start at 2 pi i/N from End A. The static equilibrium carries no lift. In the implicit step the phase is explicit. The step's lift takes the phase predicted at t_n+1 from the step-start rate (the generalised-alpha level under the configuration blend), and the commit is the Heun update with the rate at the converged end state. The lift's position and velocity derivatives enter the tangent. The phase sample and the lift use the node kinematics averaged with the neighbours, (x_i-1 + 2 x_i + x_i+1)/4. With the node's own kinematics, a step that resolves the mesh zig-zag mode (dtM 2e-3 s or less on the benchmark) let the synchronisation loop pump that mode until the line lost lock-in; the average removes the zig-zag mode exactly and keeps a resolved mode of wavenumber k to cos^2(k l0/2). Validation against MoorDyn-F (OpenFAST v5 `moordyn_driver`, dtM 5e-4 s) on a taut 100 m line in a uniform cross current, U = 0.06-0.42 m/s: - mode-1 and mode-3 lock-in (U <= 0.18 and >= 0.36 m/s): mid-span A/D within 1.2 % and the response frequency within one spectral bin, e.g. U 0.15 m/s: 0.662 against 0.663 at 0.293 Hz; - the same response at every dtM from 5e-4 to 1e-2 s; - at U 0.21-0.33 m/s the two codes settle on different modes (MoorDyn-F mode 1, CableDyn mode 2). Each is robust to the initial state, the step and the phase origin in its own code. VALIDATION.md records this as a scoped result. Scope. The coupled OpenFAST and FAST.Farm routes and mixed `EI = 0` / finite-EI decks refuse `Cl > 0` by name (they neither checkpoint the phase nor feed it the host's fluid field yet), as do finite-EI and Syrope line types, and an EI = 0 deck without water (the lift acts with the line's Morison drag). In-line VIV is not modelled. State. The phases and running mean squares are part of the committed line state (commit_state_copy): the rotation-resolved sub-steps, the recovery rungs, the line-system rollback and the snapshots save and restore them with the kinematics. Python. `DeckFile` reads the 11- and 13-column rows with MoorDyn's checks and `DeckModel` keeps `cl`, `df` and `cf` through load and save. `DeckFile` refuses `Cl > 0` where the native code does, and the builder refuses VIV columns on a 14-column finite-EI row. Tests: `viv_kernels` (lift, phase rate, RMS update, Jacobians against central differences), `viv_lockin` (the benchmark at dtM 0.01 and 0.002 s against the MoorDyn-F reference), a `test_model` case that forces sub-steps on a VIV line (a repeated sub-stepped pass and the fallback to the plain step stay bit-identical), and the deck-file and builder tests. Full suite on this branch: 304/304 ctest, 2081 pytest; the examples are unchanged. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The cross-flow VIV synchronisation model of #55 now runs on finite-EI (cubic-Hermite) cables in the standalone driver: the same LINE TYPES columns `Cl` or `Cl dF cF` on an `EI > 0` type. Model. The lift is a distributed load per unit deformed length, f = 1/2 rho d Cl cos(phi) U (t x v_r), with t the unit tangent of the centreline, v_r the relative flow and cos(phi) interpolated linearly between the element's end nodes. It is integrated against the Hermite shape functions at the drag element's three Gauss points (a point above the surface carries none), with its exact position and velocity Jacobians in the tangent (the residual path and the parallel tangent-only path). Each node carries a phase, driven by the node's cross-flow motion along its own tangent, the slope degrees of freedom; d, cF and dF at a node are the length-weighted averages over its lifting elements, and the phases start at 2 pi i/N from End A. As on EI = 0 lines the phase is explicit: the step's evaluations take the phase predicted from the step-start rate (at t_n+1 under the force blend, whose committed force F_n keeps phi_n; at the generalised-alpha level under the configuration blend), and the commit is the Heun update. With VIV the converged force is not cached as the next step's F_n (it took the predicted phase). No smoothing is needed: the Hermite tangent and the integrated lift leave no mesh-scale mode for the synchronisation loop to pump. State. The phases and running mean squares are saved and restored with the kinematics by the recovering step, the snapshot and the deallocation; every evaluation outside a step (end forces, node recovery, the held-field update, the committed acceleration) takes the committed phase. The phase commit cannot fail, so a step is never left half committed: a node whose end tangent is degenerate takes the step-start rate over the step. Installing or removing VIV refreshes the committed acceleration with the lift (the previous VIV state and acceleration come back if that solve fails), and a later drag reconfiguration carries the lift scale and the shedding diameter with it. An internal wave family (Set_Waves) is refused on a VIV cable; deck waves and current reach the standalone Hermite march as its held fluid field, which the phase follows. Routes. `build_one_hermite_cable` installs VIV only for the standalone finite-EI march. A finite-EI line with two moving ends (compatibility route), a finite-EI line beside bodies, rods or free points (multibody march), the single-cable `CD_Init_Deck_HermiteCable` entry and the aggregate (coupled, mixed) route refuse `Cl > 0` by name; `DeckFile` mirrors the refusals. Validation (VALIDATION.md L2-VIV-EI, gated in `viv_lockin` and `hermite_viv`): - the #55 benchmark line as a finite-EI cable with EI = 1 N m^2: mid/quarter-span A/D 0.662/0.421 against the EI = 0 line's 0.663/0.421 at the same frequency, unchanged at dtM 1e-2, 2e-3 and 5e-4 s; - a bending-stiff, neutrally buoyant cable (EA 5e9 N, EI 5e7 N m^2, beta = pi^2 EI/(T L^2) ~ 1) against the EI = 0 string of equal first-mode frequency, tension T(1 + beta): the same mode-1 lock-in (A/D within 2.5 %, same frequency) for U <= 0.24 m/s; for U >= 0.27 m/s the string jumps to mode 2 while the cable stays in mode 1, its bending having raised f2/f1 to about 3.15; - a lazy-wave power cable (examples/lazy_wave_buoyancy_smeared.dat with Cl 0.8, 0.5 m/s current) shows out-of-plane VIV at 0.47 Hz with the fairlead tension oscillating at twice that frequency, and stays still without the lift. Tests: `hermite_viv` (the setter's refusals, the acceleration refresh, the drag reconfiguration, the lock-in with and without lift, a mid-run snapshot replaying the state and phase bit for bit, the recovering step equal to the plain step), `viv_kernels` section 7 (the per-length lift and its flow and tangent Jacobians against central differences), `viv_lockin` (the two comparisons above, the EI = 1 cable at dtM 0.01 and 0.002 s), and the deck-file tests. Full suite: 305/305 ctest, 2082 pytest; every shipped example's output is byte-identical to dev. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…m 0 (#57) CableDyn numbers a line's nodes from 1 at End A. MoorDyn-C and MoorDyn-F number them from 0 at End A. CableDyn also runs a line written anchor-first from its fairlead. So a MoorDyn deck's `L<L>N<J>` channels name a different node in CableDyn, with no warning. Example: on a 100 m line with 50 segments, written in CableDyn's order, `L1N12PZ` reads the node at 22 m in CableDyn and the node at 24 m in MoorDyn. Confirmed from the t = 0 sag shape, against both MoorDyn codes. The numbering itself is unchanged; existing CableDyn decks and outputs are not affected. Changes: - **Notice:** a run prints one note when its OUTPUTS name a line node, or when a LINES `Outputs` flag writes the per-line node files. The note gives the correspondence: `N<J>` here is MoorDyn's `N<J-1>`, or `N<NumSegs+1-J>` on a line written anchor-first. - Channels covered: `L<L>N<J>…`, `Ten`, `Curv`, `BendMom`, `StfMom`, `Torq`, `Twist<L>N<J>`. - Printed by the standalone driver and by OpenFAST (`WrScr`, for the deck OUTPUTS of the `.CD.out` file). - Rod nodes already use MoorDyn's numbering (0 = End A) and are left alone. - **Docs:** - `outputs.rst` states the numbering and both correspondences; - the `migrating.rst` "Node identity" row replaces "MoorDyn node numbers are not reproduced"; - `options.rst` links the `N0` rejection to it; - CHANGELOG entry. - **Test:** `ei0_slack_dynamics` checks that a run with a LINES `p` flag prints the note and a run without node outputs does not. Checks: - ctest 305/305 and pytest against the built driver (2092 passed); - fprettify clean; docs build with `-W`; - OpenFAST built with this branch's CableDyn module, so `CableDyn_OF.f90` compiles. No OpenFAST run was made: no shipped OpenFAST example asks for line-node channels, and the OpenFAST side calls the same check the standalone test covers. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…linear (#58) The run banner said "Geometrically nonlinear cable & mooring dynamics for floating wind". That undersells the formulation. Both line elements use the exact large-deformation axial strain (ε = |r′| − 1) and curvature (κ = |r′ × r″| / |r′|³), never linearised. This PR changes every place that describes CableDyn so it matches the repository description: "geometrically exact finite-element statics and dynamics of mooring lines and dynamic power cables (for floating offshore wind)". Changes: - **Run banner** (`CableDyn_Banner.f90`), lines 3–4. Width is unchanged and each line is at most 68 characters. The copies in `installation.rst` and `quickstart.rst` are updated. - **OpenFAST identity line** (`CableDyn_OF.f90`, `WrScr`), and its copy in `tutorial_openfast.rst`. - **README** intro and the **manual landing page** (`index.rst`). Both now state that the strain and curvature are the exact measures; the manual links to `theory`. - **Citation:** - the `CITATION.cff` title and abstract, and the `citing.rst` reference and BibTeX; - the BibTeX key now names the version it cites (`CableDyn_0_1_1` → `CableDyn_0_3_0`). - **Package metadata:** the CMake project `DESCRIPTION`, the description in both `pyproject.toml` files, and the `cabledyn` package docstring. - CHANGELOG entry. Wording only. No numerics change. Checks: - ctest 305/305 and pytest against the built driver (2092 passed); - docs build with `-W`; ruff clean; - OpenFAST built with this branch's CableDyn module, so the `CableDyn_OF.f90` line compiles. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…h continuous (#59) * fix(statics): solve light slack finite-EI lines; keep a line's azimuth continuous A finite-EI line longer than its span with no net weight, or too little for its bending stiffness, failed its static solve. With no catenary to start from, both routes reached the compressed straight strut (a saddle) or stalled at the round-off of the axial forces, EA eps |r|/h, which a weightless line's unit force scale puts above the tolerance (0.001 N/m on a 120 m line with EI 1e4 failed; 0.01 N/m passed). When both routes fail on a slack, planar line in still water with |w| < 100 EI/L^3, the line is now solved with that auxiliary weight (of the sign of its net weight, downward for a weightless line) and carried back to its own weight by a continuation in the weight, held in the vertical plane of its chord and accepting the round-off floor of the axial forces; the result is audited and stability-checked as the routes' are. A weightless line bows as the pinned-pinned elastica: end thrust 7.0563 N and mid-span bow 17.9399 m against 7.0564 N and 17.9399 m exact. Nothing in the deck chooses the side of its bow, so it is solved bowed downward and a note says so; with its ends one above the other it is still refused, now by that cause. The tangent azimuth of a line along +X jumped between 0 and about 360 from one output row to the next as the line swayed a fraction of a degree to either side, or by the sign of a round-off component: on the IEA-15 mixed OpenFAST deck 315 to 485 of 801 rows of each cable azimuth channel read 359.9x. A line whose static chord heads within 45 deg of +X now reports its azimuths in (-180, 180], every other line in [0, 360) as before, so the cut of a line's range lies at least 45 deg from its heading; a round-off component across the cut reads on its included side. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(statics): keep a Fixed End A in recursive builds; return the weightless-bow note The recursive builds of a finite-EI line (weight continuation, coarse current pass, still-water references) ran without the standalone controls, so they refused a Fixed End A that the standalone build of the same line admits; the weight continuation of a weightless line with both ends Fixed (legal in a deck with dynamic points) failed on it. They now inherit the outer build's allowance (fixed_fairlead). All 52 examples are unchanged. The weightless-bow note was reported before the build cleared its note buffer, so the coupled aggregate, which prints nothing itself, never received it. It is now reported with the other initialisation notes. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> --------- Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn-F runs its VIV model inside OpenFAST, but CableDyn refused `Cl > 0` on the aggregate route. That route serves OpenFAST, FAST.Farm and the standalone runner of a mixed `EI = 0` / finite-EI deck. This PR lifts the refusal on all three.
## Changes
- **Lift on the aggregate.** The aggregate installs the lift on its finite-EI cables (`install_viv`), as the standalone Hermite march does. Its `EI = 0` lines already built it through `init_one_model`. The phase follows the host's fluid field (`CD_AGG_SetFluidFields`).
- **Correction rewinds.** The in-memory snapshot/restore already carried the VIV state on both line kinds, so OpenFAST's correction iterations needed no change.
- **OpenFAST checkpoint.** The state mirror (`x%states`) now carries the VIV state: the phase and the two running mean squares per node, then the averaging time.
- An `EI = 0` line ends its span with this block. The block is sized by `CD_System_Line_VIV_MirrorSize` and goes through `CD_Get/Set_System_Line_VIV_State`, which sit over the model-level `CD_Get/Set_Model_VIV_State`.
- A cable's mirror carries the same block before its torsion block (`CD_HFMF_VIVMirrorSize`).
- A reload also sets the rollback and recovery copies of the state, and the in-step phase.
- **Linearisation.** The variable registration covers the new blocks. Linearisation stays quasi-static, with no continuous states.
- **Averaging window.** Without `VIVrmsWindow`, both line kinds average over MoorDyn's 500 steps of the deck `dtM`, also when OpenFAST steps CableDyn at a `dtM` adjusted to its `DT`. With no deck `dtM`, they average over 500 coupling steps.
- **Single-cable entry.** `CD_Init_Deck_HermiteCable` applies no fluid field, so it still refuses `Cl > 0`. Its message now points to the aggregate.
- **Python.** `DeckFile` drops the coupled/mixed refusal. On the coupled route it does not ask for water in the deck, since the host supplies it.
- **Docs.** capabilities, coupling, theory, migrating, troubleshooting and CHANGELOG.
## Checks
- **New `viv_coupled` test** (22 s). An `EI = 0` riser and a finite-EI cable (EI 1 N·m²) sit side by side on the coupled aggregate in a 0.15 m/s host current: each 100 m long at 50 kN, 50 segments.
- Lock-in over 60–120 s:
| | A/D | Frequency |
|---|---|---|
| Riser | 0.6645 | 0.292 Hz |
| Cable | 0.6646 | 0.292 Hz |
| MoorDyn-F | 0.662 | 0.293 Hz |
| Standalone CableDyn | 0.665 | |
- With `Cl = 0` both lines stay still (A/D below 4e-5).
- Checkpoint restart, using the shell's rebuild recipe: it continues bit for bit. A rebuild without the VIV reload diverges.
- A correction rewind repeats bit for bit.
- Averaging window: deck `dtM` 0.001 s at a 0.01 s coupling step gives both line kinds 0.5 s; with no deck `dtM`, both get 5 s.
- **OpenFAST 5 with `CompMooring = 5`.** This ran on the IEA-15 MW mixed deck with `Cl 0.8` on the lazy-wave cable, a SeaState 0.5 m/s current across it, no waves, 60 s. It was checkpointed at 30 s and restarted.
- The restarted CableDyn and OpenFAST outputs are identical to the uninterrupted run at every row (max difference 0).
- The lift raises the cable's lateral sway by 4–10 % along its span over the `Cl = 0` run.
- **Test suite:** ctest 308/308; Python 793 passed.
- **Examples:** all 52 shipped examples are unchanged. None uses `Cl > 0` on these routes.
- **Format:** fprettify is clean.
Remaining VIV refusals: a finite-EI line beside bodies, rods or free points (next PR), and a finite-EI line with two moving ends (the Cosserat compatibility element, which has no VIV).
Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…61) A finite-EI cable runs on the multibody march when its deck has a Rigid6 body or rod, or Free or Connect points. That march refused `Cl > 0`, so VIV of such a cable was not possible. This PR lifts the refusal. ## Changes - **Lift on the multibody march.** Its cable builds now pass `install_viv`, as the Hermite march's do. Both builds are covered: clamped and pinned. - **Fluid field.** The march already refreshes each cable's held fluid field every step, so the phase sees the deck's waves and current. - **Re-steps.** Each outer iteration and each step halving re-steps the cables from `CD_HFMF_Snapshot` / `CD_HFMF_Restore`. That pair already carries the VIV phase and running mean squares, so a re-step does not advance the phase twice. - **Python.** `DeckFile` drops the matching refusal. A finite-EI line with two moving ends still refuses `Cl > 0`: that is the Cosserat compatibility element, which has no VIV. - **Docs.** capabilities, theory, troubleshooting and CHANGELOG. ## Checks - **`viv_lockin`**, new case: the same 100 m finite-EI cable (EI 1 N·m², 0.15 m/s current) as the Hermite case, with End A Fixed. A 5 t Connect point hung on two chains 300 m away puts the deck on the multibody march. | Route | Mid / quarter A/D | Frequency | |---|---|---| | Multibody march | 0.662 / 0.421 | 0.300 Hz | | Hermite march | 0.662 / 0.421 | 0.300 Hz | The gate is within 1 % and one frequency bin. - **A cable on a moving buoy.** `buoy_clamped_cable` (a clamped cable on a moored Rigid6 buoy) with `Cl 0.8`, in current, ran 30 s on the monolithic body step: at most 3 outer iterations, no step halvings. - **Python:** `buoy_clamped_cable` with `Cl 0.8` passes the validator; it was refused before. - **Test suite:** ctest all green; Python 2064 passed. - **Examples:** all 52 shipped examples byte-identical to dev (none uses `Cl > 0` on the multibody march). - **Format:** fprettify and ruff are clean. Remaining VIV refusal: a finite-EI line with two moving ends. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn's line flag `V` writes the cross-flow VIV lift at each node of a line. CableDyn rejected the flag, so the lift was not reachable as an output. This PR adds it. ## Changes - **New file `<root>.Line<L>.V.out`.** The LINES `Outputs` flag `V` writes the lift `(x, y, z)` at every node, End A to End B, at the same times as `.out`. - **Routes.** The file is written on the dynamic runs of every standalone route that carries VIV: - `EI = 0` models and the point system; - Rigid6 bodies and rods; - the multibody march and the Hermite march. - **`EI = 0` lines.** The lift comes from `CD_Get_Model_VIV_Lift`, at the committed state. The end nodes carry none, as in MoorDyn. - **Finite-EI lines.** `CD_HermiteCable_Dyn_VIV_Node_Lift` sums the translational part of each element's consistent lift load at its two nodes. The writer turns it from the cable's solve frame into the global frame. - **Case.** The flag is upper case, as in MoorDyn. Its lower-case `v` (node velocities) is not written and stays a parse error, with a message that says so. - **Refusals.** - The mixed `EI = 0` / finite-EI runner refuses `V` along with `p` and `t`. - The two-moving-end finite-EI route has no VIV and refuses the flag by name. - The Python deck validator follows both refusals. It also gains the missing native refusal of `Cl > 0` on that route. - **Docs:** outputs, migrating and CHANGELOG. ## Checks - **`viv_lockin`.** It reads the V files of the `EI = 0` line, the finite-EI cable on the Hermite march and the same cable on the multibody march, all in lock-in: - the `EI = 0` line's end nodes carry no lift; - at the interior nodes, the standard deviation of the cross-flow lift over 60–120 s agrees within 1 % across all three; - the exception is each end node's neighbour, where the `EI = 0` line's end half-segments carry no lift while a cable element shares its lift between its two nodes. - **New `msg_line_flag_velocity` test:** lower-case `v` fails with a message that names `V`. - **Python:** the flag is accepted and case-checked. It is refused on the mixed route, and on a farm-shared finite-EI cable (Turbine1 to Turbine2), where `Cl > 0` is refused too. The native driver gives the same messages on that deck. - **Test suite:** ctest 309/309; Python 2027 passed. - **Examples:** all 52 shipped examples byte-identical to dev. - **Format:** fprettify and ruff are clean. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…riser (#63) MoorDyn seeds each node's VIV shedding phase at 2π i/N, with node i counted from the line's AttachA. CableDyn counted from its own End A. For two kinds of line that gives a different start: - **A line written anchor first** (the usual MoorDyn row order). The reader turns it around, so CableDyn's node 1 is MoorDyn's node N. - **A finite-EI mesh the static solve refined.** The node index no longer names the deck nodes. ## Changes - **`CD_Deck_VIV_Phase_Seed`** gives MoorDyn's seed node by node: - counted from the deck's End A; - held at the deck nodes of a refined mesh; - interpolated in unstretched arc length at the nodes the refinement added. - **Both line kinds take it.** `CD_Set_Model_VIV` (`EI = 0`) and `CD_HermiteCable_Dyn_Set_VIV` (finite-EI) gain an optional `phase_seed`. It is checked for size and finiteness. - **Routes.** The standalone, multibody and coupled builds all pass it, since they share the line builders. - **Unchanged decks.** Lines written fairlead first on the deck mesh keep their phases exactly. - **Docs:** theory, VALIDATION and CHANGELOG. VALIDATION had listed coupled VIV as unsupported; it now records it. ## Checks - **New `viv_riser` test: MoorDyn-C's own VIV case**, the catenary riser of Thorsen et al. in a uniform 0.2 m/s current, written anchor first. Results over 20–40 s at `dtM` 1e-3 s: | | CableDyn | MoorDyn-C | Measured | |---|---|---|---| | Mean fairlead tension | 69.92 N | 69.93 N | | | Tension range | 3.73 N | 3.72 N | | | Period | 0.4853 s | 0.4811 s | 0.4808 s | The period converges with `dtM` (0.4829 s at 2.5e-4 s). - **`viv_coupled`** covers the seed on the coupled routes. - **Test suite:** ctest 310/310; Python 2027 passed. - **Examples:** all 52 shipped examples are byte-identical to dev. None uses `Cl > 0`. - **Format:** fprettify is clean. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…64) Three fixes from a user's digital-twin feedback, in one PR. Each is a separate commit: the static check of a dynamic deck, the speed of elevation-record waves, and their high cut-off. ## 1. `TMax = 0` checks the static start of any dynamic deck Checking the static start of a dynamic deck meant cutting the deck down first. - **Motion records may outlast `TMax`.** This covers `motionFile` point rows, `TURBINES` rows and `vesselMotion`. Rows after `TMax` are still parsed and placed on the `dtM` grid, then not used; off-grid rows are still refused. A shared helper, `motion_grid_index`, replaces three copies of the grid lookup. - **`RangeStart` at `TMax = 0`** is accepted, and the range graphs hold the t = 0 row. After a `TMax > 0` it is still refused. - **A pointer in the message.** A standalone deck without `TMax` whose error asks for a dynamic run now ends with `; to check a dynamic deck's static start only, give dtM with TMax = 0`. The Python validator gives the same text. - **Checks:** - New `static_check` test: a 1 s run on a 36 s record writes byte-identical output to a run on the record cut to 1 s. - `shared_anchor`: a `TURBINES` record longer than the run gives the same run, bit for bit. ## 2. Faster elevation-record waves A WaterKin `WaveKinMod 1` record becomes about `TMax/(2 dtWave)` Fourier components, which every node summed. The JONSWAP option has 200. - **Tail bound.** `CD_Component_Wave_Kinematics` gains an optional `tail_sums` table, for tables whose k does not decrease. - Below the surface, both depth ratios fall as k grows. So the last summed component's cosh ratio, times the remaining sums of `a ω`, `a ω²` and `a ω²/k`, bounds the rest of the velocity, acceleration and pressure sums. - The sums stop once that bound is below half an ulp of what has been summed. The elevation still sums every component. - The sums run in blocks of 32, in component order. Without `tail_sums` the result is bit for bit the same. - The underflow fallback reuses each block's exponentials. - The deck driver builds the table, and the `exp(-2kd)` cache, for elevation records and JONSWAP. - **WaveKinFile reading.** The file was read one row at a time, copying the whole record per row. The rows now grow by doubling. - **Measured** on a 1024-element lazy-wave cable over 300 s: | Case | Before | After | |---|---|---| | Elevation record, `dtWave` 0.25 s | 226 s | 103 s | | Elevation record, `dtWave` 0.1 s | about 660 s | 189 s | | 10 s run on a 168,000-row record | 107 s | 3.5 s | Both elevation decks give output identical to the printed digits. The JONSWAP run changes in its eighth printed digit. - **New kernel test** in `hermite_irregular_waves`: a 1500-component table, from the surface to the seabed, with and without stretching. - The elevation is bit-identical. - Velocity, acceleration and pressure agree within 4 ulp of the summed magnitudes. ## 3. `WvHiCOff`: high cut-off of an elevation record, 0.5 Hz by default - **The option.** `WvHiCOff` (rad/s, SeaState's name and meaning) drops the record's components above it. The default is π rad/s, the 0.5 Hz at which MoorDyn-C cuts `WaveKin 3`. - `WaveKin 3` now follows the option too, bit for bit at the default. - `none WvHiCOff` keeps every component, as MoorDyn-F and earlier CableDyn did. - A record with nothing at or below the cut-off is refused by name. - **Effect.** A one-hour record at `dtWave` 0.1 s drops from 18,000 components to 1,800. On the 300 s case both records then run in 72 s. Every output channel's standard deviation moves by at most 0.002 %. - **`TMax = 0`.** A `WaveKinMod 1` deck at `TMax = 0` now reduces its record over the record's own length, instead of failing for want of a positive `TMax`. - **Checks:** - `wavekin_modes`: 1 rad/s keeps only the record's 8 s harmonic, exactly; `none` reproduces the record. - `deck_driver`: the refusal, and the `TMax = 0` run. - The Python validator accepts `WvHiCOff`, and refuses 0 and text other than `none`. ## Checks - **Test suite:** ctest 311/311; Python 2031 passed. - **Examples against dev:** 50 of 52 are byte-identical. The other two are JONSWAP decks, which change at round-off: - `lazy_wave_bend_stiffener` changes in its eighth printed digit. - `lazy_wave_vessel_rao` has one step, at 46.8 s, that converges one iteration apart under its 1e-4 solver tolerance. That moves `FairTen` by 1.5 N (1.7e-4) for half a second. At a 1e-9 tolerance, old and new agree to the last printed digit. - **Format:** fprettify, ruff and Sphinx are clean. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…curvature, Syrope hydrodynamics (#65) * feat(outputs): CurvX/CurvY, the curvature on a cable's section axes Curv<L>N<J> gives the curvature as a magnitude only. The fatigue of an armour wire or conductor at a fixed point of a power cable's cross section needs its direction in the section, so cross-section analysis (CableXSec) had to rebuild it from node positions. CurvX<L>N<J> and CurvY<L>N<J> resolve the nodal curvature vector, toward the centre of curvature and of length Curv<L>N<J>, on the section axes of a finite-EI line. The vector is the normal part of the recovered section moment over EI on the side that gives the curvature, or the exact trace's (r' x r'') x r'/|r'|^4 where the recovery falls back to it (both now returned by node_values and CD_HermiteCable_Curvature). The section axis x starts at End A normal to the End A -> End B tangent: on a line restrained in torsion along End A's torsion normal; otherwise along the static start's upper normal, kept in the hang-off's axes when End A is clamped (it turns with the vessel) and in global axes at a pinned End A. It is carried to every node by parallel transport (eight smallest rotations between the Hermite tangents per element) and, in torsion, turned about the tangent by the twist from End A. The result is cached per state, so the channels of one output row share one recovery. EI = 0 lines and the two-moving-end route refuse the channels by name, natively and in the Python deck validator. section_curvature: on a planar line CurvY is zero and the norm is Curv; in a cross current both components appear with the same norm; the deck turned 30 degrees about the vertical gives the same components to 8e-9; a clamped hang-off turned 30 degrees about its tangent turns them by -30 degrees to 1e-15; on a line twisted 90 degrees the carried axes reach End B within 3e-6 rad of its own pretwisted normal. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(openfast): start a coupled run from the equilibrium in SeaState's current A coupled OpenFAST run solved its static start in still water and let the SeaState current act from t = 0, while a standalone deck starts in the equilibrium of its current OPTION. The twin user's lazy-wave cable then spent the first minutes of every coupled run drifting into the current, and those minutes were discarded. CD_Init_Deck_Aggregate (and CD_AGG_Init_From_Deck) take an optional static_current profile (z, ux, uy, uz by ascending z). With the host fluid field and the host current on, it goes into a copy of the options that only the static builders see: body and rod equilibrium, the EI = 0 system and its points, and the finite-EI cables. The dynamics take the host field alone (the EI = 0 models' fluid field is replaced, the cables' drag carries no deck current), so the current is not counted twice. A deck whose WaterKin CurrentMod 1 file gives its own profile keeps it. The OpenFAST shell builds the profile from SeaState's CurrMod 1 current at the levels of its vertical wave grid (CD_SeaState_Steady_Current) and passes it at the initialisation, the checkpoint rebuild and the linearization probes. CurrMod 2 and InflowWind currents keep the still-water start, with a note. On the mixed deck (EI = 0 chain and finite-EI cable) held in a 0.5 m/s current, the start in that current moves its loads by 2.3e-8 over 1 s, the still-water start by 4.8e-3. On the IEA-15 MW mixed example in a 0.5 m/s cross current the cable starts 29 m across at its deepest monitored node and moves less than 0.6 m in 30 s; from still water it has covered a third of that offset by then. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * feat(syrope): hydrodynamics, current, waves, host fluid and VIV on Syrope lines MoorDyn applies its line hydrodynamics to Syrope polyester lines as to any other. CableDyn built a Syrope line on its own path with gravity, buoyancy and a flat seabed only: no drag, no added mass, and current, waves, a host's fluid field, a bathymetryFile and VIV refused. The Syrope builder now keeps its working-curve initial condition (the secant EA iterated to the rest curve, the per-element running maximum and slow strain) but builds each probe and the final line through init_one_model, which takes the secant and the Syrope states as optional arguments: the line gets the seabed, hydrodynamics and fluid fields of any EI = 0 line, its static start includes the current's drag, and its legacy BA is zero (the working curve's BA_s|BA_d carries the rope's damping). Composite and finite-EI Syrope lines stay refused. A taut 88.5 m polyester line in water whose fairlead sways 2 m matches MoorDyn-C v2.7.2's fairlead tension within 10.6 N over a 44.8 kN range (1.03 MN mean; 0.5 N at t = 0); without drag and added mass the range grows 4.8 % (syrope_hydro, with a cross current, VIV and waves). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(outputs): key the CurvX/CurvY cache on the torsion state too At a bending-pinned End A restrained in torsion, a host rotation turns the committed torsion end frames and torque without moving q, v, a, the time or the load epoch, and the reference normal stays fixed (no parent end connection). The section-curvature cache then served the components of the frames before the rotation. The key now holds the torsion end frames, Theta, Phi and the torque. section_curvature turns the host 30 degrees about the End A tangent of such a line and requires the next evaluation to equal a fresh one. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> --------- Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
* feat(openfast): linearise the line dynamics, as MoorDyn-F With Linearize = True the module now registers continuous states: the interior-node positions of every EI = 0 line (MoorDyn's names and order) and the free DOFs of every finite-EI cable (node positions and tangents), then their velocities. lin_eval loads a state and an input into the committed mirror, solves the accelerations without a time step and restores the committed state; CD_CalcContStateDeriv, CD_JacobianPContState and the input Jacobian central-difference it for A, B, C and D. This replaces the quasi-static linearisation without states. Positions, tangents and coupled-point displacements are stepped by 1 um: a millimetre step lifted a light cable's grounded nodes out of their 0.3 mm seabed penetration on one side of the difference, and the former 5 cm input step slackened a chain's last element, each halving a stiffness. Velocities take MoorDyn-F's 0.1 m/s, which gives the quadratic drag its equivalent linear damping. On the UMaine twin decks the reduction D - C A^-1 B matches MoorDyn-F's to 0.1 % per fairlead and on the platform 6x6, and the lowest nine line-mode frequencies to 0.3 %; both state matrices are stable. On the mixed deck with a lazy-wave power cable every coupled point matches central differences of the deck's own static solutions to 3.3e-4, also with a hang-off spring. openfast_lin_ab.py gates the frequencies, the stability and (with --cable-deck and --driver) the mixed deck, and solves an ill-conditioned A plainly instead of truncating it. A numeric-stiffness cable end connection now linearises. Free/Connect points and a Rigid cable end connection fail closed with named messages, as bodies, rods, Point3 buoys, torsion and CONTROL already did. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * refactor(openfast): drop the quasi-static linearisation path Every Linearize call now takes the line-state branch of the input Jacobian, dXdu included only when the glue asks for it (a deck without line states has none), so quasistatic_dydu and its scratch-aggregate re-solves are unreachable and removed. Outside a linearisation run the input Jacobian is the runtime fixed-state derivative for any state count, and dXdu or a state Jacobian fails with a named message. The module comments no longer describe the zero-state reduction. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> * fix(openfast): linearise the rope models' constitutive states The viscoelastic slow-branch stretch dl_1 and the Syrope slow strain are dynamic states with their own rate laws, but the linearisation held them, so D - C A^-1 B gave these ropes' instantaneous stiffness instead of their relaxed static one. They are now first-order linearisation states (VF_DerivOrder1, "Line l segment e dl1, m" / "slow strain, -"): lin_eval loads them from x and writes their rates, which the new CD_Get_Model_Internal_Rates evaluates with the instantaneous element laws (the taut series-Kelvin ODE or the slack zero-load relaxation; the Syrope kernel at dt = 0). A viscoelastic variant of the UMaine chains (150 stretches) now matches its static solutions to 7e-5 (held: 0.6 % too stiff); a taut three-leg Syrope spread with a SYROPE IC history (60 slow strains) to 6e-6 (held: 2.9 times too stiff). The Syrope running maximum and the seabed-friction stick anchors stay held: load histories, whose operating-point values are the small-motion tangent. A line or cable with VIV fails closed: it oscillates about a lock-in cycle, not an equilibrium. The A/B script's static reference adds TMax = 0 to a deck that leaves TMax to the host. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr> --------- Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
A Syrope line had to be a single taut section. A LINE can now carry Syrope sections between plain EI = 0 sections, such as the chain-polyester-chain mooring of a floating platform. init_one_syrope_model builds each Syrope section's working curve and solves the static start through init_one_model with a secant EA per element. On a composite line the tension varies along a sagging Syrope section, so each Syrope element takes the secant of its rest curve at its own tension: every element starts on its curve, its slow strain at rest. One secant per section left the elements away from the mean off the curve, and their slow strains moved the fairlead tension by 1.4e-5 within 2 s; now a still run keeps it to the printed digits. The tension update stays a contraction where the chains' weight and the geometry set the tension. The line's sections split into runs of one secant for the model build (the mesh is unchanged), the chains keep their BA damping, and a converged tension above the OWC table or a slack Syrope element stops with a named error. An iterate whose trial tension (the first solve at the working curve's alpha) overshoots the table takes the curve's secant at the table's top row and the update continues. Where the tension update contracts slowly (a lightly loaded rope near a working curve's zero-tension strain), the last two solves' response at each element, crossed with its rest curve, gives a safeguarded secant step. A single-section line keeps its secant from the mean strain: all 52 example decks are bit-identical. SYROPE IC applies to every Syrope section of a line; the Python deck reader accepts it on any line with a Syrope section. New test syrope_composite (every polyester element on its OWC to 2e-11, the equilibrium start, the Tmax0 working curve, the named refusals) and example composite_chain_syrope_chain.dat on a moving vessel. The driver format, the rope guide and the tutorial no longer describe the current, waves and bathymetry the Syrope hydrodynamics now carry as refused. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The helical armour of a power cable or a wire rope couples stretch and twist: T = EA eps + K tau, M = GJ tau + K eps. The 14-column LINE TYPES row's GJ column now takes GJ|K (finite-EI, linear-elastic, K^2 < EA GJ). With the torque still uniform along a line, tau = (M - K eps)/GJ follows the strain pointwise and the condensed torsion stays exact. Two changes carry the coupling: - the cable takes the axial stiffness EA - K^2/GJ of a section free to twist (build_finite_section_mesh); - a line restrained in torsion twists by Theta_eff = Theta - sum (K/GJ)(l_e - L_e). CD_HermiteTorsion_Line gains an optional per-element couple = K/GJ and adds the stretched element length's value, gradient and Hessian, so the statics, the dynamics, the rank-one tangent, the stability test, the host loads and the body equilibrium all take it. The coupling twist has no 2 pi ambiguity, so a first static evaluation unwraps the holonomy alone about its hint. The node and segment tensions add the element's (K/GJ) M, which the kernel's EA - K^2/GJ leaves out. The twist channels, the range rows and CurvX/CurvY sum the element twists M L/GJ - (K/GJ)(l - L) (new CD_HermiteCable_Dyn_Element_Twist). The two-moving-end compatibility route refuses the coupling. Every reader of the kernel's axial resultant on a line restrained in torsion adds the coupling force (K/GJ) M_t (new public CD_HermiteCable_Dyn_Coupling_Tension): the dynamic tensile_safety audit at the converged torque, the final static mesh-safety diagnosis (CD_HermiteCable_Resolution_Metrics axial_offset), the element recovery and the static element profile. The OpenFAST aggregate preflight evaluates the twist with the coupling, as the step does. test_torsion_coupling: - the kernel's effective-twist gradient and Hessian match finite differences (1.7e-10, 9.8e-11); - a stretched straight cable gives T = EA eps, M = K eps between rigid ends, T = (EA - K^2/GJ) eps with a free end, and T = EA eps + K Phi/L, M = GJ Phi/L + K eps with a 90 deg pretwist, to the printed digits; - a 20 s stretch-and-roll march ends on the static values to 1e-7; - GJ|0 is the uncoupled cable bit for bit; - K^2 >= EA GJ stops by name; - the element recovery and the element profile read EA eps between rigid ends; - a cable stretched by 1e-4 and twisted by -45 deg (T = -2.14 kN, the kernel's resultant +680 N) is refused by tensile_safety True in the statics and in a march rolled there, the opposite march passes; - the coupled aggregate accepts an update at the unchanged boundary. The full suite passes and all 53 example decks are bit-identical. The Python deck reader mirrors the grammar and checks, and the builder takes gj=(GJ, K). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…node (#69) In the dynamics a finite-EI line restrained in torsion now carries a twist angle phi at every node, against reference directors that follow the node tangents by the smallest rotation over each step (time-parallel transport), so the axial angular velocity of a section is phi_dot. The statics stay condensed and set the angles from the uniform static torque. - Element twist phi_{e+1} - phi_e + beta_e - h_e: beta_e advances by the solid angles of the quadrilateral of committed and present tangents (CD_HermiteTwist_Reference, local to the element's 12 DOFs, with gradient and Hessian), so the turns live in the angles and no 2 pi branch is tracked. A rigid end takes its frame's normal carried to the node as the node's director and holds the angle; an elastic end adds its spring. - Torque M_e = (GJ/l0)(tw + (K/GJ) dl) + (Bt/l0) d/dt(...), with the polar inertia Irn (LINE TYPES column, now used) lumped at the nodes and the new torsional damping Bt of the GJ column (GJ|K|Bt, negative: -zeta of an element's critical l0 sqrt(GJ Irn)). A rigid end's element twists through rho as its end frame turns; its damping rate adds d rho/dw . omega of the frames over the step. The support reaction of a rigid end adds the held end section's polar inertia, turned by the frame's angular acceleration and the held angle; the polar kinetic energy takes that section's spin with its frame. - The angles join the generalised-alpha step; the step factors one band of [r, m, phi] per node (half-width 13). Their rows converge on the nodal torque balance, scaled by the nodal loads as the force rows are. The committed reference advances with the step's own solid angles, so the committed state reproduces the converged iterate bit for bit; the twist state joins the snapshot, the recovering step and the OpenFAST mirror. - Torq<L>N<J> is the node's torque (mean of its elements); end force, end moment, energy, element twist and section curvature read the nodal state. - Under torque-tension coupling each element's coupling force (K/GJ) M_e takes its own torque: in the dynamic tensile_safety audit (the converged evaluation's), the element recovery and the node tensions. Gates: the kernel against direct transports (1e-13) and FD; nodal_twist_dynamic: the condensed torsion in the limit of no inertia (<= 6e-7, clamped, bending-pinned, elastic ends), the continuum torsional wave (0.07 %) and its zero driven-end torque at kL = pi/2 (0.13 %), the damping decrement (6 %), a parent rolling the end frame at a steady rate loading the line with (GJ theta + Bt Omega)/L (4e-13) and spinning it with the continuum's kinetic energy (7e-4), energy band 4.9e-4, snapshot and mirror restart bit-identical; a zero-allocation step gate. The old quasi-static gates run at Irn 1e-9/1e-12; a non-stepping coupled write twists the end element against the frozen interior. Full suite passes; 52 of 53 examples bit-identical, the torsion example within 7e-5 of the torque. 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` (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). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
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.
Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…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>
…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>
…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>
…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>
…plicitly (#78) ## What changed The monolithic multibody step (`bodyScheme monolithic`, the default) coupled a finite-EI cable pinned to a moving object (a Rigid6 `Body<N>` point or a free or pinned `Rod<N>` end, the other end held) at the Newmark predictor: the cable was stepped once per step with the predicted attachment motion and its end force was held through the outer iterations. That is an explicit, partitioned coupling. Its step amplification exceeds 1 once `K_e dt^2 / m_e` is above about 0.85 (1.5 at 1.3, 2.5 at 2), with `K_e` the cable's condensed dynamic end stiffness and `m_e` the object's effective mass along the cable. A light object on a stiff cable therefore left a balanced static start. A 3 t free rod spar with a 55 m cable (`EA` 5e8 N, 40 elements) pinned at its upper end, at `dtM` 0.01 s: - the step change of the cable tension alternated in sign and grew 2.3 times per step; - the tension rose from 11 kN past 1 MN in 0.7 s; - the rod end moved 6.3 m in 2 s. The start was not at fault. It is a stable equilibrium of the march: - the same deck with an `EI = 0` cable stays at rest to 1e-10 m; - with the cable clamped (`Rigid`, already coupled implicitly) it stays at rest to 1e-7 m; - the staggered scheme holds it. **The fix.** In `src/CableDyn_DeckDriver.f90`, every cable with an end on an object the march moves now sets `cab_imp`. This covers pinned or connected ends, End A or End B, bodies and free or pinned rods. Such a cable is re-stepped at every outer iteration with its end stiffness in the Newton matrix, as clamped cables and cables between two objects already were. A cable with no moving end is still stepped once. The staggered scheme and the OpenFAST and C-API routes are unchanged. **Docs.** - `doc/driver_format.md`: the multibody route bullet. - `doc/theory.rst`: the monolithic scheme paragraph, now with the stability criterion of the old coupling, and the clamped-cable paragraph. - `CHANGELOG.md`: an `[Unreleased]` Fixed entry. The #75 Added entry no longer says a pinned cable is "coupled at the predictor". ## Gates New CTest `pinned_cable_light_object`. On dev e760bc6, 14 of its gates fail. | Gate | dev e760bc6 | this branch | |---|---|---| | H: spar rod, cable pinned at the upper end (2 s): rod end move / tension change | 6.3 m / 161 times the start | 1e-10 m / 2.7e-8 | | H: same, in a 0.5 m/s current | 5.4 m / 472 times | 6.3e-4 m / 1.2e-4 (a slow swing of the start in the current, the same on the staggered scheme) | | H: cable pinned at the lower end | 6.5 m / 5596 times | 1.8e-10 m / 3.4e-8 | | D: cable from a fixed rod's end to the free rod (End B on the moving object) | 6.1 m / 1190 times | 2e-7 m / 9e-8 | | D: cable written from its anchor | the same output byte for byte | the same output byte for byte | | B: 4 t Rigid6 buoy with a pinned keel cable (4 s) | 0.22 m / 38 times | 1e-9 m / 3.3e-8 | | S: monolithic vs staggered, upper / lower end | 6.0 / 6.5 m apart | 1e-10 / 1.7e-10 m, tensions to 2.7e-8 / 3.4e-8 | | E: controls (`EI = 0` cable; cable clamped at upper / lower end) | at rest | at rest: 1e-10 m; 1e-7 / 3e-9 m | Gate tolerances: - 1e-5 m and 1e-5 of the tension; the positions are written to 8 digits, so 1e-6 m at the rod's depth; - 2e-3 m and 1e-3 in the current; - 1e-5 m for the staggered comparison. `line_attachments` 11 and 12 had to march at `dtM` 0.002 s on #77 because of this coupling. They are back at `dtM` 0.01 s, over 1 s instead of 0.3 s: | Gate | dev e760bc6 at `dtM` 0.01 s | this branch | |---|---|---| | 11: spar rod, pinned cable with a 1500 kg clump | 0.82 m / leg tension 13 times | 1e-7 m / 2.9e-7 | | 12: the same without the clump | 1.3 m / 4.4 times | 0 m / 3.8e-8 | Over 3 s the clump deck holds to 1.1e-6 m; dev moves it 15 m. ## Example A/B (reference driver built at e760bc6) 52 of 53 example decks are identical. `mixed_body_rods_points` changes; it is a 150 t buoy with a pinned power cable, the one example with a pinned cable on a moving object: - body surge changes by up to 3.5e-5 m (7e-6 of its 5.2 m range); - `Rod2Ry` changes by 2.3e-4 deg; - the cable top tension `FairTen8` changes by 0.6 N of 8.1 kN. The new run is the more accurate one. Against the same deck at `dtM` / 4, the body surge error falls from 3.7e-5 m to 1.6e-6 m and the pitch error from 1.1e-4 to 2.2e-5 deg. The cable tension error, 17 N, comes from the cable's own time step and does not change. The deck runs about 45 % longer (6.8 s to 9.8 s), because the cable is now stepped once per outer iteration instead of once per step. ## Checks - Full ctest (Release): 345 of 345 pass. - Checked Debug build (`-fcheck=all`, `--timeout 5400`): `pinned_cable_light_object`, `line_attachments`, `static_dry_weight`, `cable_between_bodies`, `monolithic_gates`, `clamped_cable_ends`, `body_rod_physics`, `bodies_rods` and `driver_clamped_cable_pinned_rod` pass, 9 of 9. - 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. `dup_public`: 0 duplicates. ## Notes - The slow drift in a current (6.3e-4 m in 2 s, 1.3e-3 m at most over 6 s, then turning back) is the same on the staggered scheme. The `EI = 0` cable in the same current holds to 1e-10 m. So it is a small static-versus-dynamic difference of the finite-EI cable in a current, not part of this coupling, and is left for the open list. - If the 45 % cost on decks with a pinned cable on a heavy body matters, the old coupling could be kept where `K_e dt^2 / m_e` is safely below 0.85. That needs estimates of `K_e` and `m_e`; this change takes the uniformly implicit coupling for robustness. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
… deck (#79) ## Summary The standalone mixed deck (`EI = 0` lines and finite-EI cables between `Fixed`/`Coupled`/`Vessel` points, run by the driver on the OpenFAST aggregate) now takes every deck current the single-line routes take: a `current` OPTION (uniform or profile), a WaterKin `CurrentMod 1` table and MoorDyn-C `Currents 1`/`2`/`5`. Until now the route refused all of them (and the aggregate also refused a deck current on any deck with a finite-EI cable). Deck waves stay refused on the mixed route, and the coupled OpenFAST/FAST.Farm route is unchanged: it keeps taking the host's field and refusing deck currents. ## Design - `CD_Init_Deck_Aggregate` / `CD_AGG_Init_From_Deck` take a new optional `deck_current` (passed only by the driver's `run_mixed_held_deck`). With it, the current refusals (`forbid_deck_ambient`, the finite-EI scope, MoorDyn-C `Currents 1/2/5`) are lifted. The refusals of `WaveKin 3/7` and deck waves stay. A deck-owned current is refused by name beside a host field (`external_fluid`), a host placement/farm/`static_current`, or bodies, rods and `Connect`/`Free` points (those decks run on the multibody or point-system march). Without `dtM` it is refused as on the single-line routes. - Statics: the static solves of the chains and the cables already take `opts` (with the static tangent gradient of a profile or grid). They now see the deck current at `t = 0`, as on the single-line routes. - Dynamics: an opaque `CD_DeckCurrentRuntimeType` (the deck options that carry the current, plus a sample workspace) is held by the aggregate. Its samplers call the single-line routes' own updaters: `update_system_line_hydro` (the system twin of `update_wave_models`) on the `EI = 0` lines and `update_hermite_deck_fluid` on the cables. Every field therefore goes through `deck_current_velocity`, as on the other routes. - `CD_AGG_Init_From_Deck` samples it at `t = 0` at the static state (the cables' first held field sets the consistent start acceleration). - `CD_AGG_Refresh_Accelerations` (the row-1 station of a motion) samples it again at `t = 0` at the installed row. - `CD_AGG_Step_Moving` samples it at `t_committed` at the step-start nodes, as the single-line marches do; `t_committed` is required. - `update_hermite_deck_fluid` takes an optional workspace, so the aggregate's march makes no heap allocation per step. The single-line routes still call it without one, unchanged. - Python `DeckFile` mirrors the change: a mixed deck accepts the currents, and refuses deck waves and `WaveKin 3/7` with the native wording. ## Validation New `mixed_route_currents` test (driver plus library): a 100 m cable and a 110 m chain, both fairleads surging 1 m from rest, in cross currents. Numbers are fractions of each channel's range, mixed route against the single-line routes. On dev every driver run of the mixed decks is refused. | Gate | Result | | --- | --- | | OPTION `uniform` / `profile`, `Currents 1/2/5`: static start | chain exact; cable 4.9e-6 / 4.3e-6 / 1.3e-6 / 9.2e-7 / 2.1e-6 (out-of-plane offset, 4 um of 0.55 m, the coupled build's static polish; still water: exact) | | March, coupled Newton controls (driver) | cable 1.0e-3 to 1.1e-3 (still water: 1.2e-3); chain 2.1e-5 uniform, exact sheared (still water: 5.4e-5, the row-1 transfer) | | March, the deck's Newton controls (library) | cable 4.9e-6 / 4.7e-6 / 9.5e-7 / 2.4e-6, the static start's difference (still water: 1.9e-8) | | Current felt | mid nodes 0.55 m / 0.56 m out of plane (uniform); chain tension history changes by 3.0e-3 | | `Currents 2` wrapping past its last sample | equal to the unrolled table bit for bit; differs from the held table by 0.39 of the chain tension range after 6 s | | Uniform field as `Currents 1` / `Currents 5` | bit for bit / static start bit for bit and march 3.9e-8 | | Correction rewind (`CD_AGG_Snapshot`, step, `CD_AGG_Restore`, step) x10, still water and `Currents 2` | bit for bit | | Refusals | deck waves, `uniform` beside `Currents 2`, current without `dtM` | Further checks: - `step_allocations_mixed_current`: 0 heap allocations in 160 steps in a `Currents 5` grid. It made 640 (4 per step) with the cables' automatic sample arrays before the workspace. - Python: a native-verdict parity test over ten mixed-deck current/wave rows; `driver_msg_mixed_current` now runs the lazy-wave deck in its current, and `driver_msg_mixed_waves` checks the waves refusal. Checks: - Release ctest: 345/345. - Checked Debug (`-fcheck=all`): 10/10 new and touched tests (`mixed_route_currents`, `step_allocations_mixed_current`, `mixed_route_torsion`, `mdc_currents`, `openfast_aggregate*`, `driver_msg_mixed*`). - pytest: 2189 passed, 75 skipped. The native mixed-route verdict test passes 10/10, and 5/10 fail against the dev driver. - ruff, strict mypy (only the 3 known errors), pre-commit, Sphinx `-W`, ifx duplicate-PUBLIC scan: 0. - Example A/B against dev: 53/53 decks identical. Docs: `driver_format.md`, `standalone_driver.rst`, `capabilities.rst`, `troubleshooting.rst`, `VALIDATION.md`, `CHANGELOG.md`. 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. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 88ebb610b2
ℹ️ 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".
The line-channel pattern of the deck object model listed Curv but not the section-frame CurvX<L>N<J> and CurvY<L>N<J> channels of 0.4.0, so DeckModel.rename() left them on the old line id (validate() then reported an unknown line, or a reused id silently reported another line) and removal did not see them. Both prefixes are now in the pattern; a test renames and cascade-removes a finite-EI line with all four curvature and moment channels. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8e40e33fc8
ℹ️ 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".
The Python deck-model fix changes the wheels and the sdist, so the release assets (run 41687653164) and the wheels (run 41687659235) were rebuilt from 8e40e33. The record carries their hashes; the clean-machine test (12 of 12) and the linearisation check passed again on the rebuilt assets, and the Python suite was re-run (2163 passed). Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. 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". |
…or modes output check_input_not_output() refuses an output root whose files would replace the deck or a file the deck reads, but its list missed two of the names a run writes: <root>.Line<N>.V.out, the VIV lift output of 0.4.0, and <root>.modes.out, the modal-analysis output. An input named like either was opened with STATUS=REPLACE and destroyed. The numbered suffix check now takes .V.out on lines and the fixed list .modes.out; every other name the driver writes was already covered. check_driver_paths.cmake runs a deck named clash.Line2.V.out and one named clash.modes.out with the root clash, expects the refusal and checks the deck is unchanged; it fails on the previous driver. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…l outputs CableDynDriver.run(overwrite=True) moves the previous results of the root aside and restores them if the new run fails, but its list of result files held only .out, .static.out, .elements.out and the .Line<L>.p/.t and .Rod<N>.p files. The .Line<L>.V.out lift output of 0.4.0, the .Line<L>.range.out range output and .modes.out were not moved: a failing rerun overwrote them with partial files, and a successful one that no longer writes them left stale ones beside the new results. They are now result files of the root; DriverResult.line_outputs keeps its documented .p/.t files. Two tests, failing before: a rerun that writes partial lift, range and modal files and fails restores the previous ones, and a successful rerun removes the stale ones. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The .Line<L>.V.out lift output of 0.4.0 names its channels Node<i>LiftX/Y/Z(N); read_output took every Node-led table for a node-position history and refused it (malformed dynamic line-node channels). A table whose channels are all lift channels is now a TimeHistory. A test reads one with and without the DeckNode line, and every V.out of the test suite reads. doc/cli.rst states the file checks of this release: the driver input guard covers .modes.out and .V.out, and an overwrite keeps aside every file a run writes. The CHANGELOG records these output-file fixes. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 476e2c5392
ℹ️ 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".
The driver output guard and the Python output-file fixes change the executables and the wheels, so the release assets (run 41709562272) and the wheels (run 41709568758) were rebuilt from 476e2c5. The record carries their hashes and the commits each local check ran on; the clean-machine test (12 of 12) and the linearisation check passed again, and the release driver refuses decks named like a lift or modal output. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
|
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". |
… names A study writes every case into one directory, so a case named base.Line1.V, base.Line1.range or base.modes would overwrite the .V.out, .range.out or .modes.out file of a case base. The collision check now covers every <root>.<suffix>.out name the driver writes. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27ce301fd5
ℹ️ 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".
The native driver builds every EI = 0 line with the still-water Morison drag, with or without WtrDpth or bathymetry, so its VIV lift needs no seabed and the driver runs such a deck (a dry deck and a MoorDyn-C Currents 1 profile without a depth row both run to completion). The Python validation still refused them as "no water"; the check is removed so DeckFile, DeckModel and study generation accept the decks the driver accepts. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The test runs its four pretwists at once but reserved one CTest processor, so on a four-core runner with ctest --parallel 4 it shared the cores with three other tests. The ubuntu Debug job took 475-895 s on pull requests and timed out at 900 s on the last three dev pushes. PROCESSORS 4 makes it run alone, and the timeout is 1800 s. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
|
@codex review |
|
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". |
Assets run 41737729420 and wheels run 41737734726 at 0979ba7: the clean-machine check (12 of 12), the driver output guard and the linearisation check on the release openfast.exe pass as before; the Python suite passes 2170 tests. Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
CableDyn 0.4.0
This brings
mainto the 0.4.0 release: #50 to #85 ondev, plus the release preparation on this branch.mainis an ancestor of this branch, so it fast-forwards. The release notes are the[0.4.0]section ofCHANGELOG.md. In short:GJ|K|Bt).openfast.exe(fix(openfast): linearise from double-precision loads in a single-precision OpenFAST #85).CurvX/CurvY);CoupledPinnedbodies.Release preparation (this branch)
release/check_release_metadata.pychecks. The 0.4.0 notes are condensed from the development log. The README capability table and the C ABI page are updated.edd0d62): the GNU build of the test programs is warning-free too, asRELEASE.mdrequires.4cbd24b): the nitpicky Sphinx build resolves theStiffenerrow class.8e40e33, from the Codex review): renaming or removing a line now carries itsCurvX/CurvYchannels.79760e0,0920005,476e2c5, from the Codex review and the same check across the release):.Line<N>.V.outor.modes.outwould overwrite an input;overwriterun keeps aside and restores the lift, range and modal outputs;read_outputreads a.V.outlift file.27ce301).e859c79, Codex): Python validation accepts VIV on an EI = 0 line without a seabed, as the driver does since fix(hydro): an EI = 0 line above the surface carries its dry weight without a seabed #84.0979ba7):torsion_current_startreserves four processors and has a 1800 s timeout; it timed out at 900 s on the Linux Debug job of the last three dev pushes.provenance.jsonstates.validation/RELEASE_0_4_0.md.Checks
check_release_metadata.py,audit_release_tree.py(worktree andgit archive), pre-commit,git diff --check.-W -n.build_static_windows.ps1gate passes;openfast.exe: surge stiffness 7.721e4 N/m against MoorDyn-F's 7.716e4 N/m, symmetry 7e-6.CompMooring = 5runs (including a bit-identical restart) and the wheel in a new environment.After the merge (maintainer)
Fast-forward
main, tagv0.4.0, publish the GitHub release with the four assets of run 41737729420, and approve the PyPI environment.