Enable modeling of floating MHK turbines

docs/source/user/aerodyn/driver.rst

@@ -63,7 +63,7 @@ More details are provided below, where the different sections of the input file
 The input file starts with a header, the user can place a relevant description of the model on the second line.
 The input configuration section follows. 
 The user can toggle the flag `Echo` to write back the input file, as parsed by the driver, to disk.
-The `MHK` switch allows the user to specify whether or not the turbine is an MHK turbine. `MHK=0` denotes not an MHK turbine, `MHK=1` denotes a fixed MHK turbine, and `MHK=2` denotes a floating MHK turbine. Currently, only `MHK=0` or `MHK=1` can be specified.
+The `MHK` switch allows the user to specify whether or not the turbine is an MHK turbine. `MHK=0` denotes not an MHK turbine, `MHK=1` denotes a fixed MHK turbine, and `MHK=2` denotes a floating MHK turbine.
 The driver supports three kinds of analyses, but not all turbine formats and inflow types are available for each analysis type: 
 
 - `AnalysisType=1`: Simulation of one or multiple rotors with basic (HAWT) or arbitrary geometries (HAWT/VAWT, quad-rotor, etc.), with basic or advanced wind inputs, and optional time-varying motion of the tower base, nacelle and individual pitch angles. Arbitrary motion or sinusoidal motion of the tower base are possible.
