Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HydroDyn user documentation update for large platform rotation #2455

Merged
merged 3 commits into from
Oct 21, 2024
Merged

HydroDyn user documentation update for large platform rotation #2455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3847015
HD Doc: Update the HydroDyn user documentation for large platform yaw…
luwang00 Oct 8, 2024
1443b87
HD: Update error messages, variable descriptions, and comments to mat…
luwang00 Oct 8, 2024
0360ef0
HD Doc: Clarify in the HydroDyn user documentation that PtfmYMod=1 on…
luwang00 Oct 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions docs/source/user/hydrodyn/appendix.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,13 @@ structure::
False Echo - Echo the input file data (flag)
---------------------- FLOATING PLATFORM --------------------------------------- [unused 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]
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 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)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Presumably this angle should be in the [-180, 180) deg range?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PtfmRefY does not need to be strictly between [-180,180), not intentionally at least. Integer multiples of 360 deg are added as appropriate at various places in the code to handle this.

0.01 PtfmYCutOff - Cutoff frequency for the low-pass filtering of PRP yaw motion when PtfmYMod=1 [>0.0; unused when PtfmYMod=0] (Hz)
36 NExctnHdg - Number of evenly distributed platform yaw/heading angles over the range of [-180, 180) deg for which the wave excitation shall be computed [>=2; unused when PtfmYMod=0] (-)
1 RdtnMod - Radiation memory-effect model {0: no memory-effect calculation, 1: convolution, 2: state-space} (switch) [only used when PotMod=1; STATE-SPACE REQUIRES *.ss INPUT FILE]
60 RdtnTMax - Analysis time for wave radiation kernel calculations (sec) [only used when PotMod=1 and RdtnMod>0; determines RdtnDOmega=Pi/RdtnTMax in the cosine transform; MAKE SURE THIS IS LONG ENOUGH FOR THE RADIATION IMPULSE RESPONSE FUNCTIONS TO DECAY TO NEAR-ZERO FOR THE GIVEN PLATFORM!]
0.0125 RdtnDT - Time step for wave radiation kernel calculations (sec) [only used when PotMod=1 and ExctnMod>0 or RdtnMod>0; DT<=RdtnDT<=0.1 recommended; determines RdtnOmegaMax=Pi/RdtnDT in the cosine transform]
Expand All @@ -32,8 +36,8 @@ structure::
---------------------- 2ND-ORDER FLOATING PLATFORM FORCES ---------------------- [unused with WaveMod=0 or 6, or PotMod=0 or 2]
0 MnDrift - Mean-drift 2nd-order forces computed {0: None; [7, 8, 9, 10, 11, or 12]: WAMIT file to use} [Only one of MnDrift, NewmanApp, or DiffQTF can be non-zero. If NBody>1, MnDrift /=8]
0 NewmanApp - Mean- and slow-drift 2nd-order forces computed with Newman's approximation {0: None; [7, 8, 9, 10, 11, or 12]: WAMIT file to use} [Only one of MnDrift, NewmanApp, or DiffQTF can be non-zero. If NBody>1, NewmanApp/=8. Used only when WaveDirMod=0]
0 DiffQTF - Full difference-frequency 2nd-order forces computed with full QTF {0: None; [10, 11, or 12]: WAMIT file to use} [Only one of MnDrift, NewmanApp, or DiffQTF can be non-zero]
0 SumQTF - Full summation -frequency 2nd-order forces computed with full QTF {0: None; [10, 11, or 12]: WAMIT file to use}
0 DiffQTF - Full difference-frequency 2nd-order forces computed with full QTF {0: None; [10, 11, or 12]: WAMIT file to use} [Only one of MnDrift, NewmanApp, or DiffQTF can be non-zero. If PtfmYMod=1, need DiffQTF=0]
0 SumQTF - Full summation -frequency 2nd-order forces computed with full QTF {0: None; [10, 11, or 12]: WAMIT file to use} [If PtfmYMod=1, need SumQTF=0]
---------------------- PLATFORM ADDITIONAL STIFFNESS AND DAMPING -------------- [unused with PotMod=0 or 2]
0 AddF0 - Additional preload (N, N-m) [If NBodyMod=1, one size 6*NBody x 1 vector; if NBodyMod>1, NBody size 6 x 1 vectors]
0
Expand All @@ -60,7 +64,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 WaveDisp - Method of computing Wave Kinematics {0: use undisplaced position, 1: use displaced position) } (switch) [If PtfmYMod=1, need WaveDisp=1]
0 AMMod - Method of computing distributed added-mass force. (0: Only and always on nodes below SWL at the undisplaced position. 2: Up to the instantaneous free surface) [overwrite to 0 when WaveMod = 0 or 6 or when WaveStMod = 0 in SeaState]
---------------------- AXIAL COEFFICIENTS --------------------------------------
2 NAxCoef - Number of axial coefficients (-)
Expand Down
140 changes: 115 additions & 25 deletions docs/source/user/hydrodyn/input_files.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,20 @@ computed and printed to the calling terminal. **NSteps** specifies the
number of simulation time steps, and **TimeInterval** specifies the time
between steps.

