Merge 6c776ee into e631981

OpenFAST/.github/workflows/automated-dev-tests.yml

@@ -106,7 +106,7 @@ jobs:
             install_deps: brew install gcovr
           - os: ubuntu-20.04
             FORTRAN_COMPILER: gfortran-10
-            install_deps: sudo apt-get install -y gcovr
+            install_deps: sudo apt-get update && sudo apt-get install -y gcovr
 
     name: regression-test-debug-${{ matrix.os }}-${{ matrix.FORTRAN_COMPILER }}
     steps:

OpenFAST/docs/conf.py

@@ -67,6 +67,17 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
     'sphinxcontrib.bibtex',
     'sphinxcontrib.mermaid',
 ]
+bibtex_bibfiles = [
+    'source/user/aerodyn-aeroacoustics/references.bib',
+    'source/user/aerodyn-olaf/bibliography.bib',
+    'source/user/aerodyn/bibliography.bib',
+    'source/user/beamdyn/references.bib',
+    'source/user/extptfm/bibliography.bib',
+    'source/user/fast.farm/bibliography.bib',
+    'source/user/hydrodyn/references.bib',
+    'source/user/servodyn-stc/StC_Refs.bib',
+    'source/user/subdyn/references_SD.bib'
+]
 
 autodoc_default_flags = [
     'members',
@@ -117,9 +128,9 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
 # built documents.
 #
 # The short X.Y version.
-version = u'3.0'
+version = u'3.1'
 # The full version, including alpha/beta/rc tags.
-release = u'v3.0.0'
+release = u'v3.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

OpenFAST/docs/requirements.txt

@@ -3,7 +3,7 @@ docutils==0.16
 Pygments>=2.2
 pyparsing>=2.1
 Sphinx>=1.8.5
-sphinxcontrib-bibtex>=0.3.3,<2.0.0
+sphinxcontrib-bibtex>=2.0.0
 sphinxcontrib-doxylink>=1.3
 sphinxcontrib-mermaid>=0.6
 sphinx_rtd_theme>=0.3

OpenFAST/docs/source/dev/index.rst

@@ -43,49 +43,188 @@ For other questions regarding OpenFAST, please contact
     - :ref:`code_style`
     - :ref:`debugging`
 
-API Reference
-~~~~~~~~~~~~~
-Some subroutines and derived types throughout the source code have in-source
-documentation which is compiled with Doxygen. Though this portion of the
-documentation is always under development, the existing API reference can
-be found in the following pages:
+.. _development_philosophy:
 
-- `Main Page <../../html/index.html>`_
-- `Index of Types <../../html/classes.html>`_
-- `Source Files <../../html/files.html>`_
+Development Philosophy and Guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. _development_philosophy:
+OpenFAST is intended to be a self-sustaining, community developed software.
+While the NREL OpenFAST team serves as the gatekeeper of the repository, we
+actively encourage the community to share new ideas and contribute code.
+Considerations for contributing code are outlined here.
+
+Engagement with NREL
+--------------------
+
+The process for community code contribution starts with engaging directly
+with the NREL OpenFAST team to define the scope of the work and coordinate
+development efforts. This is particularly important since many groups
+work on OpenFAST simultaneously. By engaging early, all developers can
+stay up to date and minimize conflicts during the code merge.
+The prefered method of communication is `GitHub Issues <https://github.com/openfast/openfast/issues>`_.
+An initial post should contain all relevant information about the planned
+development work, the areas of the software that will be impacted,
+and any model validation materials. See :ref:`development_plan`
+for more information on describing the planned work.
+
+The NREL OpenFAST team is always working on internal projects
+that require the majority of our attention, but we will make every effort
+to engage with the community and support development efforts in
+a reasonable time frame. After posting an Issue, the NREL OpenFAST
+team may reach out to schedule a meeting to talk through the details.
+
+.. _development_plan:
+
+Development Plan / Implementation Plan
+--------------------------------------
+Significant code development efforts at NREL begin with the development
+of a detailed implementation plan, and a few such plans are available to
+download for reference:
+
+- :download:`Development Plan for the Aerodynamic Linearization of OpenFAST <../../OtherSupporting/AeroDyn/AeroLin_2019-12.pdf>`
+- :download:`FAST.Farm Development Plan <../../OtherSupporting/FAST.Farm_Plan_Rev25.doc>`.
+- :download:`Implementation Plan - 2nd-order Forces Within HydroDyn <../../OtherSupporting/HydroDyn/HydroDyn_2ndOrderForces_Plan.pdf>`
+- :download:`Implementation Plan - 2nd-order Wave Kinematics Within HydroDyn <../../OtherSupporting/HydroDyn/WAVE2_document.pdf>`
+
+A good plan within the modularization framework of OpenFAST will
+follow the definitions and nomenclature used by the
+:download:`NWTC Programmer's Handbook <../../OtherSupporting/NWTC_Programmers_Handbook.pdf>`.
+It should communication the following information:
+
+- State whether the module is intended for loose coupling,
+  tight coupling for time marching, and/or linearization.
+- Define the module's inputs (including initialization), 
+  outputs (including initialization), states (continous,
+  discrete, and constraint), and parameters, including units.
+- Lay out an example input file for the module.
+- Explain the module's mathemetical formulation, including
+  Jacobians (for tight coupling and linearization), in the form
+  required of the framework.
+- Prescribe how the module's inputs are derived from the 
+  outputs of other specific modules
+- Identify any potential numerical problems and how to avoid 
+  them in the code.
+- Lay out the module's subroutines using pseudocode (as opposed 
+  to actual code), including identifying which mathematical formulas
+  are used by which subroutines, and describing the algorithms used
+  in the solution process.
+
+This information is very helpful since it is easier to review, iterate,
+and agree on a plan before making changes to source code. Additionally,
+an implementation plan will greatly aid in the programming effort and is
+a useful starting point for writing the user and develop documentation.
+
+Qualities of a good submission
+------------------------------
+
+Development efforts should include adequate testing throughout
+the development process. When possible, new subroutines should include unit-level tests,
+and the existing regression tests should be run periodically to ensure that
+the full system behavior has not changed unintentionally. For new features,
+additional regression tests should be added to cover the new code.
+If the regression test results change in an expected manner, the baseline
+results should be updated locally and in the `openfast/r-test <https://github.com/openfast/r-test>`_
+repository. The `r-test README <https://github.com/openfast/r-test#updating-the-baselines>`_
+describes updating the baselines and the :ref:`testing`
+section in this documentation contains additional details on testing.
 
