Skip to content

Add documentation on input file parsing #678

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

Merged
andrew-platt merged 4 commits into from
Mar 10, 2021
Merged

Add documentation on input file parsing #678

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e261686
Add documentation on input file parsers
andrew-platt Mar 5, 2021
bfb01af
Docs: Fix typo in api-change for StC inputs
andrew-platt Mar 8, 2021
54f2a62
Docs: consolidate api modified table and add table of files using key…
andrew-platt Mar 10, 2021
7b5881f
Improve “scanability” of API change docs (#13)
rafmudaf Mar 10, 2021
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
73 changes: 36 additions & 37 deletions docs/source/user/api_change.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Expand All @@ -39,26 +47,16 @@ 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

- 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
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -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
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Expand All @@ -131,19 +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
- 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<AD-Nodal-Outputs>`, :ref:`BeamDyn<BD-Nodal-Outputs>`, and :ref:`ElastoDyn<ED-Nodal-Outputs>`.

============== ==== ================== =============================================================================================================================================================================
Added in OpenFAST v2.4.0
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Expand All @@ -164,19 +161,21 @@ 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
---------------------------

============== ==== ================== =============================================================================================================================================================================
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.

Additional nodal output channels added for :ref:`AeroDyn15<AD-Nodal-Outputs>`,
:ref:`BeamDyn<BD-Nodal-Outputs>`, and :ref:`ElastoDyn<ED-Nodal-Outputs>`.



Expand Down
1 change: 1 addition & 0 deletions docs/source/user/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
140 changes: 140 additions & 0 deletions docs/source/user/input_file_overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
.. _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
Comment thread
andrew-platt marked this conversation as resolved.
-----------------------

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.


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
~~~~~~~~~~~~~~~~~~

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 <https://github.com/openfast/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
============== ====================== =====================