Motion of the structure can be specified in different ways according to
**PRPInputsMod**. Irrespective of the choice of **PRPInputsMod** (which
are explained below), the translational displacement, velocity, and
acceleration are always specified in the global inertial-frame coordinate
system. With OpenFAST now updated to support potentially large platform
rotation, the specification of rotation differs from previous versions.
HydroDyn now describes body rotation using Tait-Bryan roll, pitch, and
yaw angles with the convention of intrinsic (about body-fixed axis) yaw
rotation first, followed by pitch rotation, and roll last. Furthermore,
HydroDyn now expects the first and second time derivatives of the
Tait-Bryan roll, pitch, and yaw angles in place of angular velocity and
acceleration. The standalone HydroDyn driver will convert these inputs
to angular velocity and acceleration internally.

Setting **PRPInputsMod** = 0 forces all platform reference point (PRP)
input motions to zero for all time. If you set **PRPInputsMod** = 1,
then you must set the steady-state inputs in the PRP STEADY STATE
Expand All @@ -67,25 +81,24 @@ time-series input file whose name is specified via the
file. This file has no header lines. Each data row corresponds to a
given time step, and the whitespace separated columns of floating point
values represent the necessary motion inputs as shown in
:numref:`hd-prp_input_table`. All motions are specified in the global
inertial-frame coordinate system.
:numref:`hd-prp_input_table`.

.. _hd-prp_input_table:

.. table:: PRP Inputs Time-Series Data File Contents (**PRPInputsMod** = 2)
:widths: auto

============= ================================================================================ ======================================
Column Number Input Units
============= ================================================================================ ======================================
1 Time step value .. math:: s
2-4 Translational displacements along *X*, *Y*, and *Z* .. math:: m
5-7 Rotational displacements about *X*, *Y*, and *Z* (small angle assumptions apply) .. math:: \text{radians}
8-10 Translational velocities along *X*, *Y*, and *Z* .. math:: \frac{m}{s}
11-13 Rotational velocities about *X*, *Y*, and *Z* .. math:: \frac{\text{radians}}{s}
14-16 Translational accelerations along *X*, *Y*, and *Z* .. math:: \frac{m}{s^{2}}
17-19 Rotational accelerations about *X*, *Y*, and *Z* .. math:: \frac{\text{radians}}{s^{2}}
============= ================================================================================ ======================================
============= ====================================================================== ======================================
Column Number Input Units
============= ====================================================================== ======================================
1 Time step value .. math:: s
2-4 Translational displacements along *X*, *Y*, and *Z* .. math:: m
5-7 Tait-Bryan roll, pitch, and yaw angles .. math:: \text{radians}
8-10 Translational velocities along *X*, *Y*, and *Z* .. math:: \frac{m}{s}
11-13 First time derivatives of the Tait-Bryan roll, pitch, and yaw angles .. math:: \frac{\text{radians}}{s}
14-16 Translational accelerations along *X*, *Y*, and *Z* .. math:: \frac{m}{s^{2}}
17-19 Second time derivatives of the Tait-Bryan roll, pitch, and yaw angles .. math:: \frac{\text{radians}}{s^{2}}
============= ====================================================================== ======================================

