Merge pull request #3065 from andrew-platt/wavetank3

New wavetank library for HIL simulations for MHK floating turbines with AeroDyn, MoorDyn, SeaState, and InflowWind.

Author: andrew-platt

.github/workflows/automated-dev-tests.yml

@@ -368,6 +368,7 @@ jobs:
           path: |
             ${{github.workspace}}/build/reg_tests/glue-codes/openfast-cpp
             ${{github.workspace}}/build/reg_tests/glue-codes/python
+            ${{github.workspace}}/build/reg_tests/glue-codes/other
             ${{github.workspace}}/build/reg_tests/modules/aerodyn
             ${{github.workspace}}/build/reg_tests/modules/moordyn
             ${{github.workspace}}/build/reg_tests/modules/inflowwind

docs/source/user/index.rst

@@ -32,6 +32,7 @@ This section contains documentation for the OpenFAST module-coupling environment
    TurbSim <turbsim/index.rst>
    FAST.Farm <fast.farm/index.rst>
    C++ API <cppapi/index.rst>
+   WaveTank <other/index.rst>
 
 
 Additional module documentation

docs/source/user/other/index.rst

@@ -0,0 +1,40 @@
+.. _WaveTank:
+
+WaveTank
+========
+
+The WaveTank glue-code is an experimental code for coupling hardware-in-the-loop
+MHK models in a wavetank to software simulating the MHK turbine loads that
+cannot be physically modeled in the wave tank.  The  *OpenFAST* modules
+*SeaState*, *AeroDyn*, *MoorDyn*, and *InflowWind* are statically linked into a
+single dynamic library (``cmake`` target ``wavetanktesting_c_binding``) with a
+c-binding based interface.  This library can be called from *LabView* or another
+code.
+
+Inputs to the library include the time and motions, including the velocities and
+accelerations, located at a single reference poitn at each time step.  The
+resulting forces and moments are returned to the calling code.
+
+Restrictions
+~~~~~~~~~~~~
+The current setup WaveTank library has several restrictions:
+
+- rigid structure including platform, tower, and nacelle
+- no yaw DOF
+- rigid rotor
+- constant rotor RPM for entire simulation
+- no option for controller interfacing at present
+- visualization limitted to *AeroDyn* and *SeaState*
+- Current implementation only supports floating MHK turbines (``MHK = 2``). Other modes are present but not fully implemented.
+
+
+
+
+Input File
+~~~~~~~~~~
+
+
+.. toctree::
+   :maxdepth: 2
+   
+   wavetank_input.rst

docs/source/user/other/wavetank_input.rst

