From e261686dd9eb10ef9bac179c6ede22a3391140a2 Mon Sep 17 00:00:00 2001 From: andrew-platt Date: Fri, 5 Mar 2021 12:30:39 -0700 Subject: [PATCH 1/4] Add documentation on input file parsers Also add missing documentation on the IfW input file change from v2.4.0 to v2.5.0 --- docs/source/user/api_change.rst | 14 ++- docs/source/user/index.rst | 1 + docs/source/user/input_file_overview.rst | 120 +++++++++++++++++++++++ 3 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/source/user/input_file_overview.rst diff --git a/docs/source/user/api_change.rst b/docs/source/user/api_change.rst index 2303e45a71..92d013ac31 100644 --- a/docs/source/user/api_change.rst +++ b/docs/source/user/api_change.rst @@ -135,10 +135,22 @@ InflowWind 7 VFlowAng 0 VFlowAng - Upflow angle (de - The input file parser is updated to a keyword/value pair based input. Each entry must have a corresponding keyword with the same spelling as - expected + expected. See :numref:`input_file_overview` for an overview. - Driver code includes ability to convert between wind types +Modified in OpenFAST v2.4.0 +--------------------------- + +============== ==== ================== ======================================================================================================================================================= ===================== + Module Line New Flag Name Example Value Previous Flag Name +============== ==== ================== ======================================================================================================================================================= ===================== +InflowWind 17 Filename_Uni "unused" Filename_Uni - Filename of time series data for uniform wind field. (-) Filename +InflowWind 18 RefHt_Uni 90 RefHt_Uni - Reference height for horizontal wind speed (m) RefHt +InflowWind 35 RefHt_Hawc 90 RefHt_Hawc - reference height; the height (in meters) of the vertical center of the grid (m) RefHt +InflowWind 47 PLExp_Hawc 0.2 PLExp_Hawc - Power law exponent (-) (used for PL wind profile type only) PLExp +InflowWind 49 XOffset 0 XOffset - Initial offset in +x direction (shift of wind box) InitPosition(x) +============== ==== ================== ======================================================================================================================================================= ===================== OpenFAST v2.3.0 to OpenFAST v2.4.0 diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst index 2f835a9e22..ed8260452d 100644 --- a/docs/source/user/index.rst +++ b/docs/source/user/index.rst @@ -13,6 +13,7 @@ Details on the transition from FAST v8 to OpenFAST may be found in :numref:`fast :maxdepth: 1 api_change.rst + input_file_overview.rst aerodyn/index.rst aerodyn-olaf/index.rst aerodyn-aeroacoustics/index.rst diff --git a/docs/source/user/input_file_overview.rst b/docs/source/user/input_file_overview.rst new file mode 100644 index 0000000000..d15d614f9b --- /dev/null +++ b/docs/source/user/input_file_overview.rst @@ -0,0 +1,120 @@ +.. _input_file_overview: + + +Overview of input file formats +============================== + +OpenFAST uses two primary input file formats: *value column* where the first +value on the line is read, and *key+value* where a value and keyword pair are +read. Both formats are line number based where a specific input is expected on a +specific line, with some exceptions. + +.. _sec_value_column: + +Value column input files +------------------------ + +Only the first column in a *value column* based input file is read. This is the +historical format used by OpenFAST and it's predecessors. Everything after the +first value read is simply ignored by the code. This allowed the user to keep +old values while modifying things. So for example, and input line like + +:: + + 2 20 TMax - Total run time (s) + +would be read as `2` and the `20` and everything after it ignored. + +This format and associated parsing methodology is somewhat limited in informing +the user of errors in parsing, and limited the ability to pass entire inpute +files as text strings from another code (such as a Python driver code). + +.. _sec_format_key_value: + +Key + Value input files +----------------------- + +The first two columns are read in *key + value* input files. One of these two +columns must contain the **exact** keyword, and the other must contain the value +that corresponds to it. For example, an input line + +:: + + 20 TMax - Total run time (s) + +is equivalent to + +:: + + TMax 20 - Total run time (s) + +One additional feature of this input file format is the ability to add an +arbitrary number of comment lines wherever the user wishes. Any line starting +with `!`, `#`, or `%` will be treated as a comment line and ignored. For +example, + + +:: + + ! This is a comment line that will be skipped + % and this is also a comment line that will be skipped + # as is this comment line + 20 TMax - Total run time (s) + ! the first two columns in the above line will be read as the value + key + +The parser for this format of input file also tracks which lines were comments, +and which lines contained the value and key pair. If a keyname is not found the +parser will return an error with information about which line it was reading +from. + + +Reasons for change +~~~~~~~~~~~~~~~~~~ + +The main reason for the change in the input file parsing was to allow for the +passing of a complete input file in memory from a wrapper code into OpenFAST or +a module. For example, when including the AeroDyn module into a Python code, +the input file can be passed in directly in memory without writing to disk +first. This helps reduce the IO overhead in optimization loops where the module +might be called many times sequentially with very small changes to the input +file. *NOTE: this is still a work in progress, so not all modules can be linked +this way yet*. + +To accomplish this, the file parser written by Marshall Buhl for parsing airfoil +tables in AeroDyn 15 in FAST8 was used. This parser included the more robust +*key + value* input format. + + + +.. _sec_troubleshoot_input_file: + +Troubleshooting input files +--------------------------- + +When troubleshooting an input file error, try the following procedure: + +1. An error message containing a line number and variable name, the file format + being parsed is a *key + value* format. Check that the key is spelled + exactly as the input file. See :numref:`sec_format_key_value` below. +2. An error message containing only the variable name but no line number is a + *value column* input file format. See :numref:`sec_value_column` below. +3. Turn on `echo` option in the input file and check the resulting `.ech` for + which line the file parsing stopped at. This may help isolate where the input + file parsing failed when no line number is given in the error message. +4. Compare the problematic input file with an input file of the same type from + the regression test suite distributed with OpenFAST. See section + :numref:`testing` for details on the regression tests, or check the + repository at `r-test `__ . + + +.. + Input file type by module + ------------------------- + ============== ====================== ===================== + Module Input file Type + ============== ====================== ===================== + OpenFAST Main .fst input file Value column + OpenFAST Matlab mode shape Value column + OpenFAST Mode shape Value column + OpenFAST Checkpoint file Binary + ============== ====================== ===================== From bfb01af722aaaabed03588f90d991869a78e8082 Mon Sep 17 00:00:00 2001 From: andrew-platt Date: Mon, 8 Mar 2021 08:29:15 -0700 Subject: [PATCH 2/4] Docs: Fix typo in api-change for StC inputs --- docs/source/user/api_change.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/user/api_change.rst b/docs/source/user/api_change.rst index 92d013ac31..4a53024d33 100644 --- a/docs/source/user/api_change.rst +++ b/docs/source/user/api_change.rst @@ -39,14 +39,14 @@ SubDyn na RigidSection PropSetID SubDyn na RigidSection (-) (kg/m) HydroDyn 52 NBody 1 NBody - Number of WAMIT bodies to be used (-) [>=1; only used when PotMod=1. If NBodyMod=1, the WAMIT data contains a vector of size 6*NBody x 1 and matrices of size 6*NBody x 6*NBody; if NBodyMod>1, there are NBody sets of WAMIT data each with a vector of size 6 x 1 and matrices of size 6 x 6] HydroDyn 53 NBodyMod 1 NBodyMod - Body coupling model {1: include coupling terms between each body and NBody in HydroDyn equals NBODY in WAMIT, 2: neglect coupling terms between each body and NBODY=1 with XBODY=0 in WAMIT, 3: Neglect coupling terms between each body and NBODY=1 with XBODY=/0 in WAMIT} (switch) [only used when PotMod=1] -ServoDyn 61 CompNStC 0 CompNStC - Compute nacelle structural control damping {number of nacelle TMDs} (integer) -ServoDyn 62 CompNStC "unused" NStCfile - Name of the file for nacelle structural control damping (quoted strings) [unused when CompNStC==0] -ServoDyn 63 CompNStC 0 CompTStC - Compute tower structural control damping {number of nacelle TMDs} (integer) -ServoDyn 64 CompNStC "unused" TStCfile - Name of the file for tower structural control damping (quoted strings) [unused when CompTStC==0] -ServoDyn 65 CompNStC 0 CompBStC - Compute blade structural control damping {number of nacelle tmds} (integer) -ServoDyn 66 CompNStC "unused" BStCfile - Name of the file for blade structural control damping (quoted strings) [unused when CompBStC==0] -ServoDyn 67 CompNStC 0 CompPtfmStC - Compute platform structural control damping {number of nacelle TMDs} (integer) -ServoDyn 68 CompNStC "unused" PtfmStCfile - Name of the file for blade structural control damping (quoted strings) [unused when CompPtfmStC==0] +ServoDyn 61 NumBStC 0 NumBStC - Number of blade structural controllers (integer) +ServoDyn 62 BStCfiles "unused" BStCfiles - Name of the files for blade structural controllers (quoted strings) [unused when NumBStC==0] +ServoDyn 63 NumNStC 0 NumNStC - Number of nacelle structural controllers (integer) +ServoDyn 64 NStCfiles "unused" NStCfiles - Name of the files for nacelle structural controllers (quoted strings) [unused when NumNStC==0] +ServoDyn 65 NumTStC 0 NumTStC - Number of tower structural controllers (integer) +ServoDyn 66 TStCfiles "unused" TStCfiles - Name of the files for tower structural controllers (quoted strings) [unused when NumTStC==0] +ServoDyn 67 NumSStC 0 NumSStC - Number of substructure structural controllers (integer) +ServoDyn 68 SStCfiles "unused" SStCfiles - Name of the files for substructure structural controllers (quoted strings) [unused when NumSStC==0] ============================================= ==== =============== ======================================================================================================================================================================================================== - ServoDyn From 54f2a62620d14d8c249bc4672a5a0f86f53c63d4 Mon Sep 17 00:00:00 2001 From: andrew-platt Date: Wed, 10 Mar 2021 13:08:09 -0700 Subject: [PATCH 3/4] Docs: consolidate api modified table and add table of files using key+value --- docs/source/user/api_change.rst | 29 ++++++++---------------- docs/source/user/input_file_overview.rst | 20 ++++++++++++++++ 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/docs/source/user/api_change.rst b/docs/source/user/api_change.rst index 4a53024d33..e263be104e 100644 --- a/docs/source/user/api_change.rst +++ b/docs/source/user/api_change.rst @@ -139,20 +139,6 @@ InflowWind 7 VFlowAng 0 VFlowAng - Upflow angle (de - Driver code includes ability to convert between wind types -Modified in OpenFAST v2.4.0 ---------------------------- - -============== ==== ================== ======================================================================================================================================================= ===================== - Module Line New Flag Name Example Value Previous Flag Name -============== ==== ================== ======================================================================================================================================================= ===================== -InflowWind 17 Filename_Uni "unused" Filename_Uni - Filename of time series data for uniform wind field. (-) Filename -InflowWind 18 RefHt_Uni 90 RefHt_Uni - Reference height for horizontal wind speed (m) RefHt -InflowWind 35 RefHt_Hawc 90 RefHt_Hawc - reference height; the height (in meters) of the vertical center of the grid (m) RefHt -InflowWind 47 PLExp_Hawc 0.2 PLExp_Hawc - Power law exponent (-) (used for PL wind profile type only) PLExp -InflowWind 49 XOffset 0 XOffset - Initial offset in +x direction (shift of wind box) InitPosition(x) -============== ==== ================== ======================================================================================================================================================= ===================== - - OpenFAST v2.3.0 to OpenFAST v2.4.0 ---------------------------------- @@ -179,11 +165,16 @@ AirFoilTables 4\* BL_file "unused" BL_file Modified in OpenFAST v2.4.0 --------------------------- -============== ==== ================== ============================================================================================================================================================================= - Module Line Flag Name Example Value -============== ==== ================== ============================================================================================================================================================================= -AirFoilTables 40\* filtCutOff "DEFAULT" filtCutOff - Reduced frequency cut-off for low-pass filtering the AoA input to UA, as well as the 1st and 2nd derivatives (-) [default = 0.5] -============== ==== ================== ============================================================================================================================================================================= +============== ==== ================== ======================================================================================================================================================= ========================= + Module Line New Flag Name Example Value Previous Flag Name/Value +============== ==== ================== ======================================================================================================================================================= ========================= +AirFoilTables 40\* filtCutOff "DEFAULT" filtCutOff - Reduced frequency cut-off for low-pass filtering the AoA input to UA, as well as the 1st and 2nd deriv (-) [default = 0.5] [default = 20] +InflowWind 17 Filename_Uni "unused" Filename_Uni - Filename of time series data for uniform wind field. (-) Filename +InflowWind 18 RefHt_Uni 90 RefHt_Uni - Reference height for horizontal wind speed (m) RefHt +InflowWind 35 RefHt_Hawc 90 RefHt_Hawc - reference height; the height (in meters) of the vertical center of the grid (m) RefHt +InflowWind 47 PLExp_Hawc 0.2 PLExp_Hawc - Power law exponent (-) (used for PL wind profile type only) PLExp +InflowWind 49 XOffset 0 XOffset - Initial offset in +x direction (shift of wind box) InitPosition(x) +============== ==== ================== ======================================================================================================================================================= ========================= \*non-comment line count, excluding lines contained if NumCoords is not 0. diff --git a/docs/source/user/input_file_overview.rst b/docs/source/user/input_file_overview.rst index d15d614f9b..9ff3e79dba 100644 --- a/docs/source/user/input_file_overview.rst +++ b/docs/source/user/input_file_overview.rst @@ -68,6 +68,26 @@ parser will return an error with information about which line it was reading from. +Modules using Key + Value Format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following modules use the *key + value* format input files (all other +modules use the *value column* format): + +============== ========================================================== + Module Input file +============== ========================================================== +AeroDyn Main AD15 input file +AeroDyn Airfoil files +InflowWind Main IfW input file +InflowWind Uniform wind input file +InflowWind Bladed wind summary file +ServoDyn Main ServoDyn input file +ServoDyn Structural control submodule input file +ServoDyn Structural control sumbodule prescribed force input file +SubDyn SubDyn SSI matrix input files +============== ========================================================== + Reasons for change ~~~~~~~~~~~~~~~~~~ From 7b5881f690b371e7b8833f9814f2379ec51f7b73 Mon Sep 17 00:00:00 2001 From: Rafael M Mudafort Date: Wed, 10 Mar 2021 15:12:05 -0600 Subject: [PATCH 4/4] =?UTF-8?q?Improve=20=E2=80=9Cscanability=E2=80=9D=20o?= =?UTF-8?q?f=20API=20change=20docs=20(#13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This change makes it easier to scan and find information in each section of the API documentation by bringing any information that is outside of a table to the top of the section. --- docs/source/user/api_change.rst | 42 +++++++++++++++------------------ 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/docs/source/user/api_change.rst b/docs/source/user/api_change.rst index e263be104e..a63e399081 100644 --- a/docs/source/user/api_change.rst +++ b/docs/source/user/api_change.rst @@ -17,6 +17,14 @@ Many changes were applied to SubDyn input file format. You may consult the follo :download:`(SubDyn's Input File) <./subdyn/examples/OC4_Jacket_SD_Input.dat>`: and the online SubDyn documentation. +- ServoDyn + + - The input file parser is updated to a keyword/value pair based input. + Each entry must have a corresponding keyword with the same spelling as + expected + - The TMD submodule of ServoDyn is replaced by an updated Structural Control + module (StC) with updated capabilities and input file. + ============================================= ==== =============== ======================================================================================================================================================================================================== OpenFAST v2.5.0 to OpenFAST dev --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -49,16 +57,6 @@ ServoDyn 67 NumSStC 0 ServoDyn 68 SStCfiles "unused" SStCfiles - Name of the files for substructure structural controllers (quoted strings) [unused when NumSStC==0] ============================================= ==== =============== ======================================================================================================================================================================================================== -- ServoDyn - - - The input file parser is updated to a keyword/value pair based input. - Each entry must have a corresponding keyword with the same spelling as - expected - - The TMD submodule of ServoDyn is replaced by an updated Structural Control - module (StC) with updated capabilities and input file. - - - ============================================= ====== =============== ====================================================================================================================================================================================================== Modified in OpenFAST dev --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -119,6 +117,13 @@ HydroDyn 74 PtfmYF True OpenFAST v2.4.0 to OpenFAST v2.5.0 ---------------------------------- +- InflowWind + + - The input file parser is updated to a keyword/value pair based input. + Each entry must have a corresponding keyword with the same spelling as + expected. See :numref:`input_file_overview` for an overview. + - Driver code includes ability to convert between wind types + ============== ==== ================== ============================================================================================================================================================================= Added in OpenFAST v2.5.0 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -131,17 +136,11 @@ IfW driver 9 WrVTK false WrVTK - Convert all data InflowWind 7 VFlowAng 0 VFlowAng - Upflow angle (degrees) (not used for native Bladed format WindType=7) ============== ==== ================== ============================================================================================================================================================================= -- InflowWind - - - The input file parser is updated to a keyword/value pair based input. - Each entry must have a corresponding keyword with the same spelling as - expected. See :numref:`input_file_overview` for an overview. - - Driver code includes ability to convert between wind types - - OpenFAST v2.3.0 to OpenFAST v2.4.0 ---------------------------------- +Additional nodal output channels added for :ref:`AeroDyn15`, :ref:`BeamDyn`, and :ref:`ElastoDyn`. + ============== ==== ================== ============================================================================================================================================================================= Added in OpenFAST v2.4.0 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -162,10 +161,9 @@ AeroDyn 36 OLAFInputFileName "Elliptic_OLAF.dat" OLAFInputFileName AirFoilTables 4\* BL_file "unused" BL_file - The file name including the boundary layer characteristics of the profile. Ignored if the aeroacoustic module is not called. ============== ==== ================== ============================================================================================================================================================================= -Modified in OpenFAST v2.4.0 ---------------------------- - ============== ==== ================== ======================================================================================================================================================= ========================= +Modified in OpenFAST v2.4.0 +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Module Line New Flag Name Example Value Previous Flag Name/Value ============== ==== ================== ======================================================================================================================================================= ========================= AirFoilTables 40\* filtCutOff "DEFAULT" filtCutOff - Reduced frequency cut-off for low-pass filtering the AoA input to UA, as well as the 1st and 2nd deriv (-) [default = 0.5] [default = 20] @@ -178,8 +176,6 @@ InflowWind 49 XOffset 0 XOffset - Initial offset \*non-comment line count, excluding lines contained if NumCoords is not 0. -Additional nodal output channels added for :ref:`AeroDyn15`, -:ref:`BeamDyn`, and :ref:`ElastoDyn`.