With **PRPInputsMod** = 1 or 2, any potential-flow bodies and strip-theory
members defined in the primary HydroDyn input file will follow the prescribed
Expand All @@ -110,18 +123,18 @@ with respect to time.
.. table:: PRP Inputs Time-Series Data File Contents (**PRPInputsMod** < 0)
:widths: auto

============= ================================================================================================================ ========================
Column Number Input Units
============= ================================================================================================================ ========================
1 Time step value .. math:: s
2-4 Translational displacements of the PRP along *X*, *Y*, and *Z* .. math:: m
5-7 Rotational displacements of the PRP about *X*, *Y*, and *Z* (small angle assumptions apply) .. math:: \text{radians}
8-10 Translational displacements of the 1st potential-flow body along *X*, *Y*, and *Z* .. math:: m
11-13 Rotational displacements of the 1st potential-flow body about *X*, *Y*, and *Z* (small angle assumptions apply) .. math:: \text{radians}
14-16 Translational displacements of the 2nd potential-flow body along *X*, *Y*, and *Z* .. math:: m
17-19 Rotational displacements of the 2nd potential-flow body about *X*, *Y*, and *Z* (small angle assumptions apply) .. math:: \text{radians}
... ... ...
============= ================================================================================================================ ========================
============= =================================================================================== ========================
Column Number Input Units
============= =================================================================================== ========================
1 Time step value .. math:: s
2-4 Translational displacements of the PRP along *X*, *Y*, and *Z* .. math:: m
5-7 Tait-Bryan roll, pitch, and yaw angles of the PRP .. math:: \text{radians}
8-10 Translational displacements of the 1st potential-flow body along *X*, *Y*, and *Z* .. math:: m
11-13 Tait-Bryan roll, pitch, and yaw angles of the 1st potential-flow body .. math:: \text{radians}
14-16 Translational displacements of the 2nd potential-flow body along *X*, *Y*, and *Z* .. math:: m
17-19 Tait-Bryan roll, pitch, and yaw angles of the 2nd potential-flow body .. math:: \text{radians}
... ... ...
============= =================================================================================== ========================

.. _hd-primary-input:

Expand Down Expand Up @@ -200,6 +213,83 @@ motion to prevent double counting the contributions from first-order
structural motion already included in the second-order potential-flow wave
excitation.

HydroDyn now supports large but slow (well below wave frequencies)
transient platform yaw motion with both strip-theory only and hybrid
potential-flow models. To enable this capability, the inputs
**PtfmYMod**, **PtfmRefY**, **PtfmYCutoff**, and **NExctnHdg** must
be set appropriately. Note that HydroDyn still requires the platform
roll and pitch angles to be small, i.e., within +/-15 deg.

To conform with the first- and second-order potential-flow theory,
which limits the structure to small displacement about a reference
mean position, a constant or slowly varying reference platform yaw
orientation must be established.

Setting **PtfmYMod** = 0 lets HydroDyn use a constant reference yaw
angle given by **PtfmRefY** in degrees. In this case, the platform
yaw rotation during the simulation, as given by the **PRPYaw**
output channel, must stay within +/-15 deg of **PtfmRefY** specified
by the user. A severe warning will be displayed if this requirement
is not met at any point during the simulation, while still allowing
the simulation to continue if possible. With a hybrid potential-flow
model, the potential-flow wave excitation input file needs to cover
a suitable range of wave headings relative to the platform after a
yaw offset of **PtfmRefY** is applied.

Alternatively, **PtfmYMod** = 1 lets HydroDyn update the reference
yaw position **PtfmRefY** dynamically based on the low-pass-filtered
platform yaw rotation, analogous to the modeling of slow-drift motion
with **ExctnDisp** = 2 above. In this case, the **PtfmRefY** input
allows the user to specify the initial reference yaw position at
**t** = 0. The cutoff frequency of the first-order low-pass filter
for platform yaw rotation can be set with **PtfmYCutoff** in Hz.
Ideally, **PtfmYCutoff** should be placed between the wave frequency
region and the characteristic frequency of any slow but large change
in platform heading to filter out as much wave-frequency platform
motion as possible while minimizing the phase shift in the low-frequency
heading change. Throughout the simulation, the instantaneous
platform yaw rotation should stay within +/-15 deg of the now
time-dependent **PtfmRefY**. A severe warning will be displayed if
this requirement is not met at any point during the simulation, while
still allowing the simulation to continue if possible.