-Development Philosophy
-~~~~~~~~~~~~~~~~~~~~~~
+New code should consider robustness from both the developer and user
+perspectives. Here are some questions to consider during
+code development:
 
-OpenFAST is intended to be a self sustaining community developed software.
-A couple of tenets of this goal are that the code should be reasonably
-straightforward to comprehend and manageable to improve. With that in mind, we
-expect that new capabilities will include adequate testing and documentation.
+- Is it clear to other developers how to use your subroutine?
+- Does your new code exhibit clear and predictable behavior?
+- How will your code perform under different qualities of data?
+- How does your code impact the performance of the simulation?
 
-We have the following guidance for developers:
+Additionally, user and developer documentation should be included
+with new code. User documentation includes theory, modeling guidance,
+and a description of any inputs and outputs. User documentation should be
+included as part of the online documentation described in :ref:`build_doc`.
+Developer documentation is typically included in comments in the source
+code. This should describe subroutine API's (inputs and outputs) as well
+as any algorithms or lines of code that are unclear. Ask yourself
+what you would need to know to fully understand your code if you don't
+see it again for two years.
 
-- When fixing a bug, first introduce a unit test that exposes the bug, fix the
-  bug, and submit a Pull Request. See :ref:`testing` and
-  :ref:`github_workflow` for more information.
+Submit for review and NREL feedback
+-----------------------------------
 
-- When adding a new feature, create appropriate automated unit and regression
-  tests as described in :ref:`testing`. The objective is to create a GitHub
-  pull request that provides adequate verification and validation so that the
-  NREL OpenFAST developer team can merge the pull request with confidence that
-  the new feature is "correct" and supports our goal of self-sustaining
-  software. See :ref:`pull_requests` for more information on submitting
-  a pull request.
+New code can be submitted for review from the NREL OpenFAST team by
+opening a `pull request <https://github.com/openfast/openfast/pulls>`_
+as described in :ref:`github_workflow`. We will review the code for
+accuracy, validity, quality, and robustness. Reviewing open source
+code contributions can be difficult, so it is worthwhile to review
+your own code and consider what information would help you to
+determine whether it is ready to merge.
 