@@ -0,0 +1,242 @@
+.. _WaveTank-Input:
+
+Input File
+----------
+
+This document describes the WaveTank configuration input file (``wavetankconfig_input.txt``) used to set up and run the WaveTank model for marine hydrokinetic (MHK) turbine testing.
+
+- The file is read by the WaveTank library during initialization.
+
+Conventions and Units
+---------------------
+
+- SI units are used throughout: m, s, kg, N, Pa.
+- Angles are in degrees unless otherwise specified.
+- Rotational speed is in rpm where noted.
+- Positions and heights are referenced to Mean Sea Level (MSL) unless otherwise noted.
+- Input files for modules may be relative or absolute paths.
+
+File and Simulation Control
+---------------------------
+
+OutRootName (string)
+  Root name used when writing summary or other files.
+  Example: ``FRM1Q_Floating_tank_test``.
+
+DT (s)
+  Nominal timestep for WaveTank internal scheduling. Currently unused/reserved.
+
+TMax (s)
+  Maximum simulation time for WaveTank internal scheduling. Currently unused/reserved.
+
+MHK (switch)
+  MHK turbine type switch:
+
+  - 0: Not an MHK turbine
+  - 1: Fixed MHK turbine
+  - 2: Floating MHK turbine
+
+  Only the floating option (2) is supported at present.
+
+InterpOrd (-)
+  Interpolation order for internal data interpolation. Currently unused/reserved.
+
+DebugLevel (switch)
+  Controls logging and visualization detail:
+
+  - 0: none
+  - 1: I/O summary
+  - 2: + positions/orientations passed
+  - 3: + input file
+  - 4: + all meshes
+
+.. note::
+   Parameters marked “unused” are reserved for future development and are currently ignored by the code path.
+
+Froude Scaling (disabled)
+-------------------------
+
+The following parameters may appear but are typically commented out. Froude scaling is not complete in the current code. Do not use unless explicitly enabled.
+
+ScaleFact (-)
+  Froude scaling factor λ = (full-size dimension) / (model-size dimension). Expected > 1 for scale-model testing.
+
+DensFact (-)
+  Density ratio ρ_full / ρ_model, used with Froude scaling of forces/moments.
+
+Environment
+-----------
+
+Gravity (m/s^2)
+  Gravitational acceleration.
+
+WtrDens (kg/m^3)
+  Water (working fluid) density.
+
+WtrVisc (m^2/s)
+  Kinematic viscosity of the working fluid.
+
+SpdSound (m/s)
+  Speed of sound in the working fluid.
+
+Patm (Pa)
+  Atmospheric pressure. Used for cavitation checks.
+
+Pvap (Pa)
+  Vapor pressure of the working fluid. Used for cavitation checks.
+
+WtrDpth (m)
+  Water depth.
+
+MSL2SWL (m)
+  Offset between still-water level (SWL) and mean sea level (MSL); positive upward.
+
+Sea State
+---------
+
+SS_InputFile (string)
+  Path to SeaState input file defining wave conditions. Ensure path is valid relative to the run directory or use an absolute path.
+
+WaveTimeShift (s)
+  Time shift applied to the SeaState wave time series to adjust phase and match tank conditions.
+
+MoorDyn
+-------
+
+MD_InputFile (string)
+  Path to MoorDyn input file defining mooring system properties and connections.
+
+AeroDyn and InflowWind
+----------------------
+
+AD_InputFile (string)
+  Path to AeroDyn input file defining aerodynamic model configuration (used for hydro/aero coupling as applicable in MHK context).
+
+IfW_InputFile (string)
+  Path to InflowWind input file defining inflow conditions for the rotor (e.g., currents or wind, depending on model setup).
+
+Turbine Geometry and Reference Frames
+-------------------------------------
+
+NumBl (-)
+  Number of blades on the rotor.
+
+HubRad (m)
+  Distance from the rotor apex to the blade root.
+
+PreCone (deg)
+  Blade cone angle.
+
+OverHang (m)
+  Distance from the yaw axis (tower centerline) to the rotor apex. Negative values indicate rotor apex aft of the yaw axis under the model’s convention.
+
+ShftTilt (deg)
+  Rotor shaft tilt angle.
+
+Twr2Shft (m)
+  Vertical distance from tower-top to the rotor shaft center (nacelle center). Negative values are below tower-top.
+
+TowerHt (m)
+  Height of the tower relative to MSL. Tower is vertically aligned with ``TowerBsPt`` (sloped towers not supported).
+
+TowerBsPt (m, m, m)
+  Tower base location relative to the platform reference position in x and y, and relative to MSL in z:
+
+  - x: along surge axis
+  - y: along sway axis
+  - z: height relative to MSL
+
+PtfmRefPos (m, m, m)
+  Platform reference point position relative to MSL. All platform motions and loads connect at this point.
+
+PtfmRefOrient (deg, deg, deg)
+  Platform reference orientation given as Euler angles [roll, pitch, yaw].
+
+Turbine Initial Conditions
+--------------------------
+
+RotSpeed (rpm)
+  Initial rotational speed of the rotor (in rotor coordinates).
+
+NacYaw (deg)
+  Initial or fixed nacelle yaw angle.
+
+BldPitch (deg)
+  Initial blade 1 pitch angle. If a multi-blade model is used, blade pitch control typically applies per blade in other modules; here this initializes blade 1.
+
+Azimuth (deg)
+  Initial rotor azimuth angle.
+
+Wave Buoy
+---------
+
+WaveBuoyLoc (m, m)
+  Location of the wave elevation measurement buoy in the tank coordinate frame. SeaState data is returned at each timestep at this location.
+
+Output
+------
+
+SendScreenToFile (flag)
+  If true, send screen output to a file named ``<OutRootName>.screen.log``.
+
+OutFile (switch)
+  Controls tabular output of channels:
+
+  - 0: no output file of channels
+  - 1: output file in text format (written at default DT)
+
+OutFmt (string)
+  Format specifier for text tabular output channels (excluding the time channel). Uses a Fortran-like format string.
+  Example: ``ES20.6E2``.
+
+VTK Visualization Output
+------------------------
+
+WrVTK_Dir (string)
+  Output directory for VTK visualization files.
+
+WrVTK (switch)
+  VTK visualization data output:
+
+  - 0: none
+  - 1: initialization data only
+  - 2: animation
+  - 3: mode shapes
+
+WrVTK_type (switch)
+  Type of VTK visualization data:
+
+  - 1: surfaces
+  - 2: basic meshes (lines/points)
+  - 3: all meshes (debug)
+
+.. note::
+   Only lines/points may be supported in some builds. If surfaces are not
+   supported, use ``WrVTK_type = 2`` to visualize line/point data.
+
+WrVTK_DT (s)
+  Timestep for writing VTK files.
+
+VTKNacDim (m, m, m, m, m, m)
+  Nacelle dimensions for VTK surface rendering in the format ``[x0, y0, z0, Lx, Ly, Lz]``:
+
+  - ``x0, y0, z0``: nacelle origin offsets
+  - ``Lx, Ly, Lz``: nacelle extents along x, y, z
+
+Implementation Notes and Best Practices
+---------------------------------------
+
+- Only floating MHK (``MHK = 2``) is currently supported; other MHK modes will
+  not perform as expected.
+- Ensure external file paths (*SeaState*, *MoorDyn*, *AeroDyn*, *InflowWind*)
+  are valid relative to the working directory or specify absolute paths.
+- Coordinate conventions:
+
+  - Positions and heights are referenced to MSL unless otherwise noted.
+  - The platform reference point (``PtfmRefPos``) is the coupling point for
+    motions and loads.
+  - The tower base is defined relative to ``PtfmRefPos`` in x and y, and to MSL
+    in z.
+
+- Choose ``OutFmt`` to balance precision and file size. The example ``ES20.6E2``
+  is suitable for scientific notation with fixed width.