With **PtfmYMod** = 1, HydroDyn requires the first- and second-order
(mean- or slow-drift loads from Newman's approximation only)
potential-flow wave excitation input file(s) to cover the full range
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought second-order must be disabled with PtfmYMod =1?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should still support mean- and slow-drift loads through MnDrift or NewmanApp. This is explained below, but I added a clarification here as well.

of possible wave headings with the first (smallest) wave heading being
exactly -180 deg and the last (largest) wave heading being exactly
+180 deg (the duplicated wave headings of +/-180 deg are intentional).
HydroDyn will error out if this requirement is not met by the input files.
HydroDyn uses this information to precompute the wave excitation on
the platform for **NExctnHdg** evenly distributed platform yaw/heading
angles over the range of [-180,+180) deg. For instance, with
**NExctnHdg** = 36, HydroDyn will precomupte the wave excitation for 0,
10, 20, ..., 350 deg platform heading. The instantaneous wave excitation
applied on the platform during the time-domain simulation is interpolated
from this data based on the instantaneous **PtfmRefY**. **NExctnHdg**
should be set appropriately to ensure adequate angular resolution in
platform heading. However, a high **NExctnHdg** can increase memory use
by OpenFAST substantially.

Additional constraints on HydroDyn inputs apply when **PtfmYMod** = 1.
The strip-theory hydrodynamic load must be evaluated using the wave
kinematics and dynamic pressure at the displaced structure position
by setting **WaveDisp** = 1. State-space wave excitation cannot be used.
**ExctnMod** must be either 0 (no wave excitation) or 1 (frequency-to-time
domain transform using inverse discrete Fourier transform). Lastly,
full difference- and sum-frequency QTFs are not supported, requiring
both **DiffQTF** and **SumQTF** to be set to 0. However, mean- or
slow-drift loads based on Newman's approximation can be included through
the **MnDrift** or **NewmanApp** inputs explained below.

Note that the inputs **PtfmYMod** and **PtfmRefY** also affect the
strip-theory hydrodynamic load. This is because the orientation of
the strip-theory members is updated based on **PtfmRefY** instead
of the instantaneous platform yaw rotation. Behavior of previous
versions of HydroDyn can be approximately recovered by setting
**PtfmYMod** = 0 and **PtfmRefY** = 0 deg, in which case, the
inputs **PtfmYCutoff** and **NExctnHdg** are not used.

HydroDyn has two methods for calculating the radiation memory effect.
Set **RdtnMod** to 1 for the convolution method, 2 for the linear
state-space model, or 0 to disable the memory effect calculation. For
Expand Down
2 changes: 1 addition & 1 deletion modules/hydrodyn/src/HydroDyn.f90
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1260,7 +1260,7 @@ SUBROUTINE HydroDyn_CalcOutput( Time, u, p, x, xd, z, OtherState, y, m, ErrStat,
END IF
IF ( (ABS( WrapToPi(PRPRotation(3)-PtfmRefY) ) > LrgAngle) .AND. FrstWarn_LrgY ) THEN
ErrStat2 = ErrID_Severe
ErrMsg2 = 'Yaw angle at PRP relative to the reference yaw position (PtfmRefY) violated the small angle assumption. The solution might be inaccurate. Consider using PtfmYMod=1 and adjust PtfmYCutoff in ElastoDyn. Simulation continuing, but future warnings will be suppressed.'
ErrMsg2 = 'Yaw angle at PRP relative to the reference yaw position (PtfmRefY) violated the small angle assumption. The solution might be inaccurate. Consider using PtfmYMod=1 and adjust PtfmYCutoff. Simulation continuing, but future warnings will be suppressed.'
call SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName )
FrstWarn_LrgY = .FALSE.
END IF
Expand Down
Loading