From b62b326fb214de8135da40942cefb4b062a37883 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Sun, 8 Nov 2026 16:20:04 +0900 Subject: [PATCH 1/3] fix(viv): MoorDyn's lift direction on either deck order; VIVphaseSeed MoorDyn takes the node tangent of the synchronisation model from End A to End B and starts node i from End A at 2 pi i/N. CableDyn's model numbers its nodes from End B, so on a line the reader keeps in the deck order (written fairlead first) its tangent ran from End B to End A. That turns the lift and the cross-flow axis around, which is MoorDyn's model started from the phases plus pi: the t = 0 lift 2 m from End A was -4.68 N where MoorDyn's is +4.66 N, on every route (single line, multibody march, mixed aggregate, refined mesh). The seed now adds that half turn where the model's tangent runs against MoorDyn's (CD_Deck_VIV_Phase_Seed, which the deck driver now passes on every line), so the lift field and the V line files are MoorDyn's whichever end the deck writes first. The taut line of viv_lockin locks into different modes in CableDyn and MoorDyn-F between about 0.21 and 0.33 m/s. Two lock-in branches coexist there: a line locked in mode 1 at 0.18 m/s stays in mode 1 as the current rises (A/D 0.710/0.701/0.686/0.671/0.662 at 0.21-0.33 m/s, MoorDyn-F's 0.709/0.699/0.685/0.670/0.659), one coming down from 0.30 m/s stays in mode 2. From rest CableDyn settles in mode 2, as MoorDyn-C v2.7.2 does (U 0.24 m/s: A/D 0.575 against 0.574 at x/L 0.24, the same frequency). MoorDyn-F v2.3.8 (OpenFAST v5.0.0) sets the seed in Line%phi but never copies it into the state vector it integrates, so its phases start at zero: a uniform lift that excites the symmetric modes only. With every phase at zero CableDyn follows MoorDyn-F's transient to four digits over 12 s and its mode-1 branch over the whole band. The new OPTION VIVphaseSeed (spread, the default; zero) selects that start; the Python deck validator mirrors it. viv_lockin gains the band at U 0.24 m/s against MoorDyn-C (spread) and MoorDyn-F (zero) and the t = 0 lift on both deck orders, EI = 0 and finite EI; viv_coupled and hermite_viv check the new seeds. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 12 ++++ VALIDATION.md | 2 +- doc/options.rst | 9 +++ doc/theory.rst | 14 ++++- python/cabledyn/deck_file.py | 4 ++ python/tests/test_deck_file.py | 4 ++ src/CableDyn_DeckDriver.f90 | 89 ++++++++++++++++------------ src/CableDyn_HermiteCableDynamic.f90 | 11 ++-- src/CableDyn_Model.f90 | 14 +++-- tests/test_hermite_viv.f90 | 6 +- tests/test_viv_coupled.f90 | 32 ++++++++-- tests/test_viv_lockin.py | 88 +++++++++++++++++++++++---- 12 files changed, 219 insertions(+), 66 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e3549554..bd993d76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,18 @@ All notable changes to CableDyn are recorded in this file. The format follows The touchdown element now takes the reaction of its grounded stretch, from the grounded node to the touchdown point located from the two nodes' clearances: the error falls at the second order (2.1, 0.7, 0.2 N) and the outputs vary continuously. +### Added + +- `VIVphaseSeed zero` starts every VIV phase at zero, the start of MoorDyn-F in OpenFAST v5.0.0, + which does not carry its phase seed into its state; the default `spread` keeps MoorDyn-C's + `2 pi i/N`. + +### Fixed + +- The VIV lift of a line written fairlead first pointed against MoorDyn's: the node tangent ran + from End B to End A, which is MoorDyn's model started from the phases plus pi. The lift and the + `V` line files now match MoorDyn's on either deck order. Where two lock-in branches coexist the + start can select the other one. ## [0.4.1] - 2026-11-08 diff --git a/VALIDATION.md b/VALIDATION.md index e556c0ac..63dbd7f9 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -62,7 +62,7 @@ article's methods, are compared in | **L2-V** | VolturnUS-S anchor tension | closed-form catenary | 0.77% | <3% | Pass | | **L2-80** | Lozon 80 m all-chain mooring | catenary (H) / MoorDyn-F (fairlead) | 0.03% / 1.8% | <2% / <5% | Pass | | **L2-arb** | Closed-form catenary reference check | OrcaFlex VolturnUS-S ref | 0.69% | <2% | Pass | -| **L2-VIV** | Cross-flow VIV lock-in of a taut 100 m line, U = 0.06–0.42 m/s | MoorDyn-F (OpenFAST v5 `moordyn_driver`, `dtM` 5e-4 s) | mode-1 and mode-3 lock-in (U ≤ 0.18 and ≥ 0.36 m/s): mid-span A/D within 1.2%, frequency within one spectral bin; same response at `dtM` 5e-4 to 1e-2 s; at 0.21–0.33 m/s the codes settle on different modes (MoorDyn-F mode 1, CableDyn mode 2) | A/D <3%, frequency within one spectral bin (`viv_lockin`) | Pass scoped | +| **L2-VIV** | Cross-flow VIV lock-in of a taut 100 m line, U = 0.06–0.42 m/s | MoorDyn-C v2.7.2 (RK2, `dtM` 5e-4 s) and MoorDyn-F (OpenFAST v5 `moordyn_driver`, `dtM` 5e-4 s) | mode-1 and mode-3 lock-in (U ≤ 0.18 and ≥ 0.36 m/s): mid-span A/D within 1.2% of MoorDyn-F, frequency within one spectral bin; same response at `dtM` 5e-4 to 1e-2 s. At 0.21–0.33 m/s two branches coexist (a run ramped up from 0.18 m/s stays in mode 1, one ramped down from 0.30 m/s stays in mode 2): from rest CableDyn and MoorDyn-C settle in mode 2 (U 0.24 m/s: A/D 0.575 against 0.574 at x/L 0.24, same frequency); MoorDyn-F, whose phases start at zero (it does not carry its seed into its state), in mode 1, which `zero VIVphaseSeed` reproduces (0.701 against 0.699, transient to four digits) | A/D <3%, frequency within one spectral bin; band: 3% (MoorDyn-C), 1% (MoorDyn-F) (`viv_lockin`) | Pass | | **L2-VIV-riser** | Catenary riser of Thorsen et al. in a uniform 0.2 m/s current (MoorDyn-C's VIV test: D 0.024 m, EI 10.5 N m², 100 segments, `Cl` 0.7), deck written anchor first | measured cross-flow frequency 1.04 Hz; MoorDyn-C v2.7.2 (RK4, `dtM` 1e-4 s) | over 20–40 s at `dtM` 1e-3 s: mean fairlead tension 69.92 N against 69.93 N, range 3.73 N against 3.72 N, tension period 0.4853 s against the measured 0.4808 s and MoorDyn-C's 0.4811 s (0.4843 / 0.4829 s at `dtM` 5e-4 / 2.5e-4 s) | mean 0.2%, range 10%, period 1.5% (`viv_riser`) | Pass | | **L2-VIV-EI** | Cross-flow VIV of a finite-EI cable: the L2-VIV line with EI = 1 N m², and a bending-stiff line (EA 5e9 N, EI 5e7 N m², β = π²EI/(TL²) ≈ 1, neutrally buoyant) against the EI = 0 string of equal first-mode frequency, U = 0.10–0.36 m/s | CableDyn `EI = 0` line (verification) | EI = 1: mid/quarter A/D 0.662/0.421 against 0.663/0.421, same frequency, at `dtM` 5e-4 to 1e-2 s; stiff line: mode-1 lock-in A/D within 2.5% of the string's at the same frequency for U ≤ 0.24 m/s; for U ≥ 0.27 m/s the string jumps to mode 2 while the stiff line stays in mode 1 (bending raises f₂/f₁ to 3.15) | EI = 1: A/D within 1% at `dtM` 0.01 and 0.002 s (5e-4 s run once over 200 s); stiff line at U 0.21 m/s: A/D within 3%; frequency within one spectral bin; at U 0.30 m/s stiff line A/D > 0.6, string < 0.15 (`viv_lockin`, `hermite_viv`) | Pass | | **L3-1** | WD0050 static | OrcaFlex | 0.15 / 0.85% | <2% | Pass | diff --git a/doc/options.rst b/doc/options.rst index ca74bbde..8f9e0641 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -695,6 +695,15 @@ Ambient fluid and prescribed motion different ``dtM`` with the same averaging time - lines with a LINE TYPES ``Cl > 0``, on every route - ``0.25 VIVrmsWindow`` + * - ``VIVphaseSeed`` / ``viv_phase_seed`` + - mode + - ``spread`` + - the initial phases of the VIV synchronisation model (:ref:`theory-viv`): ``spread`` starts + node ``i`` from the deck's End A at ``2 pi i/N``, as MoorDyn-C; ``zero`` starts every node + at zero, where MoorDyn-F in OpenFAST v5.0.0 starts (it does not carry its seed into its + state). Where two lock-in branches coexist, the seed selects the one a run settles on + - lines with a LINE TYPES ``Cl > 0``, on every route + - ``zero VIVphaseSeed`` * - ``motionFile`` - path, or ``0``/``none`` - absent diff --git a/doc/theory.rst b/doc/theory.rst index 6db8e69f..0dff6502 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -1037,10 +1037,22 @@ so the shedding frequency locks onto the cross-flow motion inside the band :math:`c_F \pm d_F` (MoorDyn's defaults 0.18 and 0.08). The running RMS values average over ``VIVrmsWindow`` seconds, by default 500 steps of ``dtM`` as in MoorDyn, and the phases start at :math:`2\pi i/N` at node :math:`i` counted from the deck's End A (MoorDyn's ``AttachA``), also on -a line written anchor first, which the reader turns around. On a finite-EI mesh the static solve +a line written anchor first, which the reader turns around. The node tangent +:math:`\mathbf{q}` runs from End A to End B, as MoorDyn's; turning it around turns the lift and +:math:`\mathbf{e}` around and starts the same motion from the phases plus :math:`\pi`, so the +lift field is MoorDyn's whichever end a deck writes first. On a finite-EI mesh the static solve refined, the deck nodes keep that seed and the nodes it added take the seed interpolated in arc length. The static equilibrium carries no lift. +The seed decides which response the line settles on where two lock-in branches coexist. On the +taut line of the ``viv_lockin`` test, between about 0.21 and 0.33 m/s, a line locked in its first +mode at 0.18 m/s stays there as the current rises, while one coming down from 0.30 m/s stays in +its second mode, and a start from rest with the spread seed settles in the second mode, as +MoorDyn-C does. MoorDyn-F (v2.3.8, OpenFAST v5.0.0) sets the same seed but does not copy it into +the state vector it integrates, so its phases start at zero at every node: a uniform lift that +excites the symmetric modes only, after which the line stays in its first mode. ``zero +VIVphaseSeed`` starts every phase at zero, and reproduces that start (:doc:`options`). + In the implicit step the phase is explicit: the step's lift takes the phase predicted at :math:`t_{n+1}` from the step-start rate (the generalised-α level under the configuration blend), and the committed phase is the trapezoidal (Heun) update with the rate at the converged end diff --git a/python/cabledyn/deck_file.py b/python/cabledyn/deck_file.py index 5ba451b2..0b77789a 100644 --- a/python/cabledyn/deck_file.py +++ b/python/cabledyn/deck_file.py @@ -231,6 +231,8 @@ "max_strain": "max_strain", "vivrmswindow": "viv_rms_window", "viv_rms_window": "viv_rms_window", + "vivphaseseed": "viv_phase_seed", + "viv_phase_seed": "viv_phase_seed", "rangestart": "range_start", "range_start": "range_start", "waveseed": "wave_seed", @@ -1332,6 +1334,8 @@ def _scalar_option_value_error(keyword: str, value: str) -> str | None: if _strip_quotes(value).lower() in _STATICS_FRICTION_POLICIES else "must be asLaid or none" ) + if key == "viv_phase_seed": + return None if value.lower() in {"spread", "zero"} else "must be spread or zero" if key == "cable_statics": return ( None diff --git a/python/tests/test_deck_file.py b/python/tests/test_deck_file.py index 25fea080..a56793f0 100644 --- a/python/tests/test_deck_file.py +++ b/python/tests/test_deck_file.py @@ -672,6 +672,8 @@ def test_unknown_scalar_option_keyword_fails_closed(tmp_path): ("1.5", "wave_seed", "must be an integer"), ("maybe", "alpha_force_blend", "native boolean"), ("relaxed", "cable_statics", "continuation or sequenced"), + ("random", "VIVphaseSeed", "spread or zero"), + ("0", "viv_phase_seed", "spread or zero"), ("nodal", "OutputRecovery", "equilibrium or element"), ("on", "ei0_substeps", "auto or off"), ("0", "ei0_substep_angle", r"\(0, 90\] deg"), @@ -756,6 +758,8 @@ def test_zero_e_exponent_waterkin_mode_is_accepted(tmp_path): "True alphaForceBlend", "continuation cable_statics", "sequenced cableStatics", + "spread VIVphaseSeed", + "ZERO viv_phase_seed", "equilibrium OutputRecovery", "element output_recovery", "auto ei0_substeps", diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index bb3317d5..0e31a235 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -670,6 +670,9 @@ MODULE CableDyn_DeckDriver ! of the synchronisation model (OPTION VIVrmsWindow, s); 0 = MoorDyn's 500 time steps of ! the deck dtM (or of the run's step when the deck has none). REAL(wp) :: viv_rms_window = CD_ZERO + ! Initial VIV phases (OPTION VIVphaseSeed): spread over a turn along the line, 2 pi i/N + ! (MoorDyn-C), or zero at every node (.TRUE.: the start of MoorDyn-F in OpenFAST v5.0.0). + LOGICAL :: viv_phase_zero = .FALSE. ! WaveKinMod-1 elevation history reduced once to its real Fourier components. ! These feed the same arbitrary-component Airy kernel used by reference-matched ! irregular seas; wave_eta_mean carries the zero-frequency waterline offset. @@ -3468,27 +3471,22 @@ RECURSIVE SUBROUTINE build_one_hermite_cable(ln, sections, types, points, opts, ! coupled host may step the cable at a dt adjusted from the deck dtM. IF (PRESENT(install_viv)) THEN IF (install_viv .AND. ANY(viv_cl > CD_ZERO)) THEN - ! MoorDyn's phase seed counts the deck nodes from the deck's End A: a line the reader turned - ! around, or a mesh the static solve refined, takes it node by node (CD_Deck_VIV_Phase_Seed) - IF (ln%ends_swapped .OR. ALLOCATED(cable%deck_node)) THEN - BLOCK - REAL(wp) :: seed(cable%line%nn) - IF (ALLOCATED(cable%deck_node)) THEN - CALL CD_Deck_VIV_Phase_Seed(cable%line%l0, ln%ends_swapped, seed, deck_map=cable%deck_node) - ELSE - CALL CD_Deck_VIV_Phase_Seed(cable%line%l0, ln%ends_swapped, seed) - END IF - CALL CD_HermiteCable_Dyn_Set_VIV(cable%line, viv_cl, viv_cf, viv_df, & - MERGE(opts%viv_rms_window, & - REAL(CD_VIV_NM, wp)*MERGE(opts%dtM, dt, opts%has_dtm), & - opts%viv_rms_window > CD_ZERO), es, em, phase_seed=seed) - END BLOCK - ELSE + ! MoorDyn's phase seed counts the deck nodes from the deck's End A, with its node tangent + ! towards the deck's End B; CD_Deck_VIV_Phase_Seed takes it node by node to the model's + ! nodes and tangent (a line the reader turned around, a mesh the static solve refined) + BLOCK + REAL(wp) :: seed(cable%line%nn) + IF (ALLOCATED(cable%deck_node)) THEN + CALL CD_Deck_VIV_Phase_Seed(cable%line%l0, ln%ends_swapped, seed, deck_map=cable%deck_node, & + zero=opts%viv_phase_zero) + ELSE + CALL CD_Deck_VIV_Phase_Seed(cable%line%l0, ln%ends_swapped, seed, zero=opts%viv_phase_zero) + END IF CALL CD_HermiteCable_Dyn_Set_VIV(cable%line, viv_cl, viv_cf, viv_df, & MERGE(opts%viv_rms_window, & REAL(CD_VIV_NM, wp)*MERGE(opts%dtM, dt, opts%has_dtm), & - opts%viv_rms_window > CD_ZERO), es, em) - END IF + opts%viv_rms_window > CD_ZERO), es, em, phase_seed=seed) + END BLOCK IF (es /= CD_HCDYN_OK) THEN CALL fail(ErrStat, ErrMsg, 'finite-EI cable VIV wiring failed: '//TRIM(em)); RETURN END IF @@ -10379,17 +10377,14 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er END IF tw = opts%viv_rms_window IF (.NOT. (tw > CD_ZERO) .AND. opts%has_dtm) tw = REAL(CD_VIV_NM, wp)*opts%dtM - IF (ln%ends_swapped) THEN - ! MoorDyn counts the phase seed from the deck's End A, which the reader turned around - BLOCK - REAL(wp) :: seed(model%n_dof/3) - CALL CD_Deck_VIV_Phase_Seed(model%l0, .TRUE., seed) - CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, & - phase_seed=seed) - END BLOCK - ELSE - CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em) - END IF + ! MoorDyn counts the phase seed from the deck's End A, with its node tangent towards the + ! deck's End B: CD_Deck_VIV_Phase_Seed takes it to the model's nodes and tangent + BLOCK + REAL(wp) :: seed(model%n_dof/3) + CALL CD_Deck_VIV_Phase_Seed(model%l0, ln%ends_swapped, seed, zero=opts%viv_phase_zero) + CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, & + phase_seed=seed) + END BLOCK IF (es == CD_MODEL_OK) CALL CD_Recompute_Model_Acceleration(model, es, em) IF (es /= CD_MODEL_OK) THEN ErrStat = CD_DECKDRV_BADINPUT @@ -17154,6 +17149,15 @@ SUBROUTINE apply_option(line, opts, ErrStat, ErrMsg) opts%has_max_strain = ErrStat == 0 CASE ('vivrmswindow', 'viv_rms_window') CALL rd(val, opts%viv_rms_window, ErrStat, ErrMsg) + CASE ('vivphaseseed', 'viv_phase_seed') + SELECT CASE (TRIM(to_lower(val))) + CASE ('spread') + opts%viv_phase_zero = .FALSE. + CASE ('zero') + opts%viv_phase_zero = .TRUE. + CASE DEFAULT + CALL fail(ErrStat, ErrMsg, 'OPTION VIVphaseSeed "'//TRIM(val)//'" must be spread or zero') + END SELECT CASE ('streamorder', 'stream_order') CALL rd(val, x1, ErrStat, ErrMsg) IF (ErrStat == 0) THEN @@ -38444,18 +38448,25 @@ PURE FUNCTION cable_frame_is_identity(cable) RESULT(is_id) is_id = .NOT. (ABS(cable%frame_s) > CD_ZERO .OR. ABS(cable%frame_c - CD_ONE) > CD_ZERO) END FUNCTION cable_frame_is_identity - PURE SUBROUTINE CD_Deck_VIV_Phase_Seed(l0, swapped, seed, deck_map) - !! MoorDyn's VIV phase seed i/N (phase 2 pi i/N at node i = 0 .. N counted from the deck's - !! End A, N the deck's segment count) at every node of a line, in the model's internal node - !! order (node 1 = End B; element e of length l0(e) joins nodes e and e + 1). swapped: the - !! reader turned the line's ends around, so the deck's End A is the model's End B. deck_map: - !! the mesh node (public order, End A = 1) of each deck node, on a mesh the static solve - !! refined; a node it added takes the seed interpolated linearly in unstretched arc length - !! between its two deck nodes. Without deck_map the mesh is the deck's. + PURE SUBROUTINE CD_Deck_VIV_Phase_Seed(l0, swapped, seed, deck_map, zero) + !! The initial VIV phase of every node of a line, as a fraction of a turn, in the model's + !! internal node order (node 1 = End B; element e of length l0(e) joins nodes e and e + 1). + !! + !! MoorDyn starts node i = 0 .. N (counted from the deck's End A, N the deck's segment count) + !! at the phase 2 pi i/N (MoorDyn-C; zero: at 0, where MoorDyn-F in OpenFAST v5.0.0 starts), + !! with the node tangent from the deck's End A to its End B. The model's node tangent runs from + !! its End B to its End A: against MoorDyn's on a line the reader keeps in the deck order, + !! which turns the lift and the cross-flow axis of the synchronisation model around. That + !! motion is MoorDyn's from the phases half a turn on, which the seed adds there; a line the + !! reader turned around (swapped: the deck's End A is the model's End B) has MoorDyn's tangent. + !! deck_map: the mesh node (public order, End A = 1) of each deck node, on a mesh the static + !! solve refined; a node it added takes the seed interpolated linearly in unstretched arc + !! length between its two deck nodes. Without deck_map the mesh is the deck's. REAL(wp), INTENT(IN) :: l0(:) LOGICAL, INTENT(IN) :: swapped REAL(wp), INTENT(OUT) :: seed(:) INTEGER, INTENT(IN), OPTIONAL :: deck_map(:) + LOGICAL, INTENT(IN), OPTIONAL :: zero REAL(wp) :: s(SIZE(l0) + 1), f INTEGER :: ne, nn, p, j, nd ne = SIZE(l0) @@ -38479,6 +38490,10 @@ PURE SUBROUTINE CD_Deck_VIV_Phase_Seed(l0, swapped, seed, deck_map) f = REAL(p - 1, wp)/REAL(ne, wp) END IF IF (swapped) f = CD_ONE - f + IF (PRESENT(zero)) THEN + IF (zero) f = CD_ZERO + END IF + IF (.NOT. swapped) f = MODULO(f + 0.5_wp, CD_ONE) seed(nn + 1 - p) = f END DO END SUBROUTINE CD_Deck_VIV_Phase_Seed diff --git a/src/CableDyn_HermiteCableDynamic.f90 b/src/CableDyn_HermiteCableDynamic.f90 index fb32e362..dbebc425 100644 --- a/src/CableDyn_HermiteCableDynamic.f90 +++ b/src/CableDyn_HermiteCableDynamic.f90 @@ -1050,9 +1050,12 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, Err !! per element the lift coefficient cl (0: no lift) and the band df/cf, and the running-RMS !! averaging time t_window (s; 0 takes 500 steps of the first step). The lift acts on the !! wetted Gauss points of every element with cl > 0, its phase lives on the nodes of those - !! elements; the phases start at 2 pi i/N with node i counted from End A (the model's last - !! node), as MoorDyn's; phase_seed, per node, gives i/N instead (a line whose deck End A the - !! reader turned around, or a mesh refined from the deck's). The phase follows the drag's + !! elements; MoorDyn starts node i counted from End A (the model's last node) at 2 pi i/N + !! with its tangent from End A to End B, and the material tangent here runs from End B to + !! End A, which turns the lift and the cross-flow axis around: the phases start at 2 pi i/N + !! plus pi, the same motion. phase_seed, per node, gives the start as a fraction of a turn + !! instead (CD_Deck_VIV_Phase_Seed: a line whose deck End A the reader turned around, a mesh + !! refined from the deck's). The phase follows the drag's !! current and a held host field (which !! carries any waves); the internal wave families (Set_Waves) are refused with VIV. The !! committed acceleration is refreshed with the new lift; if that fails, the previous VIV @@ -1144,7 +1147,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, Err model%viv_node(k) = .TRUE. model%viv_cf(k) = model%viv_cf(k)/wsum model%viv_df(k) = model%viv_df(k)/wsum - model%viv_phi(k) = CD_VIV_TWO_PI*REAL(nn - k, wp)/REAL(ne, wp) + model%viv_phi(k) = CD_VIV_Wrap_Phase(CD_VIV_TWO_PI*(REAL(nn - k, wp)/REAL(ne, wp) + 0.5_wp)) IF (PRESENT(phase_seed)) model%viv_phi(k) = CD_VIV_TWO_PI*phase_seed(k) END DO CALL viv_drag_terms(model) diff --git a/src/CableDyn_Model.f90 b/src/CableDyn_Model.f90 index 683b18b2..81c9ef1b 100644 --- a/src/CableDyn_Model.f90 +++ b/src/CableDyn_Model.f90 @@ -3886,9 +3886,12 @@ SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, !! rho is the water density. t_window is the averaging time of the running cross-flow mean !! squares [s]; 0 selects MoorDyn's 500 time steps, latched at the first step. Every !! interior free node next to a cl > 0 element carries a lift and a shedding phase; the - !! phases start spread over [0, 2 pi) along the line (MoorDyn-C: 2 pi i/N at node i from - !! End A; phase_seed, per node, gives i/N instead, for a line whose deck End A the reader - !! turned around), the mean squares at 0. + !! phases start spread over [0, 2 pi) along the line, the mean squares at 0. MoorDyn-C starts + !! node i from End A at 2 pi i/N with the node tangent from End A to End B; the model's + !! tangent (from node nd - 1 to nd + 1) runs from End B to End A, which turns the lift and the + !! cross-flow axis around, so the same motion starts here from those phases plus pi. + !! phase_seed, per node, gives the start as a fraction of a turn instead + !! (CD_Deck_VIV_Phase_Seed: a line whose deck End A the reader turned around, a refined mesh). !! An all-zero cl leaves the model without VIV. The mesh must be the single chain the !! line builder makes (element e joins nodes e and e+1). The caller recomputes the !! acceleration if the lift should enter the initial state (CD_Recompute_Model_Acceleration). @@ -3993,8 +3996,9 @@ SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, model%viv_df(nd) = model%viv_df(nd)/wsum model%viv_dn(nd) = model%viv_dn(nd)/wsum ! MoorDyn: phi_i = 2 pi i/N at node i = 0..N counted from End A; the model numbers its - ! nodes from End B, so node nd is MoorDyn's node n_nodes - nd - model%viv_phi(nd) = CD_VIV_TWO_PI*REAL(n_nodes - nd, wp)/REAL(n_elem, wp) + ! nodes from End B, so node nd is MoorDyn's node n_nodes - nd, and its tangent runs the other + ! way (half a turn on) + model%viv_phi(nd) = CD_VIV_Wrap_Phase(CD_VIV_TWO_PI*(REAL(n_nodes - nd, wp)/REAL(n_elem, wp) + 0.5_wp)) IF (PRESENT(phase_seed)) model%viv_phi(nd) = CD_VIV_TWO_PI*phase_seed(nd) END DO model%viv_phi_rollback = model%viv_phi diff --git a/tests/test_hermite_viv.f90 b/tests/test_hermite_viv.f90 index a1c75880..698b4534 100644 --- a/tests/test_hermite_viv.f90 +++ b/tests/test_hermite_viv.f90 @@ -73,8 +73,10 @@ PROGRAM test_hermite_viv CALL require(es == CD_HCDYN_OK .AND. model%has_viv, 'VIV installs again: '//TRIM(em)) CALL CD_HermiteCable_Dyn_Set_Waves(model, 1.0_wp, 8.0_wp, 0.0_wp, 100.0_wp, GACC, es, em) CALL require(es /= CD_HCDYN_OK, 'an internal wave family is refused on a VIV cable') - CALL require(ABS(model%viv_phi(NE + 1)) < TINY(1.0_wp) .AND. & - ABS(model%viv_phi(1) - 2.0_wp*PI) < 1.0e-12_wp, 'the phases start at 2 pi i/N from End A') + ! MoorDyn's 2 pi i/N from End A, half a turn on: the material tangent runs from End B to End A + CALL require(ABS(model%viv_phi(NE + 1) - PI) < 1.0e-12_wp .AND. & + ABS(model%viv_phi(NE) - (2.0_wp*PI/REAL(NE, wp) + PI)) < 1.0e-12_wp .AND. & + ABS(model%viv_phi(1) - PI) < 1.0e-12_wp, 'the phases start at 2 pi i/N + pi from End A') ! a drag reconfigured after VIV carries the lift scale and shedding diameter with it BLOCK REAL(wp) :: k0(NE), dn0(NE + 1), hd(NE), hn(NE), ht(NE) diff --git a/tests/test_viv_coupled.f90 b/tests/test_viv_coupled.f90 index 9272a1bd..fd9aa2a6 100644 --- a/tests/test_viv_coupled.f90 +++ b/tests/test_viv_coupled.f90 @@ -175,14 +175,21 @@ SUBROUTINE case_seed() INTEGER :: k, pass, nn ! four mesh elements (internal order, End B first) over two deck segments: deck nodes at public ! nodes 1, 3 and 5, so public node 4 lies 3/4 of the way along the second deck segment + ! MoorDyn's i/N from the deck's End A; a line kept in the deck order adds half a turn, as the + ! model's tangent runs against MoorDyn's there (End B to End A) CALL CD_Deck_VIV_Phase_Seed([1.0_wp, 3.0_wp, 2.0_wp, 2.0_wp], .FALSE., seed, deck_map=[1, 3, 5]) want = [1.0_wp, 0.875_wp, 0.5_wp, 0.25_wp, 0.0_wp] - CALL check(MAXVAL(ABS(seed - want)) < 1.0e-14_wp, 'refined mesh: deck nodes keep i/N, added nodes interpolate') + CALL check(MAXVAL(ABS(seed - MODULO(want + 0.5_wp, 1.0_wp))) < 1.0e-14_wp, & + 'refined mesh: deck nodes keep i/N, added nodes interpolate') CALL CD_Deck_VIV_Phase_Seed([1.0_wp, 3.0_wp, 2.0_wp, 2.0_wp], .TRUE., seed, deck_map=[1, 3, 5]) CALL check(MAXVAL(ABS(seed - (1.0_wp - want))) < 1.0e-14_wp, 'a turned-around line counts from its End B') CALL CD_Deck_VIV_Phase_Seed([1.0_wp, 3.0_wp, 2.0_wp, 2.0_wp], .FALSE., seed) - CALL check(MAXVAL(ABS(seed - [4.0_wp, 3.0_wp, 2.0_wp, 1.0_wp, 0.0_wp]/4.0_wp)) < 1.0e-14_wp, & + CALL check(MAXVAL(ABS(seed - [0.5_wp, 0.25_wp, 0.0_wp, 0.75_wp, 0.5_wp])) < 1.0e-14_wp, & 'the deck mesh keeps the node index') + CALL CD_Deck_VIV_Phase_Seed([1.0_wp, 3.0_wp, 2.0_wp, 2.0_wp], .FALSE., seed, zero=.TRUE.) + CALL check(MAXVAL(ABS(seed - 0.5_wp)) < 1.0e-14_wp, 'zero: every phase at 0 in MoorDyn''s frame') + CALL CD_Deck_VIV_Phase_Seed([1.0_wp, 3.0_wp, 2.0_wp, 2.0_wp], .TRUE., seed, zero=.TRUE.) + CALL check(MAXVAL(ABS(seed)) < 1.0e-14_wp, 'zero on a turned-around line') CALL write_deck('viv_coupled_stock.dat', 0.8_wp, anchor_first=.TRUE.) DO pass = 1, 2 IF (.NOT. start(agg, MERGE('viv_coupled.dat ', 'viv_coupled_stock.dat', pass == 1))) RETURN @@ -191,12 +198,17 @@ SUBROUTINE case_seed() worst_cable = 0.0_wp DO k = 2, nn - 1 ! internal node k (k = 1 at the anchor); MoorDyn's node from the deck's End A + ! (half a turn on where the reader keeps the deck order: the model's tangent runs against + ! MoorDyn's there) IF (pass == 1) THEN - worst_line = MAX(worst_line, ABS(agg%sys%fast%system%lines(1)%viv_phi(k) - TWO_PI*REAL(nn - k, wp)/50.0_wp)) - worst_cable = MAX(worst_cable, ABS(agg%cables(1)%line%viv_phi(k) - TWO_PI*REAL(nn - k, wp)/50.0_wp)) + worst_line = MAX(worst_line, turn_gap(agg%sys%fast%system%lines(1)%viv_phi(k), & + TWO_PI*(REAL(nn - k, wp)/50.0_wp + 0.5_wp))) + worst_cable = MAX(worst_cable, turn_gap(agg%cables(1)%line%viv_phi(k), & + TWO_PI*(REAL(nn - k, wp)/50.0_wp + 0.5_wp))) ELSE - worst_line = MAX(worst_line, ABS(agg%sys%fast%system%lines(1)%viv_phi(k) - TWO_PI*REAL(k - 1, wp)/50.0_wp)) - worst_cable = MAX(worst_cable, ABS(agg%cables(1)%line%viv_phi(k) - TWO_PI*REAL(k - 1, wp)/50.0_wp)) + worst_line = MAX(worst_line, turn_gap(agg%sys%fast%system%lines(1)%viv_phi(k), & + TWO_PI*REAL(k - 1, wp)/50.0_wp)) + worst_cable = MAX(worst_cable, turn_gap(agg%cables(1)%line%viv_phi(k), TWO_PI*REAL(k - 1, wp)/50.0_wp)) END IF END DO CALL check(worst_line < 1.0e-12_wp .AND. worst_cable < 1.0e-12_wp, & @@ -206,6 +218,14 @@ SUBROUTINE case_seed() END DO END SUBROUTINE case_seed + PURE REAL(wp) FUNCTION turn_gap(a, b) RESULT(gap) + !! Distance of two phases on the circle (rad). + REAL(wp), INTENT(IN) :: a, b + REAL(wp), PARAMETER :: TWO_PI = 8.0_wp*ATAN(1.0_wp) + gap = MODULO(a - b, TWO_PI) + gap = MIN(gap, TWO_PI - gap) + END FUNCTION turn_gap + LOGICAL FUNCTION start(agg, path) RESULT(ok) !! A host-fluid build of the deck at dt. TYPE(CD_AGG_ModuleType), INTENT(INOUT) :: agg diff --git a/tests/test_viv_lockin.py b/tests/test_viv_lockin.py index 7c9fa788..938853bd 100644 --- a/tests/test_viv_lockin.py +++ b/tests/test_viv_lockin.py @@ -31,7 +31,13 @@ the same first-mode frequency and shape: at U 0.21 m/s both lock into mode 1 with the same mid-span A/D (within 3 %) and frequency; at U 0.30 m/s the string jumps to mode 2 (mid-span A/D below 0.15) while the cable, whose bending raises f2/f1 to about 3.15, stays in mode 1 - (mid-span A/D above 0.6). + (mid-span A/D above 0.6); +* at U 0.24 m/s, where two lock-in branches coexist, a start from rest with the spread seed settles + in mode 2 as MoorDyn-C v2.7.2 does (x/L 0.24 A/D within 3 % of its 0.574, frequency within one + bin of 0.527 Hz), and VIVphaseSeed zero in mode 1 as MoorDyn-F in OpenFAST v5.0.0 (whose phases + start at zero) does (mid-span A/D within 1 % of its 0.699, frequency within one bin of 0.353 Hz); +* the lift at t = 0, 2 m from the deck's End A, has MoorDyn's direction and size on an EI = 0 line + and a finite-EI cable, whether the deck writes the line fairlead first or anchor first. usage: test_viv_lockin.py --exe --output """ @@ -54,6 +60,10 @@ FAILURES: list[str] = [] MD_AD, MD_F = 0.662, 0.293 # MoorDyn-F reference, mid span +# U 0.24 m/s, where two lock-in branches coexist (VALIDATION.md L2-VIV): MoorDyn-C v2.7.2 (seeded +# phases, RK2, dtM 5e-4 s) settles on mode 2 (quarter span x/L = 0.24: A/D 0.574 at 0.527 Hz); +# MoorDyn-F v2.3.8 (OpenFAST v5.0.0, phases from zero) on mode 1 (mid span: 0.699 at 0.353 Hz) +MDC_Q24, MDC_F24, MDF_M24, MDF_F24 = 0.574, 0.527, 0.699, 0.353 D = 0.1 @@ -151,24 +161,48 @@ def lift_std(path: Path) -> np.ndarray: return data[:, cols].std(axis=0) -def response(path: Path) -> tuple[float, float, float]: - """Mid A/D, mid peak frequency, quarter A/D over 60-120 s.""" +def response(path: Path, mid_name: str = "L1N25PZ", qtr_name: str = "L1N12PZ", + peak_of: str = "mid") -> tuple[float, float, float]: + """Mid A/D, peak frequency (of the mid or the quarter channel), quarter A/D over 60-120 s.""" hist = read_output(path) t = hist.column(hist.channels[0]) mask = t >= 60.0 - mid = hist.column("L1N25PZ")[mask] - qtr = hist.column("L1N12PZ")[mask] + mid = hist.column(mid_name)[mask] + qtr = hist.column(qtr_name)[mask] mid = mid - mid.mean() + qtr = qtr - qtr.mean() + sig = mid if peak_of == "mid" else qtr dt = float(np.median(np.diff(t[mask]))) - freq = np.fft.rfftfreq(mid.size, dt) - power = np.abs(np.fft.rfft(mid * np.hanning(mid.size))) + freq = np.fft.rfftfreq(sig.size, dt) + power = np.abs(np.fft.rfft(sig * np.hanning(sig.size))) return ( math.sqrt(2.0) * float(mid.std()) / D, float(freq[1:][np.argmax(power[1:])]), - math.sqrt(2.0) * float((qtr - qtr.mean()).std()) / D, + math.sqrt(2.0) * float(qtr.std()) / D, ) +def anchor_first(text: str) -> str: + """The deck with End A on the fixed point at x = 0 and End B on the coupled point at x = 100 m: + the same line, which the reader turns around (it runs from its fairlead).""" + a, b = "1 Coupled 0.0 0.0 -50.0", "2 Fixed 100.0 0.0 -50.0" + assert a in text and b in text + return text.replace(a, "1 Fixed 0.0 0.0 -50.0").replace(b, "2 Coupled 100.0 0.0 -50.0") + + +def first_lift(path: Path, x: float, from_end_b: bool) -> float: + """Cross-flow (z) lift at t = 0 at the node nearest x of a V file (public node order).""" + lines = path.read_text().splitlines() + head = next(i for i, line in enumerate(lines) if line.startswith("Time")) + names = lines[head].split("\t") + row = np.array([float(v) for v in lines[head + 1].split()]) + cols = [j for j, name in enumerate(names) if name.endswith("LiftZ(N)")] + xs = np.linspace(0.0, 100.0, len(cols)) + if from_end_b: + xs = xs[::-1] + return float(row[cols[int(np.argmin(np.abs(xs - x)))]]) + + def main() -> int: ap = argparse.ArgumentParser() ap.add_argument("--exe", required=True) @@ -178,7 +212,7 @@ def main() -> int: if out.exists(): shutil.rmtree(out) out.mkdir(parents=True) - for u in (0.15, 0.21, 0.30): + for u in (0.15, 0.21, 0.24, 0.30): (out / f"current_{u}.dat").write_text(CURRENT.format(u=u), encoding="utf-8", newline="\n") # the stiff cable and its equal-frequency string (neutrally buoyant: no sag stiffening) beta = math.pi**2 * 5.0e7 / (5.0e4 * 100.0**2) @@ -195,6 +229,18 @@ def main() -> int: for u in (0.21, 0.30): runs.append((("stiff", u), f"viv_stiff_u{u}", deck(0.01, waterkin=f"current_{u}.dat", **stiff))) runs.append((("string", u), f"viv_string_u{u}", deck(0.01, waterkin=f"current_{u}.dat", **string))) + # the two-branch band at U 0.24 m/s, probed at MoorDyn's mid (deck node 25: N26 here) and + # x/L = 0.24 (node 12: N13): the spread seed, and VIVphaseSeed zero + band = deck(0.01, waterkin="current_0.24.dat").replace("L1N25PZ\nL1N12PZ", "L1N26PZ\nL1N13PZ") + runs.append(("band", "viv_band_u0.24", band)) + runs.append(("band_zero", "viv_band_u0.24_zero", + band.replace("0.25 VIVrmsWindow", "0.25 VIVrmsWindow\nzero VIVphaseSeed"))) + # the lift at t = 0 has MoorDyn's direction whichever end the deck writes first + for ei, tag in ((0.0, "ei0"), (1.0, "fei")): + start = deck(0.01, ei=ei, waterkin="current_0.24.dat", outputs="V").replace("120.0 TMax", + "0.02 TMax") + runs.append((("t0", tag, False), f"viv_t0_{tag}", start)) + runs.append((("t0", tag, True), f"viv_t0_{tag}_anchor_first", anchor_first(start))) for _, name, text in runs: (out / f"{name}.dat").write_text(text, encoding="utf-8", newline="\n") env = dict(os.environ, OMP_NUM_THREADS="1") @@ -212,7 +258,13 @@ def run(name: str) -> subprocess.CompletedProcess[str]: print(proc.stdout[-2000:], proc.stderr[-2000:]) check(False, f"{name}: the run completes (exit {proc.returncode})") continue - results[key] = response(out / f"{name}.out") + if isinstance(key, tuple) and key[0] == "t0": + results[key] = first_lift(out / f"{name}.Line1.V.out", 2.0, key[2]) + elif key in ("band", "band_zero"): + results[key] = response(out / f"{name}.out", "L1N26PZ", "L1N13PZ", + "qtr" if key == "band" else "mid") + else: + results[key] = response(out / f"{name}.out") if 0.01 in results: ad, f, qtr = results[0.01] check(abs(ad - MD_AD) <= 0.03 * MD_AD, @@ -267,6 +319,22 @@ def run(name: str) -> subprocess.CompletedProcess[str]: check(a1 > 0.6 and a0 < 0.15, f"U 0.30 m/s: stiff cable stays in mode 1 (mid-span A/D {a1:.3f}), the string jumps to " f"mode 2 (mid-span A/D {a0:.3f})") + if "band" in results: + mid, f, qtr = results["band"] + check(abs(qtr - MDC_Q24) <= 0.03 * MDC_Q24 and abs(f - MDC_F24) <= 1.0 / 60.0 and mid < 0.1, + f"U 0.24 m/s, seeded phases: mode 2, x/L 0.24 A/D {qtr:.3f} at {f:.3f} Hz, mid span {mid:.3f}; " + f"MoorDyn-C {MDC_Q24} at {MDC_F24} Hz (within 3 % and one bin)") + if "band_zero" in results: + mid, f, _ = results["band_zero"] + check(abs(mid - MDF_M24) <= 0.01 * MDF_M24 and abs(f - MDF_F24) <= 1.0 / 60.0, + f"U 0.24 m/s, VIVphaseSeed zero: mode 1, mid-span A/D {mid:.3f} at {f:.3f} Hz; MoorDyn-F " + f"{MDF_M24} at {MDF_F24} Hz (within 1 % and one bin)") + for tag, what in (("ei0", "EI = 0 line"), ("fei", "finite-EI cable")): + a, b = results.get(("t0", tag, False)), results.get(("t0", tag, True)) + if a is not None and b is not None: + check(a > 4.0 and abs(b - a) <= 1.0e-9 * abs(a), + f"{what}: lift at t = 0, 2 m from the deck's End A, {a:+.4f} N fairlead first and " + f"{b:+.4f} N anchor first (MoorDyn's +z, the same on both)") print(f"{len(FAILURES)} failure(s)") return 1 if FAILURES else 0 From 62b1a5991b5174376289d2c6530ed9c4d7dc0f47 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Sun, 8 Nov 2026 17:22:31 +0900 Subject: [PATCH 2/3] fix(viv): a node at rest takes MoorDyn's cross-flow phase in the line's frame The phase rate falls back to phi_y = 0 at a node with no cross-flow motion (a node at rest, a held end of a finite-EI cable, whose phase feeds the lift of its elements). On a line whose node tangent runs against MoorDyn's, the seed is MoorDyn's plus pi because turning the tangent around turns the cross-flow axis and so phi_y by half a turn; the fallback has to turn with it, or the synchronisation term changes sign there. It now takes pi on such a line (CD_VIV_Phase_Rate phi_rest, set by the VIV setters from tangent_reversed, which the deck driver passes as the line's orientation). On the viv_lockin line at U 0.24 m/s the finite-EI cable written fairlead first and anchor first drifted 2.3e-4 m apart at mid span within 60 s (1.4 % of the amplitude); the two now give the same response to the printed digits, and viv_lockin gates that on both line kinds. Signed-off-by: Jae Hoon Seo --- doc/theory.rst | 6 ++++-- src/CableDyn_DeckDriver.f90 | 5 +++-- src/CableDyn_HermiteCableDynamic.f90 | 19 +++++++++++++++---- src/CableDyn_Model.f90 | 18 +++++++++++++++--- src/CableDyn_VIV.f90 | 8 ++++++-- tests/test_viv_lockin.py | 19 ++++++++++++++++++- 6 files changed, 61 insertions(+), 14 deletions(-) diff --git a/doc/theory.rst b/doc/theory.rst index 0dff6502..a16eb76b 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -1039,8 +1039,10 @@ so the shedding frequency locks onto the cross-flow motion inside the band :math:`2\pi i/N` at node :math:`i` counted from the deck's End A (MoorDyn's ``AttachA``), also on a line written anchor first, which the reader turns around. The node tangent :math:`\mathbf{q}` runs from End A to End B, as MoorDyn's; turning it around turns the lift and -:math:`\mathbf{e}` around and starts the same motion from the phases plus :math:`\pi`, so the -lift field is MoorDyn's whichever end a deck writes first. On a finite-EI mesh the static solve +:math:`\mathbf{e}` around and starts the same motion from the phases plus :math:`\pi`, with +:math:`\phi_{\dot y} = \pi` instead of MoorDyn's 0 at a node with no cross-flow motion (a node at +rest, a held end of a finite-EI cable), so the lift field is MoorDyn's whichever end a deck writes +first. On a finite-EI mesh the static solve refined, the deck nodes keep that seed and the nodes it added take the seed interpolated in arc length. The static equilibrium carries no lift. diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 0e31a235..eca88a4f 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -3485,7 +3485,8 @@ RECURSIVE SUBROUTINE build_one_hermite_cable(ln, sections, types, points, opts, CALL CD_HermiteCable_Dyn_Set_VIV(cable%line, viv_cl, viv_cf, viv_df, & MERGE(opts%viv_rms_window, & REAL(CD_VIV_NM, wp)*MERGE(opts%dtM, dt, opts%has_dtm), & - opts%viv_rms_window > CD_ZERO), es, em, phase_seed=seed) + opts%viv_rms_window > CD_ZERO), es, em, phase_seed=seed, & + tangent_reversed=.NOT. ln%ends_swapped) END BLOCK IF (es /= CD_HCDYN_OK) THEN CALL fail(ErrStat, ErrMsg, 'finite-EI cable VIV wiring failed: '//TRIM(em)); RETURN @@ -10383,7 +10384,7 @@ RECURSIVE SUBROUTINE init_one_model(ln, sections, types, points, opts, model, Er REAL(wp) :: seed(model%n_dof/3) CALL CD_Deck_VIV_Phase_Seed(model%l0, ln%ends_swapped, seed, zero=opts%viv_phase_zero) CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em, & - phase_seed=seed) + phase_seed=seed, tangent_reversed=.NOT. ln%ends_swapped) END BLOCK IF (es == CD_MODEL_OK) CALL CD_Recompute_Model_Acceleration(model, es, em) IF (es /= CD_MODEL_OK) THEN diff --git a/src/CableDyn_HermiteCableDynamic.f90 b/src/CableDyn_HermiteCableDynamic.f90 index dbebc425..925e5674 100644 --- a/src/CableDyn_HermiteCableDynamic.f90 +++ b/src/CableDyn_HermiteCableDynamic.f90 @@ -306,6 +306,9 @@ MODULE CableDyn_HermiteCableDynamic ! the Newton iterations); viv_rate/viv_ms_next hold the step-start rate and mean squares. ! ws_recovery_viv_* is the step-start copy of the recovering step, snap_viv_* the snapshot. LOGICAL :: has_viv = .FALSE. + ! the cross-flow phase of a node at rest (CD_VIV_Phase_Rate phi_rest): pi where the material + ! tangent runs against MoorDyn's node tangent (End B to End A), 0 where it runs as MoorDyn's + REAL(wp) :: viv_phi_rest = CD_ZERO REAL(wp) :: viv_tw = CD_ZERO REAL(wp), ALLOCATABLE :: viv_cl(:), viv_k(:), viv_cf(:), viv_df(:), viv_dn(:), viv_phi(:), viv_phi_eval(:) REAL(wp), ALLOCATABLE :: viv_rate(:), viv_ms(:, :), viv_ms_next(:, :) @@ -1045,7 +1048,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_Friction_Axial(model, mu_axial, ErrStat, ErrM model%tr_valid = .FALSE. END SUBROUTINE CD_HermiteCable_Dyn_Set_Friction_Axial - SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, ErrMsg, phase_seed) + SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, ErrMsg, phase_seed, tangent_reversed) !! Install the cross-flow VIV synchronisation model (CableDyn_VIV) on a cable with drag: !! per element the lift coefficient cl (0: no lift) and the band df/cf, and the running-RMS !! averaging time t_window (s; 0 takes 500 steps of the first step). The lift acts on the @@ -1065,8 +1068,12 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, Err INTEGER, INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg REAL(wp), INTENT(IN), OPTIONAL :: phase_seed(:) + !! tangent_reversed (default .TRUE., the model's own seed): the material tangent runs against + !! MoorDyn's node tangent, so a node at rest takes the cross-flow phase pi + !! (CD_VIV_Phase_Rate phi_rest); .FALSE. on a line the reader turned around + LOGICAL, INTENT(IN), OPTIONAL :: tangent_reversed INTEGER :: e, k, ne, nn, es - REAL(wp) :: wsum, tw_old + REAL(wp) :: wsum, tw_old, rest_old LOGICAL :: had_viv CHARACTER(LEN=1024) :: em REAL(wp), ALLOCATABLE :: a_old(:), o_cl(:), o_k(:), o_cf(:), o_df(:), o_dn(:), o_phi(:), o_phi_eval(:), & @@ -1112,6 +1119,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, Err ! the previous configuration and state, kept for a rollback had_viv = model%has_viv tw_old = model%viv_tw + rest_old = model%viv_phi_rest a_old = model%a CALL move_viv(.FALSE.) CALL clear_viv(model) @@ -1159,6 +1167,8 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_VIV(model, cl, cf, df, t_window, ErrStat, Err model%snap_viv_phi = model%viv_phi model%snap_viv_ms = model%viv_ms model%viv_tw = t_window + model%viv_phi_rest = 0.5_wp*CD_VIV_TWO_PI + IF (PRESENT(tangent_reversed)) model%viv_phi_rest = MERGE(0.5_wp*CD_VIV_TWO_PI, CD_ZERO, tangent_reversed) model%has_viv = .TRUE. ! the lift is part of the committed load: the first step's predictor and phase rate need it CALL refresh_acceleration() @@ -1171,6 +1181,7 @@ SUBROUTINE refresh_acceleration() CALL move_viv(.TRUE.) model%has_viv = had_viv model%viv_tw = tw_old + model%viv_phi_rest = rest_old model%a = a_old ErrStat = es ErrMsg = 'CD_HermiteCable_Dyn_Set_VIV: acceleration refresh failed: '//TRIM(em) @@ -1282,7 +1293,7 @@ SUBROUTINE viv_step_begin(model, dt, ErrStat, ErrMsg) model%viv_ms_next(2, k) = CD_VIV_Mean_Square(model%viv_ms(2, k), ydd, w) model%viv_rate(k) = CD_VIV_Phase_Rate(yd, ydd, model%viv_ms_next(1, k), model%viv_ms_next(2, k), & model%viv_phi(k), un, model%viv_dn(k), model%viv_cf(k), & - model%viv_df(k)) + model%viv_df(k), phi_rest=model%viv_phi_rest) model%viv_phi_eval(k) = model%viv_phi(k) + frac*dt*model%viv_rate(k) END DO END SUBROUTINE viv_step_begin @@ -1308,7 +1319,7 @@ SUBROUTINE viv_step_end(model, dt) ms1 = CD_VIV_Mean_Square(model%viv_ms_next(1, k), yd, w) ms2 = CD_VIV_Mean_Square(model%viv_ms_next(2, k), ydd, w) rate_end = CD_VIV_Phase_Rate(yd, ydd, ms1, ms2, model%viv_phi(k) + dt*model%viv_rate(k), un, & - model%viv_dn(k), model%viv_cf(k), model%viv_df(k)) + model%viv_dn(k), model%viv_cf(k), model%viv_df(k), phi_rest=model%viv_phi_rest) IF (.NOT. CD_Is_Finite(rate_end)) rate_end = model%viv_rate(k) END IF model%viv_phi(k) = CD_VIV_Wrap_Phase(model%viv_phi(k) + 0.5_wp*dt*(model%viv_rate(k) + rate_end)) diff --git a/src/CableDyn_Model.f90 b/src/CableDyn_Model.f90 index 81c9ef1b..166b2e8d 100644 --- a/src/CableDyn_Model.f90 +++ b/src/CableDyn_Model.f90 @@ -398,6 +398,9 @@ MODULE CableDyn_Model ! explicit generalised-alpha force-level phase. viv_rate (phase rate at the step start) ! and viv_ms_next (mean squares updated with the step-start sample) are step scratch. LOGICAL :: has_viv = .FALSE. + ! the cross-flow phase of a node at rest (CD_VIV_Phase_Rate phi_rest): pi where the node + ! tangent runs against MoorDyn's (End B to End A), 0 where it runs as MoorDyn's + REAL(wp) :: viv_phi_rest = CD_ZERO REAL(wp) :: viv_rho = CD_ZERO REAL(wp) :: viv_tw = CD_ZERO REAL(wp), ALLOCATABLE :: viv_cl(:), viv_d(:) @@ -3879,7 +3882,8 @@ SUBROUTINE CD_Set_Model_Syrope_State(model, slow, tmax, ErrStat, ErrMsg) model%recovery_syrope_tmax = tmax END SUBROUTINE CD_Set_Model_Syrope_State - SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, ErrMsg, phase_seed) + SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, ErrMsg, phase_seed, & + tangent_reversed) !! Install the cross-flow VIV model (CableDyn_VIV) on an initialised line. Per element: !! the lift coefficient cl (0 = no lift on that element), hydrodynamic diameter, and the !! synchronisation centre cf and half-range df of the non-dimensional shedding frequency; @@ -3900,6 +3904,10 @@ SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, INTEGER, INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg REAL(wp), INTENT(IN), OPTIONAL :: phase_seed(:) + !! tangent_reversed (default .TRUE., the model's own seed): the node tangent runs against + !! MoorDyn's, so a node at rest takes the cross-flow phase pi (CD_VIV_Phase_Rate phi_rest); + !! .FALSE. on a line the reader turned around, whose tangent runs as MoorDyn's + LOGICAL, INTENT(IN), OPTIONAL :: tangent_reversed INTEGER :: n_nodes, n_elem, e, nd, istat, k REAL(wp) :: wsum @@ -4009,6 +4017,8 @@ SUBROUTINE CD_Set_Model_VIV(model, rho, cl, diameter, cf, df, t_window, ErrStat, model%viv_rate = CD_ZERO model%viv_ms_next = model%viv_ms model%viv_phi_next = model%viv_phi + model%viv_phi_rest = 0.5_wp*CD_VIV_TWO_PI + IF (PRESENT(tangent_reversed)) model%viv_phi_rest = MERGE(0.5_wp*CD_VIV_TWO_PI, CD_ZERO, tangent_reversed) model%has_viv = .TRUE. END SUBROUTINE CD_Set_Model_VIV @@ -4195,7 +4205,7 @@ SUBROUTINE viv_step_begin(model, dt, ErrStat, ErrMsg) model%viv_ms_next(2, nd) = CD_VIV_Mean_Square(model%viv_ms(2, nd), ydd, w) model%viv_rate(nd) = CD_VIV_Phase_Rate(yd, ydd, model%viv_ms_next(1, nd), model%viv_ms_next(2, nd), & model%viv_phi(nd), un, model%viv_dn(nd), model%viv_cf(nd), & - model%viv_df(nd)) + model%viv_df(nd), phi_rest=model%viv_phi_rest) model%viv_phi_eval(nd) = model%viv_phi(nd) + (CD_ONE - alpha_f)*dt*model%viv_rate(nd) END DO END SUBROUTINE viv_step_begin @@ -4229,7 +4239,7 @@ SUBROUTINE viv_step_end(model, dt, ErrStat, ErrMsg) ms1 = CD_VIV_Mean_Square(model%viv_ms_next(1, nd), yd, w) ms2 = CD_VIV_Mean_Square(model%viv_ms_next(2, nd), ydd, w) rate_end = CD_VIV_Phase_Rate(yd, ydd, ms1, ms2, model%viv_phi(nd) + dt*model%viv_rate(nd), un, & - model%viv_dn(nd), model%viv_cf(nd), model%viv_df(nd)) + model%viv_dn(nd), model%viv_cf(nd), model%viv_df(nd), phi_rest=model%viv_phi_rest) model%viv_phi_next(nd) = CD_VIV_Wrap_Phase(model%viv_phi(nd) + 0.5_wp*dt*(model%viv_rate(nd) + rate_end)) END DO IF (.NOT. CD_All_Finite(model%viv_phi_next)) THEN @@ -6876,6 +6886,7 @@ SUBROUTINE CD_Copy_Model(src, dst, ErrStat, ErrMsg) work%has_viv = src%has_viv work%viv_rho = src%viv_rho work%viv_tw = src%viv_tw + work%viv_phi_rest = src%viv_phi_rest CALL copy_real1(src%viv_cl, work%viv_cl, 'viv_cl', ErrStat, ErrMsg) IF (ErrStat /= CD_MODEL_OK) RETURN CALL copy_real1(src%viv_d, work%viv_d, 'viv_d', ErrStat, ErrMsg) @@ -7047,6 +7058,7 @@ SUBROUTINE commit_model_copy(from, to) to%has_viv = from%has_viv to%viv_rho = from%viv_rho to%viv_tw = from%viv_tw + to%viv_phi_rest = from%viv_phi_rest CALL MOVE_ALLOC(from%viv_cl, to%viv_cl) CALL MOVE_ALLOC(from%viv_d, to%viv_d) CALL MOVE_ALLOC(from%viv_node, to%viv_node) diff --git a/src/CableDyn_VIV.f90 b/src/CableDyn_VIV.f90 index 27d742cc..94a60ae0 100644 --- a/src/CableDyn_VIV.f90 +++ b/src/CableDyn_VIV.f90 @@ -268,15 +268,19 @@ ELEMENTAL REAL(wp) FUNCTION CD_VIV_Mean_Square(ms_old, sample, weight) RESULT(ms ms = ms_old + weight*(sample*sample - ms_old) END FUNCTION CD_VIV_Mean_Square - PURE REAL(wp) FUNCTION CD_VIV_Phase_Rate(yd, ydd, ms_yd, ms_ydd, phi, un, diameter, cf, df) RESULT(rate) + PURE REAL(wp) FUNCTION CD_VIV_Phase_Rate(yd, ydd, ms_yd, ms_ydd, phi, un, diameter, cf, df, phi_rest) RESULT(rate) !! Rate of the vortex-shedding phase, d phi/dt = 2 pi (cF + dF sin(phi_y - phi)) U/D, with !! the cross-flow velocity phase phi_y from y', y'' normalised by their running RMS values - !! (unnormalised while either mean square is still zero, as MoorDyn). + !! (unnormalised while either mean square is still zero, as MoorDyn). A node with no + !! cross-flow motion takes phi_y = phi_rest (default 0, MoorDyn's): pi on a line whose node + !! tangent runs against MoorDyn's, which turns the cross-flow axis and so phi_y half a turn. REAL(wp), INTENT(IN) :: yd, ydd, ms_yd, ms_ydd, phi, un, diameter, cf, df + REAL(wp), INTENT(IN), OPTIONAL :: phi_rest REAL(wp) :: phi_y IF (.NOT. (ABS(yd) > CD_ZERO .OR. ABS(ydd) > CD_ZERO)) THEN phi_y = CD_ZERO + IF (PRESENT(phi_rest)) phi_y = phi_rest ELSE IF (ms_yd > CD_ZERO .AND. ms_ydd > CD_ZERO) THEN phi_y = ATAN2(-ydd/SQRT(ms_ydd), yd/SQRT(ms_yd)) ELSE diff --git a/tests/test_viv_lockin.py b/tests/test_viv_lockin.py index 938853bd..10cab73b 100644 --- a/tests/test_viv_lockin.py +++ b/tests/test_viv_lockin.py @@ -37,7 +37,9 @@ bin of 0.527 Hz), and VIVphaseSeed zero in mode 1 as MoorDyn-F in OpenFAST v5.0.0 (whose phases start at zero) does (mid-span A/D within 1 % of its 0.699, frequency within one bin of 0.353 Hz); * the lift at t = 0, 2 m from the deck's End A, has MoorDyn's direction and size on an EI = 0 line - and a finite-EI cable, whether the deck writes the line fairlead first or anchor first. + and a finite-EI cable, whether the deck writes the line fairlead first or anchor first, and the + mid-span response over 60 s is the same on both orders (within 1e-5 m: a node at rest takes + MoorDyn's cross-flow phase in the line's own frame). usage: test_viv_lockin.py --exe --output """ @@ -241,6 +243,11 @@ def main() -> int: "0.02 TMax") runs.append((("t0", tag, False), f"viv_t0_{tag}", start)) runs.append((("t0", tag, True), f"viv_t0_{tag}_anchor_first", anchor_first(start))) + # and the whole response is the same: 60 s at U 0.24 m/s, mid span, either deck order + order = deck(0.01, ei=ei, waterkin="current_0.24.dat").replace( + "L1N25PZ\nL1N12PZ", "L1N26PZ\nL1N13PZ").replace("120.0 TMax", "60.0 TMax") + runs.append((("order", tag, False), f"viv_order_{tag}", order)) + runs.append((("order", tag, True), f"viv_order_{tag}_anchor_first", anchor_first(order))) for _, name, text in runs: (out / f"{name}.dat").write_text(text, encoding="utf-8", newline="\n") env = dict(os.environ, OMP_NUM_THREADS="1") @@ -260,6 +267,9 @@ def run(name: str) -> subprocess.CompletedProcess[str]: continue if isinstance(key, tuple) and key[0] == "t0": results[key] = first_lift(out / f"{name}.Line1.V.out", 2.0, key[2]) + elif isinstance(key, tuple) and key[0] == "order": + hist = read_output(out / f"{name}.out") + results[key] = hist.column("L1N26PZ") elif key in ("band", "band_zero"): results[key] = response(out / f"{name}.out", "L1N26PZ", "L1N13PZ", "qtr" if key == "band" else "mid") @@ -335,6 +345,13 @@ def run(name: str) -> subprocess.CompletedProcess[str]: check(a > 4.0 and abs(b - a) <= 1.0e-9 * abs(a), f"{what}: lift at t = 0, 2 m from the deck's End A, {a:+.4f} N fairlead first and " f"{b:+.4f} N anchor first (MoorDyn's +z, the same on both)") + for tag, what in (("ei0", "EI = 0 line"), ("fei", "finite-EI cable")): + a, b = results.get(("order", tag, False)), results.get(("order", tag, True)) + if a is not None and b is not None and a.size == b.size: + gap = float(np.max(np.abs(a - b))) + check(gap <= 1.0e-5, + f"{what}: mid-span response over 60 s at U 0.24 m/s, fairlead first against anchor first, " + f"within {gap:.1e} m (1e-5 m; amplitude about 1.6e-2 m)") print(f"{len(FAILURES)} failure(s)") return 1 if FAILURES else 0 From 182f766b26ff47a9a2fc6062c9692371a364545a Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Sun, 8 Nov 2026 19:34:10 +0900 Subject: [PATCH 3/3] chore(changelog): the entry moves to the batch changelog change The [Unreleased] entries of the open changes are added together in one change, so that they do not conflict with each other. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd993d76..e3549554 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,18 +18,6 @@ All notable changes to CableDyn are recorded in this file. The format follows The touchdown element now takes the reaction of its grounded stretch, from the grounded node to the touchdown point located from the two nodes' clearances: the error falls at the second order (2.1, 0.7, 0.2 N) and the outputs vary continuously. -### Added - -- `VIVphaseSeed zero` starts every VIV phase at zero, the start of MoorDyn-F in OpenFAST v5.0.0, - which does not carry its phase seed into its state; the default `spread` keeps MoorDyn-C's - `2 pi i/N`. - -### Fixed - -- The VIV lift of a line written fairlead first pointed against MoorDyn's: the node tangent ran - from End B to End A, which is MoorDyn's model started from the phases plus pi. The lift and the - `V` line files now match MoorDyn's on either deck order. Where two lock-in branches coexist the - start can select the other one. ## [0.4.1] - 2026-11-08