glue-codes/labview/CMakeLists.txt

@@ -14,15 +14,29 @@
 # limitations under the License.
 #
 
-add_library(wavetanktestinglib SHARED 
+if (GENERATE_TYPES)
+  generate_f90_types(src/WaveTank_Registry.txt ${CMAKE_CURRENT_LIST_DIR}/src/WaveTank_Types.f90 -noextrap)
+endif()
+
+add_library(wavetanktesting_c_binding SHARED 
+    src/WaveTank_Types.f90
+    src/WaveTank_IO.f90
+    src/WaveTank_Struct.f90
     src/WaveTank.f90
 )
-target_link_libraries(wavetanktestinglib aerodyn_inflow_c_binding moordyn_c_binding seastate_c_binding nwtclibs versioninfolib)
+target_link_libraries(
+    wavetanktesting_c_binding
+        aerodyn_inflow_c_bind_static
+        moordyn_c_bind_static
+        seastate_c_bind_static
+        nwtclibs
+        versioninfolib
+)
 if(APPLE OR UNIX)
-    target_compile_definitions(wavetanktestinglib PRIVATE IMPLICIT_DLLEXPORT)
+    target_compile_definitions(wavetanktesting_c_binding PRIVATE IMPLICIT_DLLEXPORT)
 endif()
 
-install(TARGETS wavetanktestinglib
+install(TARGETS wavetanktesting_c_binding
 EXPORT "${CMAKE_PROJECT_NAME}Libraries"
 RUNTIME DESTINATION bin
 LIBRARY DESTINATION lib