-- If a code modification affects regression test results in an expected manner,
-  work with the NREL OpenFAST developer team to upgrade the regression test
-  suite via a GitHub issue or pull request at the `openfast/r-test <https://github.com/openfast/r-test>`_
-  repository.
+The review process begins with simply ensuring that the automated
+tests pass in `GitHub Actions <https://github.com/openfast/openfast/actions>`_.
+**Please ensure that all automated tests pass prior to requesting a review.**
+After that, the process will involve some communication between the
+reviewer and the submitter, possibly requests for more information
+on the background or validation, and comments in the pull request
+to gain additional insight into specific lines of code.
 
-Development Guidelines
-~~~~~~~~~~~~~~~~~~~~~~
-The following sections provide extended guidance on how to develop source code,
+After a consensus is reached between the submitter and reviewer,
+the pull request will be merged into the target branch (typically
+`dev`) and the pull request will be closed. You're done!
+This change will be included in the subsequent release of OpenFAST
+when the `dev` branch is merged into `main`.
+
+Bug fixes
+---------
+
+If you've found a bug in the code, it is important to fully describe
+it both in a `GitHub Issue <https://github.com/openfast/openfast/issues>`_
+and through a minimal test. Before making a commit with the bug fix,
+commit the new test that exposes the bug. This test should fail.
+Then, commit the bug fix and show that the test passes. The git-commit
+history should look something like this (progresses bottom to top):
+
+.. mermaid::
+
+  gitGraph BT:
+  options
+  {
+    "nodeSpacing": 60,
+    "nodeFillColor": "white",
+    "nodeStrokeWidth": 2,
+    "nodeStrokeColor": "#747474",
+    "lineStrokeWidth": 2,
+    "branchOffset": 30,
+    "lineColor": "grey",
+    "leftMargin": 20,
+    "branchColors": ["#007bff", "#ff2d54"],
+    "nodeRadius": 5,
+    "nodeLabel": {
+      "width": 75,
+      "height": 100,
+      "x": -25,
+      "y": 0
+    }
+  }
+  end
+
+  commit
+  branch dev
+  checkout dev
+  commit "Merge pull request #123"
+  commit "Merge pull request #124"
+  branch bugfix
+  checkout bugfix
+  commit "Add unit test exposing out of bounds error"
+  commit "Fix out of bounds error in array"
+  checkout dev
+  commit "Merge pull request #125"
+  merge bugfix
+
+See :ref:`testing` and :ref:`github_workflow` for more information.
+
+Additional guidance
+-------------------
+
+The following sections provide extended guidance on developing source code,
 interacting with the NREL OpenFAST team and other community contributors, and
 generally debugging and building out features.
 
@@ -100,12 +239,26 @@ generally debugging and building out features.
     performance.rst
     versioning.rst
 
+
+
+
+API Reference
+~~~~~~~~~~~~~
+Some subroutines and derived types throughout the source code have in-source
+documentation which is compiled with Doxygen. Though this portion of the
+documentation is always under development, the existing API reference can
+be found in the following pages:
+
+- `Main Page <../../html/index.html>`_
+- `Index of Types <../../html/classes.html>`_
+- `Source Files <../../html/files.html>`_
+
 Other Documentation
 ~~~~~~~~~~~~~~~~~~~
 Additional documentation exists that may be useful for developers seeking deeper
 understanding of the solver and mathematics.
 
-- `NWTC Programmer’s Handbook <https://drive.google.com/file/d/1bDV1fBkiZUWs6Tkzb6nhCMUQvHpN_OtM/view?usp=sharing>`_
+- :download:`NWTC Programmer's Handbook <../../OtherSupporting/NWTC_Programmers_Handbook.pdf>`
    This is an overview of programming guidelines for FAST 8. While some syntax and minor details have
    changed in OpenFAST, most of this guide is still relevant.
 - :download:`OutListParameters.xlsx <../../OtherSupporting/OutListParameters.xlsx>`

