Clean-up, refactor, streamlining, and upgrades for HydroDyn strip-theory implementation

docs/source/user/api_change.rst

@@ -41,6 +41,42 @@ AeroDyn                                       \*                            (-)
 OLAF                                          26       RegFunctionPart            2  RegFunctionPart - Particle regularization function {0: None, 1: Exponential, 2: Compact, "default": 1} [only if VelocityMethod=2,3] (switch)
 ============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
 
+The meaning of the HydroDyn ``WaveDisp`` input has changed, although its valid values (0 and 1) are unchanged.
+``WaveDisp`` now controls both where the wave kinematics and dynamic pressure are evaluated and the orientation
+of the strip-theory (Morison) members and joints. With ``WaveDisp=0``, the strip-theory members are placed at a
+reference configuration consistent with the potential-flow model—the reference yaw (from ``PtfmYMod``,
+``PtfmRefY``, and ``PtfmYCutOff``) plus a horizontal x-y drift of the platform reference point governed by
+``ExctnDisp`` and ``ExctnCutOff``—rather than being held at the undisplaced position rotated by a constant
+``PtfmRefY``. These five inputs are honored by strip-theory members when ``WaveDisp=0`` even if no potential-flow
+model is present (``PotMod=0``). The previous ``WaveDisp=0`` behavior is recovered by setting ``PtfmYMod=0`` and
+``ExctnDisp=0``. With ``WaveDisp=1``, the exact instantaneous displaced position and orientation are used, including
+the vertical displacement, which was previously ignored unless ``WaveStMod>0``.
+
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+Modified in OpenFAST `5.1.0`                             
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Module                                        Line     Flag Name            Example Value
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+HydroDyn                                      7        ExctnDisp            0     ExctnDisp      - Method of computing Wave Excitation {0: use undisplaced position, 1: use displaced position, 2: use low-pass filtered displaced position} [used by potential flow when PotMod=1, ExctnMod>0, and SeaState's WaveMod>0; also used by strip theory when WaveDisp=0] (switch)
+HydroDyn                                      8        ExctnCutOff          0.01  ExctnCutOff    - Cutoff (corner) frequency of the low-pass time-filtered displaced position (Hz) [>0.0; only used when ExctnDisp=2]
+HydroDyn                                      \*       WaveDisp             0   WaveDisp       - Method of displacing strip-theory members and joints {0: use potential-flow consistent displacement, 1: use exact instantaneous displacement} (switch)
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+
+In previous versions of OpenFAST, HydroDyn's input file included the ``AMMod`` option to control the method of computing
+distributed strip-theory added-mass force. Setting ``AMMod`` to 0 forces HydroDyn to always compute the added-mass
+force up to the still water level (SWL). This switch was added because of numerical stability issues encountered when
+evaluating the added-mass force up to the instantaneous free surface with some hydroelastic models. With the improved
+solver stability of OpenFAST `5.1.0`, the ``AMMod`` option was deemed no longer necessary based on user feedback and was
+removed.
+
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+Removed in OpenFAST `5.1.0`                             
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Module                                        Line     Flag Name            Example Value
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+HydroDyn                                      \*       AMMod                0   AMMod       - Method of computing distributed strip-theory added-mass force {0: evaluate up to SWL, 1: evaluate up to instantaneous free surface if WaveStMod > 0} (switch)
+============================================= ======== ==================== ==========================================================================================================================================================================================================================================================================================================
+
 OpenFAST v4.2.x to OpenFAST  v5.0.0
 -----------------------------------
 

docs/source/user/hydrodyn/appendix.rst

@@ -10,11 +10,11 @@ structure::
       ------- HydroDyn Input File ----------------------------------------------------
       historic NREL 5.0 MW offshore baseline floating platform HydroDyn input properties for the OC4 Semi-submersible.
       False            Echo           - Echo the input file data (flag)
-      ---------------------- FLOATING PLATFORM --------------------------------------- [unused with WaveMod=6]
+      ---------------------- FLOATING PLATFORM --------------------------------------- [only ExctnDisp, ExctnCutOff, PtfmYMod, PtfmRefY, and PtfmYCutOff used with WaveMod=6]
                    1   PotMod         - Potential-flow model {0: none=no potential flow, 1: frequency-to-time-domain transforms based on WAMIT output, 2: fluid-impulse theory (FIT)} (switch)
                    1   ExctnMod       - Wave-excitation model {0: no wave-excitation calculation, 1: DFT, 2: state-space} (switch) [only used when PotMod=1; STATE-SPACE REQUIRES *.ssexctn INPUT FILE; if PtfmYMod=1, need ExctnMod=0 or 1]
-                   0   ExctnDisp      - Method of computing Wave Excitation {0: use undisplaced position, 1: use displaced position, 2: use low-pass filtered displaced position) [only used when PotMod=1 and ExctnMod>0 and SeaState's WaveMod>0]} (switch)
-                  10   ExctnCutOff    - Cutoff (corner) frequency of the low-pass time-filtered displaced position (Hz) [>0.0] [used only when PotMod=1, ExctnMod>0, and ExctnDisp=2]) [only used when PotMod=1 and ExctnMod>0 and SeaState's WaveMod>0]} (switch)
+                   0   ExctnDisp      - Method of computing Wave Excitation {0: use undisplaced position, 1: use displaced position, 2: use low-pass filtered displaced position} [used by potential flow when PotMod=1, ExctnMod>0, and SeaState's WaveMod>0; also used by strip theory when WaveDisp=0] (switch)
+                  10   ExctnCutOff    - Cutoff (corner) frequency of the low-pass time-filtered displaced position (Hz) [>0.0; only used when ExctnDisp=2]
                    0   PtfmYMod       - Model for large platform yaw offset {0: Static reference yaw offset based on PtfmRefY, 1: dynamic reference yaw offset based on low-pass filtering the PRP yaw motion with cutoff frequency PtfmYCutOff} (switch)
                    0   PtfmRefY       - Constant (if PtfmYMod=0) or initial (if PtfmYMod=1) platform reference yaw offset (deg)
                 0.01   PtfmYCutOff    - Cutoff frequency for the low-pass filtering of PRP yaw motion when PtfmYMod=1 [>0.0; unused when PtfmYMod=0] (Hz)
@@ -67,8 +67,7 @@ structure::
                    0             0             0             0             0             0
                    0             0             0             0             0             0
       ---------------------- STRIP THEORY OPTIONS --------------------------------------
-                   0   WaveDisp       - Method of computing Wave Kinematics {0: use undisplaced position, 1: use displaced position} (switch)
-                   0   AMMod          - Method of computing distributed added-mass force. {0: Only and always on nodes below SWL at the undisplaced position. 1: Up to the instantaneous free surface} (switch) [overwrite to 0 when WaveStMod = 0 in SeaState]
+                   0   WaveDisp       - Method of displacing strip-theory members and joints {0: use potential-flow consistent displacement, 1: use exact instantaneous displacement} (switch)
                    0   HstMod         - Method of computing hydrostatic loads. {0: Up to the still water level. 1: Up to the instantaneous free surface} (switch) [overwrite to 0 when WaveStMod = 0 in SeaState]
       ---------------------- AXIAL COEFFICIENTS --------------------------------------
                    2   NAxCoef        - Number of axial coefficients (-)