diff --git a/CHANGELOG.md b/CHANGELOG.md index 134915c6..fbe1f1b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,13 @@ All notable changes to CableDyn are recorded in this file. The format follows ### Added +- Cross-flow vortex-induced vibration of `EI = 0` lines in the standalone driver: MoorDyn v2's + LINE TYPES columns `Cl` or `Cl dF cF` switch on the synchronisation model of Thorsen et al., + with the same phase start and running-RMS window (`VIVrmsWindow`, default 500 steps of + `dtM`). On a taut 100 m line in a uniform current it follows MoorDyn-F's lock-in amplitude + and frequency to two to three digits through mode-1 and mode-3 lock-in, at any `dtM` from + 5e-4 to 1e-2 s. The Python deck tools read and keep the columns. The coupled and mixed + routes refuse `Cl > 0` by name. - Bend stiffeners (`STIFFENERS` table): a tapered polyurethane sleeve over an end of a finite-EI line, given as conical segments from the root outward (outer diameters, bore, modulus, density). Each element it covers takes the compliance average of the cable-plus-sleeve diff --git a/CMakeLists.txt b/CMakeLists.txt index a67f6b8c..22d27f5d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -413,6 +413,7 @@ add_library(cabledyn_obj OBJECT src/CableDyn_Damping.f90 src/CableDyn_Viscoelastic.f90 src/CableDyn_Syrope.f90 + src/CableDyn_VIV.f90 src/CableDyn_Dynamic.f90 src/CableDyn_Model.f90 src/CableDyn_Modal.f90 @@ -1169,6 +1170,11 @@ add_test(NAME flagship_compression_note COMMAND test_flagship_compression_note ${CMAKE_SOURCE_DIR}/examples/iea15mw_umaine_mixed_cabledyn.dat) set_tests_properties(flagship_compression_note PROPERTIES LABELS "fortran;integration;static;contact") +add_executable(test_viv_kernels tests/test_viv_kernels.f90) +target_link_libraries(test_viv_kernels PRIVATE cabledyn_core) +add_test(NAME viv_kernels COMMAND test_viv_kernels) +set_tests_properties(viv_kernels PROPERTIES LABELS "fortran;unit;dynamic;viv") + add_executable(test_hfmf_mirror tests/test_hfmf_mirror.f90) target_link_libraries(test_hfmf_mirror PRIVATE cabledyn_core) add_test(NAME hfmf_mirror COMMAND test_hfmf_mirror WORKING_DIRECTORY ${CMAKE_BINARY_DIR}) @@ -1614,6 +1620,21 @@ if(Python3_Interpreter_FOUND) message(STATUS "anchor_uplift_channels: skipped (numpy not importable in ${Python3_EXECUTABLE})") endif() + # Cross-flow VIV lock-in of a taut line against MoorDyn-F, at a coarse and a zig-zag-resolving + # dtM (needs numpy). + if(_range_tdp_numpy_rc EQUAL 0) + add_test(NAME viv_lockin + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_viv_lockin.py + --exe $ + --output ${CMAKE_BINARY_DIR}/viv_lockin) + set_tests_properties(viv_lockin PROPERTIES + LABELS "python;integration;dynamic;viv;validation" + TIMEOUT 600 + ENVIRONMENT "${_cabledyn_python_test_environment}") + else() + message(STATUS "viv_lockin: skipped (numpy not importable in ${Python3_EXECUTABLE})") + endif() + # Node channels on a refined finite-EI line name deck nodes: the static profile's DeckNode # column, the standalone static and dynamic cubic-Hermite routes, the mixed route (the OpenFAST # aggregate evaluator) and the C API on the coarse lazy-wave deck the static solve refines diff --git a/VALIDATION.md b/VALIDATION.md index a0f24c89..fe21a1f6 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -62,6 +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 | | **L3-1** | WD0050 static | OrcaFlex | 0.15 / 0.85% | <2% | Pass | | **L3-2** | Regular-wave dynamic | OrcaFlex (pinned, dt-converged) | mean 0.30%, swing 8.4% | <2% / <15% | Pass | | **L3-3** | Current-deflected static | OrcaFlex | 0.07–0.67% | <2% | Pass | diff --git a/doc/capabilities.rst b/doc/capabilities.rst index 2225ca7d..450b8b01 100644 --- a/doc/capabilities.rst +++ b/doc/capabilities.rst @@ -113,9 +113,11 @@ Line and constitutive capability - natural frequencies and mode shapes of each line about its static equilibrium (all ``EI = 0`` lines, or all finite-EI lines on the Hermite route; flat seabed); a deck with torsion is rejected - * - VIV (``compVIV``) - - Not implemented - - use another validated model; CableDyn rejects the request + * - Cross-flow VIV (LINE TYPES ``Cl``, ``dF``, ``cF``) + - Standalone only + - MoorDyn v2's synchronisation model on ``EI = 0`` lines (:ref:`theory-viv`); in-line VIV + and finite-EI cables are not provided; the coupled OpenFAST and FAST.Farm routes and + mixed ``EI = 0`` / finite-EI decks refuse ``Cl > 0`` by name Loads and environment --------------------- diff --git a/doc/cli.rst b/doc/cli.rst index affb914c..5036ac73 100644 --- a/doc/cli.rst +++ b/doc/cli.rst @@ -1016,7 +1016,8 @@ native reader's rules. - ``LINE TYPES`` row ``NAME``; fields ``name``, ``diam``, ``mass``, ``ea``, ``ba``, ``ei`` followed by ``cdn``, ``cdt``, ``can``, ``cat`` (CableDyn columns), ``cd``, ``ca``, ``cdax``, ``caax`` (MoorDyn-style columns), or ``gas``, ``gj``, ``irt``, - ``irn``, ``cdn``, ``cdt``, ``can``, ``cat`` (14-column rows). + ``irn``, ``cdn``, ``cdt``, ``can``, ``cat`` (14-column rows); an 11- or 13-column row + adds ``cl`` or ``cl``, ``df``, ``cf`` (VIV). * - ``section.LINE.OCCURRENCE.FIELD`` - The ``OCCURRENCE``-th section (1-based, End A to End B) of line ``LINE``; fields ``lineid``, ``linetype``, ``length``, ``numsegs``. A 7-column ``LINES`` row counts as a diff --git a/doc/concepts.rst b/doc/concepts.rst index e6277908..0f9e57c4 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -80,7 +80,9 @@ A ``LINE TYPES`` row is the reusable material a section refers to by name: diame metre, axial stiffness ``EA``, axial damping ``BA``, bending stiffness ``EI``, and the four Morison coefficients (``Cd_n``, ``Cd_t``, ``Ca_n``, ``Ca_t``). ``EI`` is the switch between the two solver paths (next section). Axial response can be linear ``EA`` or a stateful constitutive model -(viscoelastic, Syrope) — see :doc:`theory`. +(viscoelastic, Syrope) — see :doc:`theory`. An ``EI = 0`` row may end with MoorDyn's cross-flow +VIV columns ``Cl`` or ``Cl dF cF`` (lift coefficient and synchronisation band; see +:ref:`theory-viv`). Two solver paths, selected by ``EI`` ------------------------------------ diff --git a/doc/coupling.rst b/doc/coupling.rst index d66c8d64..8ec85665 100644 --- a/doc/coupling.rst +++ b/doc/coupling.rst @@ -57,7 +57,7 @@ solve is mathematically incorrect; changing ``NumCrctn`` does not change that de ``current`` except as a steady current on a single-turbine, pure ``EI = 0`` deck without Rigid6 bodies or rods in a SeaState without waves or current (a WaterKin ``CurrentMod 1`` table remains available), - - VIV (``compVIV``), and + - cross-flow VIV (a LINE TYPES ``Cl > 0``), which runs in the standalone driver only, and - fluid-source combinations that the nodewise SeaState field cannot separate without double counting. diff --git a/doc/migrating.rst b/doc/migrating.rst index de3e5fc7..9a851f77 100644 --- a/doc/migrating.rst +++ b/doc/migrating.rst @@ -92,6 +92,10 @@ Keyword map * - ``LINE TYPES`` ``Name Diam MassDen EA BA/-zeta EI Cd Ca CdAx CaAx`` - same row; the native order is ``Cd_n Cd_t Ca_n Ca_t`` and the header decides which is meant. ``EI > 0`` switches the line to the bending element. + * - ``LINE TYPES`` VIV columns ``Cl`` or ``Cl dF cF`` + - same columns and the same synchronisation model on ``EI = 0`` types in the standalone + driver (:ref:`theory-viv`); the running-RMS window is ``VIVrmsWindow`` seconds, by default + 500 steps of ``dtM`` as MoorDyn's * - ``ElasticMod 2/3`` viscoelastic ``EA``/``BA`` - ``Es|Ed`` / ``Es|alphaMBL|vbeta`` in ``EA`` and ``BA_s|BA_d`` in ``BA`` * - Syrope line type and ``SYROPE IC`` diff --git a/doc/options.rst b/doc/options.rst index 3d6090de..e5accfcf 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -676,6 +676,15 @@ Ambient fluid and prescribed motion shape; one to two peak periods is typical - standalone ``waves``, ``wavetrain``, and WaterKin ``WaveKinMod 1`` waves - ``20.0 rampTime`` + * - ``VIVrmsWindow`` / ``viv_rms_window`` + - real, s + - ``0`` + - finite, ≥ 0; the averaging time of the running RMS cross-flow velocity and acceleration + of the VIV synchronisation model (:ref:`theory-viv`). ``0`` takes MoorDyn's 500 steps of + ``dtM`` (of the first step when the deck has no ``dtM``); set it to compare runs at + different ``dtM`` with the same averaging time + - standalone ``EI = 0`` lines with a LINE TYPES ``Cl > 0`` + - ``0.25 VIVrmsWindow`` * - ``motionFile`` - path, or ``0``/``none`` - absent diff --git a/doc/references.rst b/doc/references.rst index 371c264b..9498856b 100644 --- a/doc/references.rst +++ b/doc/references.rst @@ -77,6 +77,18 @@ Time integration and nonlinear solution Hydrodynamics and ocean environment ----------------------------------- +.. _ref-thorsen2014: + +- **Thorsen, M. J., Sævik, S. & Larsen, C. M. (2014).** A simplified method for time domain + simulation of cross-flow vortex-induced vibrations. *Journal of Fluids and Structures* + **49**, 135–148. https://doi.org/10.1016/j.jfluidstructs.2014.04.006 + +.. _ref-thorsen2016: + +- **Thorsen, M. J., Sævik, S. & Larsen, C. M. (2016).** Time domain simulation of + vortex-induced vibrations in stationary and oscillating flows. *Journal of Fluids and + Structures* **61**, 1–19. https://doi.org/10.1016/j.jfluidstructs.2015.11.006 + .. _ref-morison1950: - **Morison, J. R., O'Brien, M. P., Johnson, J. W. & Schaaf, S. A. (1950).** The force diff --git a/doc/theory.rst b/doc/theory.rst index 046aea2e..9b96cc7e 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -715,6 +715,51 @@ fluid acceleration :math:`\dot{\mathbf{u}}_f = \dot{\mathbf{u}}_{f,n} + \dot{\ma The fluid acceleration is the local (Eulerian) acceleration of the wave field. +.. _theory-viv: + +Cross-flow vortex-induced vibration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``EI = 0`` lines can carry the cross-flow lift of the synchronisation model of +:ref:`Thorsen et al. (2014) ` and :ref:`(2016) ` in the form +MoorDyn v2 implements it: a LINE TYPES row with a lift coefficient :math:`C_L > 0` (see +:doc:`file_formats`). At an interior node with unit tangent :math:`\mathbf{q}` (the chord of its +neighbours) and normal relative flow :math:`\mathbf{v}_n` of speed :math:`U = \lvert\mathbf{v}_n\rvert`, +each node carries a vortex-shedding phase :math:`\phi` and the lift + +.. math:: + + \mathbf{F}_L = \tfrac{1}{4}\rho\,d\,C_L\,(l_{i} + l_{i+1})\,U\cos\phi\;\mathbf{q}\times\mathbf{v}_n , + +the per-length :math:`\tfrac{1}{2}\rho d C_L U^2\cos\phi` over the node's half elements (wetted +fraction included). The phase follows the cross-flow motion +:math:`\dot y = \dot{\mathbf{r}}\cdot\mathbf{e}`, :math:`\ddot y = \ddot{\mathbf{r}}\cdot\mathbf{e}` +along :math:`\mathbf{e} = \mathbf{q}\times\mathbf{v}_n/U`: + +.. math:: + + \dot\phi = 2\pi\,\hat f\,\frac{U}{d}, \qquad + \hat f = c_F + d_F \sin(\phi_{\dot y} - \phi), \qquad + \phi_{\dot y} = \operatorname{atan2}\!\left(-\frac{\ddot y}{\ddot y_\text{rms}},\, + \frac{\dot y}{\dot y_\text{rms}}\right), + +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` along the line 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 +: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 +state. The lift's position and velocity derivatives enter the tangent. The cross-flow motion of +the phase and the velocity in the lift are the node values averaged with the neighbours, +:math:`(\mathbf{x}_{i-1} + 2\mathbf{x}_i + \mathbf{x}_{i+1})/4`. That keeps a resolved mode of +wavenumber :math:`k` to :math:`\cos^2(k l_0/2)` and removes the mesh-scale zig-zag mode exactly. +With the node's own kinematics, a step that resolves the zig-zag mode lets the synchronisation +loop pump it until the line loses lock-in; a coarse step only hides this behind the +integrator's numerical damping. VIV runs in the standalone driver; the coupled and mixed +aggregate routes refuse a deck with :math:`C_L > 0`. + Buoyancy and wetting ~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index ab6092ed..5d80a286 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -838,8 +838,9 @@ aborts with a CableDyn fatal error, check whether the deck uses one of these com - linearise a pinned-hang-off, uncontrolled variant of the deck; time-domain runs support both * - a ``Rigid`` end-connection direction reversed by exactly 180 degrees in one host update - drive the platform through intermediate orientations - * - VIV (``compVIV``) - - use a solver with a separately validated VIV model + * - VIV on the coupled or mixed route (``VIV (LINE TYPES Cl > 0) runs in the standalone driver + of an EI = 0 deck``) + - run the VIV study on a standalone ``EI = 0`` deck, or set ``Cl = 0`` for the coupled run * - a host/file fluid combination named as inseparable - select host wave/current and file wave/current independently as documented, or place the whole field in SeaState diff --git a/python/cabledyn/builder.py b/python/cabledyn/builder.py index 8bf7c1a6..1aa415b3 100644 --- a/python/cabledyn/builder.py +++ b/python/cabledyn/builder.py @@ -193,6 +193,11 @@ class LineType: Optional finite-EI columns (shear and torsional stiffness, rotary inertias). All four set writes the 14-column row; all ``None`` writes the 10-column row. + cl, df, cf : float | None + Optional cross-flow VIV columns of an ``EI = 0`` type (MoorDyn's lift + coefficient and the half-range and centre of the synchronisation band + in non-dimensional frequency). ``cl`` set writes the 13-column row, with + MoorDyn's ``df = 0.08`` and ``cf = 0.18`` where they are ``None``. """ name: str @@ -209,6 +214,9 @@ class LineType: gj: float | None = None irt: float | None = None irn: float | None = None + cl: float | None = None + df: float | None = None + cf: float | None = None @dataclass(eq=False) @@ -1622,6 +1630,9 @@ def add_line_type( gj: float | None = None, irt: float | None = None, irn: float | None = None, + cl: float | None = None, + df: float | None = None, + cf: float | None = None, ) -> LineType: """Add a ``LINE TYPES`` row; see :class:`LineType` for the fields. @@ -1637,7 +1648,9 @@ def add_line_type( """ _text(name, "line-type name") self._check_new_key(self.line_types, name) - item = LineType(name, diam, mass, ea, ba, ei, cdn, cdt, can, cat, gas, gj, irt, irn) + item = LineType( + name, diam, mass, ea, ba, ei, cdn, cdt, can, cat, gas, gj, irt, irn, cl, df, cf + ) self._line_types.append(item) return item @@ -2631,7 +2644,7 @@ def save( def _line_type_table(self) -> tuple[str, str, list[list[str]]]: rows: list[list[str]] = [] - wide = False + wide = viv = False for item in self._line_types: what = f"line type {item.name!r}" row = [_text(item.name, what), _num(item.diam, what), _num(item.mass, what)] @@ -2649,10 +2662,23 @@ def _line_type_table(self) -> tuple[str, str, list[list[str]]]: elif any(value is not None for value in extra): raise ValueError(f"{what}: give all of gas, gj, irt, irn or none") row += [_num(v, what) for v in (item.cdn, item.cdt, item.can, item.cat)] + if item.cl is not None: + if all(value is not None for value in extra): + # a LINE TYPES row has 10, 11, 13 or 14 columns: no VIV on the wide row + raise ValueError(f"{what}: cl, df and cf do not combine with gas, gj, irt, irn") + viv = True + df = 0.08 if item.df is None else item.df + cf = 0.18 if item.cf is None else item.cf + row += [_num(v, what) for v in (item.cl, df, cf)] + elif item.df is not None or item.cf is not None: + raise ValueError(f"{what}: df and cf need the VIV lift coefficient cl") rows.append(row) if wide: header = "Name Diam Mass EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t" units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (N) (N-m^2) (kg-m) (kg-m) (-) (-) (-) (-)" + elif viv: + header = "Name Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t Cl dF cF" + units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (-) (-) (-) (-) (-) (-) (-)" else: header = "Name Diam Mass EA BA EI Cd_n Cd_t Ca_n Ca_t" units = "(-) (m) (kg/m) (N) (N-s) (N-m^2) (-) (-) (-) (-)" @@ -3142,6 +3168,9 @@ def line_type(self, row: DeckRecord) -> None: gj=_f(values["gj"]) if wide else None, irt=_f(values["irt"]) if wide else None, irn=_f(values["irn"]) if wide else None, + cl=_f(values["cl"]) if "cl" in values else None, + df=_f(values["df"]) if "df" in values else None, + cf=_f(values["cf"]) if "cf" in values else None, ) def body(self, row: DeckRecord) -> None: diff --git a/python/cabledyn/deck_file.py b/python/cabledyn/deck_file.py index 9f7f1ea7..343667df 100644 --- a/python/cabledyn/deck_file.py +++ b/python/cabledyn/deck_file.py @@ -227,6 +227,8 @@ "tramp": "ramp_time", "maxstrain": "max_strain", "max_strain": "max_strain", + "vivrmswindow": "viv_rms_window", + "viv_rms_window": "viv_rms_window", "rangestart": "range_start", "range_start": "range_start", "waveseed": "wave_seed", @@ -1124,6 +1126,7 @@ def _scalar_option_value_error(keyword: str, value: str) -> str | None: "ramp_time", "max_strain", "range_start", + "viv_rms_window", }: if key == "friction" and value.lower() == "none": return None @@ -1153,6 +1156,7 @@ def _scalar_option_value_error(keyword: str, value: str) -> str | None: "ramp_time", "max_strain", "range_start", + "viv_rms_window", } or raw in {"dtic", "tmaxic", "cdscaleic", "threshic", "writelog", "dtout", "dtwave"}: try: numeric = _native_float(value) @@ -2582,7 +2586,7 @@ def effective(key: str, default: float) -> float: raise DeckFormatError( f"{self._label}: standalone OPTION frictionMu requires dtM and TMax" ) - allowed_widths = {"LINE TYPES": {10, 14}, "POINTS": {5, 9}, "LINES": {3, 4, 7}} + allowed_widths = {"LINE TYPES": {10, 11, 13, 14}, "POINTS": {5, 9}, "LINES": {3, 4, 7}} # Every row present is checked, also in a line-free deck of bodies and rods: the # native reader parses each table row whether or not a line uses it. for name in sorted(allowed_widths): @@ -2607,6 +2611,10 @@ def numeric(token: str, row: DeckRecord, field: str) -> float: line_type_scales: dict[str, tuple[float, float]] = {} # name -> (BA, max Cd/Ca) line_type_meta: dict[str, tuple[float, float, float, float]] = {} line_type_gj: dict[str, float] = {} # name -> explicit GJ of a 14-column row, else 0 + # Cl > 0 on any LINE TYPES row (native CD_Init_Deck_Aggregate), and on an EI = 0 row + # (native init_one_model, which needs the line's Morison drag in water) + has_viv = False + has_viv_ei0 = False for row in self.line_types: for index in (1, 2, *range(5, len(row.tokens))): numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}") @@ -2658,11 +2666,12 @@ def numeric(token: str, row: DeckRecord, field: str) -> float: f"{self._at(row)}: Syrope BA_s and BA_d must be non-negative " "with a positive sum" ) - # Native append_type: drag and added-mass coefficients (the last four - # columns in either column order) must be non-negative. + # Native append_type: drag and added-mass coefficients (columns 7-10, the last + # four of a 14-column row, in either column order) must be non-negative. + hydro_start = len(row.tokens) - 4 if len(row.tokens) == 14 else 6 hydro = [ numeric(row.tokens[index], row, f"LINE TYPES column {index + 1}") - for index in range(len(row.tokens) - 4, len(row.tokens)) + for index in range(hydro_start, hydro_start + 4) ] if any(value < 0.0 for value in hydro): raise DeckFormatError( @@ -2670,6 +2679,35 @@ def numeric(token: str, row: DeckRecord, field: str) -> float: "(Cd_n Cd_t Ca_n Ca_t) must be non-negative" ) ei = numeric(row.tokens[5], row, "EI") + if len(row.tokens) in (11, 13): + # Native check_viv_columns: MoorDyn's cross-flow VIV columns Cl [dF cF] + cl = numeric(row.tokens[10], row, "Cl") + d_f, c_f = ( + (numeric(row.tokens[11], row, "dF"), numeric(row.tokens[12], row, "cF")) + if len(row.tokens) == 13 + else (0.08, 0.18) + ) + if cl < 0.0: + raise DeckFormatError( + f"{self._at(row)}: LINE TYPES VIV lift coefficient Cl must be " + "non-negative (0 = VIV off)" + ) + if cl > 0.0 and not (c_f > 0.0 and 0.0 <= d_f < c_f): + raise DeckFormatError( + f"{self._at(row)}: LINE TYPES VIV synchronisation band needs cF > 0 " + "and 0 <= dF < cF" + ) + if cl > 0.0 and ei > 0.0: + raise DeckFormatError( + f"{self._at(row)}: VIV (Cl > 0) is implemented for EI = 0 line types only" + ) + if cl > 0.0 and is_syrope: + raise DeckFormatError( + f"{self._at(row)}: VIV (Cl > 0) does not combine with the Syrope " + "working-curve model" + ) + has_viv = has_viv or cl > 0.0 + has_viv_ei0 = has_viv_ei0 or (cl > 0.0 and not ei > 0.0) if ei > 0.0 and (is_syrope or len(ea_parts) > 1): model = "Syrope" if is_syrope else "viscoelastic stiffness" raise DeckFormatError(f"{self._at(row)}: {model} is not supported with EI > 0") @@ -3453,6 +3491,12 @@ def end_key(token: str) -> str: ) if not line_ids: raise DeckFormatError(f"{self._label}: the coupled route needs at least one line") + if has_viv: + raise DeckFormatError( + f"{self._label}: VIV (LINE TYPES Cl > 0) runs in the standalone driver of an " + "EI = 0 deck; the coupled OpenFAST and FAST.Farm routes and mixed EI = 0 / " + "finite-EI decks do not carry it yet. Set Cl = 0 for this run" + ) if self.caller_driven: # native CD_Init_Deck_Aggregate: nothing on the coupled route evaluates deck # waves (the host SeaState supplies them). A deck current is a steady field on a @@ -3472,6 +3516,24 @@ def end_key(token: str) -> str: "single-turbine pure EI=0 deck without Rigid6 bodies or rods; remove the " "deck current OPTION (the host SeaState supplies the current)" ) + if has_viv_ei0 and deck_driver_route: + # native init_one_model: the lift acts with the line's Morison drag, which the + # deck switches on with water (a depth or bathymetry, a current, or waves) + waterkin_option = option_by_key.get("waterkin") + waterkin_text = "" if waterkin_option is None else waterkin_option.values[0] + has_water = ( + has_depth + or has_bathymetry + or has_waves + or bool(trains) + or (current is not None and current.values[0].lower() != "none") + or waterkin_text.lower() not in {"", "0", "none", "seastate"} + ) + if not has_water: + raise DeckFormatError( + f"{self._label}: VIV (LINE TYPES Cl > 0) acts with the line's Morison drag " + "in water: declare WtrDpth (or bathymetryFile), a current or waves" + ) if mixed_route and not self.caller_driven: n_modes_value = option_by_key.get("n_modes") if n_modes_value is not None and round(_native_float(n_modes_value.values[0])) != 0: @@ -4164,9 +4226,11 @@ def _line_type_fields(self, record: DeckRecord) -> tuple[str, ...]: fields = _FIELDS["line_type"] if len(record.tokens) == 14: return (*fields[:6], "gas", "gj", "irt", "irn", "cdn", "cdt", "can", "cat") + # MoorDyn's optional cross-flow VIV columns follow the ten standard ones + viv = {11: ("cl",), 13: ("cl", "df", "cf")}.get(len(record.tokens), ()) if self._stock_line_type_columns(record): - return (*fields[:6], "cd", "ca", "cdax", "caax") - return fields + return (*fields[:6], "cd", "ca", "cdax", "caax", *viv) + return (*fields, *viv) def _line_section_records(self, line_id: int) -> list[tuple[DeckRecord, tuple[str, ...], str]]: """Return one line's native section sequence in deck (End A to End B) order. diff --git a/python/tests/test_builder.py b/python/tests/test_builder.py index c45b3f43..f483ffc1 100644 --- a/python/tests/test_builder.py +++ b/python/tests/test_builder.py @@ -185,6 +185,24 @@ def test_build_single_catenary_validates_and_saves(tmp_path: Path) -> None: assert model.save(target, overwrite=True) == target +def test_viv_columns_do_not_combine_with_the_wide_finite_ei_row(tmp_path: Path) -> None: + model = _chain_model(tmp_path) + model.add_line_type( + "cable", + diam=0.2, + mass=40.0, + ea=5.0e8, + ei=1.0e4, + gas=1.0e8, + gj=1.0e3, + irt=0.1, + irn=0.05, + cl=0.0, + ) + with pytest.raises(ValueError, match="do not combine with gas, gj, irt, irn"): + model.to_text(validate=False) + + def test_build_spread_mooring_with_multi_section_lines() -> None: import math diff --git a/python/tests/test_deck_file.py b/python/tests/test_deck_file.py index 12bc59d3..9f8e7825 100644 --- a/python/tests/test_deck_file.py +++ b/python/tests/test_deck_file.py @@ -4406,7 +4406,7 @@ def test_line_free_object_deck_checks_line_type_rows_without_crashing(): ("1 2 1 -\n", ""), ("1 chain 410.0 41\n", ""), ) - with pytest.raises(DeckFormatError, match="LINE TYPES row needs 10, 14 fields"): + with pytest.raises(DeckFormatError, match="LINE TYPES row needs 10, 11, 13, 14 fields"): DeckFile.from_text(_with_section(no_lines, "BODIES", *body_rows)) # a header-only LINES section does not make the deck a line deck (the rule counts rows) with pytest.raises(DeckFormatError) as caught: @@ -4543,3 +4543,78 @@ def test_coupled_route_keeps_deck_current_only_on_pure_ei0_decks(tmp_path, old, path.write_text(source.replace(old, new), encoding="utf-8") with pytest.raises(DeckFormatError, match="deck current on the coupled route is kept only"): DeckFile.read(path, caller_driven=True) + + +# MoorDyn's optional cross-flow VIV columns: Cl, or Cl dF cF, after the ten standard ones. +_VIV_ROW = "chain 0.252 390.0 1.674e9 -1.0 0.0 1.37 0.64 1.0 0.0" + + +@pytest.mark.parametrize( + "columns, expected", + [ + (" 0.8", (0.8, None, None)), + (" 0.8 0.05 0.2", (0.8, 0.05, 0.2)), + (" 0.0 0.08 0.18", (0.0, 0.08, 0.18)), + ], +) +def test_line_type_viv_columns_are_read_and_kept(tmp_path, columns, expected): + from cabledyn import DeckModel + + text = _edit(_STATIC, (_VIV_ROW, _VIV_ROW + columns)) + DeckFile.from_text(text) + path = tmp_path / "viv.dat" + path.write_text(text, encoding="utf-8") + line_type = DeckModel.load(path).line_types["chain"] + assert (line_type.cl, line_type.df, line_type.cf) == expected + saved = tmp_path / "saved.dat" + DeckModel.load(path).save(saved) + reread = DeckModel.load(saved).line_types["chain"] + # a saved Cl row always writes the band; MoorDyn's defaults fill a Cl-only row + assert (reread.cl, reread.df, reread.cf) == ( + expected[0], + 0.08 if expected[1] is None else expected[1], + 0.18 if expected[2] is None else expected[2], + ) + + +@pytest.mark.parametrize( + "columns, message", + [ + (" -0.1", "Cl must be non-negative"), + (" 0.8 0.2 0.18", "needs cF > 0 and 0 <= dF < cF"), + (" 0.8 0.05 0.0", "needs cF > 0 and 0 <= dF < cF"), + (" 0.8 0.08", "LINE TYPES row needs 10, 11, 13, 14 fields"), + ], +) +def test_line_type_viv_columns_follow_the_native_checks(columns, message): + with pytest.raises(DeckFormatError, match=re.escape(message)): + DeckFile.from_text(_edit(_STATIC, (_VIV_ROW, _VIV_ROW + columns))) + + +def test_line_type_viv_needs_an_ei0_line_type(): + row = "chain 0.252 390.0 1.674e9 -1.0 1.0e4 1.37 0.64 1.0 0.0" + text = _edit(_DYNAMIC, (row, row + " 0.8")) + with pytest.raises(DeckFormatError, match="implemented for EI = 0 line types only"): + DeckFile.from_text(text) + + +def test_viv_is_refused_on_the_coupled_route(): + text = _edit(_STATIC, (_VIV_ROW, _VIV_ROW + " 0.8")) + DeckFile.from_text(text) + with pytest.raises(DeckFormatError, match="runs in the standalone driver"): + DeckFile.from_text(text, caller_driven=True) + + +def test_viv_needs_water_on_an_ei0_line(): + text = _edit(_STATIC, (_VIV_ROW, _VIV_ROW + " 0.8"), ("50.0 WtrDpth\n", "")) + with pytest.raises(DeckFormatError, match="acts with the line's Morison drag in water"): + DeckFile.from_text(text) + # without the lift the same dry deck stays valid + DeckFile.from_text(_edit(_STATIC, ("50.0 WtrDpth\n", ""))) + + +def test_viv_rms_window_option_is_non_negative(): + base = _edit(_STATIC, (_VIV_ROW, _VIV_ROW + " 0.8")) + DeckFile.from_text(_edit(base, ("50.0 WtrDpth\n", "50.0 WtrDpth\n0.25 VIVrmsWindow\n"))) + with pytest.raises(DeckFormatError, match="VIVrmsWindow"): + DeckFile.from_text(_edit(base, ("50.0 WtrDpth\n", "50.0 WtrDpth\n-1.0 VIVrmsWindow\n"))) diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 5e2b639f..fbeca086 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -57,7 +57,7 @@ MODULE CableDyn_DeckDriver CD_Get_Model_EndForces, & CD_Update_Model_CoupledMotion, CD_Update_Model_Hydro_Fields, & CD_Recompute_Model_Acceleration, CD_Step_Model, CD_Step_Model_Recovering, CD_MODEL_OK, & - CD_Audit_Model_Step + CD_Audit_Model_Step, CD_Set_Model_VIV USE CableDyn_System, ONLY: CD_SystemType, CD_SystemPointType, CD_LineEndpointBinding, & CD_Init_System_From_Points, CD_End_System, CD_System_Line_NDOF, & CD_System_Line_NElem, CD_Get_System_Point_State, CD_Get_System_Line_State, & @@ -126,6 +126,7 @@ MODULE CableDyn_DeckDriver CD_HFMF_CalcOutput, CD_HFMF_Snapshot, CD_HFMF_Restore, & CD_HFMF_SetCoupledKinematics, CD_HFMF_GetCoupledKinematics, & CD_HFMF_End, CD_HFMF_OK + USE CableDyn_VIV, ONLY: CD_VIV_DEFAULT_DF, CD_VIV_DEFAULT_CF, CD_VIV_NM USE CableDyn_Hydro, ONLY: CD_Airy_Wave_Kinematics_Precomputed, CD_Component_Wave_Kinematics, & CD_Current_Profile_Velocity, & CD_JONSWAP_COMPONENTS, CD_JONSWAP_Random_Components, & @@ -362,6 +363,11 @@ MODULE CableDyn_DeckDriver REAL(wp), ALLOCATABLE :: syrope_owc_strain(:), syrope_owc_tension(:) ! The OWC table file the settings file names, resolved. CHARACTER(CD_DECK_PATHLEN) :: syrope_owc_file = '' + ! Cross-flow VIV (MoorDyn's optional LINE TYPES columns Cl dF cF, CableDyn_VIV): the lift + ! coefficient (0 = off) and the synchronisation half-range dF and centre cF of the + ! non-dimensional shedding frequency. A row with Cl only takes MoorDyn's dF = 0.08 and + ! cF = 0.18. + REAL(wp) :: cl = CD_ZERO, viv_df = CD_VIV_DEFAULT_DF, viv_cf = CD_VIV_DEFAULT_CF ! Deck file line of the row (0 when not read from a file), for error messages. INTEGER :: deck_line = 0 END TYPE @@ -575,6 +581,10 @@ MODULE CableDyn_DeckDriver ! element stretched beyond this strain (or non-finite) fails the run; 0 disables. REAL(wp) :: max_strain = 0.5_wp LOGICAL :: has_max_strain = .FALSE. + ! Cross-flow VIV (LINE TYPES Cl > 0): averaging time of the running cross-flow RMS values + ! 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 ! 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. @@ -6701,6 +6711,15 @@ SUBROUTINE CD_Init_Deck_Aggregate(deck_path, dt, agg, ErrStat, ErrMsg, env_gravi 'EI=0/finite-EI decks reject deck water kinematics)') RETURN END IF + ! Cross-flow VIV runs in the standalone EI = 0 driver: the aggregate route (OpenFAST, FAST.Farm, + ! mixed EI = 0 / finite-EI decks) neither checkpoints its shedding phase nor feeds it the host's + ! fluid field yet. + IF (ANY(types%cl > CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV (LINE TYPES Cl > 0) runs in the standalone driver of an EI = 0 deck; '// & + 'the coupled OpenFAST and FAST.Farm routes and mixed EI = 0 / finite-EI decks do not carry it '// & + 'yet. Set Cl = 0 for this run') + RETURN + END IF IF (opts%waterkin_seastate) THEN IF (.NOT. PRESENT(external_fluid)) THEN @@ -8389,6 +8408,7 @@ SUBROUTINE init_one_model(ln, sections, types, points, opts, model, ErrStat, Err REAL(wp), ALLOCATABLE :: ba(:), fluid_velocity(:, :), fluid_acceleration(:, :), drag_waterline(:) REAL(wp), ALLOCATABLE :: hydro_diam(:), hydro_cdn(:), hydro_cdt(:), hydro_can(:), hydro_cat(:) REAL(wp), ALLOCATABLE :: ve_ead(:), ve_bas(:), ve_bad(:), ve_ambl(:), ve_vbet(:) + REAL(wp), ALLOCATABLE :: viv_cl(:), viv_cf(:), viv_df(:) REAL(wp) :: anchor(3), fairlead(3) REAL(wp), PARAMETER :: factors(4) = [0.25_wp, 0.5_wp, 0.75_wp, CD_ONE] INTEGER :: j, i, e, es @@ -8425,7 +8445,11 @@ SUBROUTINE init_one_model(ln, sections, types, points, opts, model, ErrStat, Err END IF ALLOCATE (ba(SIZE(l0)), hydro_diam(SIZE(l0)), hydro_cdn(SIZE(l0)), hydro_cdt(SIZE(l0)), & hydro_can(SIZE(l0)), hydro_cat(SIZE(l0)), ve_ead(SIZE(l0)), ve_bas(SIZE(l0)), & - ve_bad(SIZE(l0)), ve_ambl(SIZE(l0)), ve_vbet(SIZE(l0))) + ve_bad(SIZE(l0)), ve_ambl(SIZE(l0)), ve_vbet(SIZE(l0)), viv_cl(SIZE(l0)), viv_cf(SIZE(l0)), & + viv_df(SIZE(l0))) + viv_cl = CD_ZERO + viv_cf = CD_ZERO + viv_df = CD_ZERO ve_ead = CD_ZERO ve_bas = CD_ZERO ve_bad = CD_ZERO @@ -8462,8 +8486,14 @@ SUBROUTINE init_one_model(ln, sections, types, points, opts, model, ErrStat, Err hydro_cdt(e) = types(line_section_type(sections, ln%id, i))%cdt hydro_can(e) = types(line_section_type(sections, ln%id, i))%can hydro_cat(e) = types(line_section_type(sections, ln%id, i))%cat + viv_cl(e) = types(line_section_type(sections, ln%id, i))%cl + viv_cf(e) = types(line_section_type(sections, ln%id, i))%viv_cf + viv_df(e) = types(line_section_type(sections, ln%id, i))%viv_df END DO END DO + viv_cl = viv_cl(SIZE(viv_cl):1:-1) + viv_cf = viv_cf(SIZE(viv_cf):1:-1) + viv_df = viv_df(SIZE(viv_df):1:-1) ba = ba(SIZE(ba):1:-1) ve_ead = ve_ead(SIZE(ve_ead):1:-1) ve_bas = ve_bas(SIZE(ve_bas):1:-1) @@ -8486,6 +8516,9 @@ SUBROUTINE init_one_model(ln, sections, types, points, opts, model, ErrStat, Err syt = line_section_type(sections, ln%id, i2) END DO IF (syt > 0) THEN + IF (ANY(viv_cl > CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV (LINE TYPES Cl > 0) does not combine with a Syrope line'); RETURN + END IF CALL init_one_syrope_model(types, syt, ln, lts, secs, anchor, fairlead, l0, opts, & static_cfg, dynamic_cfg, factors, bathymetry, model, ErrStat, ErrMsg) RETURN @@ -8712,6 +8745,28 @@ SUBROUTINE init_one_model(ln, sections, types, points, opts, model, ErrStat, Err IF (ErrStat /= CD_MODEL_OK) THEN ErrMsg = 'CableDyn_DeckDriver: model init failed: '//TRIM(ErrMsg) IF (ErrStat /= CD_DECKDRV_BADINPUT) ErrStat = CD_DECKDRV_SOLVEFAIL + RETURN + END IF + ! Cross-flow VIV on the Cl > 0 sections (CableDyn_VIV), installed on the initialised line + ! (the static equilibrium carries no lift, as MoorDyn's initial-condition generation), and + ! the initial acceleration recomputed with the t = 0 lift. + IF (ANY(viv_cl > CD_ZERO)) THEN + BLOCK + REAL(wp) :: tw + IF (.NOT. model%has_morison_drag) THEN + CALL fail(ErrStat, ErrMsg, 'VIV (LINE TYPES Cl > 0) acts with the line''s Morison drag in water: '// & + 'declare WtrDpth (or bathymetryFile), a current or waves'); RETURN + END IF + tw = opts%viv_rms_window + IF (.NOT. (tw > CD_ZERO) .AND. opts%has_dtm) tw = REAL(CD_VIV_NM, wp)*opts%dtM + CALL CD_Set_Model_VIV(model, opts%rhoW, viv_cl, hydro_diam, viv_cf, viv_df, tw, es, em) + IF (es == CD_MODEL_OK) CALL CD_Recompute_Model_Acceleration(model, es, em) + IF (es /= CD_MODEL_OK) THEN + ErrStat = CD_DECKDRV_BADINPUT + ErrMsg = 'CableDyn_DeckDriver: VIV setup failed: '//TRIM(em) + RETURN + END IF + END BLOCK END IF END SUBROUTINE init_one_model @@ -12536,9 +12591,10 @@ SUBROUTINE append_type(line, types, nt, stock_cols, ErrStat, ErrMsg) INTEGER :: ios, ntok ErrStat = 0; ErrMsg = '' ntok = count_tokens(line) - IF (ntok /= 10 .AND. ntok /= 14) THEN + IF (ntok /= 10 .AND. ntok /= 11 .AND. ntok /= 13 .AND. ntok /= 14) THEN CALL fail(ErrStat, ErrMsg, 'LINE TYPES row needs 10 cols '// & - '(Name Diam MassDenInAir EA BA/-zeta EI Cd_n Cd_t Ca_n Ca_t) or 14 cols '// & + '(Name Diam MassDenInAir EA BA/-zeta EI Cd_n Cd_t Ca_n Ca_t), 11 or 13 cols (the same '// & + 'followed by MoorDyn''s VIV columns Cl [dF cF]) or 14 cols '// & '(Name Diam MassDenInAir EA BA/-zeta EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t)'); RETURN END IF ! EA and BA read as STRINGS: MoorDyn's viscoelastic syntax carries @@ -12550,6 +12606,24 @@ SUBROUTINE append_type(line, types, nt, stock_cols, ErrStat, ErrMsg) ELSE READ (line, *, IOSTAT=ios) t%name, t%diam, t%mass, ea_str, ba_str, t%ei, t%cdn, t%cdt, t%can, t%cat END IF + ELSE IF (ntok == 11 .OR. ntok == 13) THEN + ! MoorDyn v2's optional cross-flow VIV columns after the ten standard ones: Cl, or + ! Cl dF cF (MoorDyn.f90 line-type parse; dF and cF default to 0.08 and 0.18) + IF (stock_cols) THEN + IF (ntok == 11) THEN + READ (line, *, IOSTAT=ios) t%name, t%diam, t%mass, ea_str, ba_str, t%ei, t%cdn, t%can, t%cdt, t%cat, t%cl + ELSE + READ (line, *, IOSTAT=ios) t%name, t%diam, t%mass, ea_str, ba_str, t%ei, t%cdn, t%can, t%cdt, t%cat, & + t%cl, t%viv_df, t%viv_cf + END IF + ELSE + IF (ntok == 11) THEN + READ (line, *, IOSTAT=ios) t%name, t%diam, t%mass, ea_str, ba_str, t%ei, t%cdn, t%cdt, t%can, t%cat, t%cl + ELSE + READ (line, *, IOSTAT=ios) t%name, t%diam, t%mass, ea_str, ba_str, t%ei, t%cdn, t%cdt, t%can, t%cat, & + t%cl, t%viv_df, t%viv_cf + END IF + END IF ELSE IF (stock_cols) THEN CALL fail(ErrStat, ErrMsg, 'the 14-column LINE TYPES row is a CableDyn form (... Cd_n Cd_t '// & @@ -12569,10 +12643,41 @@ SUBROUTINE append_type(line, types, nt, stock_cols, ErrStat, ErrMsg) END IF CALL parse_stiffness_columns(ea_str, ba_str, t, ErrStat, ErrMsg) IF (ErrStat /= 0) RETURN + IF (ntok == 11 .OR. ntok == 13) THEN + CALL check_viv_columns(t, ErrStat, ErrMsg) + IF (ErrStat /= 0) RETURN + END IF CALL grow_types(types, nt) nt = nt + 1; types(nt) = t END SUBROUTINE append_type + SUBROUTINE check_viv_columns(t, ErrStat, ErrMsg) + !! The VIV columns of a LINE TYPES row: a finite, non-negative Cl; with Cl > 0 a positive + !! shedding frequency band (cF > 0, 0 <= dF < cF) on an EI = 0, non-Syrope line type. + TYPE(DeckLineType), INTENT(IN) :: t + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + ErrStat = 0; ErrMsg = '' + IF (.NOT. (IEEE_IS_FINITE(t%cl) .AND. IEEE_IS_FINITE(t%viv_df) .AND. IEEE_IS_FINITE(t%viv_cf))) THEN + CALL fail(ErrStat, ErrMsg, 'LINE TYPES VIV columns (Cl dF cF) must be finite'); RETURN + END IF + IF (t%cl < CD_ZERO) THEN + CALL fail(ErrStat, ErrMsg, 'LINE TYPES VIV lift coefficient Cl must be non-negative (0 = VIV off)'); RETURN + END IF + IF (.NOT. (t%cl > CD_ZERO)) RETURN + IF (.NOT. (t%viv_cf > CD_ZERO .AND. t%viv_df >= CD_ZERO .AND. t%viv_df < t%viv_cf)) THEN + CALL fail(ErrStat, ErrMsg, 'LINE TYPES VIV synchronisation band needs cF > 0 and 0 <= dF < cF'); RETURN + END IF + IF (t%ei > CD_ZERO) THEN + CALL fail(ErrStat, ErrMsg, 'LINE TYPES "'//TRIM(t%name)//'": VIV (Cl > 0) is implemented for EI = 0 '// & + 'line types only; set EI = 0 or Cl = 0 (VIV of finite-EI cables is not available)'); RETURN + END IF + IF (t%is_syrope) THEN + CALL fail(ErrStat, ErrMsg, 'LINE TYPES "'//TRIM(t%name)//'": VIV (Cl > 0) does not combine with the '// & + 'Syrope working-curve model'); RETURN + END IF + END SUBROUTINE check_viv_columns + SUBROUTINE parse_stiffness_columns(ea_str, ba_str, t, ErrStat, ErrMsg) !! MoorDyn's bar-separated stiffness/damping columns (MoorDyn.f90 line-type !! parse): EA parts select ElasticMod (1 plain; 2 = Es|Ed; 3 = Es|alphaMBL| @@ -14479,6 +14584,8 @@ SUBROUTINE apply_option(line, opts, ErrStat, ErrMsg) CASE ('maxstrain', 'max_strain') CALL rd(val, opts%max_strain, ErrStat, ErrMsg) opts%has_max_strain = ErrStat == 0 + CASE ('vivrmswindow', 'viv_rms_window') + CALL rd(val, opts%viv_rms_window, ErrStat, ErrMsg) CASE ('streamorder', 'stream_order') CALL rd(val, x1, ErrStat, ErrMsg) IF (ErrStat == 0) THEN @@ -14948,7 +15055,7 @@ SUBROUTINE check_option_row_value(kw, val, ErrStat, ErrMsg) CASE ('g', 'gravity', 'rhow', 'wtrdnsty', 'water_density', 'wtrdpth', 'water_depth', 'dtm', 'dt', 'dtwave') rule = 'positive' CASE ('tmax', 'tensile_strain_tolerance', 'tensilestraintolerance', 'ramptime', 'ramp_time', 'tramp', & - 'maxstrain', 'max_strain', 'rangestart', 'range_start') + 'maxstrain', 'max_strain', 'rangestart', 'range_start', 'vivrmswindow', 'viv_rms_window') rule = 'non-negative' CASE ('frictionmu', 'mu', 'frictioncoefficient') IF (to_lower(TRIM(val)) == 'none') RETURN diff --git a/src/CableDyn_Hydro.f90 b/src/CableDyn_Hydro.f90 index 2e033c65..1f4287b5 100644 --- a/src/CableDyn_Hydro.f90 +++ b/src/CableDyn_Hydro.f90 @@ -53,6 +53,7 @@ MODULE CableDyn_Hydro PUBLIC :: CD_Added_Mass_Element PUBLIC :: CD_Added_Mass_Element_Matrix PUBLIC :: CD_Added_Mass_Element_Force + PUBLIC :: CD_Submerged_Fraction INTEGER, PARAMETER :: CD_HYDRO_OK = 0 INTEGER, PARAMETER :: CD_HYDRO_BADINPUT = 1 @@ -2530,6 +2531,14 @@ SUBROUTINE scatter_mass_block(M, node_row, node_col, block) END DO END SUBROUTINE scatter_mass_block + SUBROUTINE CD_Submerged_Fraction(za, zb, fraction) + !! Wetted fraction of a straight element whose end heights above the local waterline + !! are za and zb: the convention every element load of this module uses. + REAL(wp), INTENT(IN) :: za, zb + REAL(wp), INTENT(OUT) :: fraction + CALL submerged_fraction_only(za, zb, fraction) + END SUBROUTINE CD_Submerged_Fraction + SUBROUTINE submerged_fraction_only(za, zb, fraction) REAL(wp), INTENT(IN) :: za, zb REAL(wp), INTENT(OUT) :: fraction diff --git a/src/CableDyn_Model.f90 b/src/CableDyn_Model.f90 index c89dde2d..a1ca388c 100644 --- a/src/CableDyn_Model.f90 +++ b/src/CableDyn_Model.f90 @@ -54,7 +54,10 @@ MODULE CableDyn_Model CD_Cable_Buoyancy_Recovery_Load, CD_Cable_Buoyancy_Recovery_Force, & CD_Buoyancy_Recovery_Element_Load, CD_Buoyancy_Recovery_Element_Force, & CD_Cable_Added_Mass, CD_Cable_Added_Mass_Matrix, CD_Cable_Added_Mass_Force, & - CD_Added_Mass_Element, CD_Added_Mass_Element_Matrix, CD_Added_Mass_Element_Force + CD_Added_Mass_Element, CD_Added_Mass_Element_Matrix, CD_Added_Mass_Element_Force, & + CD_Submerged_Fraction + USE CableDyn_VIV, ONLY: CD_VIV_Node_Lift, CD_VIV_Crossflow_Motion, CD_VIV_Phase_Rate, CD_VIV_Mean_Square, & + CD_VIV_Wrap_Phase, CD_VIV_NM, CD_VIV_TWO_PI USE CableDyn_Dynamic, ONLY: GenAlphaConfig, CD_CableGenAlphaWorkspace, CD_Clear_GenAlpha_Workspace, & CD_Cable_Initial_Acceleration, CD_Cable_Gen_Alpha_Step, CD_DYN_OK, CD_DYN_ALLOCFAIL, & CD_EI0_SUBSTEPS_AUTO, CD_EI0_SUBSTEPS_OFF @@ -91,6 +94,8 @@ MODULE CableDyn_Model PUBLIC :: CD_Set_Model_Friction_Axial PUBLIC :: CD_Get_Model_Syrope_State PUBLIC :: CD_Set_Model_Syrope_State + PUBLIC :: CD_Set_Model_VIV + PUBLIC :: CD_Latch_Model_VIV_Window PUBLIC :: CD_Get_Model_Tension PUBLIC :: CD_Get_Model_EndForces PUBLIC :: CD_Get_Model_EndNodeMassDiag @@ -144,7 +149,7 @@ MODULE CableDyn_Model ! slots. commit_state_copy holds the one list of that state. TYPE :: CD_ModelCommitSlot REAL(wp), ALLOCATABLE :: q(:), v(:), a(:), ve_dl_1(:), syrope_slow(:), syrope_tmax(:) - REAL(wp), ALLOCATABLE :: fr_anchor(:, :), l0_c(:), l0_dot_c(:) + REAL(wp), ALLOCATABLE :: fr_anchor(:, :), l0_c(:), l0_dot_c(:), viv_phi(:), viv_ms(:, :) END TYPE CD_ModelCommitSlot ! Diagnostics of the rotation- and snap-resolved sub-stepping (CD_Step_Model): calls counts @@ -369,6 +374,29 @@ MODULE CableDyn_Model REAL(wp), ALLOCATABLE :: added_mass_diameter_elem(:) REAL(wp), ALLOCATABLE :: added_mass_can_elem(:) REAL(wp), ALLOCATABLE :: added_mass_cat_elem(:) + ! Cross-flow vortex-induced vibration (CableDyn_VIV; MoorDyn LINE TYPES Cl dF cF), + ! installed by CD_Set_Model_VIV after initialisation. Per element: the lift coefficient + ! viv_cl (0 = no lift on that element) and diameter viv_d; viv_rho the water density. + ! Per node: viv_node marks an interior free node next to a Cl > 0 element, with the + ! synchronisation centre/range viv_cf/viv_df and diameter viv_dn (averaged over the + ! node's Cl > 0 elements, weighted by unstretched length). The STATE is the shedding + ! phase viv_phi and the running mean squares of the cross-flow velocity and + ! acceleration viv_ms(1:2, node), with their system-rollback and step-recovery twins. + ! viv_tw is the averaging time of the mean squares [s]; 0 until CD_Latch_Model_VIV_Window + ! (or the first step) sets MoorDyn's 500 steps. viv_phi_eval is the phase the lift + ! contributor uses: the committed phase, except inside CD_Step_Model, where it is the + ! 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. + REAL(wp) :: viv_rho = CD_ZERO + REAL(wp) :: viv_tw = CD_ZERO + REAL(wp), ALLOCATABLE :: viv_cl(:), viv_d(:) + LOGICAL, ALLOCATABLE :: viv_node(:) + REAL(wp), ALLOCATABLE :: viv_cf(:), viv_df(:), viv_dn(:) + REAL(wp), ALLOCATABLE :: viv_phi(:), viv_ms(:, :) + REAL(wp), ALLOCATABLE :: viv_phi_rollback(:), viv_ms_rollback(:, :) + REAL(wp), ALLOCATABLE :: recovery_viv_phi(:), recovery_viv_ms(:, :) + REAL(wp), ALLOCATABLE :: viv_phi_eval(:), viv_rate(:), viv_ms_next(:, :), viv_phi_next(:) TYPE(GenAlphaConfig) :: cfg ! Run audit of the committed host steps (CD_Audit_Model_Step), diagnostics only: never part ! of the state, of a copy, or of a result. audit_t holds the segment tensions of the last two @@ -2213,6 +2241,13 @@ LOGICAL FUNCTION sub_alloc(model, has_pres) RESULT(ok) IF (istat /= 0) RETURN END IF END IF + IF (model%has_viv) THEN + IF (.NOT. sized(s%viv_phi, SIZE(model%viv_phi))) THEN + IF (ALLOCATED(s%viv_phi)) DEALLOCATE (s%viv_phi, s%viv_ms) + ALLOCATE (s%viv_phi(SIZE(model%viv_phi)), s%viv_ms(2, SIZE(model%viv_phi)), STAT=istat) + IF (istat /= 0) RETURN + END IF + END IF END ASSOCIATE END DO IF (.NOT. sized(model%sub_t0, model%n_elem)) THEN @@ -2243,11 +2278,11 @@ END FUNCTION sized END FUNCTION sub_alloc SUBROUTINE commit_state_copy(model, to_model, q, v, a, ve_dl_1, syrope_slow, syrope_tmax, fr_anchor, & - l0_c, l0_dot_c) + l0_c, l0_dot_c, viv_phi, viv_ms) !! The one list of the state a line step commits: the kinematics, the viscoelastic dl_1, the - !! Syrope slow strain and running maximum tension, the friction anchors, and the unstretched + !! Syrope slow strain and running maximum tension, the friction anchors, the unstretched !! lengths and rates the committed state was reached with (l0_c, l0_dot_c, active line - !! control). to_model = + !! control), and the VIV shedding phases and running mean squares. to_model = !! .FALSE. saves the model's state into the arrays given, .TRUE. returns the model to them. !! Every snapshot of the committed state in this module goes through here (the sub-step !! slots of CD_Step_Model, save_recovery_state and restore_recovery_state). A state a step @@ -2260,7 +2295,7 @@ SUBROUTINE commit_state_copy(model, to_model, q, v, a, ve_dl_1, syrope_slow, syr LOGICAL, INTENT(IN) :: to_model REAL(wp), INTENT(INOUT) :: q(:), v(:), a(:) REAL(wp), INTENT(INOUT), OPTIONAL :: ve_dl_1(:), syrope_slow(:), syrope_tmax(:), fr_anchor(:, :) - REAL(wp), INTENT(INOUT), OPTIONAL :: l0_c(:), l0_dot_c(:) + REAL(wp), INTENT(INOUT), OPTIONAL :: l0_c(:), l0_dot_c(:), viv_phi(:), viv_ms(:, :) IF (to_model) THEN model%q = q model%v = v @@ -2275,6 +2310,11 @@ SUBROUTINE commit_state_copy(model, to_model, q, v, a, ve_dl_1, syrope_slow, syr model%l0_c = l0_c model%l0_dot_c = l0_dot_c END IF + IF (model%has_viv .AND. PRESENT(viv_phi) .AND. PRESENT(viv_ms)) THEN + model%viv_phi = viv_phi + model%viv_ms = viv_ms + model%viv_phi_eval = viv_phi + END IF ELSE q = model%q v = model%v @@ -2289,6 +2329,10 @@ SUBROUTINE commit_state_copy(model, to_model, q, v, a, ve_dl_1, syrope_slow, syr l0_c = model%l0_c l0_dot_c = model%l0_dot_c END IF + IF (model%has_viv .AND. PRESENT(viv_phi) .AND. PRESENT(viv_ms)) THEN + viv_phi = model%viv_phi + viv_ms = model%viv_ms + END IF END IF END SUBROUTINE commit_state_copy @@ -2299,7 +2343,8 @@ SUBROUTINE sub_store(model, slot) CALL commit_state_copy(model, .FALSE., model%sub_slot(slot)%q, model%sub_slot(slot)%v, model%sub_slot(slot)%a, & model%sub_slot(slot)%ve_dl_1, model%sub_slot(slot)%syrope_slow, & model%sub_slot(slot)%syrope_tmax, model%sub_slot(slot)%fr_anchor, & - model%sub_slot(slot)%l0_c, model%sub_slot(slot)%l0_dot_c) + model%sub_slot(slot)%l0_c, model%sub_slot(slot)%l0_dot_c, & + model%sub_slot(slot)%viv_phi, model%sub_slot(slot)%viv_ms) END SUBROUTINE sub_store SUBROUTINE sub_load(model, slot) @@ -2309,7 +2354,8 @@ SUBROUTINE sub_load(model, slot) CALL commit_state_copy(model, .TRUE., model%sub_slot(slot)%q, model%sub_slot(slot)%v, model%sub_slot(slot)%a, & model%sub_slot(slot)%ve_dl_1, model%sub_slot(slot)%syrope_slow, & model%sub_slot(slot)%syrope_tmax, model%sub_slot(slot)%fr_anchor, & - model%sub_slot(slot)%l0_c, model%sub_slot(slot)%l0_dot_c) + model%sub_slot(slot)%l0_c, model%sub_slot(slot)%l0_dot_c, & + model%sub_slot(slot)%viv_phi, model%sub_slot(slot)%viv_ms) END SUBROUTINE sub_load SUBROUTINE sub_lengths_target(model) @@ -2584,7 +2630,7 @@ SUBROUTINE step_model_plain(model, dt, converged, stalled, n_iter, ErrStat, ErrM has_load = model%has_seabed .OR. model%has_seabed_damping .OR. model%has_seabed_friction .OR. & model%has_damping .OR. model%has_viscoelastic .OR. model%has_syrope .OR. model%has_morison_drag .OR. & - model%has_froude_krylov .OR. model%has_buoyancy_recovery + model%has_froude_krylov .OR. model%has_buoyancy_recovery .OR. model%has_viv ! Force-blended generalised alpha: the load contributors at the committed state (q_n, v_n) ! carry the alpha_f share of the residual. They are evaluated here, in the instantaneous ! limit (ve_dt = 0), so the viscoelastic and Syrope elements give their committed force, @@ -2622,6 +2668,22 @@ SUBROUTINE step_model_plain(model, dt, converged, stalled, n_iter, ErrStat, ErrM CALL step_start_load(ErrStat, ErrMsg) IF (force_lengths) CALL leave_committed_lengths(model, aside) IF (ErrStat /= CD_MODEL_OK) RETURN + ! VIV: phase rate and mean squares at the step-start state (after the committed-state + ! load above, which takes the committed phase), and the explicit phase for the in-step + ! lift (see viv_step_begin). Nothing is + ! committed until the step succeeds; viv_phi_eval returns to the committed phase on + ! every exit, as ve_dt below. + IF (model%has_viv) THEN + IF (.NOT. (CD_Is_Finite(dt) .AND. dt > CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'dt must be finite and positive') + RETURN + END IF + CALL viv_step_begin(model, dt, ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) THEN + model%viv_phi_eval = model%viv_phi + RETURN + END IF + END IF ! arm the viscoelastic contributors with the step size: in-step load ! evaluations use the backward-Euler-eliminated dl_1(q, v); it is reset to ! the instantaneous limit (0) on EVERY exit below so committed-state queries @@ -2737,6 +2799,7 @@ SUBROUTINE step_model_plain(model, dt, converged, stalled, n_iter, ErrStat, ErrM IF (ALLOCATED(l0_dot_new)) model%l0_dot = l0_dot_new IF (ALLOCATED(f_ext_new)) model%f_ext = f_ext_new model%ve_dt = CD_ZERO + IF (model%has_viv) model%viv_phi_eval = model%viv_phi CALL CD_Profile_Count_Line_Step(n_iter) IF (es /= CD_DYN_OK) THEN ErrStat = model_status_from_dyn(es) @@ -2806,6 +2869,14 @@ SUBROUTINE step_model_plain(model, dt, converged, stalled, n_iter, ErrStat, ErrM RETURN END IF END IF + ! VIV pass 1: the end-of-step phase (Heun) into viv_phi_next; committed below. + IF (model%has_viv) THEN + CALL viv_step_end(model, dt, ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) THEN + converged = .FALSE. + RETURN + END IF + END IF IF (model%has_viscoelastic) THEN ! Pass 2 (mutate): commit dl_1 from the SAME lagged coefficients the in-step ! loads used (mode 3 reads the still-committed dl_1). Validated above, so no @@ -2859,6 +2930,13 @@ SUBROUTINE step_model_plain(model, dt, converged, stalled, n_iter, ErrStat, ErrM END DO END BLOCK END IF + IF (model%has_viv) THEN + ! VIV pass 2 (mutate): the phase and the mean squares updated with the step-start + ! sample (the next step starts by adding its own sample, the end state of this one) + model%viv_phi = model%viv_phi_next + model%viv_ms = model%viv_ms_next + model%viv_phi_eval = model%viv_phi + END IF model%q = model%q_step model%v = model%v_step model%a = model%a_step @@ -3049,6 +3127,8 @@ SUBROUTINE CD_Step_Model_Recovering(model, dt, converged, stalled, n_iter, ErrSt RETURN END IF + ! MoorDyn's VIV averaging window counts NOMINAL steps: latch it before any subdivision + IF (model%has_viv) CALL CD_Latch_Model_VIV_Window(model, dt) CALL save_recovery_state(model) hmax0 = model%audit_hmax stats0 = model%sub_stats @@ -3272,7 +3352,8 @@ SUBROUTINE save_recovery_state(model) TYPE(CD_ModelType), INTENT(INOUT) :: model CALL commit_state_copy(model, .FALSE., model%recovery_q0, model%recovery_v0, model%recovery_a0, & model%recovery_ve_dl_1, model%recovery_syrope_slow, model%recovery_syrope_tmax, & - model%recovery_fr_anchor, model%recovery_l0_c, model%recovery_l0_dot_c) + model%recovery_fr_anchor, model%recovery_l0_c, model%recovery_l0_dot_c, & + model%recovery_viv_phi, model%recovery_viv_ms) END SUBROUTINE save_recovery_state SUBROUTINE restore_recovery_state(model) @@ -3280,7 +3361,8 @@ SUBROUTINE restore_recovery_state(model) TYPE(CD_ModelType), INTENT(INOUT) :: model CALL commit_state_copy(model, .TRUE., model%recovery_q0, model%recovery_v0, model%recovery_a0, & model%recovery_ve_dl_1, model%recovery_syrope_slow, model%recovery_syrope_tmax, & - model%recovery_fr_anchor, model%recovery_l0_c, model%recovery_l0_dot_c) + model%recovery_fr_anchor, model%recovery_l0_c, model%recovery_l0_dot_c, & + model%recovery_viv_phi, model%recovery_viv_ms) model%ve_dt = CD_ZERO END SUBROUTINE restore_recovery_state @@ -3775,6 +3857,282 @@ 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) + !! 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; + !! 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), the mean squares at 0. + !! 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). + TYPE(CD_ModelType), INTENT(INOUT) :: model + REAL(wp), INTENT(IN) :: rho, cl(:), diameter(:), cf(:), df(:), t_window + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + INTEGER :: n_nodes, n_elem, e, nd, istat, k + REAL(wp) :: wsum + + ErrStat = CD_MODEL_OK + ErrMsg = '' + IF (.NOT. model%initialized) THEN + ErrStat = CD_MODEL_NOT_INITIALIZED + ErrMsg = 'CableDyn_Model: model is not initialized' + RETURN + END IF + n_elem = model%n_elem + n_nodes = model%n_dof/3 + IF (SIZE(cl) /= n_elem .OR. SIZE(diameter) /= n_elem .OR. SIZE(cf) /= n_elem .OR. SIZE(df) /= n_elem) THEN + CALL fail(ErrStat, ErrMsg, 'VIV cl, diameter, cf and df must each have shape (n_elem)') + RETURN + END IF + IF (.NOT. (CD_All_Finite(cl) .AND. CD_All_Finite(diameter) .AND. CD_All_Finite(cf) .AND. & + CD_All_Finite(df))) THEN + CALL fail(ErrStat, ErrMsg, 'VIV coefficients must be finite') + RETURN + END IF + IF (ANY(cl < CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV lift coefficient Cl must be non-negative') + RETURN + END IF + IF (.NOT. (CD_Is_Finite(t_window) .AND. t_window >= CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV averaging time must be finite and non-negative') + RETURN + END IF + CALL clear_viv(model) + IF (.NOT. ANY(cl > CD_ZERO)) RETURN + IF (.NOT. (CD_Is_Finite(rho) .AND. rho > CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV water density must be finite and positive') + RETURN + END IF + DO e = 1, n_elem + IF (.NOT. (cl(e) > CD_ZERO)) CYCLE + IF (.NOT. (diameter(e) > CD_ZERO)) THEN + CALL fail(ErrStat, ErrMsg, 'VIV needs a positive diameter on every Cl > 0 element') + RETURN + END IF + IF (.NOT. (cf(e) > CD_ZERO .AND. df(e) >= CD_ZERO .AND. df(e) < cf(e))) THEN + CALL fail(ErrStat, ErrMsg, 'VIV synchronisation needs cF > 0 and 0 <= dF < cF (a positive '// & + 'shedding frequency)') + RETURN + END IF + END DO + DO e = 1, n_elem + IF (model%elem_conn(1, e) /= e .OR. model%elem_conn(2, e) /= e + 1) THEN + CALL fail(ErrStat, ErrMsg, 'VIV needs a single-chain line mesh (element e joining nodes e and e+1)') + RETURN + END IF + END DO + ALLOCATE (model%viv_cl(n_elem), model%viv_d(n_elem), model%viv_node(n_nodes), model%viv_cf(n_nodes), & + model%viv_df(n_nodes), model%viv_dn(n_nodes), model%viv_phi(n_nodes), model%viv_ms(2, n_nodes), & + model%viv_phi_rollback(n_nodes), model%viv_ms_rollback(2, n_nodes), & + model%recovery_viv_phi(n_nodes), model%recovery_viv_ms(2, n_nodes), & + model%viv_phi_eval(n_nodes), model%viv_rate(n_nodes), model%viv_ms_next(2, n_nodes), & + model%viv_phi_next(n_nodes), STAT=istat) + IF (istat /= 0) THEN + CALL clear_viv(model) + CALL alloc_fail(ErrStat, ErrMsg, 'VIV storage allocation failed') + RETURN + END IF + model%viv_rho = rho + model%viv_tw = t_window + model%viv_cl = MERGE(cl, CD_ZERO, cl > CD_ZERO) + model%viv_d = MERGE(diameter, CD_ZERO, cl > CD_ZERO) + model%viv_node = .FALSE. + model%viv_cf = CD_ZERO + model%viv_df = CD_ZERO + model%viv_dn = CD_ZERO + model%viv_phi = CD_ZERO + model%viv_ms = CD_ZERO + DO nd = 2, n_nodes - 1 + IF (.NOT. (cl(nd - 1) > CD_ZERO .OR. cl(nd) > CD_ZERO)) CYCLE + IF (ANY(model%fixed_dofs >= 3*nd - 2 .AND. model%fixed_dofs <= 3*nd)) CYCLE + model%viv_node(nd) = .TRUE. + wsum = CD_ZERO + DO k = nd - 1, nd + IF (.NOT. (cl(k) > CD_ZERO)) CYCLE + wsum = wsum + model%l0(k) + model%viv_cf(nd) = model%viv_cf(nd) + model%l0(k)*cf(k) + model%viv_df(nd) = model%viv_df(nd) + model%l0(k)*df(k) + model%viv_dn(nd) = model%viv_dn(nd) + model%l0(k)*diameter(k) + END DO + model%viv_cf(nd) = model%viv_cf(nd)/wsum + 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) + END DO + model%viv_phi_rollback = model%viv_phi + model%viv_ms_rollback = model%viv_ms + model%recovery_viv_phi = model%viv_phi + model%recovery_viv_ms = model%viv_ms + model%viv_phi_eval = model%viv_phi + model%viv_rate = CD_ZERO + model%viv_ms_next = model%viv_ms + model%viv_phi_next = model%viv_phi + model%has_viv = .TRUE. + END SUBROUTINE CD_Set_Model_VIV + + SUBROUTINE CD_Latch_Model_VIV_Window(model, dt) + !! Fix MoorDyn's default VIV averaging time, 500 steps of the nominal step dt, unless the + !! model already has one (a deck VIVrmsWindow or an earlier latch). Callers that subdivide + !! a step latch with the nominal step before subdividing; otherwise the first step does. + TYPE(CD_ModelType), INTENT(INOUT) :: model + REAL(wp), INTENT(IN) :: dt + IF (.NOT. model%has_viv) RETURN + IF (model%viv_tw > CD_ZERO) RETURN + IF (.NOT. (CD_Is_Finite(dt) .AND. dt > CD_ZERO)) RETURN + model%viv_tw = REAL(CD_VIV_NM, wp)*dt + END SUBROUTINE CD_Latch_Model_VIV_Window + + SUBROUTINE viv_node_coef(model, q, nd, coef, uu) + !! Lift scale of interior node nd at positions q, sum over its two elements of + !! (1/2 l0_e w_e)(1/2 rho D_e Cl_e) with w_e the wetted fraction under the drag waterline + !! (as MoorDyn's 1/4 rho d Cl (F_i l_i + F_i+1 l_i+1)), and the ambient fluid velocity there. + TYPE(CD_ModelType), INTENT(IN) :: model + REAL(wp), INTENT(IN) :: q(:) + INTEGER, INTENT(IN) :: nd + REAL(wp), INTENT(OUT) :: coef, uu(3) + INTEGER :: e + REAL(wp) :: wla, wlb, frac + coef = CD_ZERO + DO e = nd - 1, nd + IF (.NOT. (model%viv_cl(e) > CD_ZERO)) CYCLE + wla = CD_ZERO + wlb = CD_ZERO + IF (ALLOCATED(model%drag_waterline_z)) THEN + wla = model%drag_waterline_z(e) + wlb = model%drag_waterline_z(e + 1) + END IF + CALL CD_Submerged_Fraction(q(3*e) - wla, q(3*e + 3) - wlb, frac) + coef = coef + 0.25_wp*model%viv_rho*model%viv_d(e)*model%viv_cl(e)*model%l0(e)*frac + END DO + uu = CD_ZERO + IF (ALLOCATED(model%fluid_velocity)) uu = model%fluid_velocity(:, nd) + END SUBROUTINE viv_node_coef + + SUBROUTINE viv_step_begin(model, dt, ErrStat, ErrMsg) + !! Step-start VIV quantities from the committed state (q_n, v_n, a_n, phi_n): the mean + !! squares with the step-start cross-flow sample (viv_ms_next), the phase rate + !! (viv_rate), and the explicit phase the in-step lift uses (viv_phi_eval): at t_{n+1}, + !! phi_n + dt rate_n, under the force blend, whose in-step force is r(q_{n+1}, v_{n+1}) + !! (the committed-state force F_n keeps phi_n); at the generalised-alpha level, + !! phi_n + (1 - alpha_f) dt rate_n, under the configuration blend. + TYPE(CD_ModelType), INTENT(INOUT) :: model + REAL(wp), INTENT(IN) :: dt + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + INTEGER :: nd, ia + REAL(wp) :: w, alpha_f, yd, ydd, un, coef, uu(3) + LOGICAL :: ok + ErrStat = CD_MODEL_OK + ErrMsg = '' + CALL CD_Latch_Model_VIV_Window(model, dt) + w = MIN(CD_ONE, dt/model%viv_tw) + alpha_f = model%cfg%rho_inf/(model%cfg%rho_inf + CD_ONE) + IF (model%cfg%force_blend) alpha_f = CD_ZERO + model%viv_rate = CD_ZERO + model%viv_ms_next = model%viv_ms + model%viv_phi_eval = model%viv_phi + DO nd = 2, model%n_dof/3 - 1 + IF (.NOT. model%viv_node(nd)) CYCLE + CALL viv_node_coef(model, model%q, nd, coef, uu) + ia = 3*nd - 2 + CALL CD_VIV_Crossflow_Motion(model%q(ia - 3:ia - 1), model%q(ia + 3:ia + 5), smoothed(model%v, ia), & + smoothed(model%a, ia), uu, yd, ydd, un, ok) + IF (.NOT. ok) THEN + CALL fail(ErrStat, ErrMsg, 'VIV phase: the neighbours of a node coincide (no line tangent)') + RETURN + END IF + model%viv_ms_next(1, nd) = CD_VIV_Mean_Square(model%viv_ms(1, nd), yd, w) + 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_phi_eval(nd) = model%viv_phi(nd) + (CD_ONE - alpha_f)*dt*model%viv_rate(nd) + END DO + END SUBROUTINE viv_step_begin + + SUBROUTINE viv_step_end(model, dt, ErrStat, ErrMsg) + !! End-of-step VIV phase by Heun's rule (the trapezoidal corrector of the explicit Euler + !! predictor): phi_n+1 = phi_n + dt/2 (rate_n + rate(state_n+1, phi_n + dt rate_n)), with + !! the end-state cross-flow sample added to the mean squares for that rate (not stored: + !! the next step adds it itself). Writes viv_phi_next only. + TYPE(CD_ModelType), INTENT(INOUT) :: model + REAL(wp), INTENT(IN) :: dt + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + INTEGER :: nd, ia + REAL(wp) :: w, yd, ydd, un, coef, uu(3), ms1, ms2, rate_end + LOGICAL :: ok + ErrStat = CD_MODEL_OK + ErrMsg = '' + w = MIN(CD_ONE, dt/model%viv_tw) + model%viv_phi_next = model%viv_phi + DO nd = 2, model%n_dof/3 - 1 + IF (.NOT. model%viv_node(nd)) CYCLE + CALL viv_node_coef(model, model%q_step, nd, coef, uu) + ia = 3*nd - 2 + CALL CD_VIV_Crossflow_Motion(model%q_step(ia - 3:ia - 1), model%q_step(ia + 3:ia + 5), & + smoothed(model%v_step, ia), smoothed(model%a_step, ia), uu, yd, ydd, un, ok) + IF (.NOT. ok) THEN + CALL fail(ErrStat, ErrMsg, 'VIV phase: the neighbours of a node coincide (no line tangent)') + RETURN + END IF + 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_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 + CALL fail(ErrStat, ErrMsg, 'VIV phase update produced a non-finite phase') + END IF + END SUBROUTINE viv_step_end + + PURE FUNCTION smoothed(x, ia) RESULT(xs) + !! Node kinematics for the VIV phase and lift: the node value averaged with its two + !! neighbours, (x_{i-1} + 2 x_i + x_{i+1})/4, at the node whose x component is ia. Thorsen's + !! model follows the cross-flow motion of a continuum. The node's own acceleration weights + !! the mesh-scale zig-zag mode (neighbours moving opposite to the node) by omega^2, so at + !! steps that resolve that mode it took over the phase, and through the lift the phase + !! pumped the 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). The lift takes the + !! smoothed velocity as well: through its dependence on the node's own velocity, modulated by + !! the phase, the zig-zag mode was pumped even with a smoothed phase. + REAL(wp), INTENT(IN) :: x(:) + INTEGER, INTENT(IN) :: ia + REAL(wp) :: xs(3) + xs = 0.25_wp*(x(ia - 3:ia - 1) + 2.0_wp*x(ia:ia + 2) + x(ia + 3:ia + 5)) + END FUNCTION smoothed + + SUBROUTINE clear_viv(model) + !! Release the VIV storage; the model then carries no VIV. + TYPE(CD_ModelType), INTENT(INOUT) :: model + IF (ALLOCATED(model%viv_cl)) DEALLOCATE (model%viv_cl) + IF (ALLOCATED(model%viv_d)) DEALLOCATE (model%viv_d) + IF (ALLOCATED(model%viv_node)) DEALLOCATE (model%viv_node) + IF (ALLOCATED(model%viv_cf)) DEALLOCATE (model%viv_cf) + IF (ALLOCATED(model%viv_df)) DEALLOCATE (model%viv_df) + IF (ALLOCATED(model%viv_dn)) DEALLOCATE (model%viv_dn) + IF (ALLOCATED(model%viv_phi)) DEALLOCATE (model%viv_phi) + IF (ALLOCATED(model%viv_ms)) DEALLOCATE (model%viv_ms) + IF (ALLOCATED(model%viv_phi_rollback)) DEALLOCATE (model%viv_phi_rollback) + IF (ALLOCATED(model%viv_ms_rollback)) DEALLOCATE (model%viv_ms_rollback) + IF (ALLOCATED(model%recovery_viv_phi)) DEALLOCATE (model%recovery_viv_phi) + IF (ALLOCATED(model%recovery_viv_ms)) DEALLOCATE (model%recovery_viv_ms) + IF (ALLOCATED(model%viv_phi_eval)) DEALLOCATE (model%viv_phi_eval) + IF (ALLOCATED(model%viv_rate)) DEALLOCATE (model%viv_rate) + IF (ALLOCATED(model%viv_ms_next)) DEALLOCATE (model%viv_ms_next) + IF (ALLOCATED(model%viv_phi_next)) DEALLOCATE (model%viv_phi_next) + model%has_viv = .FALSE. + model%viv_rho = CD_ZERO + model%viv_tw = CD_ZERO + END SUBROUTINE clear_viv + SUBROUTINE CD_Set_Model_Friction_Axial(model, mu_axial, ErrStat, ErrMsg) !! Make the stick-slip seabed friction of a model anisotropic: the model's seabed_mu !! becomes the lateral coefficient and mu_axial the coefficient along the line (the @@ -5517,7 +5875,7 @@ SUBROUTINE recompute_model_acceleration_now(model, ErrStat, ErrMsg) END IF has_load = model%has_seabed .OR. model%has_seabed_damping .OR. model%has_seabed_friction .OR. & model%has_damping .OR. model%has_viscoelastic .OR. model%has_syrope .OR. model%has_morison_drag .OR. & - model%has_froude_krylov .OR. model%has_buoyancy_recovery + model%has_froude_krylov .OR. model%has_buoyancy_recovery .OR. model%has_viv nc = SIZE(model%fixed_dofs) prescribed_workspace_ready = ALLOCATED(model%a_prescribed_work) IF (prescribed_workspace_ready) prescribed_workspace_ready = SIZE(model%a_prescribed_work) >= nc @@ -6055,6 +6413,7 @@ SUBROUTINE CD_End_Model(model, ErrStat, ErrMsg) IF (ALLOCATED(model%added_mass_diameter_elem)) DEALLOCATE (model%added_mass_diameter_elem) IF (ALLOCATED(model%added_mass_can_elem)) DEALLOCATE (model%added_mass_can_elem) IF (ALLOCATED(model%added_mass_cat_elem)) DEALLOCATE (model%added_mass_cat_elem) + CALL clear_viv(model) model%initialized = .FALSE. model%tension_only = .FALSE. model%has_seabed = .FALSE. @@ -6318,6 +6677,41 @@ SUBROUTINE CD_Copy_Model(src, dst, ErrStat, ErrMsg) IF (ErrStat /= CD_MODEL_OK) RETURN CALL copy_real1(src%added_mass_cat_elem, work%added_mass_cat_elem, 'added_mass_cat_elem', ErrStat, ErrMsg) IF (ErrStat /= CD_MODEL_OK) RETURN + work%has_viv = src%has_viv + work%viv_rho = src%viv_rho + work%viv_tw = src%viv_tw + 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) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_logical1(src%viv_node, work%viv_node, 'viv_node', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_cf, work%viv_cf, 'viv_cf', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_df, work%viv_df, 'viv_df', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_dn, work%viv_dn, 'viv_dn', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_phi, work%viv_phi, 'viv_phi', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real2(src%viv_ms, work%viv_ms, 'viv_ms', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_phi_rollback, work%viv_phi_rollback, 'viv_phi_rollback', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real2(src%viv_ms_rollback, work%viv_ms_rollback, 'viv_ms_rollback', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%recovery_viv_phi, work%recovery_viv_phi, 'recovery_viv_phi', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real2(src%recovery_viv_ms, work%recovery_viv_ms, 'recovery_viv_ms', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_phi_eval, work%viv_phi_eval, 'viv_phi_eval', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_rate, work%viv_rate, 'viv_rate', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real2(src%viv_ms_next, work%viv_ms_next, 'viv_ms_next', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL copy_real1(src%viv_phi_next, work%viv_phi_next, 'viv_phi_next', ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN work%initialized = src%initialized ! Commit: release the caller's previous model, then move the fully-built copy in component by @@ -6453,6 +6847,25 @@ SUBROUTINE commit_model_copy(from, to) CALL MOVE_ALLOC(from%added_mass_diameter_elem, to%added_mass_diameter_elem) CALL MOVE_ALLOC(from%added_mass_can_elem, to%added_mass_can_elem) CALL MOVE_ALLOC(from%added_mass_cat_elem, to%added_mass_cat_elem) + to%has_viv = from%has_viv + to%viv_rho = from%viv_rho + to%viv_tw = from%viv_tw + 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) + CALL MOVE_ALLOC(from%viv_cf, to%viv_cf) + CALL MOVE_ALLOC(from%viv_df, to%viv_df) + CALL MOVE_ALLOC(from%viv_dn, to%viv_dn) + CALL MOVE_ALLOC(from%viv_phi, to%viv_phi) + CALL MOVE_ALLOC(from%viv_ms, to%viv_ms) + CALL MOVE_ALLOC(from%viv_phi_rollback, to%viv_phi_rollback) + CALL MOVE_ALLOC(from%viv_ms_rollback, to%viv_ms_rollback) + CALL MOVE_ALLOC(from%recovery_viv_phi, to%recovery_viv_phi) + CALL MOVE_ALLOC(from%recovery_viv_ms, to%recovery_viv_ms) + CALL MOVE_ALLOC(from%viv_phi_eval, to%viv_phi_eval) + CALL MOVE_ALLOC(from%viv_rate, to%viv_rate) + CALL MOVE_ALLOC(from%viv_ms_next, to%viv_ms_next) + CALL MOVE_ALLOC(from%viv_phi_next, to%viv_phi_next) IF (from%has_bathymetry) THEN to%bathymetry%nx = from%bathymetry%nx @@ -7072,6 +7485,31 @@ SUBROUTINE model_contributor_load(model, q, v, force, jac_q, jac_v, ErrStat, Err jac_v = jac_v + jv_tmp END IF END ASSOCIATE + IF (model%has_viv) THEN + BLOCK + INTEGER :: nd, ia + REAL(wp) :: fl(3), jv3(3, 3), jp3(3, 3), jn3(3, 3), coef, uu(3) + LOGICAL :: ok + DO nd = 2, SIZE(q)/3 - 1 + IF (.NOT. model%viv_node(nd)) CYCLE + CALL viv_node_coef(model, q, nd, coef, uu) + ia = 3*nd - 2 + CALL CD_VIV_Node_Lift(q(ia - 3:ia - 1), q(ia + 3:ia + 5), smoothed(v, ia), uu, coef, & + model%viv_phi_eval(nd), fl, ok, jv3, jp3, jn3) + IF (.NOT. ok) THEN + CALL fail(ErrStat, ErrMsg, 'VIV lift: the neighbours of a node coincide (no line tangent)') + RETURN + END IF + force(ia:ia + 2) = force(ia:ia + 2) + fl + ! the lift takes the smoothed velocity (v_{i-1} + 2 v_i + v_{i+1})/4 (smoothed) + jac_v(ia:ia + 2, ia:ia + 2) = jac_v(ia:ia + 2, ia:ia + 2) + 0.5_wp*jv3 + jac_v(ia:ia + 2, ia - 3:ia - 1) = jac_v(ia:ia + 2, ia - 3:ia - 1) + 0.25_wp*jv3 + jac_v(ia:ia + 2, ia + 3:ia + 5) = jac_v(ia:ia + 2, ia + 3:ia + 5) + 0.25_wp*jv3 + jac_q(ia:ia + 2, ia - 3:ia - 1) = jac_q(ia:ia + 2, ia - 3:ia - 1) + jp3 + jac_q(ia:ia + 2, ia + 3:ia + 5) = jac_q(ia:ia + 2, ia + 3:ia + 5) + jn3 + END DO + END BLOCK + END IF END SUBROUTINE model_contributor_load SUBROUTINE model_contributor_load_banded(model, q, v, free, kl, ku, force, jac_q_band, jac_v_band, & @@ -7364,6 +7802,48 @@ SUBROUTINE model_contributor_load_banded(model, q, v, free, kl, ku, force, jac_q END IF END DO + IF (model%has_viv) THEN + ! cross-flow VIV lift on the interior nodes (CableDyn_VIV), with its velocity Jacobian + ! and the position Jacobian through the node tangent (the two neighbours) + BLOCK + INTEGER :: nd, ia, ra, cb + REAL(wp) :: fl(3), jv3(3, 3), jp3(3, 3), jn3(3, 3), coef, uu(3) + LOGICAL :: ok + DO nd = 2, n/3 - 1 + IF (.NOT. model%viv_node(nd)) CYCLE + CALL viv_node_coef(model, q, nd, coef, uu) + ia = 3*nd - 2 + CALL CD_VIV_Node_Lift(q(ia - 3:ia - 1), q(ia + 3:ia + 5), smoothed(v, ia), uu, coef, & + model%viv_phi_eval(nd), fl, ok, jv3, jp3, jn3) + IF (.NOT. ok) THEN + CALL fail(ErrStat, ErrMsg, 'VIV lift: the neighbours of a node coincide (no line tangent)') + RETURN + END IF + force(ia:ia + 2) = force(ia:ia + 2) + fl + DO cb = 1, 3 + DO ra = 1, 3 + ! the lift takes the smoothed velocity (v_{i-1} + 2 v_i + v_{i+1})/4 (smoothed) + CALL scatter_scalar_band(jac_v_band, model%free_map_work, kl, ku, ia + ra - 1, ia + cb - 1, & + 0.5_wp*jv3(ra, cb), ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL scatter_scalar_band(jac_v_band, model%free_map_work, kl, ku, ia + ra - 1, ia + cb - 4, & + 0.25_wp*jv3(ra, cb), ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL scatter_scalar_band(jac_v_band, model%free_map_work, kl, ku, ia + ra - 1, ia + cb + 2, & + 0.25_wp*jv3(ra, cb), ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL scatter_scalar_band(jac_q_band, model%free_map_work, kl, ku, ia + ra - 1, ia + cb - 4, & + jp3(ra, cb), ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + CALL scatter_scalar_band(jac_q_band, model%free_map_work, kl, ku, ia + ra - 1, ia + cb + 2, & + jn3(ra, cb), ErrStat, ErrMsg) + IF (ErrStat /= CD_MODEL_OK) RETURN + END DO + END DO + END DO + END BLOCK + END IF + IF (.NOT. CD_All_Finite(force) .OR. .NOT. CD_All_Finite(jac_q_band) .OR. & .NOT. CD_All_Finite(jac_v_band)) THEN CALL fail(ErrStat, ErrMsg, 'banded model load returned non-finite force/Jacobian') @@ -7575,6 +8055,26 @@ SUBROUTINE model_contributor_force(model, q, v, force, ErrStat, ErrMsg, end_node CALL scatter_element_vector(force, idx, f2) END IF END DO + ! VIV lift acts on interior nodes only, so an end-node recovery carries none of it + IF (model%has_viv .AND. .NOT. ends) THEN + BLOCK + INTEGER :: nd, ia + REAL(wp) :: fl(3), coef, uu(3) + LOGICAL :: ok + DO nd = 2, nn - 1 + IF (.NOT. model%viv_node(nd)) CYCLE + CALL viv_node_coef(model, q, nd, coef, uu) + ia = 3*nd - 2 + CALL CD_VIV_Node_Lift(q(ia - 3:ia - 1), q(ia + 3:ia + 5), smoothed(v, ia), uu, coef, & + model%viv_phi_eval(nd), fl, ok) + IF (.NOT. ok) THEN + CALL fail(ErrStat, ErrMsg, 'VIV lift: the neighbours of a node coincide (no line tangent)') + RETURN + END IF + force(ia:ia + 2) = force(ia:ia + 2) + fl + END DO + END BLOCK + END IF IF (.NOT. CD_All_Finite(force)) CALL fail(ErrStat, ErrMsg, 'model force returned non-finite force') CONTAINS diff --git a/src/CableDyn_System.f90 b/src/CableDyn_System.f90 index b34ef6de..7a2cd623 100644 --- a/src/CableDyn_System.f90 +++ b/src/CableDyn_System.f90 @@ -18,6 +18,7 @@ MODULE CableDyn_System CD_Model_Has_Viscoelastic, CD_Get_Model_VE_Dl1, CD_Set_Model_VE_Dl1, & CD_Model_Has_Syrope, CD_Get_Model_Syrope_State, CD_Set_Model_Syrope_State, & CD_Model_Has_Friction, CD_Get_Model_Friction_Anchors, CD_Set_Model_Friction_Anchors, & + CD_Latch_Model_VIV_Window, & CD_Get_Model_EndNodeMassDiag, CD_Get_Model_EndNodeAddedMass, & CD_Get_Model_EndNodeTangent, CD_Set_Model_EndQuery, CD_Get_Model_EndQuery, & CD_Model_Seabed_Point_Load, & @@ -235,6 +236,9 @@ MODULE CableDyn_System ! the sub-stepping diagnostics of every line (CD_SubstepStats): they roll back with the ! states, so a restored and re-advanced step counts once TYPE(CD_SubstepStats), ALLOCATABLE :: snap_sub(:) + ! VIV shedding phase and cross-flow mean squares join the snapshot (phi then the two + ! mean squares per node, 3 per node: sized like snap_q, line by line). + REAL(wp), ALLOCATABLE :: snap_viv(:) LOGICAL :: snap_valid = .FALSE. END TYPE CD_SystemType @@ -469,6 +473,7 @@ SUBROUTINE CD_End_System(system, ErrStat, ErrMsg) IF (ALLOCATED(system%snap_l0_c)) DEALLOCATE (system%snap_l0_c, system%snap_l0_dot_c) IF (ALLOCATED(system%snap_fbase)) DEALLOCATE (system%snap_fbase) IF (ALLOCATED(system%snap_ve_dl_1)) DEALLOCATE (system%snap_ve_dl_1) + IF (ALLOCATED(system%snap_viv)) DEALLOCATE (system%snap_viv) IF (ALLOCATED(system%snap_syrope_slow)) DEALLOCATE (system%snap_syrope_slow, system%snap_syrope_tmax) IF (ALLOCATED(system%snap_fr_anchor)) DEALLOCATE (system%snap_fr_anchor) IF (ALLOCATED(system%snap_sub)) DEALLOCATE (system%snap_sub) @@ -1270,7 +1275,7 @@ RECURSIVE SUBROUTINE CD_Step_System(system, dt, q_coupled, v_coupled, a_coupled, LOGICAL :: conv2, stall2 CHARACTER(1024) :: em REAL(wp), ALLOCATABLE :: q0(:), v0(:), a0(:), qm(:), vm(:), am(:), qs(:), vs(:), as(:) - REAL(wp), ALLOCATABLE :: dl1s(:), slows(:), tmaxs(:), frs(:, :), hmaxs(:), l0cs(:), l0dcs(:) + REAL(wp), ALLOCATABLE :: dl1s(:), slows(:), tmaxs(:), frs(:, :), hmaxs(:), l0cs(:), l0dcs(:), vivs(:) TYPE(CD_SubstepStats), ALLOCATABLE :: subs(:) converged = .FALSE. @@ -1290,6 +1295,12 @@ RECURSIVE SUBROUTINE CD_Step_System(system, dt, q_coupled, v_coupled, a_coupled, RETURN END IF + ! MoorDyn's VIV averaging window counts nominal steps: latch it before any subdivision + IF (depth == 0) THEN + DO i = 1, system%n_lines + CALL CD_Latch_Model_VIV_Window(system%lines(i), dt) + END DO + END IF CALL save_line_states(system, ErrStat, ErrMsg) IF (ErrStat /= CD_SYSTEM_OK) RETURN converged = .TRUE. @@ -1409,7 +1420,8 @@ RECURSIVE SUBROUTINE CD_Step_System(system, dt, q_coupled, v_coupled, a_coupled, IF (CD_Model_Has_Friction(system%lines(i))) nfr = nfr + SIZE(system%lines(i)%fr_anchor, 2) END DO ALLOCATE (qs(ntot), vs(ntot), as(ntot), dl1s(nve), slows(nsy), tmaxs(nsy), frs(2, nfr), & - hmaxs(system%n_lines), subs(system%n_lines), l0cs(nel), l0dcs(nel)) + hmaxs(system%n_lines), subs(system%n_lines), l0cs(nel), l0dcs(nel), vivs(ntot)) + vivs = CD_ZERO lo = 1 lo_ve = 1 lo_sy = 1 @@ -1424,6 +1436,7 @@ RECURSIVE SUBROUTINE CD_Step_System(system, dt, q_coupled, v_coupled, a_coupled, ! states, so the halves of a fallback that does not complete leave no trace hmaxs(i) = system%lines(i)%audit_hmax subs(i) = system%lines(i)%sub_stats + IF (system%lines(i)%has_viv) CALL pack_viv(system%lines(i), vivs(lo:hi)) lo = hi + 1 ne = SIZE(system%lines(i)%l0_c) l0cs(lo_el:lo_el + ne - 1) = system%lines(i)%l0_c @@ -1473,6 +1486,7 @@ RECURSIVE SUBROUTINE CD_Step_System(system, dt, q_coupled, v_coupled, a_coupled, system%lines(i)%a = as(lo:hi) system%lines(i)%audit_hmax = hmaxs(i) system%lines(i)%sub_stats = subs(i) + IF (system%lines(i)%has_viv) CALL unpack_viv(system%lines(i), vivs(lo:hi)) lo = hi + 1 ne = SIZE(system%lines(i)%l0_c) system%lines(i)%l0_c = l0cs(lo_el:lo_el + ne - 1) @@ -3146,6 +3160,11 @@ SUBROUTINE save_line_states(system, ErrStat, ErrMsg) ! the stick-slip friction anchors move with every committed step too IF (CD_Model_Has_Friction(system%lines(i))) & system%lines(i)%fr_anchor_rollback = system%lines(i)%fr_anchor + ! the VIV shedding phase and cross-flow mean squares advance every committed step + IF (system%lines(i)%has_viv) THEN + system%lines(i)%viv_phi_rollback = system%lines(i)%viv_phi + system%lines(i)%viv_ms_rollback = system%lines(i)%viv_ms + END IF END DO END SUBROUTINE save_line_states @@ -3171,9 +3190,36 @@ SUBROUTINE restore_line_states(system) END IF IF (CD_Model_Has_Friction(system%lines(i))) & system%lines(i)%fr_anchor = system%lines(i)%fr_anchor_rollback + IF (system%lines(i)%has_viv) THEN + system%lines(i)%viv_phi = system%lines(i)%viv_phi_rollback + system%lines(i)%viv_ms = system%lines(i)%viv_ms_rollback + system%lines(i)%viv_phi_eval = system%lines(i)%viv_phi + END IF END DO END SUBROUTINE restore_line_states + PURE SUBROUTINE pack_viv(line, buf) + !! A line's committed VIV state as 3 reals per node: the phases, then the two mean + !! squares per node (the size of the line's q). + TYPE(CD_ModelType), INTENT(IN) :: line + REAL(wp), INTENT(OUT) :: buf(:) + INTEGER :: nn + nn = SIZE(line%viv_phi) + buf(1:nn) = line%viv_phi + buf(nn + 1:3*nn) = RESHAPE(line%viv_ms, [2*nn]) + END SUBROUTINE pack_viv + + PURE SUBROUTINE unpack_viv(line, buf) + !! Inverse of pack_viv; the in-step phase returns to the committed one. + TYPE(CD_ModelType), INTENT(INOUT) :: line + REAL(wp), INTENT(IN) :: buf(:) + INTEGER :: nn + nn = SIZE(line%viv_phi) + line%viv_phi = buf(1:nn) + line%viv_ms = RESHAPE(buf(nn + 1:3*nn), [2, nn]) + line%viv_phi_eval = line%viv_phi + END SUBROUTINE unpack_viv + SUBROUTINE restore_failed_step(system, failed_stat, msg, converged, stalled, n_iter, ErrStat, ErrMsg) TYPE(CD_SystemType), INTENT(INOUT) :: system INTEGER, INTENT(IN) :: failed_stat @@ -3273,7 +3319,7 @@ SUBROUTINE CD_System_Snapshot(system, ErrStat, ErrMsg) ALLOCATE (system%snap_l0(netot), system%snap_l0_dot(netot), system%snap_fbase(ntot), & system%snap_l0_c(netot), system%snap_l0_dot_c(netot), & system%snap_ve_dl_1(netot), system%snap_syrope_slow(netot), & - system%snap_syrope_tmax(netot), system%snap_fr_anchor(ntot)) + system%snap_syrope_tmax(netot), system%snap_fr_anchor(ntot), system%snap_viv(ntot)) END BLOCK END IF lo = 1 @@ -3287,6 +3333,7 @@ SUBROUTINE CD_System_Snapshot(system, ErrStat, ErrMsg) IF (CD_Model_Has_Friction(system%lines(i))) & system%snap_fr_anchor(lo:lo + 2*SIZE(system%lines(i)%fr_anchor, 2) - 1) = & RESHAPE(system%lines(i)%fr_anchor, [2*SIZE(system%lines(i)%fr_anchor, 2)]) + IF (system%lines(i)%has_viv) CALL pack_viv(system%lines(i), system%snap_viv(lo:hi)) lo = hi + 1 END DO IF (.NOT. ALLOCATED(system%snap_sub)) ALLOCATE (system%snap_sub(system%n_lines)) @@ -3356,6 +3403,7 @@ SUBROUTINE CD_System_Restore(system, ErrStat, ErrMsg) IF (CD_Model_Has_Friction(system%lines(i))) & system%lines(i)%fr_anchor = RESHAPE(system%snap_fr_anchor(lo:lo + 2*SIZE(system%lines(i)%fr_anchor, 2) - 1), & [2, SIZE(system%lines(i)%fr_anchor, 2)]) + IF (system%lines(i)%has_viv) CALL unpack_viv(system%lines(i), system%snap_viv(lo:hi)) lo = hi + 1 END DO IF (ALLOCATED(system%snap_sub)) THEN diff --git a/src/CableDyn_VIV.f90 b/src/CableDyn_VIV.f90 new file mode 100644 index 00000000..fd6554b0 --- /dev/null +++ b/src/CableDyn_VIV.f90 @@ -0,0 +1,208 @@ +! File: src/CableDyn_VIV.f90 +! SPDX-License-Identifier: Apache-2.0 +! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +MODULE CableDyn_VIV + !! Cross-flow vortex-induced vibration (VIV) of EI = 0 line nodes: the synchronisation + !! model of Thorsen, Saevik and Larsen (J. Fluids Struct. 49, 2014, 135-148; 61, 2016, + !! 1-19) in the form MoorDyn v2 implements it (LINE TYPES columns Cl dF cF; Davies et al., + !! J. Fluids Struct. 146, 2026, 104651). Pure node kernels; the model layer + !! (CableDyn_Model) owns the phase state and the time integration. + !! + !! At an interior node with unit tangent q (the chord of its two neighbours), velocity r', + !! acceleration r'' and ambient fluid velocity u: + !! + !! v_r = u - r' relative fluid velocity + !! v_n = v_r - (q.v_r) q its component normal to the line, U = |v_n| + !! e = q x v_n / U cross-flow unit vector + !! y' = r'.e , y'' = r''.e cross-flow velocity and acceleration of the node + !! + !! The cross-flow velocity phase is phi_y = atan2(-y''/rms(y''), y'/rms(y')) in [0, 2 pi), + !! with running RMS values. The vortex-shedding (lift) phase phi obeys + !! + !! d phi/dt = 2 pi f_hat U / D , f_hat = cF + dF sin(phi_y - phi) + !! + !! so the shedding frequency locks onto the cross-flow motion inside the non-dimensional + !! synchronisation band cF +- dF, and the lift force on the node is + !! + !! F = C cos(phi) U (q x v_n) , C = sum over the node's two elements of + !! (1/2 l0_e w_e) (1/2 rho D_e Cl_e) + !! + !! (w_e the submerged fraction of element e): per unit length 1/2 rho D Cl U^2 cos(phi) + !! along e, exactly MoorDyn's Lf = 1/2 rho_w d |Vp| Cl cos(phi) (q x Vp) l_node. + !! + !! Load convention (CableDyn_Hydro, CD_Cable_Dynamic_Load_Proc): `force` is the external + !! load; the Jacobians are residual contributions, -dF/d(node velocity) and + !! -dF/d(neighbour positions) through the node tangent. The wetted-fraction factor in C is + !! held at its current value in the Jacobians (it moves only for an element that crosses + !! the waterline); the residual itself is exact. + USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE + IMPLICIT NONE + PRIVATE + + PUBLIC :: CD_VIV_Node_Lift + PUBLIC :: CD_VIV_Crossflow_Motion + PUBLIC :: CD_VIV_Phase_Rate + PUBLIC :: CD_VIV_Mean_Square + PUBLIC :: CD_VIV_Wrap_Phase + + !> MoorDyn's running-RMS window in time steps (Line%n_m): each step updates the stored + !> mean square as ((n_m - 1) old + new) / n_m. + INTEGER, PARAMETER, PUBLIC :: CD_VIV_NM = 500 + !> MoorDyn's defaults of the synchronisation range dF and centre cF when a LINE TYPES row + !> gives Cl only. + REAL(wp), PARAMETER, PUBLIC :: CD_VIV_DEFAULT_DF = 0.08_wp + REAL(wp), PARAMETER, PUBLIC :: CD_VIV_DEFAULT_CF = 0.18_wp + REAL(wp), PARAMETER, PUBLIC :: CD_VIV_TWO_PI = 6.283185307179586476925286766559005768394_wp + + !> Chord below which a node tangent is undefined (a collapsed pair of neighbours). + REAL(wp), PARAMETER :: TINY_CHORD = 1.0e-12_wp + +CONTAINS + + PURE SUBROUTINE node_frame(r_prev, r_next, rd, u, q, chord, vr, vn, un, ok) + !! Unit tangent from the neighbour chord and the normal relative velocity of a node. + REAL(wp), INTENT(IN) :: r_prev(3), r_next(3), rd(3), u(3) + REAL(wp), INTENT(OUT) :: q(3), chord, vr(3), vn(3), un + LOGICAL, INTENT(OUT) :: ok + REAL(wp) :: c(3) + + c = r_next - r_prev + chord = SQRT(c(1)*c(1) + c(2)*c(2) + c(3)*c(3)) + ok = chord > TINY_CHORD + IF (.NOT. ok) THEN + q = CD_ZERO + vr = CD_ZERO + vn = CD_ZERO + un = CD_ZERO + RETURN + END IF + q = c/chord + vr = u - rd + vn = vr - (q(1)*vr(1) + q(2)*vr(2) + q(3)*vr(3))*q + un = SQRT(vn(1)*vn(1) + vn(2)*vn(2) + vn(3)*vn(3)) + END SUBROUTINE node_frame + + PURE FUNCTION cross3(a, b) RESULT(c) + REAL(wp), INTENT(IN) :: a(3), b(3) + REAL(wp) :: c(3) + c(1) = a(2)*b(3) - a(3)*b(2) + c(2) = a(3)*b(1) - a(1)*b(3) + c(3) = a(1)*b(2) - a(2)*b(1) + END FUNCTION cross3 + + PURE SUBROUTINE CD_VIV_Node_Lift(r_prev, r_next, rd, u, coef, phi, force, ok, jac_v, jac_prev, jac_next) + !! Lift force on one node, F = coef cos(phi) U (q x v_n), and optionally its residual + !! Jacobians (all three present or none): jac_v = -dF/dr', jac_prev = -dF/dr_prev, + !! jac_next = -dF/dr_next. ok = .FALSE. (and F = 0) when the two neighbours coincide. + REAL(wp), INTENT(IN) :: r_prev(3), r_next(3), rd(3), u(3), coef, phi + REAL(wp), INTENT(OUT) :: force(3) + LOGICAL, INTENT(OUT) :: ok + REAL(wp), INTENT(OUT), OPTIONAL :: jac_v(3, 3), jac_prev(3, 3), jac_next(3, 3) + REAL(wp) :: q(3), chord, vr(3), vn(3), un, w(3), s, alpha + REAL(wp) :: dfdq(3, 3), dfdv(3, 3), proj(3, 3) + INTEGER :: i, j + + force = CD_ZERO + IF (PRESENT(jac_v)) THEN + jac_v = CD_ZERO + jac_prev = CD_ZERO + jac_next = CD_ZERO + END IF + CALL node_frame(r_prev, r_next, rd, u, q, chord, vr, vn, un, ok) + IF (.NOT. ok) RETURN + s = coef*COS(phi) + w = cross3(q, vn) + force = (s*un)*w + IF (.NOT. PRESENT(jac_v)) RETURN + IF (.NOT. (un > CD_ZERO)) RETURN ! F and its derivatives vanish with the normal flow + ! w = q x v_n = q x v_r. dF/dv_r = s [w (x) v_n/U + U [q]x]; dr' enters v_r with a minus + ! sign, so jac_v = -dF/dr' = +dF/dv_r. + DO j = 1, 3 + DO i = 1, 3 + dfdv(i, j) = s*w(i)*vn(j)/un + END DO + END DO + dfdv(1, 2) = dfdv(1, 2) - s*un*q(3) + dfdv(1, 3) = dfdv(1, 3) + s*un*q(2) + dfdv(2, 1) = dfdv(2, 1) + s*un*q(3) + dfdv(2, 3) = dfdv(2, 3) - s*un*q(1) + dfdv(3, 1) = dfdv(3, 1) - s*un*q(2) + dfdv(3, 2) = dfdv(3, 2) + s*un*q(1) + jac_v = dfdv + ! dF/dq = s [-(alpha/U) w (x) v_r - U [v_r]x], alpha = q.v_r (U^2 = |v_r|^2 - alpha^2 and + ! d(q x v_r)/dq = -[v_r]x), chained through dq/dr_next = (I - q q^T)/chord = -dq/dr_prev. + alpha = q(1)*vr(1) + q(2)*vr(2) + q(3)*vr(3) + DO j = 1, 3 + DO i = 1, 3 + dfdq(i, j) = -s*(alpha/un)*w(i)*vr(j) + END DO + END DO + dfdq(1, 2) = dfdq(1, 2) + s*un*vr(3) + dfdq(1, 3) = dfdq(1, 3) - s*un*vr(2) + dfdq(2, 1) = dfdq(2, 1) - s*un*vr(3) + dfdq(2, 3) = dfdq(2, 3) + s*un*vr(1) + dfdq(3, 1) = dfdq(3, 1) + s*un*vr(2) + dfdq(3, 2) = dfdq(3, 2) - s*un*vr(1) + DO j = 1, 3 + DO i = 1, 3 + proj(i, j) = -q(i)*q(j)/chord + END DO + proj(j, j) = proj(j, j) + CD_ONE/chord + END DO + jac_next = -MATMUL(dfdq, proj) + jac_prev = -jac_next + END SUBROUTINE CD_VIV_Node_Lift + + PURE SUBROUTINE CD_VIV_Crossflow_Motion(r_prev, r_next, rd, rdd, u, yd, ydd, un, ok) + !! Cross-flow velocity y' and acceleration y'' of a node along e = q x v_n / U, and the + !! normal relative flow speed U. Both are zero when there is no normal flow (MoorDyn's + !! normalisation of a zero vector). + REAL(wp), INTENT(IN) :: r_prev(3), r_next(3), rd(3), rdd(3), u(3) + REAL(wp), INTENT(OUT) :: yd, ydd, un + LOGICAL, INTENT(OUT) :: ok + REAL(wp) :: q(3), chord, vr(3), vn(3), e(3) + + yd = CD_ZERO + ydd = CD_ZERO + CALL node_frame(r_prev, r_next, rd, u, q, chord, vr, vn, un, ok) + IF (.NOT. ok) RETURN + IF (.NOT. (un > CD_ZERO)) RETURN + e = cross3(q, vn)/un + yd = rd(1)*e(1) + rd(2)*e(2) + rd(3)*e(3) + ydd = rdd(1)*e(1) + rdd(2)*e(2) + rdd(3)*e(3) + END SUBROUTINE CD_VIV_Crossflow_Motion + + ELEMENTAL REAL(wp) FUNCTION CD_VIV_Mean_Square(ms_old, sample, weight) RESULT(ms) + !! One step of the running mean square, ms_old + weight (sample^2 - ms_old); weight = + !! 1/n_m is MoorDyn's ((n_m - 1) old^2 + new^2)/n_m. + REAL(wp), INTENT(IN) :: ms_old, sample, weight + 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) + !! 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). + REAL(wp), INTENT(IN) :: yd, ydd, ms_yd, ms_ydd, phi, un, diameter, cf, df + REAL(wp) :: phi_y + + IF (.NOT. (ABS(yd) > CD_ZERO .OR. ABS(ydd) > CD_ZERO)) THEN + phi_y = CD_ZERO + ELSE IF (ms_yd > CD_ZERO .AND. ms_ydd > CD_ZERO) THEN + phi_y = ATAN2(-ydd/SQRT(ms_ydd), yd/SQRT(ms_yd)) + ELSE + phi_y = ATAN2(-ydd, yd) + END IF + IF (phi_y < CD_ZERO) phi_y = phi_y + CD_VIV_TWO_PI + rate = CD_VIV_TWO_PI*(cf + df*SIN(phi_y - phi))*un/diameter + END FUNCTION CD_VIV_Phase_Rate + + ELEMENTAL REAL(wp) FUNCTION CD_VIV_Wrap_Phase(phi) RESULT(wrapped) + !! The phase mapped to [0, 2 pi); the model only uses cos(phi) and sin(. - phi). + REAL(wp), INTENT(IN) :: phi + wrapped = MODULO(phi, CD_VIV_TWO_PI) + ! a tiny negative phase can round to exactly 2 pi + IF (wrapped >= CD_VIV_TWO_PI .OR. wrapped < CD_ZERO) wrapped = CD_ZERO + END FUNCTION CD_VIV_Wrap_Phase + +END MODULE CableDyn_VIV diff --git a/tests/test_model.f90 b/tests/test_model.f90 index b7fd128d..35b1a7b2 100644 --- a/tests/test_model.f90 +++ b/tests/test_model.f90 @@ -25,7 +25,7 @@ PROGRAM test_model CD_Update_Model_Hydro_Fields, & CD_Update_Model_External_Loads, CD_Update_Model_CoupledMotion, & CD_Recompute_Model_Acceleration, & - CD_Copy_Model, & + CD_Copy_Model, CD_Set_Model_VIV, & CD_MODEL_OK, CD_MODEL_BADINPUT, CD_MODEL_SOLVEFAIL, CD_MODEL_NOT_INITIALIZED, & CD_Update_Model_SegmentLength, CD_Set_Model_EndQuery USE CableDyn_Loads, ONLY: CD_Assemble_Distributed_Load @@ -53,6 +53,7 @@ PROGRAM test_model CALL case_resolved_substeps() CALL case_substep_paths() CALL case_substep_snap_only() + CALL case_substeps_restore_viv_state() CALL case_coupled_load_sign() CALL case_coupled_motion_update() CALL case_external_load_update() @@ -1718,6 +1719,98 @@ SUBROUTINE case_damping_model_load() CALL require(es == CD_MODEL_OK, 'damping:end') END SUBROUTINE case_damping_model_load + SUBROUTINE case_substeps_restore_viv_state() + !! The rotation-resolved sub-stepping of a line carrying VIV: a 10 m taut line in a 0.5 m/s + !! cross current with Cl 0.8 on every element, End B heaved by 1 m over 2 s so that its + !! chords turn by more than a degree per 0.02 s step. Solving the first sub-stepped pass + !! twice, the second from the restored committed state (TEST-ONLY sub_test_repeat), changes + !! nothing bit for bit, the shedding phases and running mean squares included; a failing + !! sub-step (TEST-ONLY sub_test_fail) returns the plain step, and the run then equals the + !! run with ei0_substeps off bit for bit. Without the VIV state in the sub-step slots the + !! sub-steps advanced the phase again from the plain step's phase. + INTEGER, PARAMETER :: NE = 10, NN = NE + 1, NSTEP = 60 + REAL(wp), PARAMETER :: DT = 0.02_wp, AMP = 1.0_wp, PER = 2.0_wp + TYPE(CD_ModelType) :: auto_m, rep_m, fb_m, off_m + TYPE(GenAlphaConfig) :: cfg + INTEGER :: conn(2, NE), fixed(6), es, k, n_iter + REAL(wp) :: q0(3*NN), v0(3*NN), f_ext(3*NN), pq(3*NN), pv(3*NN), pa(3*NN), fluid(3, NN), wl(NN) + REAL(wp) :: l0(NE), ea(NE), rho_a(NE), cl(NE), dia(NE), cf(NE), df(NE), phi0(NN), w, t + LOGICAL :: conv, stalled, all_conv + CHARACTER(200) :: em + + DO k = 1, NE + conn(:, k) = [k, k + 1] + END DO + q0 = 0.0_wp + DO k = 1, NN + q0(3*k - 2) = REAL(k - 1, wp) + q0(3*k) = -5.0_wp + END DO + v0 = 0.0_wp + f_ext = 0.0_wp + fixed = [1, 2, 3, 3*NN - 2, 3*NN - 1, 3*NN] + l0 = 0.99_wp + ea = 1.0e6_wp + rho_a = 10.0_wp + fluid = 0.0_wp + fluid(2, :) = 0.5_wp + wl = 0.0_wp + cl = 0.8_wp + dia = 0.1_wp + cf = 0.18_wp + df = 0.08_wp + CALL CD_Init_Model(auto_m, q0, v0, conn, l0, ea, rho_a, .TRUE., f_ext, fixed, cfg, es, em, & + fluid_velocity=fluid, drag_waterline_z=wl, drag_rho=1025.0_wp, & + drag_diameter=0.1_wp, drag_cdn=1.2_wp, drag_cdt=0.0_wp) + CALL require(es == CD_MODEL_OK, 'substep-viv:init: '//TRIM(em)) + IF (es /= CD_MODEL_OK) RETURN + CALL CD_Set_Model_VIV(auto_m, 1025.0_wp, cl, dia, cf, df, 0.25_wp, es, em) + CALL require(es == CD_MODEL_OK, 'substep-viv:viv: '//TRIM(em)) + IF (es /= CD_MODEL_OK) RETURN + phi0 = auto_m%viv_phi + CALL CD_Copy_Model(auto_m, rep_m, es, em) + rep_m%sub_test_repeat = .TRUE. + CALL CD_Copy_Model(auto_m, fb_m, es, em) + fb_m%sub_test_fail = 1 + CALL CD_Copy_Model(auto_m, off_m, es, em) + off_m%cfg%ei0_substeps = CD_EI0_SUBSTEPS_OFF + w = 2.0_wp*ACOS(-1.0_wp)/PER + all_conv = .TRUE. + DO k = 1, NSTEP + ! End B heaves on z0 + AMP (1 - cos wt) from rest; End A holds + t = REAL(k, wp)*DT + pq = q0 + pv = 0.0_wp + pa = 0.0_wp + pq(3*NN) = q0(3*NN) + AMP*(1.0_wp - COS(w*t)) + pv(3*NN) = AMP*w*SIN(w*t) + pa(3*NN) = AMP*w*w*COS(w*t) + CALL CD_Step_Model(auto_m, DT, conv, stalled, n_iter, es, em, prescribed_q=pq, prescribed_v=pv, prescribed_a=pa) + all_conv = all_conv .AND. es == CD_MODEL_OK .AND. conv + CALL CD_Step_Model(rep_m, DT, conv, stalled, n_iter, es, em, prescribed_q=pq, prescribed_v=pv, prescribed_a=pa) + all_conv = all_conv .AND. es == CD_MODEL_OK .AND. conv + CALL CD_Step_Model(fb_m, DT, conv, stalled, n_iter, es, em, prescribed_q=pq, prescribed_v=pv, prescribed_a=pa) + all_conv = all_conv .AND. es == CD_MODEL_OK .AND. conv + CALL CD_Step_Model(off_m, DT, conv, stalled, n_iter, es, em, prescribed_q=pq, prescribed_v=pv, prescribed_a=pa) + all_conv = all_conv .AND. es == CD_MODEL_OK .AND. conv + END DO + WRITE (*, '(A,I0,A,I0,A,I0,A)') ' sub-steps with VIV: ', auto_m%sub_stats%events, ' of ', & + auto_m%sub_stats%calls, ' steps sub-stepped, ', fb_m%sub_stats%fallbacks, ' failing-sub-step fallbacks' + CALL require(all_conv, 'substep-viv:converged') + CALL require(auto_m%sub_stats%events > 0, 'substep-viv:sub-stepped') + CALL require(ANY(auto_m%viv_phi /= phi0) .AND. ANY(auto_m%viv_ms /= 0.0_wp), 'substep-viv:states-move') + CALL require(ALL(rep_m%q == auto_m%q) .AND. ALL(rep_m%v == auto_m%v) .AND. ALL(rep_m%a == auto_m%a) .AND. & + ALL(rep_m%viv_phi == auto_m%viv_phi) .AND. ALL(rep_m%viv_ms == auto_m%viv_ms), & + 'substep-viv:restore-is-complete') + CALL require(fb_m%sub_stats%fallbacks > 0 .AND. ALL(fb_m%q == off_m%q) .AND. ALL(fb_m%v == off_m%v) .AND. & + ALL(fb_m%a == off_m%a) .AND. ALL(fb_m%viv_phi == off_m%viv_phi) .AND. & + ALL(fb_m%viv_ms == off_m%viv_ms), 'substep-viv:fallback-is-the-plain-step') + CALL CD_End_Model(auto_m, es, em) + CALL CD_End_Model(rep_m, es, em) + CALL CD_End_Model(fb_m, es, em) + CALL CD_End_Model(off_m, es, em) + END SUBROUTINE case_substeps_restore_viv_state + SUBROUTINE case_morison_drag_model_load() !! Model-owned Morison current drag contributes to the coupled-load boundary. !! This mirrors the hydro primitive's one fully wet horizontal element case: diff --git a/tests/test_viv_kernels.f90 b/tests/test_viv_kernels.f90 new file mode 100644 index 00000000..afe04541 --- /dev/null +++ b/tests/test_viv_kernels.f90 @@ -0,0 +1,135 @@ +! File: tests/test_viv_kernels.f90 +! SPDX-License-Identifier: Apache-2.0 +! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +PROGRAM test_viv_kernels + !! Gate for the node kernels of the cross-flow VIV synchronisation model (CableDyn_VIV): + !! 1) the lift equals MoorDyn's Lf = 1/4 rho d |Vp| Cl cos(phi) (q x Vp) (l_i + l_i+1) through + !! coef = sum (1/2 l0)(1/2 rho D Cl); it is normal to the tangent and to the normal flow, + !! |F| = coef |cos(phi)| U^2, and vanishes for flow along the line; + !! 2) its residual Jacobians (-dF/dr', -dF/dr_prev, -dF/dr_next) match central differences; + !! 3) the cross-flow velocity and acceleration are the components along e = q x v_n / U; + !! 4) the phase rate is 2 pi (cF + dF sin(phi_y - phi)) U/D, with phi_y from the RMS-normalised + !! y', y'' (cF at phase lock, cF + dF a quarter period ahead); + !! 5) the running mean square is MoorDyn's ((n_m - 1) old^2 + new^2)/n_m; + !! 6) the phase wraps to [0, 2 pi), and a node whose neighbours coincide fails closed. + USE CableDyn_Precision, ONLY: wp + USE CableDyn_VIV, ONLY: CD_VIV_Node_Lift, CD_VIV_Crossflow_Motion, CD_VIV_Phase_Rate, CD_VIV_Mean_Square, & + CD_VIV_Wrap_Phase, CD_VIV_TWO_PI, CD_VIV_NM + IMPLICIT NONE + REAL(wp), PARAMETER :: RHO = 1025.0_wp, DIAM = 0.1_wp, CL = 0.8_wp, L1 = 2.0_wp, L2 = 1.5_wp + REAL(wp) :: rp(3), rn(3), rd(3), u(3), coef, phi, f(3), q(3), vr(3), vn(3), un, w(3), ref(3) + REAL(wp) :: jv(3, 3), jp(3, 3), jn(3, 3), fd(3, 3), fp(3), fm(3), h, e(3), yd, ydd, un2, rate + REAL(wp) :: ms, ms_md + LOGICAL :: ok + INTEGER :: nfail, j, k + + nfail = 0 + rp = [0.1_wp, -0.2_wp, -50.3_wp] + rn = [3.6_wp, 0.4_wp, -49.8_wp] + rd = [0.05_wp, -0.12_wp, 0.31_wp] + u = [0.2_wp, 0.15_wp, -0.03_wp] + coef = (0.5_wp*L1 + 0.5_wp*L2)*0.5_wp*RHO*DIAM*CL + phi = 0.7_wp + + ! (1) MoorDyn's lift and its geometry + CALL CD_VIV_Node_Lift(rp, rn, rd, u, coef, phi, f, ok) + CALL require(ok, 'lift: frame defined') + q = (rn - rp)/NORM2(rn - rp) + vr = u - rd + vn = vr - DOT_PRODUCT(q, vr)*q + un = NORM2(vn) + w = cross(q, vn) + ref = 0.25_wp*RHO*DIAM*un*CL*COS(phi)*w*(L1 + L2) + CALL require(NORM2(f - ref) <= 1.0e-12_wp*NORM2(ref), 'lift equals MoorDyn''s Lf') + CALL require(ABS(DOT_PRODUCT(f, q)) <= 1.0e-12_wp*NORM2(f) .AND. ABS(DOT_PRODUCT(f, vn)) <= 1.0e-12_wp*NORM2(f)*un, & + 'lift normal to the tangent and to the normal flow') + CALL require(ABS(NORM2(f) - coef*ABS(COS(phi))*un*un) <= 1.0e-12_wp*NORM2(f), '|lift| = coef |cos phi| U^2') + CALL CD_VIV_Node_Lift(rp, rn, rd, rd + 0.3_wp*q, coef, phi, f, ok) + CALL require(ok .AND. NORM2(f) <= 1.0e-14_wp, 'no lift for flow along the line') + + ! (2) Jacobians against central differences + CALL CD_VIV_Node_Lift(rp, rn, rd, u, coef, phi, f, ok, jv, jp, jn) + h = 1.0e-6_wp + DO j = 1, 3 + CALL CD_VIV_Node_Lift(rp, rn, rd + h*unit(j), u, coef, phi, fp, ok) + CALL CD_VIV_Node_Lift(rp, rn, rd - h*unit(j), u, coef, phi, fm, ok) + fd(:, j) = -(fp - fm)/(2.0_wp*h) + END DO + CALL require(MAXVAL(ABS(jv - fd)) <= 1.0e-6_wp*MAXVAL(ABS(fd)), 'velocity Jacobian matches differences') + DO j = 1, 3 + CALL CD_VIV_Node_Lift(rp + h*unit(j), rn, rd, u, coef, phi, fp, ok) + CALL CD_VIV_Node_Lift(rp - h*unit(j), rn, rd, u, coef, phi, fm, ok) + fd(:, j) = -(fp - fm)/(2.0_wp*h) + END DO + CALL require(MAXVAL(ABS(jp - fd)) <= 1.0e-6_wp*MAXVAL(ABS(fd)), 'previous-node Jacobian matches differences') + DO j = 1, 3 + CALL CD_VIV_Node_Lift(rp, rn + h*unit(j), rd, u, coef, phi, fp, ok) + CALL CD_VIV_Node_Lift(rp, rn - h*unit(j), rd, u, coef, phi, fm, ok) + fd(:, j) = -(fp - fm)/(2.0_wp*h) + END DO + CALL require(MAXVAL(ABS(jn - fd)) <= 1.0e-6_wp*MAXVAL(ABS(fd)), 'next-node Jacobian matches differences') + + ! (3) cross-flow motion along e = q x v_n / U + CALL CD_VIV_Crossflow_Motion(rp, rn, rd, [1.0_wp, 2.0_wp, -0.5_wp], u, yd, ydd, un2, ok) + e = w/un + CALL require(ok .AND. ABS(un2 - un) <= 1.0e-14_wp, 'cross-flow: normal flow speed') + CALL require(ABS(yd - DOT_PRODUCT(rd, e)) <= 1.0e-14_wp .AND. & + ABS(ydd - DOT_PRODUCT([1.0_wp, 2.0_wp, -0.5_wp], e)) <= 1.0e-14_wp, & + 'cross-flow velocity and acceleration along e') + + ! (4) phase rate: at phase lock (phi_y = phi) the band centre, a quarter period ahead cF + dF + ! (y' = cos, y'' = -sin with unit RMS: phi_y is the motion phase) + rate = CD_VIV_Phase_Rate(COS(1.1_wp), -SIN(1.1_wp), 1.0_wp, 1.0_wp, 1.1_wp, 0.15_wp, DIAM, 0.18_wp, & + 0.08_wp) + CALL require(ABS(rate - CD_VIV_TWO_PI*0.18_wp*0.15_wp/DIAM) <= 1.0e-12_wp*rate, 'rate at phase lock is cF U/D') + rate = CD_VIV_Phase_Rate(COS(1.1_wp), -SIN(1.1_wp), 1.0_wp, 1.0_wp, 1.1_wp - 0.25_wp*CD_VIV_TWO_PI, & + 0.15_wp, DIAM, 0.18_wp, 0.08_wp) + CALL require(ABS(rate - CD_VIV_TWO_PI*0.26_wp*0.15_wp/DIAM) <= 1.0e-12_wp*rate, 'rate a quarter period ahead is (cF+dF) U/D') + + ! (5) MoorDyn's running mean square + ms_md = 0.3_wp + DO k = 1, 50 + ms = CD_VIV_Mean_Square(ms_md, SIN(0.1_wp*k), 1.0_wp/REAL(CD_VIV_NM, wp)) + CALL require(ABS(ms - (REAL(CD_VIV_NM - 1, wp)*ms_md + SIN(0.1_wp*k)**2)/REAL(CD_VIV_NM, wp)) <= 1.0e-15_wp, & + 'mean square is MoorDyn''s running RMS update') + ms_md = ms + END DO + + ! (6) wrap and degenerate frame + CALL require(CD_VIV_Wrap_Phase(-1.0e-300_wp) >= 0.0_wp .AND. CD_VIV_Wrap_Phase(-1.0e-300_wp) < CD_VIV_TWO_PI, & + 'a tiny negative phase wraps into [0, 2 pi)') + CALL require(ABS(CD_VIV_Wrap_Phase(7.0_wp) - (7.0_wp - CD_VIV_TWO_PI)) <= 1.0e-15_wp, 'phase wraps by 2 pi') + CALL CD_VIV_Node_Lift(rp, rp, rd, u, coef, phi, f, ok) + CALL require(.NOT. ok .AND. NORM2(f) <= 0.0_wp, 'coinciding neighbours fail closed with no lift') + + IF (nfail > 0) THEN + WRITE (*, '(A,I0,A)') 'FAIL: ', nfail, ' assertion(s) failed' + ERROR STOP 1 + END IF + WRITE (*, '(A)') 'PASS: VIV synchronisation-model kernels' + +CONTAINS + + PURE FUNCTION cross(a, b) RESULT(c) + REAL(wp), INTENT(IN) :: a(3), b(3) + REAL(wp) :: c(3) + c = [a(2)*b(3) - a(3)*b(2), a(3)*b(1) - a(1)*b(3), a(1)*b(2) - a(2)*b(1)] + END FUNCTION cross + + PURE FUNCTION unit(j) RESULT(e) + INTEGER, INTENT(IN) :: j + REAL(wp) :: e(3) + e = 0.0_wp + e(j) = 1.0_wp + END FUNCTION unit + + SUBROUTINE require(cond, msg) + LOGICAL, INTENT(IN) :: cond + CHARACTER(*), INTENT(IN) :: msg + IF (.NOT. cond) THEN + WRITE (*, '(A)') 'MISMATCH: '//msg + nfail = nfail + 1 + END IF + END SUBROUTINE require + +END PROGRAM test_viv_kernels diff --git a/tests/test_viv_lockin.py b/tests/test_viv_lockin.py new file mode 100644 index 00000000..82500fae --- /dev/null +++ b/tests/test_viv_lockin.py @@ -0,0 +1,158 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +# Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +"""Cross-flow VIV lock-in of a taut line against MoorDyn-F. + +A 100 m line (50 segments, D 0.1 m, 10 kg/m, EA 5e7 N, about 50 kN) between two points at 50 m +depth in a uniform 0.15 m/s cross current, lift coefficient 0.8 with MoorDyn's band (dF 0.08, +cF 0.18): the shedding frequency cF U/D = 0.27 Hz sits on the first vertical mode, and the line +locks in. MoorDyn-F (OpenFAST v5 moordyn_driver, dtM 5e-4 s) gives a mid-span A/D of 0.662 at +0.293 Hz over 150-300 s. Gates, over 60-120 s: + +* at dtM 0.01 s the mid-span A/D is within 3 % of MoorDyn-F's and the response frequency within + one spectral bin (1/60 Hz) of it, with the quarter-span amplitude of the first mode; +* at dtM 0.002 s, a step that resolves the mesh zig-zag mode, the line stays locked in with the + same amplitude (within 2 %): with the nodes' own kinematics in the synchronisation model the + zig-zag mode was pumped there and the line lost lock-in after about 70 s. + +usage: test_viv_lockin.py --exe --output +""" + +from __future__ import annotations + +import argparse +import math +import shutil +import subprocess +import sys +from pathlib import Path + +import numpy as np + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "python")) +from cabledyn import read_output # noqa: E402 + +FAILURES: list[str] = [] +MD_AD, MD_F = 0.662, 0.293 # MoorDyn-F reference, mid span +D = 0.1 + + +def check(ok: bool, message: str) -> None: + print(("PASS: " if ok else "FAIL: ") + message) + if not ok: + FAILURES.append(message) + + +CURRENT = """MoorDyn v2 water kinematics file +uniform cross-flow current for the VIV lock-in gate +--------------------------- WAVES ------------------------------------- +0 WaveKinMod - type of wave input +"" WaveKinFile - file containing wave elevation time series +0.000000E+00 dtWave - time step to use in setting up wave kinematics grid (s) +0 WaveDir - wave heading (deg) +2 - X wave input type +-10, 110, 2 - X wave grid point data +2 - Y wave input type +-10, 10, 2 - Y wave grid point data +2 - Z wave input type +-100, 0, 2 - Z wave grid point data +--------------------------- CURRENT ------------------------------------- +1 CurrentMod - type of current input +z-depth x-current y-current +(m) (m/s) (m/s) +0.0 0.0 0.15 +-100.0 0.0 0.15 +--------------------- need this line ------------------ +""" + + +def deck(dtm: float) -> str: + length = 100.0 / (1.0 + 5.0e4 / 5.0e7) + return f"""--------------------- CableDyn Input File --------------------------------- +VIV lock-in gate: taut line in a uniform cross current +----------------------- LINE TYPES ------------------------------------------ +TypeName Diam Mass/m EA BA/-zeta EI Cd Ca CdAx CaAx Cl dF cF +(name) (m) (kg/m) (N) (N-s/-) (-) (-) (-) (-) (-) (-) (-) (-) +riser 0.10 10.0 5.0e7 -0.8 0.0 1.2 1.0 0.0 0.0 0.8 0.08 0.18 +----------------------- POINTS ---------------------------------------------- +ID Attachment X Y Z M V CdA CA +(#) (-) (m) (m) (m) (kg) (m^3) (m^2) (-) +1 Coupled 0.0 0.0 -50.0 0 0 0 0 +2 Fixed 100.0 0.0 -50.0 0 0 0 0 +----------------------- LINES ----------------------------------------------- +ID LineType AttachA AttachB UnstrLen NumSegs Outputs +(#) (name) (#) (#) (m) (-) (-) +1 riser 1 2 {length:.6f} 50 - +---------------------- OPTIONS ---------------------------------------------- +{dtm} dtM +100.0 WtrDpth +1025.0 rhoW +9.80665 g +current.dat WaterKin +0.25 VIVrmsWindow +120.0 TMax +---------------------- OUTPUTS ----------------------------------------------- +L1N25PZ +L1N12PZ +END +------------------------- need this line -------------------------------------- +""" + + +def response(path: Path) -> tuple[float, float, float]: + """Mid A/D, mid peak frequency, 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 = mid - mid.mean() + 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))) + 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, + ) + + +def main() -> int: + ap = argparse.ArgumentParser() + ap.add_argument("--exe", required=True) + ap.add_argument("--output", required=True) + args = ap.parse_args() + out = Path(args.output) + if out.exists(): + shutil.rmtree(out) + out.mkdir(parents=True) + (out / "current.dat").write_text(CURRENT, encoding="utf-8", newline="\n") + results = {} + for dtm in (0.01, 0.002): + name = f"viv_dt{dtm}" + (out / f"{name}.dat").write_text(deck(dtm), encoding="utf-8", newline="\n") + proc = subprocess.run([args.exe, f"{name}.dat", name], cwd=out, capture_output=True, text=True) + if proc.returncode != 0: + print(proc.stdout[-2000:], proc.stderr[-2000:]) + check(False, f"dtM {dtm}: the run completes (exit {proc.returncode})") + continue + results[dtm] = 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, + f"dtM 0.01 s: mid-span A/D {ad:.3f}, MoorDyn-F {MD_AD} (within 3 %)") + check(abs(f - MD_F) <= 1.0 / 60.0, + f"dtM 0.01 s: response frequency {f:.3f} Hz, MoorDyn-F {MD_F} Hz (within 1/60 Hz)") + ratio = math.sin(math.pi * 22.0 / 100.0) + check(abs(qtr / ad - ratio) <= 0.05, + f"dtM 0.01 s: quarter/mid amplitude {qtr / ad:.3f}, first mode {ratio:.3f}") + if 0.01 in results and 0.002 in results: + a1, a2 = results[0.01][0], results[0.002][0] + check(abs(a2 - a1) <= 0.02 * a1, + f"dtM 0.002 s stays locked in: mid-span A/D {a2:.3f} against {a1:.3f} at 0.01 s (within 2 %)") + print(f"{len(FAILURES)} failure(s)") + return 1 if FAILURES else 0 + + +if __name__ == "__main__": + sys.exit(main())