OpenFAST/docs/source/this_doc.rst

@@ -10,7 +10,7 @@ generated from both the
 `dev <http://github.com/openfast/openfast/tree/dev/>`_ branches whenever
 new commits are added. Clicking on the bar on the lower left corner of the
 page reveals a panel (see image below) containing options to select the branch
-of the repository, download the documentation other formats (PFD, HTML, EPub),
+of the repository, download the documentation other formats (PDF, HTML, EPub),
 and link to other relevant websites.
 
 .. image:: ../_static/docs_options.png

OpenFAST/docs/source/user/aerodyn-aeroacoustics/example/AD15.ipt

@@ -1,12 +1,12 @@
-------- AERODYN v15.03.\* INPUT FILE ------------------------------------------------
+------- AERODYN INPUT FILE -----------------------------------------------
 IEA Wind Task 37 land-based reference wind turbine
 ====== General Options ===================================================
 False          Echo        - Echo the input to "<rootname>.AD.ech"? (flag)
 "default"      DT_AA       - Time interval for aerodynamic calculations {or "default"} (s)
 1              WakeMod     - Type of wake/induction model (switch) {0=none, 1=BEMT}
 2              AFAeroMod   - Type of blade airfoil aerodynamics model (switch
-0              TwrPotent   - Type tower influence on wind around the tower (switch)
-False          TwrShadow   - Calculate tower influence on wind (flag)
+0              TwrPotent   - Type of tower influence on wind around the tower (switch)
+0              TwrShadow   - Type of tower influence on wind based on downstream tower shadow (switch) {0=none, 1=Powles model, 2=Eames model}
 False          TwrAero     - Calculate tower aerodynamic loads? (flag)
 False          FrozenWake  - Assume frozen wake during linearization? (flag
 False          CavitCheck  - Perform cavitation check? (flag)

OpenFAST/docs/source/user/aerodyn-aeroacoustics/example/AFtab.dat

@@ -1,12 +1,12 @@
-! ------------ AirfoilInfo v1.01.x Input File ----------------------------------
+! ------------ AirfoilInfo Input File ------------------------------------------
 ! AeroElasticSE FAST driver
 !
 !
 ! ------------------------------------------------------------------------------
-DEFAULT                  InterpOrd   ! Interpolation order to use for quasi-steady table lookup {1=linear; 3=cubic spline; "default"} [default=3]
+DEFAULT                  InterpOrd   ! Interpolation order to use for quasi-steady table lookup {1=linear; 3=cubic spline; "default"} [default=1]
 1                        NonDimArea  ! The non-dimensional area of the airfoil (area/chord^2) (set to 1.0 if unsure or unneeded)
 @"AF20_Coords.txt"       NumCoords   ! The number of coordinates in the airfoil shape file. Set to zero if coordinates not included.
-AF20_BL.txt              BL_file     ! The file name including the boundary layer characteristics of the profile. Ignored if the aeroacoustic module is not called.
+AF20_BL.txt              BL_file     ! The file name including the boundary layer characteristics of the profile. Optional and ignored if the aeroacoustic module is not called.
 1                        NumTabs     ! Number of airfoil tables in this file.  Each table must have lines for Re and Ctrl.
 ! ------------------------------------------------------------------------------
 ! data for table 1

OpenFAST/docs/source/user/aerodyn-aeroacoustics/example/AeroAcousticsInput.dat

@@ -1,7 +1,7 @@
-------- AeroAcoustics Module v1.00.* INPUT FILE ------------------------------------------------
+------- AeroAcoustics Module INPUT FILE -------------------------------------------------------------
 IEA task 37 RWT turbine -- https://github.com/IEAWindTask37/IEA-3.4-130-RWT
 ======  General Options  ============================================================================
-False        Echo         - Echo the input to "<rootname>.AD.ech"?  (flag)
+False        Echo         - Echo the input to "<rootname>.AD.NN.ech"?  (flag)
 0.1          DT_AA        - Time interval for aeroacoustics calculations (s), must be a multiple of DT_Aero from AeroDyn15  (or "default")
 0            AAStart      - Time after which the AeroAcoustics module is run (s)
 70           BldPrcnt     - Percentage of the blade span, starting from the tip, that will contribute to the overall noise levels. (float)