diff --git a/CHANGELOG.md b/CHANGELOG.md index 99f92999..ba564c6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -150,6 +150,21 @@ All notable changes to CableDyn are recorded in this file. The format follows standalone driver and the C API refuse `CoupledPinned` rods by name; FAST.Farm decks still refuse rods, OpenFAST linearisation still refuses rods, and `CoupledPinned` bodies remain unsupported. See the manual's OpenFAST page (Lifecycle features). +- A warning when line nodes of a coupled OpenFAST run (`CompMooring = 5`) lie outside the + SeaState wave-kinematics grid (`X_HalfWidth`, `Y_HalfWidth`, `Z_Depth`). SeaState gives such a + node the kinematics of the grid boundary: waves out of phase beyond a half-width, and + kinematics that are too strong below `Z_Depth`. Its fluid load was therefore wrong without + any message. CableDyn now checks its nodes at the static equilibrium and at every CableDyn + step. At the first node outside the grid it prints one warning with the number of nodes, + the farthest node in each direction and the SeaState inputs to enlarge. Only nodes in the + water are checked (a cable or jumper above the free surface carries no fluid load), and + nodes below a grid that reaches the seabed (`Z_Depth` equal to the water depth, its + default) are not reported. + The OpenFAST tutorial and `examples/openfast/README.md` now enlarge the r-test `MD_Shared` + grid (`X_HalfWidth = 100 m`, `Z_Depth = 40 m`), which covers the platform but not the + moorings, and quote their results for the enlarged grid. With the `MD_Shared` grid, the + line-1 fairlead tension standard deviation of the tutorial was 18 % too high. See the + manual's OpenFAST page (SeaState grid). ### Changed diff --git a/doc/openfast.rst b/doc/openfast.rst index 92f0c401..941f7a94 100644 --- a/doc/openfast.rst +++ b/doc/openfast.rst @@ -78,7 +78,7 @@ Time step ``DT`` is the OpenFAST glue step; ``dtM`` is CableDyn's committed step. With no deck ``dtM``, CableDyn targets 0.1 s rounded to a whole number of glue steps and holds its loads (zero-order hold) between commits. ``dtM = DT`` solves every glue step. The console reports the result, for -example ``CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM )``. A deck ``dtM`` +example ``CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM)``. A deck ``dtM`` larger than ``DT`` but not a whole multiple of it is never coarsened: CableDyn uses the largest multiple of ``DT`` that does not exceed it and reports a warning with both values (``dtM = 0.025`` with ``DT = 0.01`` runs at 0.02 s), matching MoorDyn, which only ever shortens its step to fit the @@ -98,6 +98,72 @@ WaterKin file can select file waves, a file depth-dependent current, host waves, current independently where the field is separable. Unsupported or double-counted combinations fail during initialisation. The selector matrix is in :doc:`options` and :doc:`driver_format`. +SeaState grid +~~~~~~~~~~~~~ + +SeaState computes the wave and current kinematics on a grid set in its input file and +interpolates them at the line nodes: ``X_HalfWidth`` and ``Y_HalfWidth`` about the origin, +``Z_Depth`` below the still-water level, and ``NX``, ``NY``, ``NZ`` grid points (``NZ`` is +spaced more finely near the surface). A node outside the grid gets the kinematics of the +nearest grid boundary point, so its fluid load is wrong: beyond a half-width the waves are +out of phase, and below ``Z_Depth`` the wave and current kinematics are those of the grid +bottom, which are too strong. A SeaState file written for the platform alone usually covers +only the platform. The r-test ``MD_Shared`` file used in :doc:`tutorial_openfast` has +``X_HalfWidth = Y_HalfWidth = 100 m``, ``Z_Depth = 40 m`` and ``NZ = 2``, while the anchors lie +838 m from the platform on a 200 m seabed. Size the grid for the lines: + +* ``X_HalfWidth`` and ``Y_HalfWidth`` beyond the farthest anchor or cable end, with margin for + the platform offset; +* ``Z_Depth`` equal to the water depth (``"default"``); nodes on the seabed are then inside the + grid; and +* ``NX``, ``NY`` and ``NZ`` raised with the extents to keep the grid spacing: a horizontal + spacing of about a tenth of the peak wavelength or less. A long-crested sea (``WaveDirMod = + 0``) that travels along x does not vary in y, so ``NY = 2`` is enough for it. + +SeaState holds the whole time history of the grid in memory, so memory and initialisation time +grow with (2 ``NX`` − 1)(2 ``NY`` − 1) ``NZ`` ``WaveTMax`` / ``WaveDT``. For the +IEA-15MW case of :doc:`tutorial_openfast` (Hs 6 m, Tp 12 s, ``WaveTMax = 4800 s``, +``WaveDT = 0.2 s``), ``X_HalfWidth = Y_HalfWidth = 900``, the default ``Z_Depth``, ``NX = 37`` +(25 m spacing), ``NY = 2`` and ``NZ = 11`` needs about 4.6 GB. Halving the spacing (``NX = 73``) +or using ``NZ = 16`` changes the 10–70 s platform and fairlead-tension statistics by less than +0.1 %. The ``MD_Shared`` grid gives a line-1 fairlead tension standard deviation 18 % too high +(0.136 MN instead of 0.115 MN). + +CableDyn compares its nodes with the grid at the static equilibrium and at every CableDyn step. +At the first node found outside it prints one warning and continues: + +.. code-block:: text + + WARNING: CableDyn mooring module: 147 of the 153 CableDyn sampling nodes in the water lie + outside the SeaState wave-kinematics grid at t = 0 s (warned once). SeaState clamps them to + the grid boundary, so their fluid kinematics and loads are not physical. Farthest: x = -837.6 + m (grid |x| <= X_HalfWidth = 100 m); y = 725.38 m (grid |y| <= Y_HalfWidth = 100 m); z = + -200.01 m (grid z >= -Z_Depth = -40 m). In the SeaState input file enlarge X_HalfWidth, + Y_HalfWidth and Z_Depth (Z_Depth at most WtrDpth + MSL2SWL, its default) to cover the lines + with margin for their motion, and raise NX, NY and NZ to keep the grid spacing. + +Only nodes in the water are checked: a node above the free surface carries no fluid load, +whatever kinematics SeaState would give it, so a suspended cable or jumper above the water may +leave the grid. A node counts as in the water at or below the free-surface elevation sampled +for it, which also decides its wetting in CableDyn (the still-water level when the host waves +are off), and, without wave stretching (``WaveStMod = 0``), at or below the still-water level, +above which SeaState gives zero kinematics without reading the grid. Only the directions in +which nodes leave the grid are listed. Waves are checked in all three +directions and a SeaState current (uniform in x and y) only in depth; under Wheeler stretching +(``WaveStMod = 3``) the depth checked is the one SeaState interpolates at, the node depth mapped +linearly from the range between the seabed and the local wave elevation onto the range between +the seabed and the still-water level (with the elevation SeaState sampled, also when only the +host current is used). A dynamic current field (an InflowWind-driven current) is read on its +own grid; when that field is gridded, a separate one-time warning reports nodes outside its +vertical extent or lateral half-width. SeaState measures its field from the still-water level, and the +mooring samples it at positions relative to the mean sea level, so a run with host waves or +current from SeaState refuses a nonzero ``MSL2SWL`` at initialisation (a deck that takes +both from WaterKin does not query SeaState and is not affected). Excursions smaller than +1 % of the grid spacing at the boundary are ignored, and so are nodes below a grid that reaches +the seabed (``Z_Depth = WtrDpth + MSL2SWL``): they are in the seabed, where the kinematics of the +grid bottom are the right ones. FAST.Farm runs, which use still water, and SeaState fields +without waves or current are not checked. + Run and confirm --------------- @@ -193,8 +259,9 @@ Example files The turbine sub-models are not part of this repository. :doc:`tutorial_openfast` gives the exact steps to fetch them from OpenFAST's ``r-test`` (``glue-codes/fast-farm/MD_Shared`` at revision -``dd5feaaaa500ba7283140107806300d551cff0a7``) and to reset that farm model's turbine-1 initial -pose to a single turbine at the origin. +``dd5feaaaa500ba7283140107806300d551cff0a7``), to reset that farm model's turbine-1 initial +pose to a single turbine at the origin, and to enlarge its SeaState grid to cover the moorings +(see *SeaState grid*). Mixed moorings and power cables ------------------------------- diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 2ef21c85..30b6a095 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -521,6 +521,8 @@ Warnings and notes that do not stop a run :header-rows: 1 :widths: 42 58 + * - Message + - Cause and fix * - ``Note: line is torsionally restrained at one end only; ... no torsion is solved`` - with the other end free to twist the line carries no torque, so the torsion columns of the restrained end have no effect. Restrain both ends to solve torsion. @@ -529,9 +531,17 @@ Warnings and notes that do not stop a run - the static twist stage of a torsional line. A non-zero descent count means the straight or untwisted branch was unstable at the imposed twist and the solve moved to a buckled shape; check the shape and the ``Twist`` channel. - - * - Message - - Cause and fix + * - ``WARNING: CableDyn mooring module: of the CableDyn sampling nodes in the water + lie outside the SeaState wave-kinematics grid at t = ... s (warned once)`` (OpenFAST) + - the SeaState grid (``X_HalfWidth``, ``Y_HalfWidth``, ``Z_Depth``) does not cover the + lines in the water (nodes above the free surface carry no fluid load and are not + counted), and SeaState gives the nodes outside it the kinematics of the grid boundary: waves + out of phase beyond a half-width, kinematics that are too strong below ``Z_Depth``. The + message names the farthest node in each direction. Enlarge the listed inputs in the + SeaState file past the farthest anchor (``Z_Depth`` to the water depth, its default) and + raise ``NX``, ``NY``, ``NZ`` to keep the spacing. A SeaState file written for the + platform alone, such as the r-test ``MD_Shared`` file, triggers it. See + :ref:`openfast:SeaState grid` for sizes and memory. * - ``WARNING: line type ... sinks ... m into the seabed ...; kBot is soft for this line`` - a grounded run of this type would sink deeper than its own diameter into the penalty seabed. Raise ``kBot``; the default ``1.0e5`` embeds a heavy chain by about half its diff --git a/doc/tutorial_openfast.rst b/doc/tutorial_openfast.rst index 425ad77d..0b04142a 100644 --- a/doc/tutorial_openfast.rst +++ b/doc/tutorial_openfast.rst @@ -10,8 +10,8 @@ CableDyn results, compare against stock MoorDyn in the same binary, and add a la cable. **Needs:** ``openfast.exe`` from the release, the ``examples`` folder, and Git (or a browser) to -fetch the turbine model · **Run time:** about 5 s for 70 s of simulation (the MoorDyn comparison run -takes a few minutes) +fetch the turbine model · **Run time:** under half a minute for 70 s of simulation, about a +third of it SeaState generating the wave grid (the MoorDyn comparison run takes a few minutes) .. contents:: :local: @@ -75,8 +75,8 @@ The folder now holds, among others: ``HydroData\``, ``Airfoils\``, … - the turbine and platform model from ``MD_Shared`` -3. Make the model a single turbine at the origin ------------------------------------------------- +3. Prepare the turbine model +---------------------------- ``MD_Shared`` is a two-turbine FAST.Farm case. Its turbine-1 files start the platform at its farm pose (20.3 m surge, 180° yaw, small roll/pitch/heave) and set HydroDyn's reference yaw @@ -102,6 +102,28 @@ This sets ``PtfmSurge``, ``PtfmSway``, ``PtfmHeave``, ``PtfmRoll``, ``PtfmPitch` 321 MN fairlead tension. Always read the initial fairlead tensions before trusting a coupled run. +``MD_Shared``'s ``SeaState.dat`` computes the wave kinematics on a grid that covers only the +platform: ``X_HalfWidth = Y_HalfWidth = 100 m``, ``Z_Depth = 40 m``, ``NX = NY = NZ = 2``. The +mooring lines reach anchors 838 m away on the 200 m seabed, and SeaState gives every line node +outside the grid the kinematics of the grid boundary. Enlarge the grid to cover the lines: + +.. code-block:: powershell + + $ss = 'SeaState.dat' + (Get-Content $ss) -replace '^\s*\S+(\s+[XY]_HalfWidth\s)', ' 900$1' ` + -replace '^\s*\S+(\s+Z_Depth\s)', ' "default"$1' ` + -replace '^\s*\S+(\s+NX\s)', ' 37$1' ` + -replace '^\s*\S+(\s+NZ\s)', ' 11$1' | + Set-Content $ss -Encoding ascii + +This sets ``X_HalfWidth`` and ``Y_HalfWidth`` to 900 m, ``Z_Depth`` to the water depth, 37 grid +points along each half of x (25 m spacing) and 11 in depth. ``NY`` stays 2 because the +long-crested sea travels along x and does not vary in y. SeaState then needs about 4.6 GB of +memory and several seconds to generate the grid. Without this step the run still completes, but +CableDyn warns that 147 of its 153 line nodes lie outside the SeaState wave-kinematics grid, and +the line-1 fairlead tension standard deviation comes out 18 % too high. Grid sizing is +described in :ref:`openfast:SeaState grid`. + 4. How CableDyn is wired in --------------------------- @@ -148,7 +170,7 @@ The CableDyn part of the console (other modules' lines trimmed): Running CableDyn (v0.1.1, 2026-10-09). CableDyn: geometrically nonlinear cable & mooring dynamics for floating wind. ... - CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM ) + CableDyn time step dtM = 2.50000E-02 s (1 x glue DT; deck dtM) Parsing CableDyn input file: .\CableDyn_UMaine.dat CableDyn: SeaState wave/current kinematics drive the mooring hydro (153 sampling nodes, refreshed every mooring step). @@ -163,16 +185,14 @@ The CableDyn part of the console (other modules' lines trimmed): ... CableDyn initialization completed. Requested CableDyn OUTPUTS at t = 0 s (equilibrium pose, SeaState kinematics at t = 0): - FairTen1 = 2.43621E+06 (N) - AnchTen1 = 1.35173E+06 (N) + FairTen1 = 2.43752E+06 (N) + AnchTen1 = 1.35164E+06 (N) FairIncl1 = 55.685 (deg) ... These values are also the t = 0 CableDyn columns in the OpenFAST output file. Time: 0 of 70 seconds. ... - Total Real Time: 4.63 seconds Simulated Time: 70 seconds - Time Ratio (Sim/CPU): 15.887 OpenFAST terminated normally. @@ -180,13 +200,14 @@ Check, in order: #. ``Running CableDyn (`` — the CableDyn-enabled executable is in use. A stock OpenFAST rejects ``CompMooring = 5`` during input validation. -#. The line inventory (3 lines, 6 points) and ``dtM``. +#. The line inventory (3 lines, 6 points) and ``dtM``, and no ``WARNING: CableDyn mooring module: + ... lie outside the SeaState wave-kinematics grid`` line (step 3). #. The initial fairlead tensions: 2.437 MN per line, with the line tangent 55.7° below horizontal, as in the standalone ``spread_3line_chain.dat`` of :doc:`tutorial_spread`. The tension is the magnitude of the line-end force, which includes the fairlead node's share of the chain weight, so the force points slightly steeper, 56.3° below horizontal, with a horizontal component of 1.351 MN. -#. The ``OUTPUTS`` at t = 0: ``FairTen1`` reads 2.436 MN, 0.04 % below the equilibrium value +#. The ``OUTPUTS`` at t = 0: ``FairTen1`` reads 2.4375 MN, 0.02 % above the equilibrium value above. The equilibrium is solved before the SeaState kinematics act, and at t = 0 the wave kinematics add their hydrodynamic load on the fairlead end node. In still water (``WaveMod = 0``) the two values are equal. ``.CD.static.out`` holds the equilibrium, and the @@ -218,8 +239,8 @@ Check, in order: Time FairTen1 AnchTen1 FairIncl1 AnchIncl1 FairTen2 ... (s) (N) (N) (deg) (deg) (N) ... - 0.0000000E+00 2.436210E+06 1.351729E+06 5.568478E+01 -1.961023E-02 2.435610E+06 ... - 2.5000000E-02 2.434498E+06 1.352272E+06 5.568418E+01 -1.957846E-02 2.433048E+06 ... + 0.0000000E+00 2.437520E+06 1.351636E+06 5.568478E+01 -1.961023E-02 2.436576E+06 ... + 2.5000000E-02 2.438082E+06 1.351645E+06 5.568463E+01 -1.961023E-02 2.435530E+06 ... CableDyn channels are chosen in the deck's ``OUTPUTS`` section (keep its closing ``END``), not in the ``.fst`` ``OutList``. Channel names and units: :doc:`outputs`; sign and angle conventions: @@ -254,30 +275,30 @@ the main ``.out``. Statistics over 10–70 s from the two main output files: - CableDyn std - MoorDyn std * - ``PtfmSurge`` (m) - - 0.893 - - 0.893 - - 1.364 - - 1.363 + - 0.899 + - 0.899 + - 1.380 + - 1.378 * - ``PtfmHeave`` (m) - −1.030 - −1.030 - - 1.216 - - 1.215 + - 1.221 + - 1.221 * - ``PtfmPitch`` (deg) - - 1.497 - - 1.497 - - 1.382 - - 1.381 + - 1.496 + - 1.496 + - 1.390 + - 1.390 * - fairlead tension, line 1 (MN) - - 2.452 - - 2.452 - - 0.136 - - 0.136 + - 2.456 + - 2.456 + - 0.115 + - 0.116 * - fairlead tension, line 2 (MN) - - 2.376 - - 2.376 - - 0.069 - - 0.069 + - 2.372 + - 2.372 + - 0.064 + - 0.064 The platform motions agree to within 0.2 %, the mean fairlead tensions to within 0.01 % and their standard deviations to within 0.5 %. Both codes report the fairlead tension as the force @@ -319,7 +340,7 @@ seabed. Copy it into the case folder and point a copy of the ``.fst`` at it: force [Fx, Fy, Fz]: [1230, 0, -11858] N, inclination=84.078 deg line tangent: inclination=83.943 deg, declination=173.94 deg, azimuth=0 deg ... - Curv4N38 = 9.01821E-02 (1/m) + Curv4N38 = 9.01822E-02 (1/m) BendMom4N38 = 1794.6 (N.m) CableDyn found the cable's touchdown and lazy-wave shape by itself: in @@ -339,9 +360,9 @@ Exercises ``MD_Shared`` InflowWind and AeroDyn files are already present) and compare the mean surge and line-1 tension with the parked case. 2. **Supercycling.** Remove the ``dtM`` row from ``CableDyn_UMaine.dat``. The console now - reports ``dtM = 0.1 s (4 x glue DT; the default )``, the run takes about 3 s instead of 5 s, + reports ``dtM = 0.1 s (4 x glue DT; the default)``, CableDyn solves once per four glue steps, and ``.CD.out`` has one row per 0.1 s. Here the line-1 tension statistics over 10–70 s barely - move (mean 2.453 MN, std 0.136 MN, against 2.452 and 0.136 MN); verify that for your own + move (mean 2.456 MN, std 0.116 MN, against 2.456 and 0.115 MN); verify that for your own quantities before adopting a coarser step. 3. **Still water.** Set ``WaveMod = 0`` in ``SeaState.dat``. Without waves the platform settles toward its still-water pose (mean heave −1.1 m, pitch 1.5°) with a decaying heave–pitch diff --git a/examples/openfast/README.md b/examples/openfast/README.md index 0ba76238..b0bae7a4 100644 --- a/examples/openfast/README.md +++ b/examples/openfast/README.md @@ -46,6 +46,23 @@ $hd = 'IEA-15-240-RWT-UMaineSemi_HydroDynT1.dat' The initial CableDyn fairlead tensions are then the ~2.4 MN chain pretension. +The `MD_Shared` `SeaState.dat` computes the wave kinematics on a grid that covers only the +platform (`X_HalfWidth = Y_HalfWidth = 100 m`, `Z_Depth = 40 m`), while the anchors lie 838 m +away on the 200 m seabed. SeaState gives every line node outside the grid the kinematics of the +grid boundary, and CableDyn warns about it. Enlarge the grid: + +```powershell +$ss = 'SeaState.dat' +(Get-Content $ss) -replace '^\s*\S+(\s+[XY]_HalfWidth\s)', ' 900$1' ` + -replace '^\s*\S+(\s+Z_Depth\s)', ' "default"$1' ` + -replace '^\s*\S+(\s+NX\s)', ' 37$1' ` + -replace '^\s*\S+(\s+NZ\s)', ' 11$1' | + Set-Content $ss -Encoding ascii +``` + +SeaState then needs about 4.6 GB of memory. The values in this file are for the enlarged grid. +Grid sizing is described in the manual's OpenFAST page (SeaState grid). + ## Run ```powershell @@ -66,7 +83,7 @@ The force is the one the line exerts on the fairlead, including the end node's s chain weight, so it is slightly steeper than the line tangent. These are the static-equilibrium values, also written to `.CD.static.out`. The requested `OUTPUTS` printed below them are the t = 0 values, which add the load of the SeaState wave kinematics at t = 0 on the end node: -`FairTen1` reads 2.43621E+06 N. In still water the two agree. +`FairTen1` reads 2.43752E+06 N. In still water the two agree. For the power-cable case, copy `../iea15mw_umaine_mixed_cabledyn.dat` beside the template and point `MooringFile` at it. @@ -109,12 +126,12 @@ The channels to read for an ALS check: - The static equilibrium of every line is in `.CD.static.out`. In the `MD_Shared` JONSWAP sea (Hs 6 m, Tp 12 s, travelling along +X) line 1 is the only line on -the up-wave side. Before the break the fairlead tensions are 2.44 MN and `PtfmSurge` stays within -−2.4 to 2.8 m. After it the platform drifts down-wave: `PtfmSurge` reaches 147 m by t = 400 s and -is still growing, because the two remaining anchors lie down-wave of the platform. The intact -lines slacken as it approaches them (`FairTen2` mean 1.29 MN over 300–400 s, no peak above the -2.50 MN at the break). Run longer (`TMax`) to reach the new equilibrium. The 400 s run takes -about 26 s. +the up-wave side. Before the break the line-1 fairlead tension averages 2.44 MN and `PtfmSurge` +stays within −2.5 to 3.6 m. After it the platform drifts down-wave: `PtfmSurge` reaches 147 m by +t = 400 s and is still growing, because the two remaining anchors lie down-wave of the platform. +The intact lines slacken as it approaches them (`FairTen2` mean 1.29 MN over 300–400 s, no peak +above the 2.51 MN at the break). Run longer (`TMax`) to reach the new equilibrium. The 400 s run +takes about 60 s. ## Notes diff --git a/src/openfast/CableDyn_OF.f90 b/src/openfast/CableDyn_OF.f90 index 854f534c..9443f1b5 100644 --- a/src/openfast/CableDyn_OF.f90 +++ b/src/openfast/CableDyn_OF.f90 @@ -111,6 +111,7 @@ MODULE CableDyn CD_Recompute_System_Acceleration, CD_SYSTEM_OK USE SeaSt_WaveField, ONLY: WaveField_GetNodeWaveKin USE SeaSt_WaveField_Types, ONLY: WaveMod_None + USE IfW_FlowField_Types, ONLY: Grid3D_FieldType IMPLICIT NONE @@ -191,6 +192,10 @@ MODULE CableDyn LOGICAL :: use_extfluid = .FALSE. INTEGER(IntKi) :: nfluid = 0 REAL(wp), ALLOCATABLE :: fx_xyz(:,:), fx_vel(:,:), fx_acc(:,:), fx_wl(:), fx_pd(:) + ! TRUE once the warning that sampling nodes lie outside the SeaState wave-kinematics + ! grid has been issued: one warning per run (check_wavefield_grid). + LOGICAL :: grid_warned = .FALSE. + LOGICAL :: curr_grid_warned = .FALSE. !< the dynamic current-field grid check has warned ! CHECKPOINT-RESTART identity: serial is the generation stamp minted at ! Init/rebuild and mirrored into other%restart_serial; t_commit is the time of the ! last committed mooring advance, mirrored into other%t_commit. A restored @@ -804,7 +809,7 @@ SUBROUTINE CD_Init(InitInp, u, p, x, xd, z, other, y, m, DTcoupling, InitOut, Er ! wave-capable-at-ZERO-fields build -- a still-water start under a declared sea ! state. Seeding after the static solve matches the stock-MoorDyn convention: ! the IC is the still-water equilibrium, wave kinematics act from t = 0. - CALL sample_wavefield( Inst(id), p, m, 0.0_DbKi, ErrStat2, ErrMsg2 ) + CALL sample_wavefield( Inst(id), p, m, 0.0_DbKi, ErrStat2, ErrMsg2, at_init=.TRUE. ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) IF (ErrStat >= AbortErrLev) RETURN END IF @@ -1690,7 +1695,7 @@ SUBROUTINE CD_UpdateStates( t, n, u, t_array, p, x, xd, z, other, m, ErrStat, Er END SUBROUTINE CD_UpdateStates !---------------------------------------------------------------------------------------------------------------------------------- - SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) + SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg, at_init ) !! Sample the SeaState WaveField at every mooring line node's committed position -- !! fluid velocity (waves + current), fluid acceleration, and the local free-surface !! elevation -- and prescribe them to the aggregate for the coming advance. Nodes @@ -1703,20 +1708,29 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) REAL(DbKi), INTENT(IN ) :: t_sample INTEGER(IntKi), INTENT( OUT) :: ErrStat CHARACTER(*), INTENT( OUT) :: ErrMsg + LOGICAL, OPTIONAL, INTENT(IN ) :: at_init !< the Init seeding call (see check_wavefield_grid) character(*), parameter :: RoutineName = 'sample_wavefield' INTEGER(IntKi) :: i, l, es, nodeInWater, n_current_nodes + LOGICAL :: init_call REAL(SiKi) :: zeta1, zeta2, zeta, pdyn, fv(3), fa(3), famcf(3) REAL(SiKi) :: wave_zeta1, wave_zeta2, wave_zeta, wave_pdyn REAL(SiKi) :: wave_fv(3), wave_fa(3), wave_famcf(3) REAL(wp) :: profile_fv(3), steady_fv_wp(3), grid_z REAL(SiKi) :: steady_fv(3), grid_fv(3), grid_weight + ! the SeaState free-surface elevation as sampled at each node (kept also when the host + ! waves are off and fx_wl takes the still-water level): SeaState's Wheeler stretching + ! interpolates the current at the depth mapped with it. Only the grid check reads it, so + ! it exists only until that check has warned. + REAL(wp), ALLOCATABLE :: wl_sampled(:) CHARACTER(512) :: em INTEGER(IntKi) :: ErrStat2 CHARACTER(ErrMsgLen) :: ErrMsg2 ErrStat = ErrID_None ErrMsg = '' + init_call = .FALSE. + IF (PRESENT(at_init)) init_call = at_init IF (.NOT. ASSOCIATED(p%WaveField)) THEN CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: the WaveField pointer is null but '// & 'SeaState kinematics were requested at Init.', ErrStat, ErrMsg, RoutineName ) @@ -1727,6 +1741,19 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: '//TRIM(em), ErrStat, ErrMsg, RoutineName ) RETURN END IF + ! SeaState measures its wave field and grid from the still-water level, and its node + ! queries take SWL-relative positions; the mooring samples it at positions relative to the + ! mean sea level, which coincide only for MSL2SWL = 0. Checked here, where the deck's + ! WaterKin policy has decided whether SeaState is queried at all. + IF ((inst_e%agg%host_wave_enabled .OR. inst_e%agg%host_current_enabled) .AND. & + ABS(p%WaveField%MSL2SWL) > 0.0_ReKi) THEN + CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: SeaState MSL2SWL = '// & + TRIM(Num2LStr(p%WaveField%MSL2SWL))//' m is not supported with host waves or '// & + 'current: the mooring samples SeaState at positions relative to the mean sea '// & + 'level. Set MSL2SWL = 0, or take the waves and current from the deck (WaterKin).', & + ErrStat, ErrMsg, RoutineName ) + RETURN + END IF IF ((inst_e%agg%host_wave_enabled .NEQV. inst_e%agg%host_current_enabled) .AND. & p%WaveField%Current_InitInput%CurrMod == 2_IntKi) THEN CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: WaterKin requests separate host wave/current '// & @@ -1734,6 +1761,7 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) ErrStat, ErrMsg, RoutineName ) RETURN END IF + IF (.NOT. inst_e%grid_warned) ALLOCATE (wl_sampled(inst_e%nfluid)) DO i = 1, inst_e%nfluid IF (.NOT. inst_e%agg%host_wave_enabled .AND. .NOT. inst_e%agg%host_current_enabled) THEN ! An explicit WaterKin file may disable both host components even @@ -1750,6 +1778,7 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) IF (ErrStat >= AbortErrLev) RETURN END IF + IF (ALLOCATED(wl_sampled)) wl_sampled(i) = REAL(zeta, wp) steady_fv = 0.0_SiKi IF (nodeInWater /= 0_IntKi .AND. & (.NOT. inst_e%agg%host_wave_enabled .OR. .NOT. inst_e%agg%host_current_enabled)) THEN @@ -1828,6 +1857,14 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) inst_e%fx_pd(i) = 0.0_wp IF (inst_e%agg%host_wave_enabled) inst_e%fx_pd(i) = REAL(pdyn, wp) END DO + ! Grid coverage: checked on the positions just sampled (with their free-surface + ! elevations), at Init (the static equilibrium) and then every mooring step until the one + ! warning has been issued. + IF (.NOT. inst_e%grid_warned) THEN + CALL check_wavefield_grid( inst_e, p%WaveField, t_sample, init_call, wl_sampled, ErrStat2, ErrMsg2 ) + CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) + END IF + IF (.NOT. inst_e%curr_grid_warned) CALL check_current_field_grid( inst_e, p%WaveField, t_sample ) CALL CD_AGG_SetFluidFields( inst_e%agg, inst_e%fx_vel, inst_e%fx_acc, inst_e%fx_wl, es, em, & dynamic_pressure=inst_e%fx_pd ) IF (es /= CD_AGG_OK) THEN @@ -1835,6 +1872,225 @@ SUBROUTINE sample_wavefield( inst_e, p, m, t_sample, ErrStat, ErrMsg ) END IF END SUBROUTINE sample_wavefield +!---------------------------------------------------------------------------------------------------------------------------------- + SUBROUTINE check_wavefield_grid( inst_e, wf, t_sample, at_init, wl_sampled, ErrStat, ErrMsg ) + !! Warn, once per run, when sampling nodes lie outside the SeaState wave-kinematics grid. + !! The volume grid spans X_HalfWidth and Y_HalfWidth about the origin of the global frame + !! the nodes are sampled in (FAST.Farm runs in still water and never samples) and Z_Depth + !! below the SWL. Beyond it SeaState clamps the position to the grid boundary (GridInterp + !! SetIndex horizontally, the depth mapping of WaveField_Interp_Setup4D vertically), so + !! the node receives the kinematics of the nearest boundary point -- out of phase + !! horizontally, too strong below Z_Depth. SeaState's own clamping notice is generic, names + !! no node, and is issued once, at the Init sample, where the glue drops it. The extents are + !! read from the WaveField's volume-grid parameters, i.e. exactly the grid the sampler + !! interpolates. Excursions below 1 % of the boundary grid spacing are ignored. Below a + !! grid that reaches the seabed (Z_Depth = WtrDpth + MSL2SWL, the SeaState maximum) a node + !! is in the seabed and the seabed kinematics are the right ones. SeaState's current is + !! uniform in x and y, so the horizontal check applies to waves only. + !! + !! Only nodes in the water are checked: a node above the free surface carries no fluid + !! load whatever kinematics it is given, so a suspended cable or jumper above the water + !! outside the grid is no error. A node is in the water at or below the free-surface + !! elevation just sampled for it (fx_wl; the still-water level when the host waves are + !! off), which decides its wetting in CableDyn, and, without wave stretching + !! (WaveStMod = 0), at or below the still-water level too, above which SeaState gives a + !! node zero kinematics without reading the grid. Called after the nodes' sampling, on the + !! positions just sampled. Cost: a few comparisons per node per mooring step until the + !! warning. at_init marks the Init call, at the static equilibrium (t = 0). + !! + !! The message states first that it is given once, so that a caller's message buffer that + !! cuts its tail keeps that; the farthest-node details are left out if the message would not + !! fit the remaining length of ErrMsg. + TYPE(CD_OF_Instance), INTENT(INOUT) :: inst_e + TYPE(SeaSt_WaveFieldType), INTENT(IN ) :: wf + REAL(DbKi), INTENT(IN ) :: t_sample + LOGICAL, INTENT(IN ) :: at_init + REAL(wp), INTENT(IN ) :: wl_sampled(:) !< SeaState elevation as sampled per node + INTEGER(IntKi), INTENT( OUT) :: ErrStat + CHARACTER(*), INTENT( OUT) :: ErrMsg + + character(*), parameter :: RoutineName = 'check_wavefield_grid' + LOGICAL :: waves, grid_current, check_xy(2), check_z, outside + INTEGER(IntKi) :: i, k, nout, nin, nwet, room + REAL(wp) :: lo(2), hi(2), tol(2), zbot, tol_z, ex, ex_max(3), at_max(3), surface + REAL(wp) :: zq, dep + CHARACTER(11) :: inp(3), res(3) + CHARACTER(1024) :: farthest, enlarge, refine + CHARACTER(:), ALLOCATABLE :: head, msg + + ErrStat = ErrID_None + ErrMsg = '' + waves = inst_e%agg%host_wave_enabled .AND. wf%WaveMod /= WaveMod_None + grid_current = inst_e%agg%host_current_enabled .AND. wf%Current_InitInput%CurrMod /= 0_IntKi + IF (.NOT. (waves .OR. grid_current)) RETURN + DO k = 1, 2 + check_xy(k) = waves .AND. wf%VolGridParams%n(k + 1) > 1_IntKi + lo(k) = REAL(wf%VolGridParams%pZero(k + 1), wp) + hi(k) = lo(k) + REAL(wf%VolGridParams%n(k + 1) - 1_IntKi, wp)*REAL(wf%VolGridParams%delta(k + 1), wp) + tol(k) = 0.01_wp*REAL(wf%VolGridParams%delta(k + 1), wp) + END DO + ! the vertical grid is cosine-spaced in delta(4); its bottom interval is Z_Depth*sin(delta(4)) + zbot = -REAL(wf%GridDepth, wp) + tol_z = 0.01_wp*REAL(wf%GridDepth, wp)*SIN(REAL(wf%VolGridParams%delta(4), wp)) + check_z = wf%VolGridParams%n(4) > 1_IntKi .AND. & + REAL(wf%GridDepth, wp) < REAL(wf%EffWtrDpth, wp) - tol_z + IF (.NOT. (ANY(check_xy) .OR. check_z)) RETURN + + nout = 0_IntKi + nwet = 0_IntKi + ex_max = 0.0_wp + at_max = 0.0_wp + DO i = 1, inst_e%nfluid + ! nodes above the free surface carry no fluid load (see above) + surface = inst_e%fx_wl(i) + IF (wf%WaveStMod == 0_IntKi) surface = MIN(surface, 0.0_wp) + IF (inst_e%fx_xyz(3, i) > surface) CYCLE + nwet = nwet + 1_IntKi + outside = .FALSE. + DO k = 1, 2 + IF (.NOT. check_xy(k)) CYCLE + ex = MAX(lo(k) - inst_e%fx_xyz(k, i), inst_e%fx_xyz(k, i) - hi(k)) + IF (ex > tol(k)) THEN + outside = .TRUE. + IF (ex > ex_max(k)) THEN + ex_max(k) = ex + at_max(k) = inst_e%fx_xyz(k, i) + END IF + END IF + END DO + IF (check_z) THEN + ! SeaState interpolates at the node depth, or under Wheeler stretching (WaveStMod 3) at + ! the depth mapped linearly from [-EffWtrDpth, wave elevation] to [-EffWtrDpth, 0] with + ! the elevation it sampled -- also for the current of a current-only host mode, whose + ! fx_wl is the still-water level + zq = inst_e%fx_xyz(3, i) + IF (wf%WaveMod /= WaveMod_None .AND. wf%WaveStMod == 3_IntKi) THEN + dep = REAL(wf%EffWtrDpth, wp) + IF (dep + wl_sampled(i) > 0.0_wp) zq = MIN(dep*(dep + zq)/(dep + wl_sampled(i)) - dep, 0.0_wp) + END IF + ex = zbot - zq + IF (ex > tol_z) THEN + outside = .TRUE. + IF (ex > ex_max(3)) THEN + ex_max(3) = ex + at_max(3) = inst_e%fx_xyz(3, i) + END IF + END IF + END IF + IF (outside) nout = nout + 1_IntKi + END DO + IF (nout == 0_IntKi) RETURN + + ! the farthest node per direction, and the SeaState inputs that would cover it + nin = 0_IntKi + farthest = '' + IF (ex_max(1) > 0.0_wp) THEN + farthest = TRIM(farthest)//'; x = '//TRIM(Num2LStr(at_max(1)))//' m (grid |x| <= X_HalfWidth = '// & + TRIM(Num2LStr(0.5_wp*(hi(1) - lo(1))))//' m)' + nin = nin + 1_IntKi + inp(nin) = 'X_HalfWidth' + res(nin) = 'NX' + END IF + IF (ex_max(2) > 0.0_wp) THEN + farthest = TRIM(farthest)//'; y = '//TRIM(Num2LStr(at_max(2)))//' m (grid |y| <= Y_HalfWidth = '// & + TRIM(Num2LStr(0.5_wp*(hi(2) - lo(2))))//' m)' + nin = nin + 1_IntKi + inp(nin) = 'Y_HalfWidth' + res(nin) = 'NY' + END IF + IF (ex_max(3) > 0.0_wp) THEN + farthest = TRIM(farthest)//'; z = '//TRIM(Num2LStr(at_max(3)))//' m (grid z >= -Z_Depth = '// & + TRIM(Num2LStr(zbot))//' m)' + nin = nin + 1_IntKi + inp(nin) = 'Z_Depth' + res(nin) = 'NZ' + END IF + enlarge = TRIM(inp(1)) + refine = TRIM(res(1)) + DO k = 2, nin + IF (k == nin) THEN + enlarge = TRIM(enlarge)//' and '//TRIM(inp(k)) + refine = TRIM(refine)//' and '//TRIM(res(k)) + ELSE + enlarge = TRIM(enlarge)//', '//TRIM(inp(k)) + refine = TRIM(refine)//', '//TRIM(res(k)) + END IF + END DO + IF (ex_max(3) > 0.0_wp) enlarge = TRIM(enlarge)//' (Z_Depth at most WtrDpth + MSL2SWL, its default)' + + inst_e%grid_warned = .TRUE. + head = 'CableDyn mooring module: '//TRIM(Num2LStr(nout))//' of the '//TRIM(Num2LStr(nwet))// & + ' CableDyn sampling nodes in the water lie outside the SeaState wave-kinematics grid at t = '// & + TRIM(Num2LStr(t_sample))//' s (warned once). SeaState clamps them to the grid boundary, so '// & + 'their fluid kinematics and loads are not physical.' + msg = head//' Farthest: '//TRIM(farthest(3:))//'. In the SeaState input file enlarge '//TRIM(enlarge)// & + ' to cover the lines with margin for their motion, and raise '//TRIM(refine)// & + ' to keep the grid spacing.' + ! SetErrStat appends the message to ErrMsg after a line break and the routine name + room = LEN(ErrMsg) - LEN_TRIM(ErrMsg) - LEN(RoutineName) - 2 + IF (LEN(msg) > room) msg = head//' Enlarge '//TRIM(enlarge)//' in the SeaState input file.' + CALL SetErrStat( ErrID_Warn, msg, ErrStat, ErrMsg, RoutineName ) + ! The OpenFAST glue does not print module initialization warnings (FAST_InitializeAll_T + ! passes its status on to FAST_InitMappings, which resets it), so the Init check also + ! writes the warning to the screen, as the deck dtM warning does. A warning raised + ! during the time march reaches the screen through the glue's error check. + IF (at_init) CALL WrScr( ' WARNING: '//msg ) + END SUBROUTINE check_wavefield_grid + + SUBROUTINE check_current_field_grid( inst_e, wf, t_sample ) + !! A dynamically populated current field (an InflowWind-driven MHK current, hasCurrField) is + !! not read on the SeaState grid: InflowWind reads it on its own field at the node position + !! shifted up by the water depth (the field's z = 0 is the seabed). For a gridded (Grid3D) + !! field, warn once when submerged sampling nodes lie outside its vertical extent + !! [GridBase, GridBase + 2 ZHWid] or its lateral half-width YHWid (in the field's frame, + !! rotated about its reference position when the box is rotated), where InflowWind + !! extrapolates or stops. Other field types have no extent to check. + TYPE(CD_OF_Instance), INTENT(INOUT) :: inst_e + TYPE(SeaSt_WaveFieldType), INTENT(IN ) :: wf + REAL(DbKi), INTENT(IN ) :: t_sample + INTEGER(IntKi) :: i, nout + REAL(wp) :: zlo, zhi, yhw, dep, tol, pos(3), rel(3), yw, zw, surface, ez, ey + CHARACTER(1024):: msg + + IF (.NOT. (inst_e%agg%host_current_enabled .AND. wf%hasCurrField)) RETURN + IF (wf%CurrField%FieldType /= Grid3D_FieldType) RETURN + dep = REAL(wf%EffWtrDpth, wp) + zlo = REAL(wf%CurrField%Grid3D%GridBase, wp) + zhi = zlo + 2.0_wp*REAL(wf%CurrField%Grid3D%ZHWid, wp) + yhw = REAL(wf%CurrField%Grid3D%YHWid, wp) + tol = 1.0E-6_wp*MAX(1.0_wp, dep) + nout = 0_IntKi + ez = 0.0_wp + ey = 0.0_wp + DO i = 1, inst_e%nfluid + surface = MIN(inst_e%fx_wl(i), 0.0_wp) + IF (inst_e%fx_xyz(3, i) > MAX(inst_e%fx_wl(i), surface)) CYCLE + pos = [inst_e%fx_xyz(1, i), inst_e%fx_xyz(2, i), inst_e%fx_xyz(3, i) + dep] + IF (wf%CurrField%RotateWindBox) THEN + rel = MATMUL(REAL(wf%CurrField%RotToWind, wp), pos - REAL(wf%CurrField%RefPosition, wp)) + & + REAL(wf%CurrField%RefPosition, wp) + ELSE + rel = pos + END IF + yw = rel(2) + zw = rel(3) + IF (zw < zlo - tol .OR. zw > zhi + tol .OR. ABS(yw) > yhw + tol) THEN + nout = nout + 1_IntKi + ez = MAX(ez, zlo - zw, zw - zhi) + ey = MAX(ey, ABS(yw) - yhw) + END IF + END DO + IF (nout == 0_IntKi) RETURN + inst_e%curr_grid_warned = .TRUE. + WRITE (msg, '(A,I0,A,ES10.3,A,ES10.3,A,ES10.3,A,ES10.3,A,ES10.3,A,ES10.3,A)') & + 'CableDyn mooring module: ', nout, ' submerged CableDyn sampling node(s) lie outside the '// & + 'InflowWind current-field grid at t = ', REAL(t_sample, wp), ' s (warned once): the field covers '// & + 'z = ', zlo, ' to ', zhi, ' m above the seabed and |y| <= ', yhw, ' m; the farthest node is ', & + MAX(ez, 0.0_wp), ' m outside in z and ', MAX(ey, 0.0_wp), & + ' m in y. InflowWind extrapolates or stops there; enlarge the current-field grid to cover the lines.' + CALL WrScr( TRIM(msg) ) + END SUBROUTINE check_current_field_grid + !---------------------------------------------------------------------------------------------------------------------------------- SUBROUTINE CD_CalcOutput( t, u, p, x, xd, z, other, y, m, ErrStat, ErrMsg ) REAL(DbKi) , INTENT(IN ) :: t @@ -3816,6 +4072,8 @@ SUBROUTINE release_instance( k, ErrStat, ErrMsg ) Inst(k)%fx_wl, Inst(k)%fx_pd) Inst(k)%use_extfluid = .FALSE. Inst(k)%nfluid = 0 + Inst(k)%grid_warned = .FALSE. + Inst(k)%curr_grid_warned = .FALSE. ! close the CableDyn-owned committed-step record (flushes the final rows) IF (Inst(k)%native_un > 0) THEN CLOSE (Inst(k)%native_un) diff --git a/tests/test_openfast_aggregate.f90 b/tests/test_openfast_aggregate.f90 index c2a04914..c3a2a6da 100644 --- a/tests/test_openfast_aggregate.f90 +++ b/tests/test_openfast_aggregate.f90 @@ -3687,7 +3687,7 @@ SUBROUTINE case_external_fluid_report() !! they agree; the host fields then act from t = 0 and change the t = 0 channel, while the !! summary keeps the equilibrium value. The OpenFAST shell prints the summary, writes the !! static profile before it seeds the t = 0 fields and labels the t = 0 outputs; in the - !! IEA-15MW JONSWAP example the summary reads 2.43712 MN and the t = 0 FairTen1 2.43621 MN. + !! IEA-15MW JONSWAP example the summary reads 2.43712 MN and the t = 0 FairTen1 2.43752 MN. TYPE(CD_AGG_ModuleType) :: agg REAL(wp), PARAMETER :: DT = 0.05_wp REAL(wp), ALLOCATABLE :: fu(:, :), fud(:, :), wl(:)