@@ -97,7 +97,7 @@ Environmental conditions are specified here and passed to AeroDyn. `FldDens` (eq
 
 The inflow can be provided in two ways:
 
-- basic (`CompInflow=0`): uniform wind with a power law shear. The wind is defined using a reference height (`RefHt`), a power law exponent (`PLExp`), and the wind speed at reference height (`HWindSpeed`). With `AnalysisType=2`, the reference wind speed and power law are defined separately as time series (see "time-dependent analysis"). With `AnalysisType=3`, these parameters are provided in a separate table (see "Combined-Case analyses"). The reference height is used for all analyses types, since this height may be different than the hub height. The wind at a given node is determined using the following equation, where :math:`Z` is the instantaneous elevation of the node above the ground for land-based wind turbines, above the mean sea level (MSL) for offshore wind turbines, or above the seabed for MHK turbines.
+- basic (`CompInflow=0`): uniform wind with a power law shear. The wind is defined using a reference height (`RefHt`), a power law exponent (`PLExp`), and the wind speed at reference height (`HWindSpeed`). With `AnalysisType=2`, the reference wind speed and power law are defined separately as time series (see "time-dependent analysis"). With `AnalysisType=3`, these parameters are provided in a separate table (see "Combined-Case analyses"). The reference height is used for all analyses types, since this height may be different than the hub height. The wind at a given node is determined using the following equation, where :math:`Z` is the instantaneous elevation of the node above the ground for land-based wind turbines, above the mean sea level (MSL) for offshore wind turbines, or above the seabed for fixed and floating MHK turbines.
 
 .. math::
 
@@ -150,15 +150,15 @@ Two turbine input formats are supported:
 
 - basic (`BasicHAWTFormat=True`): Basic horizontal axis wind turbine (HAWT) format.
   In this format, the turbine geometry is entirely determined by the number of blades (`NumBlades`), the hub radius (`HubRad`), the hub height  (`HubHt`), the overhang (`Overhang`), the shaft tilt (`ShftTilt`), the precone (`Precone`), and the vertical distance from the tower-top to the rotor shaft (`Twr2Shft`), as shown in :numref:`fig:BasicGeometry`.
-  The definition of each parameter follows the ElastoDyn convention. For example, `HubRad` specifies the radius from the center-of-rotation to the blade root along the (possibly preconed) blade-pitch axis and must be greater than zero. `HubHt` specifies the elevation of the hub center above the ground for land-based wind turbines, above the mean sea level (MSL) for offshore wind turbines, or above the seabed for MHK turbines. `Overhang` specifies the distance along the (possibly tilted) rotor shaft between the tower centerline and hub center and is positive downwind (use a negative number for upwind rotors). `ShftTilt` is the angle (in degrees) between the rotor shaft and the horizontal plane, and positive `ShftTilt` means that the downwind end of the shaft is the highest (upwind turbines have negative `ShftTilt` for improved tower clearance). `Precone` is the angle (in degrees) between a flat rotor disk and the cone swept by the blades, positive downwind (upwind turbines have negative `Precone` for improved tower clearance).
+  The definition of each parameter follows the ElastoDyn convention. For example, `HubRad` specifies the radius from the center-of-rotation to the blade root along the (possibly preconed) blade-pitch axis and must be greater than zero. `HubHt` specifies the elevation of the hub center above the ground for land-based wind turbines, relative to the mean sea level (MSL) for offshore wind and floating MHK turbines, or relative to the seabed for fixed MHK turbines. For floating MHK turbines with the hub positioned below the MSL, `HubHt` should be negative. `Overhang` specifies the distance along the (possibly tilted) rotor shaft between the tower centerline and hub center and is positive downwind (use a negative number for upwind rotors). `ShftTilt` is the angle (in degrees) between the rotor shaft and the horizontal plane, and positive `ShftTilt` means that the downwind end of the shaft is the highest (upwind turbines have negative `ShftTilt` for improved tower clearance). For floating MHK turbines, the sign of `ShftTilt` should be flipped to achieve an equivalent shaft tilt. For example, floating, upwind MHK turbines have positive `ShftTilt` for improved tower clearance. `Precone` is the angle (in degrees) between a flat rotor disk and the cone swept by the blades, positive downwind (upwind turbines have negative `Precone` for improved tower clearance). `Twr2Shft` is the vertical distance from the tower-top to the rotor shaft. For floating MHK turbines with the rotor below the tower-top, this value should be negative.
 
   .. figure:: figs/aerodyn_driver_geom.png
    :width: 60%
    :name: fig:BasicGeometry
 
    Definition of basic turbine geometry.
 
-  Additionally, the user needs to provide the origin of the turbine base at `t=0` (`BaseOriginInit`). An example of basic input is given below:
+  Additionally, the user needs to provide the origin of the turbine base at `t=0` (`BaseOriginInit`). For fixed MHK turbines, `BaseOriginInit` is input relative to the seabed. For floating MHK turbines, `BaseOriginInit` is input relative to the MSL, and the vertical component is negative if the turbine base is below the MSL. An example of basic input is given below:
 
 .. code::
 
@@ -176,7 +176,7 @@ Two turbine input formats are supported:
 
 - advanced (`BasicHAWTFormat=False`): The position and orientation of the tower base, nacelle, hub, and individual blades can be arbitrarily defined. This can be used for HAWT and any other turbine concepts. 
   The definition of the different frames are given in :numref:`fig:MultiRotor`.
-  The position (`BaseOriginInit`) and orientation (`BaseOrientationInit`) of the turbine base frame are defined with respect to the global frame. Orientations are given using the values of three successive rotations (x-y-z Euler angle sequence). If the base undergoes a motion, the orientation of the base frame will consist of the time-varying rotations followed by these initial rotations.
+  The position (`BaseOriginInit`) and orientation (`BaseOrientationInit`) of the turbine base frame are defined with respect to the global frame. The vertical component of `BaseOriginInit` is defined relative to the seabed for fixed MHK turbines and relative to the MSL for floating MHK turbines. Orientations are given using the values of three successive rotations (x-y-z Euler angle sequence). If the base undergoes a motion, the orientation of the base frame will consist of the time-varying rotations followed by these initial rotations.
 
   A flag indicating whether the turbine has a tower is given on the next line (`HasTower`). This flag currently affects the VTK outputs and does not have an impact on AeroDyn yet. The user still has to provide tower input data in AeroDyn for each turbine (see :numref:`ad_inputs_multirot`).
   The next line indicates which projection AeroDyn is to use in its calculation. It is recommended to use `HAWTprojection=True` for HAWT, which is the default projection used in AeroDyn (projects on the coned-pitched axis). For other rotor concepts, set `HAWTprojection=False`.
@@ -185,7 +185,8 @@ Two turbine input formats are supported:
   The tower and the nacelle are defined with respect to the turbine base (t) origin and frame.
   The tower top is assumed to coincide with the nacelle origin. 
   The tower stations defined in the AeroDyn input file are assumed to be given with respect to the tower origin, unlike OpenFAST which uses ground/MSL as a reference (see :numref:`ad_inputs_multirot`).
-  The hub is defined with respect to the nacelle origin and frame (n).
+  For floating MHK turbines, the vertical components of `TwrOrigin_t` and `NacOrigin_t` are negative if the tower origin and nacelle origin are below the turbine base.
+  The hub is defined with respect to the nacelle origin and frame (n). The vertical component of `HubOrigin_n` is negative for floating MHK turbines if the hub origin is below the nacelle origin (i.e., tower top).
 
   The definitions of the blades follow, starting with the number of blades `NumBlades`. A rotor with zero blades is supported and can be used to model an isolated tower.
   If tower shadow/potential is used in AeroDyn, then the isolated tower will disturb the flow of the vortex wake when OLAF is used.
@@ -250,7 +251,7 @@ An example of inputs for a sinusoidal surge motion is given below:
 
 The different inputs for the basic and advanced geometries are given below:
 
-- basic: The motion of a basic turbine consists of a constant nacelle yaw (`NacYaw`, positive rotation of the nacelle about the vertical tower axis, counterclockwise when looking downward), rotor speed (`RotSpeed`, positive clockwise looking downwind), and blade pitch (`BldPitch`, negative around :math:`z_b`). 
+- basic: The motion of a basic turbine consists of a constant nacelle yaw (`NacYaw`, positive rotation of the nacelle about the vertical tower axis, counterclockwise when looking downward), rotor speed (`RotSpeed`, positive clockwise looking downwind), and blade pitch (`BldPitch`, negative around :math:`z_b`). For floating MHK turbines, `NacYaw` should be flipped to achieve the same global yaw direction (i.e., positive rotation of the nacelle about the vertical tower axis, clockwise when looking downward).
   Examples are given below:
 
 .. code::

docs/source/user/aerodyn/index.rst

@@ -15,7 +15,7 @@ can be downladed from the list below.
 - :download:`Predicting Cavitation on Marine and Hydrokinetic Turbine Blades with AeroDyn V15.04 <https://www.nrel.gov/docs/fy17osti/68398.pdf>`
 - :download:`Development Plan for the Aerodynamic Linearization of OpenFAST <../../../OtherSupporting/AeroDyn/AeroLin_2019-12.pdf>`
 - :download:`AeroDyn Meshes and Related Calculations <../../../OtherSupporting/AeroDyn/AeroDynMesh_Rev4.docx>`
-- :download:`Calculation of Buoyancy on a Marine Hydrokinetic Turbine in AeroDyn <../../../OtherSupporting/AeroDyn/Buoyancy_Implementation_Plan_Rev3.docx>`
+- :download:`Calculation of Buoyancy on a Marine Hydrokinetic Turbine in AeroDyn <../../../OtherSupporting/AeroDyn/Buoyancy_Implementation_Plan_Rev11.docx>`
 
 .. - :download:` <AeroDyn_Plan_TCF_AddedMass_Force.docx*>`
 

docs/source/user/aerodyn/input.rst

@@ -324,6 +324,28 @@ rotors. The file names should be in quotations and can contain an absolute path
 or a relative path. The data in each file need not be identical, which
 permits modeling of aerodynamic imbalances.
 
+Hub Properties
+~~~~~~~~~~~~~~
+The input parameters in this section pertain to the calculation of buoyant loads
+on the hub and are only used when ``Buoyancy = TRUE``.
+
+``VolHub`` is the volume of the hub and ``HubCenBx`` is the x offset of the hub
+center of buoyancy from the hub center in local hub coordinates;
+offsets in the y and z directions are assumed to be zero. To neglect buoyant 
+loads on the hub, set ``VolHub`` to 0.
+
+Since the hub and blades are joined elements, hub buoyancy should be turned on if blade buoyancy is on, and vice versa.
+
+Nacelle Properties
+~~~~~~~~~~~~~~~~~~
+The input parameters in this section pertain to the calculation of buoyant loads
+on the nacelle and are only used when ``Buoyancy = TRUE``.
+
+``VolNac`` is the volume of the nacelle and ``NacCenB``` is the 
+position (x,y,z vector) of the nacelle center of buoyancy from
+the yaw bearing in local nacelle coordinates. To neglect buoyant 
+loads on the nacelle, set ``VolNac`` to 0.
+
 Tail fin AeroDynamics
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -358,16 +380,18 @@ header lines). ``NumTwrNds`` must be greater than or equal to two; the
 higher the number, the finer the resolution and longer the computational
 time; we recommend that ``NumTwrNds`` be between 10 and 20 to balance
 accuracy with computational expense. For each node, ``TwrElev``
-specifies the local elevation of the tower node above ground (or above
-MSL for offshore wind turbines or above the seabed for MHK turbines),
+specifies the local elevation of the tower node above ground (or relative
+to MSL for offshore wind and floating MHK turbines or relative to the seabed for fixed MHK turbines),
 ``TwrDiam`` specifies the local tower diameter, ``TwrCd`` specifies the
 local tower drag-force coefficient, ``TwrTI`` specifies the
 turbulence intensity used in the Eames tower shadow model
 (``TwrShadow`` = 2) as a fraction (rather than a percentage) of the
 wind fluctuation, and ``TwrCb`` specifies the tower buoyancy coefficient.
 ``TwrElev`` must be entered in monotonically increasing order—from the lowest
-(tower-base) to the highest (tower-top) elevation. Values of ``TwrTI`` between
-0.05 and 0.4 are recommended.  Values larger than 0.4 up to 1 will trigger a 
+(tower-base) to the highest (tower-top) elevation. For floating MHK turbines with 
+the tower below MSL, tower nodes should be entered as increasingly negative values,
+from the tower-base (closest to the platform) to the tower-top (closest to the nacelle).
+Values of ``TwrTI`` between 0.05 and 0.4 are recommended. Values larger than 0.4 up to 1 will trigger a 
 warning that the results will need to be interpreted carefully, but the code
 will allow such values for scientific investigation purposes. ``TwrCb`` is
 defined at each node as the cross-sectional area of the tower divided by the 
@@ -376,26 +400,6 @@ cross section (i.e., ``TwrDiam``). For towers with circular cross-sections,
 ``TwrCb`` will likely be 1.0 at each node. To neglect buoyant loads on the 
 tower, set ``TwrCb`` to 0. See :numref:`ad_tower_geom`.
 
-Hub Properties
-~~~~~~~~~~~~~~
-The input parameters in this section pertain to the calculation of buoyant loads
-on the hub and are only used when ``Buoyancy = TRUE``.
-
-``VolHub`` is the volume of the hub and ``HubCenBx`` is the x offset of the hub
-center of buoyancy from the hub center in local hub coordinates;
-offsets in the y and z directions are assumed to be zero. To neglect buoyant 
-loads on the hub, set ``VolHub`` to 0.
-
-Nacelle Properties
-~~~~~~~~~~~~~~~~~~
-The input parameters in this section pertain to the calculation of buoyant loads
-on the nacelle and are only used when ``Buoyancy = TRUE``.
-
-``VolNac`` is the volume of the nacelle and ``NacCenB``` is the 
-position (x,y,z vector) of the nacelle center of buoyancy from
-the yaw bearing in local nacelle coordinates. To neglect buoyant 
-loads on the nacelle, set ``VolNac`` to 0.
-
 .. _AD-Outputs:
 
 Outputs
@@ -836,7 +840,7 @@ nodes. For each node:
 -  ``BlCb`` specifies the blade buoyancy coefficient, defined as the local
    cross-sectional area of the blade divided by the area of a circle with 
    diameter equal to ``BlChord``; to neglect buoyant loads on the blade,
-   set ``BlCb`` to 0;
+   set ``BlCb`` to 0; since the blades and hub are joined elements, blade buoyancy should be turned on if hub buoyancy is on, and vice versa;
 
 -  ``BlCenBn`` specifies the offset of the blade center of buoyancy from the
    aerodynamic center in the direction normal to the chord (positive pointing

docs/source/user/aerodyn/modeling.rst

@@ -51,15 +51,15 @@ When the tower potential-flow (``TwrPotent > 0``), tower shadow
 (``TwrAero = TRUE``) models are enabled, we also recommend that
 ``NumTwrNds`` be between 10 and 20 to balance accuracy with
 computational expense. Normally the local elevation of the tower node
-above ground (or above MSL for offshore wind turbines or above the
-seabed for MHK turbines) (``TwrElev``), must be entered in
-monotonically increasing order from the lowest (tower-base) to the
-highest (tower-top) elevation. However, when AeroDyn is coupled to FAST,
-the tower-base node in AeroDyn cannot be set lower than the lowest point
+above ground (or relative to MSL for offshore wind and floating 
+MHK turbines or relative to the seabed for fixed MHK turbines) (``TwrElev``),
+must be entered in monotonically increasing order from the lowest (tower-base) to the
+highest (tower-top) elevation (or monotonically decreasing order for floating MHK turbines).
+However, when AeroDyn is coupled to FAST, the tower-base node in AeroDyn cannot be set lower than the lowest point
 where wind is specified in the InflowWind module. To avoid truncating
 the lower section of the tower in AeroDyn, we recommend that the wind be
 specified in InflowWind as low to the ground (or MSL for offshore wind
-turbines or above the seabed for MHK turbines) as possible (this is a
+turbines or seabed for fixed and floating MHK turbines) as possible (this is a
 particular issue for full-field wind file formats).
 
 Model Options Under Operational and Parked/Idling Conditions