diff --git a/.gitignore b/.gitignore index c799069b8..8a3337ef1 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,7 @@ __pycache__/* # Build specific files build*/ +_build*/ install/ vs-build/ diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..431543a33 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,29 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: + - htmlzip + - pdf + # - epub + +python: + version: 3.7 + install: + - requirements: docs/requirements.txt + system_packages: true + +# select the docker image to use: stable | latest +build: + image: stable + +sphinx: + builder: html + configuration: docs/conf.py + fail_on_warning: true diff --git a/.travis.yml b/.travis.yml index b3e8bf79e..82c62b183 100644 --- a/.travis.yml +++ b/.travis.yml @@ -36,7 +36,7 @@ addons: update: true before_install: - # linux configuration + # linux configuration - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install gfortran libblas-dev liblapack-dev; fi - if [[ "$TRAVIS_OS_NAME" == "linux" && "$CPP_API" == "ON" ]]; then sudo apt-get install libopenmpi-dev libyaml-cpp-dev libhdf5-dev libxml2-dev; fi - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then pyenv shell 3.7.1; fi diff --git a/README.md b/README.md deleted file mode 100644 index ee5384bfc..000000000 --- a/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# OpenFAST - -OpenFAST is a wind turbine simulation tool which builds on FAST v8. It was -created with the goal of being a community model developed and used by research -laboratories, academia, and industry. It is managed by a dedicated team at the -National Renewable Energy Lab. Our objective is to ensure that OpenFAST is -sustainable software that is well tested and well documented. If you'd like -to contribute, see the -[Developer Documentation](https://openfast.readthedocs.io/en/dev/source/dev/index.html) -and any open GitHub issues with the -[Help Wanted](https://github.com/OpenFAST/openfast/issues?q=is%3Aopen+is%3Aissue+label%3A"Help+wanted") -tag. - -**OpenFAST is under active development**. - -### FAST v8 - OpenFAST v0.1.0 - -The transition from FAST v8 to OpenFAST v0.1.0 represents the effort to better support an open-source developer community around FAST-based aero-hydro-servo-elastic engineering models of wind-turbines and wind-plants. OpenFAST is the next generation of FAST analysis tools. More inforation is available in the [transition notes](http://openfast.readthedocs.io/en/latest/source/user/fast_to_openfast.html). - -FAST v8 is a computer-aided engineering tool for simulating the coupled dynamic response of wind turbines. FAST joins aerodynamics models, hydrodynamics models for offshore structures, control and electrical system (servo) dynamics models, and structural (elastic) dynamics models to enable coupled nonlinear aero-hydro-servo-elastic simulation in the time domain. The FAST tool enables the analysis of a range of wind turbine configurations, including two- or three-blade horizontal-axis rotor, pitch or stall regulation, rigid or teetering hub, upwind or downwind rotor, and lattice or tubular tower. The wind turbine can be modeled on land or offshore on fixed-bottom or floating substructures. FAST is based on advanced engineering models derived from fundamental laws, but with appropriate simplifications and assumptions, and supplemented where applicable with computational solutions and test data. - -The aerodynamic models use wind-inflow data and solve for the rotor-wake effects and blade-element aerodynamic loads, including dynamic stall. The hydrodynamics models simulate the regular or irregular incident waves and currents and solve for the hydrostatic, radiation, diffraction, and viscous loads on the offshore substructure. The control and electrical system models simulate the controller logic, sensors, and actuators of the blade-pitch, generator-torque, nacelle-yaw, and other control devices, as well as the generator and power-converter components of the electrical drive. The structural-dynamics models apply the control and electrical system reactions, apply the aerodynamic and hydrodynamic loads, adds gravitational loads, and simulate the elasticity of the rotor, drivetrain, and support structure. Coupling between all models is achieved through a modular interface and coupler. - -### Documentation -Web based documentation is available at . - -This documentation is stored and maintained alongside the source code. It is compiled into html with Sphinx, so it is tied to a particular version of OpenFAST. [readthedocs](http://openfast.readthedocs.io) compiles various versions of the documentation automatically upon new commits: -* `latest` - The latest commit on the `master` branch -* `stable` - Corresponds to the last tagged release -* `dev` - The latest commit on the `dev` branch - -These can be toggled with the `v: latest` button in the lower left corner of the docs site. - -### Obtaining OpenFAST - -OpenFAST is hosted entirely on GitHub so you are in the [right place](https://github.com/OpenFAST/OpenFAST)! The repository is structured with various branches following the "git-flow" convention: -* `master` -* `dev` - -The `master` branch is stable, well tested, and represents the most up to date released version of OpenFAST. The latest commit on `master` contains a tag with version info and brief release notes. The tag history can be obtained with the `git tag` command and viewed in more detail on [GitHub Releases](https://github.com/OpenFAST/openfast/releases). For general use, the `master` branch is highly recommended. - -The `dev` branch is generally stable and tested, but not static. It contains new features, bug fixes, and documentation updates that have not been compiled into a production release. Before proceeding with new development, it is recommended to explore the `dev` branch. This branch is updated regularly through pull requests, so be sure to `git fetch` often and check [outstanding pull requests](https://github.com/OpenFAST/openfast/pulls). - -For those not familiar with git and GitHub, there are many resources, e.g., - -* -* -* -* -* - -### Compilation, Usage, and Development - -Details for compiling [compiling](http://openfast.readthedocs.io/en/latest/source/install/index.html), -[using](http://openfast.readthedocs.io/en/latest/source/user/index.html), and -[developing](http://openfast.readthedocs.io/en/latest/source/dev/index.html) -OpenFAST on Linux-based and Windows machines are available at -. - - -### Nightly Testing - -The `dev` branch is automatically compiled and run through the test suite nightly. The results are publicly available through the [CDash Dashboard](http://my.cdash.org/index.php?project=OpenFAST&date=). - -### Help - -Please use [github issues](https://github.com/OpenFAST/OpenFAST/issues) to: -* ask usage questions -* report bugs -* request code enhancements - -For other questions regarding OpenFAST, please contact [Mike Sprague](mailto:michael.a.sprague@nrel.gov). - -Users and developers may also be interested in the NREL National Wind Technology Center (NWTC) [phpBB Forum](https://wind.nrel.gov/forum/wind/). - -### Acknowledgments - -OpenFAST is being maintained and developed by researchers and software engineers at the [National Renewable Energy Laboratory](http://www.nrel.gov/) (NREL), with support from the US Department of Energy's Wind Energy Technology Office. NREL gratefully acknowledges development contributions from the following organizations: - -* Envision Energy USA, Ltd -* Brigham Young University -* [Intel® Parallel Computing Center (IPCC)](https://software.intel.com/en-us/ipcc) diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..3900f682d --- /dev/null +++ b/README.rst @@ -0,0 +1,148 @@ +OpenFAST +======== + +|travisci| |nbsp| |rtfd| + +.. |travisci| image:: https://travis-ci.org/OpenFAST/openfast.svg?branch=dev + :target: https://travis-ci.org/OpenFAST/openfast + :alt: Build Status +.. |rtfd| image:: https://readthedocs.org/projects/openfast/badge/?version=dev + :target: https://openfast.readthedocs.io/en/dev + :alt: Documentation Status +.. |nbsp| unicode:: 0xA0 + :trim: + +OpenFAST is a wind turbine simulation tool which builds on FAST v8. It was +created with the goal of being a community model developed and used by research +laboratories, academia, and industry. It is managed by a dedicated team at the +National Renewable Energy Lab. Our objective is to ensure that OpenFAST is +sustainable software that is well tested and well documented. If you'd like +to contribute, see the `Developer Documentation `_ +and any open GitHub issues with the +`Help Wanted `_ +tag. + +**OpenFAST is under active development**. + +FAST v8 - OpenFAST v0.1.0 +------------------------- +The transition from FAST v8 to OpenFAST v0.1.0 represents the effort to better +support an open-source developer community around FAST-based aero-hydro-servo- +elastic engineering models of wind-turbines and wind-plants. OpenFAST is the +next generation of FAST analysis tools. More inforation is available in the +`transition notes `_. + +FAST v8 is a computer-aided engineering tool for simulating the coupled dynamic +response of wind turbines. FAST joins aerodynamics models, hydrodynamics models +for offshore structures, control and electrical system (servo) dynamics models, +and structural (elastic) dynamics models to enable coupled nonlinear aero- +hydro-servo-elastic simulation in the time domain. The FAST tool enables the +analysis of a range of wind turbine configurations, including two- or +three-blade horizontal-axis rotor, pitch or stall regulation, rigid or +teetering hub, upwind or downwind rotor, and lattice or tubular tower. The wind +turbine can be modeled on land or offshore on fixed-bottom or floating +substructures. FAST is based on advanced engineering models derived from +fundamental laws, but with appropriate simplifications and assumptions, and +supplemented where applicable with computational solutions and test data. + +The aerodynamic models use wind-inflow data and solve for the rotor-wake +effects and blade-element aerodynamic loads, including dynamic stall. The +hydrodynamics models simulate the regular or irregular incident waves and +currents and solve for the hydrostatic, radiation, diffraction, and viscous +loads on the offshore substructure. The control and electrical system models +simulate the controller logic, sensors, and actuators of the blade-pitch, +generator-torque, nacelle-yaw, and other control devices, as well as the +generator and power-converter components of the electrical drive. The +structural-dynamics models apply the control and electrical system +reactions, apply the aerodynamic and hydrodynamic loads, adds gravitational +loads, and simulate the elasticity of the rotor, drivetrain, and support +structure. Coupling between all models is achieved through a modular +interface and coupler. + +Documentation +------------- +The full documentation is available at http://openfast.readthedocs.io/. + +This documentation is stored and maintained alongside the source code. +It is compiled into HTML with Sphinx and is tied to a particular version +of OpenFAST. `Readthedocs `_ hosts the following +versions of the documentation: + +* ``latest`` - The latest commit on the ``master`` branch +* ``stable`` - Corresponds to the last tagged release +* ``dev`` - The latest commit on the ``dev`` branch + +These can be toggled with the ``v: latest`` button in the lower left corner of +the docs site. + +Obtaining OpenFAST +------------------ +OpenFAST is hosted entirely on GitHub so you are in the `right place `_! +The repository is structured with two branches following the +"git-flow" convention: + +* ``master`` +* ``dev`` + +The ``master`` branch is stable, well tested, and represents the most up to +date released version of OpenFAST. The latest commit on ``master`` contains +a tag with version info and brief release notes. The tag history can be +obtained with the ``git tag`` command and viewed in more detail on +`GitHub Releases `_. For general +use, the ``master`` branch is highly recommended. + +The ``dev`` branch is generally stable and tested, but not static. It contains +new features, bug fixes, and documentation updates that have not been compiled +into a production release. Before proceeding with new development, it is +recommended to explore the ``dev`` branch. This branch is updated regularly +through pull requests, so be sure to ``git fetch`` often and check +`outstanding pull requests `_. + +For those not familiar with git and GitHub, there are many resources: + +* https://guides.github.com +* https://try.github.io +* https://help.github.com/categories/bootcamp/ +* https://desktop.github.com/ +* http://nvie.com/posts/a-successful-git-branching-model/ + +Compilation, Usage, and Development +----------------------------------- +Details for compiling +`compiling `_, +`using `_, and +`developing `_ +OpenFAST on Unux-based and Windows machines are available at `readthedocs `_. + +Nightly Testing +--------------- +The ``dev`` branch is automatically compiled and run through the test suite +nightly. The results are publicly available through the +`CDash Dashboard `_. + +Help +---- +Please use `github issues `_ to: + +* ask usage questions +* report bugs +* request code enhancements + +For other questions regarding OpenFAST, please contact +`Mike Sprague `_. + +Users and developers may also be interested in the NREL National Wind +Technology Center (NWTC) `phpBB Forum `_. + +Acknowledgments +--------------- + +OpenFAST is maintained and developed by researchers and software engineers at +the `National Renewable Energy Laboratory `_ (NREL), with +support from the US Department of Energy's Wind Energy Technology Office. NREL +gratefully acknowledges development contributions from the following +organizations: + +* Envision Energy USA, Ltd +* Brigham Young University +* `Intel® Parallel Computing Center (IPCC) `_ diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index e154543c1..88c8b3b1f 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.13 +# Doxyfile 1.8.16 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -17,11 +17,11 @@ # Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 @@ -44,14 +44,14 @@ PROJECT_NUMBER = # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "OpenFAST description goes here." +PROJECT_BRIEF = "Wind turbine multiphysics simulator" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = @CMAKE_BINARY_DIR@/docs/html/_static/openfastlogo.jpg +PROJECT_LOGO = @CMAKE_BINARY_DIR@/docs/_static/openfastlogo.jpg # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -93,6 +93,14 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English +# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all generated output in the proper direction. +# Possible values are: None, LTR, RTL and Context. +# The default value is: None. + +OUTPUT_TEXT_DIRECTION = None + # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -189,6 +197,16 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = YES + # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus @@ -236,7 +254,12 @@ TAB_SIZE = 4 # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines. +# newlines (in the resulting output). You can put ^^ in the value part of an +# alias to insert a newline as if a physical newline was in the original file. +# When you need a literal { or } or , in the value part of an alias you have to +# escape them by means of a backslash (\), this can lead to conflicts with the +# commands \{ and \} for these it is advised to use the version @{ and @} or use +# a double escape (\\{ and \\}) ALIASES = @@ -274,16 +297,26 @@ OPTIMIZE_FOR_FORTRAN = YES OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it -# language is one of the parsers supported byen:IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: -# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: -# Fortran. In the later case the parser tries to guess whether the code is fixed -# or free formatted code, this is the default for Fortran type files), VHDL. For -# instance to make doxygen treat .inc files as Fortran files (default is PHP), -# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, +# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files), VHDL, tcl. For instance to make doxygen treat +# .inc files as Fortran files (default is PHP), and .f files as C (default is +# Fortran), use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # @@ -294,7 +327,7 @@ EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. +# documentation. See https://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. @@ -306,10 +339,10 @@ MARKDOWN_SUPPORT = YES # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. -# Minimum value: 0, maximum value: 99, default value: 0. +# Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 0 +TOC_INCLUDE_HEADINGS = 5 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -336,7 +369,7 @@ BUILTIN_STL_SUPPORT = YES CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. @@ -434,7 +467,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -442,11 +475,17 @@ EXTRACT_ALL = YES EXTRACT_PRIVATE = YES +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. -EXTRACT_PACKAGE = YES +EXTRACT_PACKAGE = NO # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. @@ -468,7 +507,7 @@ EXTRACT_LOCAL_CLASSES = YES # included. # The default value is: NO. -EXTRACT_LOCAL_METHODS = YES +EXTRACT_LOCAL_METHODS = NO # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called @@ -520,7 +559,7 @@ INTERNAL_DOCS = NO # names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# (including Cygwin) ands Mac users are advised to set this option to NO. # The default value is: system dependent. CASE_SENSE_NAMES = NO @@ -707,7 +746,7 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. @@ -752,7 +791,8 @@ WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. +# parameter documentation, but not about the absence of documentation. If +# EXTRACT_ALL is set to YES then this flag will automatically be disabled. # The default value is: NO. WARN_NO_PARAMDOC = NO @@ -795,7 +835,7 @@ INPUT = @CMAKE_SOURCE_DIR@/glue-codes/ \ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of +# documentation (see: https://www.gnu.org/software/libiconv/) for the list of # possible encodings. # The default value is: UTF-8. @@ -819,6 +859,7 @@ FILE_PATTERNS = *.f90 \ *.F90 \ *.f \ *.F \ + *.for \ *.c \ *.cxx \ *.cpp \ @@ -827,7 +868,8 @@ FILE_PATTERNS = *.f90 \ *.hh \ *.hxx \ *.hpp \ - *.h + *.h \ + *.py # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -842,12 +884,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE_PATTERNS = @CMAKE_SOURCE_DIR@/.git/* \ - @CMAKE_SOURCE_DIR@/build/* \ - @CMAKE_SOURCE_DIR@/cmake/* \ - @CMAKE_SOURCE_DIR@/docs/* \ - @CMAKE_SOURCE_DIR@/modules/orcaflex-interface/src/OrcaFlexInterface.f90 \ - @CMAKE_SOURCE_DIR@/modules/servodyn/src/BladedInterface.f90 +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -863,6 +900,13 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* +EXCLUDE_PATTERNS = @CMAKE_SOURCE_DIR@/.git/* \ + @CMAKE_SOURCE_DIR@/build/* \ + @CMAKE_SOURCE_DIR@/cmake/* \ + @CMAKE_SOURCE_DIR@/docs/* \ + @CMAKE_SOURCE_DIR@/modules/orcaflex-interface/src/OrcaFlexInterface.f90 \ + @CMAKE_SOURCE_DIR@/modules/servodyn/src/BladedInterface.f90 + # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the @@ -943,7 +987,9 @@ FILTER_SOURCE_FILES = NO # The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file # pattern. A pattern will override the setting for FILTER_PATTERN (if any) and -# it is also possible to disable source filtering for a specific pattern usihistag requires that the tag FILTER_SOURCE_FILES is set to YES. +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. FILTER_SOURCE_PATTERNS = @@ -981,16 +1027,16 @@ INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented -# function all documented functions referencing it will be listed. +# entity all documented functions referencing it will be listed. # The default value is: NO. -REFERENCED_BY_RELATION = YES +REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. -REFERENCES_RELATION = YES +REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set # to YES then the hyperlinks from functions in REFERENCES_RELATION and @@ -1013,12 +1059,12 @@ SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system -# (see http://www.gnu.org/software/global/global.html). You will need version +# (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global -# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # @@ -1158,7 +1204,7 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. @@ -1194,6 +1240,17 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = NO +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via Javascript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have Javascript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1217,13 +1274,13 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# environment (see: https://developer.apple.com/xcode/), introduced with OSX +# 10.5 (Leopard). To create a documentation set, doxygen will generate a # Makefile in the HTML output directory. Running make will produce the docset in # that directory and running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1262,7 +1319,7 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on # Windows. # # The HTML Help Workshop contains a compiler that can convert all HTML output @@ -1338,7 +1395,7 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1346,7 +1403,7 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- +# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- # folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1355,7 +1412,7 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1363,7 +1420,7 @@ QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1371,7 +1428,7 @@ QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = @@ -1464,7 +1521,7 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # @@ -1476,7 +1533,7 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1503,11 +1560,11 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/. # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/ # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example @@ -1543,7 +1600,7 @@ MATHJAX_CODEFILE = # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -SEARCHENGINE = NO +SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a web server instead of a web client using Javascript. There @@ -1565,7 +1622,7 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). +# Xapian (see: https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1578,7 +1635,7 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). See the section "External Indexing and +# Xapian (see: https://xapian.org/). See the section "External Indexing and # Searching" for details. # This tag requires that the tag SEARCHENGINE is set to YES. @@ -1630,21 +1687,35 @@ LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. # -# Note that when enabling USE_PDFLATEX this option is only used for generating -# bitmaps for formulas in the HTML output, but not in the Makefile that is -# written to the output directory. -# The default file is: latex. +# Note that when not enabling USE_PDFLATEX the default is latex when enabling +# USE_PDFLATEX the default is pdflatex and when in the later case latex is +# chosen this is overwritten by pdflatex. For specific output languages the +# default can have been set differently, this depends on the implementation of +# the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_CMD_NAME = latex # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. +# Note: This tag is used in the Makefile / make.bat. +# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file +# (.tex). # The default file is: makeindex. # This tag requires that the tag GENERATE_LATEX is set to YES. MAKEINDEX_CMD_NAME = makeindex +# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. +# Note: This tag is used in the generated output file (.tex). +# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. +# The default value is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_MAKEINDEX_CMD = makeindex + # If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. @@ -1765,7 +1836,7 @@ LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1779,6 +1850,14 @@ LATEX_BIB_STYLE = plain LATEX_TIMESTAMP = NO +# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) +# path from which the emoji images will be read. If a relative path is entered, +# it will be relative to the LATEX_OUTPUT directory. If left blank the +# LATEX_OUTPUT directory will be used. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EMOJI_DIRECTORY = + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- @@ -1818,9 +1897,9 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's config -# file, i.e. a series of assignments. You only have to provide replacements, -# missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# configuration file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. # # See also section "Doxygen usage" for information on how to generate the # default style sheet that doxygen normally uses. @@ -1829,8 +1908,8 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an RTF document. Syntax is -# similar to doxygen's config file. A template extensions file can be generated -# using doxygen -e rtf extensionFile. +# similar to doxygen's configuration file. A template extensions file can be +# generated using doxygen -e rtf extensionFile. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = @@ -1916,6 +1995,13 @@ XML_OUTPUT = xml XML_PROGRAMLISTING = YES +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO + #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- @@ -1948,9 +2034,9 @@ DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sf.net) file that captures the -# structure of the code including all documentation. Note that this feature is -# still experimental and incomplete at the moment. +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -2040,7 +2126,7 @@ INCLUDE_PATH = # used. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -INCLUDE_FILE_PATTERNS = *.h *.hpp +INCLUDE_FILE_PATTERNS = # The PREDEFINED tag can be used to specify one or more macro names that are # defined before the preprocessor is started (similar to the -D option of e.g. @@ -2088,12 +2174,14 @@ SKIP_FUNCTION_MACROS = YES # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. -GENERATE_TAGFILE = @CMAKE_BINARY_DIR@/docs/openfast.tag +TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create a # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. +GENERATE_TAGFILE = @CMAKE_BINARY_DIR@/docs/openfast.tag + # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be # listed. @@ -2115,12 +2203,6 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- @@ -2134,15 +2216,6 @@ PERL_PATH = /usr/bin/perl CLASS_DIAGRAMS = YES -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2205,7 +2278,7 @@ DOT_FONTPATH = # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -CLASS_GRAPH = NO +CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation @@ -2214,14 +2287,14 @@ CLASS_GRAPH = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -COLLABORATION_GRAPH = NO +COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for # groups, showing the direct groups dependencies. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GROUP_GRAPHS = NO +GROUP_GRAPHS = YES # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling @@ -2259,7 +2332,7 @@ TEMPLATE_RELATIONS = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDE_GRAPH = NO +INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing @@ -2280,7 +2353,7 @@ INCLUDED_BY_GRAPH = NO # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -CALL_GRAPH = NO +CALL_GRAPH = YES # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller # dependency graph for every global function or class method. @@ -2292,7 +2365,7 @@ CALL_GRAPH = NO # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -CALLER_GRAPH = NO +CALLER_GRAPH = YES # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical # hierarchy of all classes instead of a textual one. @@ -2308,7 +2381,7 @@ GRAPHICAL_HIERARCHY = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -DIRECTORY_GRAPH = NO +DIRECTORY_GRAPH = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section diff --git a/docs/_static/.blank b/docs/_static/.blank deleted file mode 100644 index 5a5329651..000000000 --- a/docs/_static/.blank +++ /dev/null @@ -1 +0,0 @@ -Need this file so I can check in a blank _static directory. diff --git a/docs/_static/GitFlowFeatureBranches.png b/docs/_static/GitFlowFeatureBranches.png index 13e2b0325..5b96426c7 100644 Binary files a/docs/_static/GitFlowFeatureBranches.png and b/docs/_static/GitFlowFeatureBranches.png differ diff --git a/docs/_static/docs_options.png b/docs/_static/docs_options.png new file mode 100644 index 000000000..9105d95e6 Binary files /dev/null and b/docs/_static/docs_options.png differ diff --git a/docs/conf.py b/docs/conf.py index 85479a74d..f73c5c2af 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,11 +24,11 @@ #sys.path.append(os.path.abspath('_extensions/')) readTheDocs = os.environ.get('READTHEDOCS', None) == 'True' -sourcedir = sys.argv[-2] builddir = sys.argv[-1] +sourcedir = sys.argv[-2] # Use this to turn Doxygen on or off -useDoxygen=False +useDoxygen = True # This function was adapted from https://gitlab.kitware.com/cmb/smtk # Only run when on readthedocs @@ -37,13 +37,12 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): cfg = dx.read() srcdir = os.path.abspath(os.path.join(os.getcwd(), '..')) bindir = srcdir - c2 = re.sub('@CMAKE_SOURCE_DIR@', srcdir, \ - re.sub('@CMAKE_BINARY_DIR@', bindir, cfg)) + c2 = re.sub('@CMAKE_SOURCE_DIR@', srcdir, re.sub('@CMAKE_BINARY_DIR@', bindir, cfg)) doxname = os.path.join(sourcedir, doxyfileOut) dox = open(doxname, 'w') - print >>dox, c2 + print(c2, file=dox) dox.close() - print 'Running Doxygen on %s' % doxyfileOut + print("Running Doxygen on {}".format(doxyfileOut)) doxproc = subprocess.call(('doxygen', doxname)) if readTheDocs and useDoxygen: @@ -59,15 +58,19 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.mathjax', - 'sphinx.ext.intersphinx', - 'sphinxcontrib.doxylink', - 'sphinxcontrib.bibtex', - ] + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.mathjax', + 'sphinx.ext.intersphinx', + 'sphinxcontrib.doxylink', + 'sphinxcontrib.bibtex', +] -autodoc_default_flags = ['members','show-inheritance','undoc-members'] +autodoc_default_flags = [ + 'members', + 'show-inheritance', + 'undoc-members' +] autoclass_content = 'both' @@ -77,16 +80,16 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): if useDoxygen: if readTheDocs: doxylink = { - 'openfast' : ( - os.path.join(builddir, '..', '..', 'openfast.tag'), - os.path.join('html') + 'openfast': ( + os.path.join(builddir, '..', '..', 'openfast.tag'), + os.path.join('html') ) } else: doxylink = { - 'openfast' : ( - os.path.join(builddir, '..', 'openfast.tag'), - os.path.join('html') + 'openfast': ( + os.path.join(builddir, '..', 'openfast.tag'), + os.path.join('html') ) } @@ -159,7 +162,9 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + "analytics_id": "UA-68999653-10" +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -197,8 +202,13 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Openfast.tex', u'OpenFAST Documentation', - u'National Renewable Energy Laboratory', 'manual'), + ( + master_doc, + 'Openfast.tex', + u'OpenFAST Documentation', + u'National Renewable Energy Laboratory', + 'manual' + ), ] @@ -207,8 +217,13 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'openfast', u'OpenFAST Documentation', - [author], 1) + ( + master_doc, + 'openfast', + u'OpenFAST Documentation', + [author], + 1 + ) ] @@ -218,16 +233,27 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'OpenFAST', u'OpenFAST Documentation', - author, 'OpenFAST', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + 'OpenFAST', + u'OpenFAST Documentation', + author, + 'OpenFAST', + 'One line description of project.', + 'Miscellaneous' + ), ] def setup(app): - app.add_object_type("confval", "confval", - objname="input file parameter", - indextemplate="pair: %s; input file parameter") - app.add_object_type("cmakeval", "cmakeval", - objname="CMake configuration value", - indextemplate="pair: %s; CMake configuration") - + app.add_object_type( + "confval", + "confval", + objname="input file parameter", + indextemplate="pair: %s; input file parameter" + ) + app.add_object_type( + "cmakeval", + "cmakeval", + objname="CMake configuration value", + indextemplate="pair: %s; CMake configuration" + ) diff --git a/docs/index.rst b/docs/index.rst index b2258bb52..c4474e974 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,19 +9,9 @@ OpenFAST Documentation :Version: |release| :Date: |today| -OpenFAST is an open-source wind turbine simulation tool established in 2017 -which builds on FAST v8 (see :ref:`fast_to_openfast`). It was -created with the goal of being a community model developed and used by research -laboratories, academia, and industry. It is managed by a dedicated team at the -National Renewable Energy Lab. Our objective is to ensure that OpenFAST is -sustainable software that is well tested and well documented. If you'd like -to contribute, see the :ref:`dev_guide` and any open GitHub issues with the -`Help Wanted `_ -tag. - OpenFAST is a multi-physics, multi-fidelity tool for simulating the coupled dynamic response of wind turbines. Practically speaking, OpenFAST is the -framework (or glue code) that couples computational modules for +framework (or "glue code") that couples computational modules for aerodynamics, hydrodynamics for offshore structures, control and electrical system (servo) dynamics, and structural dynamics to enable coupled nonlinear aero-hydro-servo-elastic simulation in the time domain. OpenFAST enables the @@ -31,26 +21,36 @@ teetering hub, upwind or downwind rotor, and lattice or tubular tower. The wind turbine can be modeled on land or offshore on fixed-bottom or floating substructures. -OpenFAST and its underlying modules are mostly written in Fortran (adhering to -the 2003 standard), but modules can be written in C/C++. OpenFAST was created -with the goal of being a community model, with developers and users from -research laboratories, academia, and industry. Our goal is also to ensure that -OpenFAST is sustainable software that is well tested and well documented. To -that end, we are continually improving the documentation and test coverage for -existing code, and we expect that new capabilities will include adequate -testing and documentation. - -Here are some important links: -- `Github Organization Page `_ +Established in 2017, OpenFAST is an open-source software package +that builds on FAST v8 (see :ref:`fast_to_openfast`). The glue code +and underlying modules are mostly written in Fortran +(adhering to the 2003 standard), and modules can also be written in C or +C++. It was created with the goal of being a community model developed +and used by research laboratories, academia, and industry. It is +managed by a dedicated team at the National Renewable Energy Lab. +Our objective is to ensure that OpenFAST is well tested, well +documented, and self-sustaining software. To that end, we are continually +improving the documentation and test coverage for existing code, and we +expect that new capabilities will include adequate testing and +documentation. If you'd like to contribute, see the +:ref:`dev_guide` and any open GitHub issues with the +`Help Wanted `_ +tag. + +The following links provide more insight into OpenFAST as a software +package: + +- `OpenFAST Github Organization `_ - `Github Repository `_ -- `Nightly Testing Results `_ +- `Nightly Tests `_ + +**Documentation Directory** .. toctree:: :numbered: :maxdepth: 2 source/this_doc.rst - source/get_started.rst source/install/index.rst source/testing/index.rst source/user/index.rst @@ -58,6 +58,3 @@ Here are some important links: source/license.rst source/help.rst source/acknowledgements.rst - - Nightly Testing Results - github.com Repository diff --git a/docs/source/acknowledgements.rst b/docs/source/acknowledgements.rst index 92e938241..dedd7a58b 100644 --- a/docs/source/acknowledgements.rst +++ b/docs/source/acknowledgements.rst @@ -3,15 +3,16 @@ Acknowledgements ================ -This software is developed and maintained by researchers at the `National Renewable Energy Laboratory `_ with funding from U.S. -Department of Energy (DOE) Wind Energy Technology Office through the `Atmosphere to electrons (A2e) `_ research initiative. +This software is developed and maintained by researchers at the +`National Renewable Energy Laboratory `_ with funding +from U.S. Department of Energy Wind Energy Technology Office through the +`Atmosphere to electrons (A2e) `_ research initiative. -NREL gratefully acknowledges development contributions from the following organizations: +NREL gratefully acknowledges development contributions from the following +organizations: -* Envision Energy USA, Ltd - -* Brigham Young University - -NREL gratefully acknowledges additional development support through an -`Intel® Parallel Computing Center (IPCC) `_ +- Envision Energy USA, Ltd +- Brigham Young University +NREL gratefully acknowledges additional development support through designation +as an `Intel® Parallel Computing Center (IPCC) `_. diff --git a/docs/source/dev/build_doc.rst b/docs/source/dev/build_doc.rst index d8e57eeca..c906cb558 100644 --- a/docs/source/dev/build_doc.rst +++ b/docs/source/dev/build_doc.rst @@ -4,80 +4,93 @@ Developing Documentation ======================== OpenFAST documentation is hosted on `readthedocs `_. It is automatically generated -through the readthedocs build system from both the ``master`` and ``dev`` +through the ``readthedocs`` build system from both the ``master`` and ``dev`` branches whenever new commits are added. This documentation uses the `restructured text `_ markup language. Building this documentation locally ----------------------------------- -The documentation is compiled with Sphinx, which is a Python based tool. -Install it and the other required Python packages listed in -``docs/requirements.txt`` with pip or another python package manager. +The documentation is compiled with `Sphinx `__, which is +a Python based tool. Install it and the other required Python packages listed +in ``openfast/docs/requirements.txt`` with ``pip`` or another Python package +manager. + +These additional packages are optional and are not included in the requirements +file: -These packages are optional: - `Doxygen `__ - `Doxylink `__ - `Graphviz `__ +- `LaTeX `__ Doxygen and Graphviz can be installed directly from their website or with a package manager like ``brew``, ``yum``, or ``apt``. Pure python build ------------------ +~~~~~~~~~~~~~~~~~ If CMake and Make are not available on your system, the documentation can be generated directly with `sphinx`. -**Note: This method does not generate the API documentation through Doxygen.** -First, align your build structure to the standard OpenFAST build by creating -a directory at ``openfast/build``. +.. note:: + + This method does not generate the API documentation through Doxygen. -If all tools are available, move into ``openfast/build`` and run the `sphinx` -command: +First, align your directory structure to the standard OpenFAST build by +creating a directory at ``openfast/build``. Then, move into +``openfast/build`` and run this command: -:: +.. code-block:: bash # sphinx-build -b sphinx-build -b html ../docs ./docs/html -If this completes successfully, a html file will be created at +If this completes successfully, an html file will be created at ``build/docs/html/index.html`` which can be opened with any web browser. Building with CMake and Make ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the OpenFAST directory, create a ``build`` directory and move into it. -Then, run CMake with this flag: ``-DBUILD_DOCUMENTATION=ON``. If all -of the required tools are found successfully, CMake will configure with the -ability to build the documentation. +Then, run CMake with this flag: ``-DBUILD_DOCUMENTATION=ON``. CMake will +configure the build system with the necessary files for building +the documentation. -Next, run the command ``make docs`` which will first build the Doxygen -documentation and then the Sphinx documentation. If this completes -successfully, a html file will be created at ``build/docs/html/index.html`` -which can be opened with any web browser. +Next, run the command to compile the docs: -For example, from the OpenFAST directory: +.. code-block:: bash + + make docs -:: +This will first build the Doxygen API documentation and then the Sphinx +documentation. If this completes successfully, a html file will be +created at ``build/docs/html/index.html`` which can be opened with any web +browser. + +The full procedure for configuring and building the documentation is: + +.. code-block:: bash mkdir build cd build cmake .. -DBUILD_DOCUMENTATION=ON make docs -If you modify document source files in ``openfast/docs/source``, you can simply -update the html files through another ``make docs`` in ``openfast/build``: +If any modifications are made to the source files in ``openfast/docs/source``, +you can simply update the html files by executing the ``make`` command again. -:: +The table below lists make-targets related to the documentation. - make docs +======================= ================== ======================================== + Target Command Output location +======================= ================== ======================================== + Full docs make docs openfast/build/docs/html/index.html + Full docs make sphinx openfast/build/docs/html/index.html + Doxygen API Reference make doxygen + HTML only make sphinx-html openfast/build/docs/html/index.html + PDF only make sphinx-pdf openfast/build/docs/latex/Openfast.pdf +======================= ================== ======================================== -Building only the html -~~~~~~~~~~~~~~~~~~~~~~ -Generating the only html is much faster than compiling all components of the -documentation. This can be done with ``make sphinx-html``. +Adding documentation +-------------------- -Building the PDF -~~~~~~~~~~~~~~~~ -If LaTeX is installed, a pdf version of the documentation can be built with -``make sphinx-pdf``, and the output is available at -``OpenFAT/build/docs/latex/Openfast.pdf``. +Coming soon. Feel like contributing? Start here! diff --git a/docs/source/dev/code_style.rst b/docs/source/dev/code_style.rst new file mode 100644 index 000000000..eac515713 --- /dev/null +++ b/docs/source/dev/code_style.rst @@ -0,0 +1,15 @@ +.. _code_style: + +Code Style +~~~~~~~~~~ +OpenFAST and its underlying modules are mostly written in Fortran adhering to +the 2003 standard, but modules can be written in C or C++. The +`NWTC Programmer's Handbook `__ +is the definitive reference for all questions related to working with the +FAST Framework and adding code to OpenFAST. + +Generally, code should be written such that it is straightforward to read. +Syntactic sugar or brevity should not detract from readability. The exception +to this is in situations where performance requires poorly readable code. +Here, comment blocks should be used to describe what is not readily apparent +in the code. Indentation is typically three spaces and no tabs. diff --git a/docs/source/dev/debugging.rst b/docs/source/dev/debugging.rst index e2620ce26..807c72674 100644 --- a/docs/source/dev/debugging.rst +++ b/docs/source/dev/debugging.rst @@ -4,46 +4,54 @@ Debugging OpenFAST ================== Being a Fortran project, OpenFAST can be challenging to debug and the process -is unique for each system and environment. However, a common requirement for -all systems is to compile OpenFAST in debug mode. +is unique for each system and environment. Keep in mind that some OpenFAST +cases can be quite large in their memory footprint and may take a long time +to reach the point of interest in the code. Choosing a test case carefully +could save a significant amount time. -Keep in mind that some OpenFAST cases can be quite large in their memory -footprint and may take a long time to reach the point you're targetting in -the code. Choosing a minimal test case could save significant time. - -It may by helpful to write a small fortran program to verify that your +It may by helpful to write a small fortran program to verify that all debugging tools are set up properly before diving in to OpenFAST. Be sure to simulate a bug by doing something like accessing an array element that is not -allocated and verify that you can catch the bug with your tools. +allocated and verify that you can catch the bug with a given set of tools. + +.. note:: + + A requirement for all systems is to compile OpenFAST in **debug** mode. + +.. _debugging_windows: Debugging on Windows -------------------- -Windows developers using Intel tools can use Visual Studio for debugging. This -is a straightforward process with lots of support from Intel. +Windows developers using Intel tools can use Visual Studio solution included in +the OpenFAST repository for debugging. This is a straightforward process with +lots of support from Intel. + +Otherwise, Windows developers compiling in Unix-style environments should +proceed to :ref:`debugging_linux`. -Otherwise, Windows developers compiling with CygWin or MinGW should proceed to -the section for debugging with linux. +.. _debugging_linux: Debugging on Linux and macOS ---------------------------- -First, compile OpenFAST in debug mode by setting CMAKE_BUILD_TYPE to Debug. -You can do this on the command line with +First, compile OpenFAST in debug mode by setting ``CMAKE_BUILD_TYPE`` to +"Debug". This can be done on the command line with: .. code-block:: bash cmake .. -D CMAKE_BUILD_TYPE=Debug -or by using ccmake to open the command line cmake gui to change it. +or by using ``ccmake`` to open the command line cmake gui to change it. -The GNU debugger, GDB, works well for debugging compiled code. It has a +The GNU debugger, ``gdb``, works well for debugging compiled code. It has a comprehensive command line interface which enables developers to add breakpoints and inspect variables. Driving the debugger through an IDE can make inspecting the code much more -efficient. One IDE known to work well is Visual Studio Code with the Native -Debug extension. You can set up a launch configuration in VS Code so that -you can debug a particular OpenFAST case through the IDE. To do this, open -the launch configuration and add a block similar to this: +efficient. One IDE known to work well is `Visual Studio Code `__ +with the `Native Debug `__ +extension. You can set up a `launch configuration `__ +so that you can debug a particular OpenFAST case through the IDE. To do this, +open the launch configuration and add a block similar to this: .. code-block:: json @@ -58,12 +66,12 @@ the launch configuration and add a block similar to this: "target": "${workspaceRoot}/build/glue-codes/openfast/openfast", "cwd": "${workspaceRoot}/build/reg_tests/glue-codes/openfast/AOC_WSt/", "arguments": "${workspaceRoot}/build/reg_tests/glue-codes/openfast/AOC_WSt/AOC_WSt.fst", - }, + } -macOS configuration -~~~~~~~~~~~~~~~~~~~ +macOS-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GDB on macOS needs some configuration before the system allows it to take -over a process. It is recommended that gdb be installed with homebrew +over a process. It is recommended that ``gdb`` be installed with homebrew .. code-block:: bash @@ -71,7 +79,7 @@ over a process. It is recommended that gdb be installed with homebrew brew install gdb After that completes, be sure to follow the caveats to finish the installation. -For gdb 8.2.1, it looks like this: +For ``gdb 8.2.1``, it looks like this: .. code-block:: bash @@ -86,8 +94,10 @@ For gdb 8.2.1, it looks like this: echo "set startup-with-shell off" >> ~/.gdbinit For Native Debug on macOS, you have to sort of hack the extension to allow -breakpoints in fortran files by adding this line to your settings.json: +breakpoints in fortran files by adding this line to ``.vscode/settings.json``: .. code-block:: json - "debug.allowBreakpointsEverywhere": true, + { + "debug.allowBreakpointsEverywhere": true + } diff --git a/docs/source/dev/dev_phil.rst b/docs/source/dev/dev_phil.rst deleted file mode 100644 index 3211cb5a4..000000000 --- a/docs/source/dev/dev_phil.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _dev_philosophy: - -OpenFAST Development Philosophy -=============================== - -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. - -We have the following guidance for developers: - -- When fixing a bug, first introduce a unit test that exposes the bug, fix the - bug, and submit a Pull Request. See :numref:`testing` and - :numref:`github_workflow` for information on testing and the GitHub workflow. - -- When adding a new feature, create appropriate automated unit and regression - tests as described in :numref:`testing`. The objective is to create a GitHub - pull request that provides adequate verification and validation such 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 :numref:`pull_requests` for detailed information on submitting - a pull request. - -- 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 `_ - repository. - -Versioning ----------- -OpenFAST follows `semantic versioning `_. In summary, this -means that with a version number as MAJOR.MINOR.PATCH, the components will be -incremented as follows: - -- MAJOR version when introducing incompatible API changes, -- MINOR version when adding functionality in a backwards-compatible manner, and -- PATCH version when making backwards-compatible bug fixes. - -For example, ``OpenFAST-v1.0.0-123-gabcd1234-dirty`` describes OpenFAST as: - -- v1.0.0 is the MAJOR.MINOR.PATCH numbering system and corresponds to a tagged - commit made by NREL on GitHub -- 123-g is the number of additional commits after the most recent tag for a - build [the ``-g`` is for ``git``] -- abcd1234 is the first 8 characters of the current commit hash -- dirty denotes that local changes have been made but not committed - -Code Style ----------- -OpenFAST and its underlying modules are mostly written in Fortran adhering to -the 2003 standard, but modules can be written in C or C++. Indentation is -typically three spaces and no tabs. - -Generally, code should be written such that it is straightforward to read. -Syntactic sugar or brevity should not detract from readability. The exception -to this is in situations where performance dictates a poorly readable code. -Here, comment blocks should be used to describe what is not readily apparent -in the code. diff --git a/docs/source/dev/doxy_doc.rst b/docs/source/dev/doxy_doc.rst deleted file mode 100644 index 15bdda41c..000000000 --- a/docs/source/dev/doxy_doc.rst +++ /dev/null @@ -1,8 +0,0 @@ -Doxygen API documentation -========================= - -If the Doxygen documentation is available, it can be found at the following locations - - * `Main Page <../../../doxygen/html/index.html>`_ - * `Index of Classes <../../../doxygen/html/classes.html>`_ - * `Files <../../../doxygen/html/files.html>`_ diff --git a/docs/source/dev/github_workflow.rst b/docs/source/dev/github_workflow.rst index 6c10939f0..d00408e8b 100644 --- a/docs/source/dev/github_workflow.rst +++ b/docs/source/dev/github_workflow.rst @@ -3,7 +3,7 @@ Working with OpenFAST on GitHub =============================== The majority of the collaboration and development for OpenFAST takes place -on the `github repository `__. There, +on the `GitHub repository `__. There, `issues `__ and `pull requests `__ are discussed and new versions are released. It is the best mechanism for @@ -26,14 +26,14 @@ submitted along with all appropriate documentation and tests. An NREL OpenFAST team member will assign a reviewer and work with the developer to have the code merged into the main repository. -New pull requests should contain +New pull requests should contain the following: - A description of the need for modifications - If the pull request fixes a bug, the accompanying GitHub issue should be referenced -- A highlight of the work implemented +- A summary of the work implemented - Regression test results - If all tests pass, the summary print out should be provided @@ -47,19 +47,16 @@ New pull requests should contain Git workflow and interacting with the main repository ----------------------------------------------------- OpenFAST development should follow "Git Flow" when interacting with the github -repository. Git Flow is a git workflow outlining safe methods of pushing and -pulling commits to a shared repository. Maintaining Git Flow is critical to -prevent remote changes from blocking your local development. - -Git Flow --------- -The Git Flow process is well defined and adopted throughout the software -development community. It is detailed nicely +repository. Git Flow is a well-defined and widely adopted workflow for using +git that outlines safe methods of pushing and pulling commits to a shared +repository. Maintaining Git Flow is critical to prevent remote changes from +blocking your local development. This workflow is detailed nicely `here `__ and the chart below provides a high level perspective. .. image:: ../../_static/GitFlowFeatureBranches.png - :align: center + :width: 70% + :align: center Reference: http://nvie.com/posts/a-successful-git-branching-model @@ -71,24 +68,45 @@ On public branches, avoid using `git rebase `__ and never `force push `__. -In OpenFAST development, the typical workflow follows this procedure +In OpenFAST development, the typical workflow follows this procedure: -1. Fork the OpenFAST/OpenFAST repository on GitHub +1. Fork the OpenFAST repository on GitHub -2. Clone your new fork: ``git clone https://github.com//OpenFAST`` +2. Clone your new fork -3. Add OpenFAST/OpenFAST as a remote: ``git remote add upstream https://github.com/OpenFAST/OpenFAST`` +.. code-block:: bash -4. Create a feature branch for active development: -``git branch feature/a_great_feature`` or -``git checkout -b feature/a_great_feature`` + git clone https://github.com//OpenFAST -5. Add new development on `feature/a_great_feature`: -``git add a_file.f90 && git commit -m "A message" && git push`` +3. Add OpenFAST/OpenFAST as a remote named ``upstream`` -5. Update your feature branch with OpenFAST/dev: -``git pull upstream dev && git push`` +.. code-block:: bash -6. Create a GitHub pull request to merge -``youruser/OpenFAST/feature/a_great_feature`` into ``OpenFAST/OpenFAST/dev`` + git remote add upstream https://github.com/OpenFAST/OpenFAST +4. Create a feature branch for active development starting from the OpenFAST + ``dev`` branch and check it out + +.. code-block:: bash + + git branch feature/a_great_feature upstream/dev + git checkout feature/a_great_feature + +5. Add new development on ``feature/a_great_feature`` + +.. code-block:: bash + + git add a_file.f90 + git commit -m "A message" + git push origin feature/a_great_feature + +6. Update your feature branch with ``upstream`` + +.. code-block:: bash + + git pull upstream dev + git push origin feature/a_great_feature + +7. Open a new `pull request `__ + to merge ``/OpenFAST/feature/a_great_feature`` into + ``OpenFAST/OpenFAST/dev`` diff --git a/docs/source/dev/index.rst b/docs/source/dev/index.rst index 36c523398..2725408ae 100644 --- a/docs/source/dev/index.rst +++ b/docs/source/dev/index.rst @@ -3,8 +3,8 @@ Developer Documentation ======================= -**Our goal as developers is to ensure that OpenFAST is a sustainable open -source software that is well tested and well documented.** To that end, we +**Our goal as developers of OpenFAST is to ensure that it is well tested, well +documented, and self-sustaining software.** To that end, we continually work to improve the documentation and test coverage along with feature additions and improvements. This section of the documentation outlines the processes and procedures we have established for external developers @@ -14,16 +14,14 @@ If you'd like to help with general OpenFAST development or work on a particular feature, then first install OpenFAST following the :doc:`installation instructions <../install/index>` for your machine. Next, verify that your installation is valid by running the test suite following the -:doc:`testing instructions <../testing/index>`. - -After a successful and validated build, we encourage reading through the -:doc:`OpenFAST development philosophy ` to understand the general -workflow for individual and coordinated development. Finally, be sure to review -the :doc:`GitHub workflow ` to avoid any merge or code -conflicts. +:doc:`testing instructions <../testing/index>`. While OpenFAST is compiling, we +encourage reading through the :ref:`development_philosophy` section to +understand the general workflow for individual and coordinated development. +Finally, be sure to review the :doc:`GitHub workflow ` to +avoid any merge or code conflicts. With development happening in parallel between NREL, industry partners, and -universities, NREL relies on these GitHub tools to coordinate efforts: +universities, NREL relies on GitHub to coordinate efforts: - `GitHub Issues `_ is the place to ask usage or development questions, report bugs, and @@ -35,13 +33,69 @@ universities, NREL relies on these GitHub tools to coordinate efforts: For other questions regarding OpenFAST, please contact `Mike Sprague `_. +.. tip:: + + The following sections provide valuable guidance on workflow and + development tips which make the process more efficient and + effective: + + - :ref:`github_workflow` + - :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: + +- `Main Page <../../html/index.html>`_ +- `Index of Types <../../html/classes.html>`_ +- `Source Files <../../html/files.html>`_ + +.. _development_philosophy: + +Development Philosophy +~~~~~~~~~~~~~~~~~~~~~~ + +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. + +We have the following guidance for developers: + +- 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. + +- 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. + +- 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 `_ + repository. + +Development Guidelines +~~~~~~~~~~~~~~~~~~~~~~ +The following sections provide extended guidance on how to develop source code, +interacting with the NREL OpenFAST team and other community contributors, and +generally debugging and building out features. + .. toctree:: :maxdepth: 1 - dev_phil.rst github_workflow.rst - debugging.rst + code_style.rst build_doc.rst types_files.rst + debugging.rst performance.rst - doxy_doc.rst + versioning.rst diff --git a/docs/source/dev/versioning.rst b/docs/source/dev/versioning.rst new file mode 100644 index 000000000..8f742f196 --- /dev/null +++ b/docs/source/dev/versioning.rst @@ -0,0 +1,22 @@ +.. _versioning: + +Versioning +~~~~~~~~~~ +OpenFAST follows `semantic versioning `_. In summary, this +means that with a version number as MAJOR.MINOR.PATCH, the components will be +incremented as follows: + +- MAJOR version when introducing incompatible API changes, +- MINOR version when adding functionality in a backwards-compatible manner, and +- PATCH version when making backwards-compatible bug fixes. + +For example, ``OpenFAST-v1.0.0-123-gabcd1234-dirty`` describes OpenFAST as: + +=================== ============= + Version Component Explanation +=================== ============= + v1.0.0 MAJOR.MINOR.PATCH numbering system; corresponds to a tagged commit made by NREL on GitHub + 123-g Number of additional commits after the most recent tag for a build (the ``-g`` is for ``git``) + abcd1234 First 8 characters of the current commit hash + dirty Denotes that local changes have been made but not committed; omitted if there are no local changes +=================== ============= diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst deleted file mode 100644 index 87f26ca6b..000000000 --- a/docs/source/get_started.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _get_started: - -Getting Started -=============== - -**Get the code:** - -OpenFAST can be cloned (i.e., downloaded) from its `Github Repository `_, e.g., from the command line: -:: - - git clone https://github.com/OpenFAST/OpenFAST.git - -It can also be downloaded directly from https://github.com/OpenFAST/OpenFAST.git. - -**Compile the code:** - -See :ref:`installation`, for installation instructions (including dependency requirements) for CMake, Spack, and Visual Studio and for multiple platforms (Linux, Mac, Windows). -As an example, from the command line in a Mac or Linux environment: -:: - - cd OpenFAST - mkdir build && cd build - cmake ../ - make - -Note that one can see all of the `make` targets via -:: - - make help - - -**Use the code:** - -See :ref:`user_guide`, which is under construction. -In the interim, users may refer to the FAST v8 documentation at https://nwtc.nrel.gov/. - -**Develop the code:** - -See :ref:`dev_guide`, which is under construction. -In the interim, developers may consult the FAST v8 `Programmer's Handbook `_. - diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 72ecebbec..9c42a658b 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -2,38 +2,462 @@ Installing OpenFAST =================== +Guidelines and procedures for obtaining precompiled binaries or compiling +OpenFAST from source code are described here. While there +are multiple ways to achieve the same outcome, the OpenFAST team has developed +a comprehensive and well thought out system for compiling the source code. +Thus, the methods described here are the only officially supported and +maintained paths for obtaining an OpenFAST executable. -The following pages provide instructions for building OpenFAST and/or its modules from source code. -The developer team is moving towards a CMake-only approach that well supports Window Visual Studio users, -but at this time we provide a separate build path for those users. +For Windows users only, precompiled binaries are available as described in the +:ref:`download_binaries` section. For all platforms, OpenFAST is configured +to build with with CMake and a system-appropriate build tool. Background +on CMake is given in :ref:`understanding_cmake`, and procedures for configuring +and compiling are given in :ref:`cmake_unix` and :ref:`cmake_windows`. Finally, +an alternative and more appropriate option for compiling on Windows while +doing active software development is given in :ref:`vs_windows`. -Obtaining the OpenFAST source code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _download_binaries: -OpenFAST can be cloned (i.e., downloaded) from its `Github Repository `_. -For example, from a command line: +Download binaries +~~~~~~~~~~~~~~~~~ +Each tagged release is accompanied by precompiled binaries for Windows +systems. DLL's for MAP and the DISCON controllers are also included. +The following architecture and precision combinations are currently +available: -:: +- 32 bit single precision +- 64 bit single precision +- 64 bit double precision + +All precompiled binaries can be found in the ``Assets`` dropdown in the +`GitHub Releases `__. Click +`here `__ +to download the latest binaries. + +Compile from source +~~~~~~~~~~~~~~~~~~~ +For compiling from source code, the NREL OpenFAST team has developed an +approach that uses CMake to generate build files for all platforms. Currently, +CMake support for Visual Studio while doing active development +is not well supported, so OpenFAST maintains a Visual Studio solution +giving Windows developers a better option for developing code, compiling +and debugging in a streamlined manner. See :ref:`vs_windows` +for more information. + +Dependencies +------------ +Compiling OpenFAST from source requires additional libraries and tools that +are not distributed with the OpenFAST repository. In many cases, these tools +can be installed with a system's package manager (e.g. ``homebrew`` for macOS, +``yum`` for CentOS/Red Hat, or ``apt`` for Debian-based systems like Ubuntu). +If binaries are downloaded or compiled manually, be sure they are +installed in a standard location for your system so that the other components +of the OpenFAST build system can find the dependencies. + +Build tools ++++++++++++ + +An environment-specific build system is required and will consist of a +combination of the packages listed in the table below. + +============================================== ==================== ================= ======= + Package Applicable systems Minimum version Link +============================================== ==================== ================= ======= + CMake All 3.0 https://cmake.org + GNU Make macOS, Linux 1.8 https://www.gnu.org/software/make/ + Visual Studio Windows 2015 https://visualstudio.microsoft.com> + GNU Compiler Collection (gfortran, gcc, g++) macOS, Linux 4.6.0 https://gcc.gnu.org + Intel Parallel Studio (ifort, icc) All 2013 https://software.intel.com/en-us/parallel-studio-xe/ +============================================== ==================== ================= ======= + +Math libraries +++++++++++++++ + +Math libraries with the BLAS and LAPACK interfaces are also required. These can +be obtained as free, open source libraries or paid, closed source versions. +Some packages contain separate libraries for each interface while others have +the interfaces bundles into a single binary. The most common options are listed +in the table below. + +============ ============ =========== ============== ====== +Library Maintainer Paid/Free Open Source? Link +============ ============ =========== ============== ====== +BLAS NetLib Free Yes http://www.netlib.org/blas/ +LAPACK NetLib Free Yes http://www.netlib.org/lapack/ +BLAS/LAPACK OpenBLAS Free Yes https://www.openblas.net +MKL Intel Paid No https://software.intel.com/en-us/mkl +============ ============ =========== ============== ====== + +Dependencies for the test suite ++++++++++++++++++++++++++++++++ + +The following packages are required to run the test suite: + +- `Python 3 `__ +- `MatPlotLib `__ - used for generating error plots + +Dependencies for the C++ API +++++++++++++++++++++++++++++ + +When using the C++ API, the following packages are required: + +- `HDF5 `_ (provided by ``HDF5_ROOT``) +- `yaml-cpp `_ (provided by ``YAML_ROOT``) + +Get the code +------------ +OpenFAST can be cloned (i.e., downloaded) from its `Github repository `_ +via the command line: + +.. code-block:: bash git clone https://github.com/OpenFAST/OpenFAST.git -It can also be downloaded directly from https://github.com/OpenFAST/OpenFAST. +An archive of the source code can also be downloaded directly from these links: + +- `"master" branch `__ - Stable release +- `"dev" branch `__ - Latest updates + +.. _vs_windows: -Linux and Mac -~~~~~~~~~~~~~ +Visual Studio Solution for Windows +---------------------------------- +A complete Visual Studio solution is maintained for working with the OpenFAST +on Windows systems. The procedure for configuring the system and proceding +with the build process are documentated in the following section: .. toctree:: :maxdepth: 1 - install_cmake_linux.rst - install_spack.rst + install_vs_windows.rst + +.. _understanding_cmake: + +Understanding CMake +------------------- +To more fully understand CMake and its methodology, visit this guide on +`running CMake `__. + +CMake is a build configuration system that creates files as input to a build +tool like GNU Make, Visual Studio, or Ninja. CMake does not compile code +or run compilers directly, but +rather creates the environment needed for another tool to run compilers and +create binaries. A CMake project is described by a series of files called +``CMakeLists.txt`` located in directories throughout the project. The main +CMake file for OpenFAST is located at ``openfast/CMakeLists.txt`` and each +module and glue-code has its own ``CMakeLists.txt``; for example, AeroDyn +and BeamDyn have one at ``openfast/modules/aerodyn/CMakeLists.txt`` and +``openfast/modules/beamdyn/CMakeLists.txt``, respectively. + +Running CMake ++++++++++++++ +Running CMake and a build tool will create many files (text files and binaries) +used in the various stages of the build. For this reason, a ``build`` folder +should be created to contain all of the generated files associated with the +build process. Here, an important file called ``CMakeCache.txt`` contains the +user-defined settings for the CMake configuration. This file functions like +memory storage for the build. It is initially created the first time the CMake +command is run and populated with the initial settings. Then, any subsequent +changes to the settings will be updated and stored there. + +CMake can be executed in a few ways: + +- Command line interace: ``cmake`` +- Command line curses interface: ``ccmake`` +- Official CMake GUI + +The CMake GUI is only distributed for Windows, but it can be built from source +for other platforms. OpenFAST's build process focuses on the command line +execution of CMake for both the Linux/macOS and Windows terminals. The command +line syntax to run CMake for OpenFAST is generally: + +.. code-block:: bash + + cmake [options] + + Options + -D [:]= = Create or update a cmake cache entry. + +For example, a common CMake command issued from the ``openfast/build`` +directory is: + +.. code-block:: bash + + # cmake [options] + # where + # is ".." + # [options] can be + # -DBUILD_SHARED_LIBS:BOOL=ON or + # -DBUILD_SHARED_LIBS=ON + + cmake .. -DBUILD_SHARED_LIBS=ON + +The command line curses interface can be invoked similarly: + +.. code-block:: bash + + ccmake .. + +The interface will be rendered in the terminal window and all navigation +happens through keyboard inputs. + +OpenFAST CMake options +++++++++++++++++++++++ +CMake has a large number of general configuration variables available. A good +resource for useful CMake variables is at this link: `GitLab CMake variables `_. +The `CMake API documentation `_ +is also helpful for searching through variables and determining the resulting +action. Note that the CMake process should be well understood before +customizing the general options. + +The CMake options specific to OpenFAST and their default settings are: + +:: + + BUILD_DOCUMENTATION - Build documentation (Default: OFF) + BUILD_OPENFAST_CPP_API - Enable building OpenFAST - C++ API (Default: OFF) + BUILD_OPENFAST_SIMULINK_API - Enable building OpenFAST for use with Simulink + BUILD_SHARED_LIBS - Enable building shared libraries (Default: OFF) + BUILD_TESTING - Build the testing tree (Default: OFF) + CMAKE_BUILD_TYPE - Choose the build type: Debug Release (Default: Release) + CMAKE_Fortran_MODULE_DIRECTORY - Set the Fortran Modules directory + CMAKE_INSTALL_PREFIX - Install path prefix, prepended onto install directories. + DOUBLE_PRECISION - Treat REAL as double precision (Default: ON) + FPE_TRAP_ENABLED - Enable Floating Point Exception (FPE) trap in compiler options (Default: OFF) + GENERATE_TYPES - Use the openfast-regsitry to autogenerate types modules + ORCA_DLL_LOAD - Enable OrcaFlex library load (Default: OFF) + USE_DLL_INTERFACE - Enable runtime loading of dynamic libraries (Default: ON) + +Additional system-specific options may exist for a given system, but those +should not impact the OpenFAST configuration. As mentioned above, the +configuration variables are set initially but can be changed at any time. +For example, the defaults may be accepted to initially configure the project, +but then the settings may be configured individually: + +.. code-block:: bash + + # Initial configuration with the default settings + cmake .. + + # Change the build to Debug mode rather than Release + cmake .. -DCMAKE_BUILD_TYPE=Debug + + # Use dynamic linking rather than static linking + cmake .. -DBUILD_SHARED_LIBS=ON + +The commands above are equivalent to having run this command the first time: + +.. code-block:: bash -Windows -~~~~~~~ + # Initial configuration in Debug mode with dynamic linking + cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON + +CMAKE_BUILD_TYPE +**************** +This option allows to set the compiler optimization level and debug +information. The value and its effect are listed in the table below. + +================== ================================================================================================================ + CMAKE_BUILD_TYPE Effect +================== ================================================================================================================ + Release ``-O3`` optimization level + RelWithDebInfo ``-O2`` optimization level with ``-g`` flag for debug info + MinSizeRel ``-O1`` optimization level + Debug No optimization and `-g` flag for debug info; additional debugging flags: ``-fcheck=all -pedantic -fbacktrace`` +================== ================================================================================================================ + +Use ``Debug`` during active development to add debug symbols for use with a +debugger. This build type also adds flags for generating runtime checks that +would otherwise result in undefined behavior. ``MinSizeRel`` adds basic +optimizations and targets a minimal size for the generated executable. The next +level, ``RelWithDebInfo``, enables vectorization and other more agressive +optimizations. It also adds debugging symbols and results in a larger +executable size. Finally, use ``Release`` for best performance at the cost +of increased compile time. + +This flag can be set with the following command: + +.. code-block:: bash + + cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo + +CMAKE_INSTALL_PREFIX +******************** +This flag sets the location of the compiled binaries when the build +tool runs the ``install`` command. It should be a full path in a carefully +chosen location. The binaries will be copied into ``include``, ``lib``, +and ``bin`` subfolders under the value of this flag. The default is to +install binaries within the repository in a folder called ``install``. + +This flag can be set with the following command: + +.. code-block:: bash + + cmake .. -DCMAKE_INSTALL_PREFIX="/usr/local/" + +Setting the build tool +++++++++++++++++++++++ +CMake can target a variety of build tools or *generators*. To obtain a list +of available generators on the current system, run with the empty generator +flag, select the target from the list, and rerun with the generator flag +populated: + +.. code-block:: bash + + # Run with the empty -G flag to get a list of available generators + cmake .. -G + + # CMake Error: No generator specified for -G + # + # Generators + # * Unix Makefiles = Generates standard UNIX makefiles. + # Ninja = Generates build.ninja files. + # Xcode = Generate Xcode project files. + # CodeBlocks - Ninja = Generates CodeBlocks project files. + # CodeBlocks - Unix Makefiles = Generates CodeBlocks project files. + # CodeLite - Ninja = Generates CodeLite project files. + # CodeLite - Unix Makefiles = Generates CodeLite project files. + # Sublime Text 2 - Ninja = Generates Sublime Text 2 project files. + # Sublime Text 2 - Unix Makefiles + # = Generates Sublime Text 2 project files. + # Kate - Ninja = Generates Kate project files. + # Kate - Unix Makefiles = Generates Kate project files. + # Eclipse CDT4 - Ninja = Generates Eclipse CDT 4.0 project files. + # Eclipse CDT4 - Unix Makefiles= Generates Eclipse CDT 4.0 project files. + + # Choose one from the list above and pass it as an argument after -G + # NOTE: wrap this is in quotes! + cmake .. -G"Sublime Text 2 - Ninja" + +.. note:: + + If the chosen generator name contains spaces, be sure to wrap it in quotes. + +Math libraries +++++++++++++++ +The CMake project is configured to search for the required math libraries +in default locations. However, if math libraries are not found, they can +be specified directly to CMake. The two required libraries are ``BLAS`` +and ``LAPACK``, and their location can be passed to CMake with this command +syntax: + +.. code-block:: bash + + cmake .. -DBLAS_LIBRARIES="/path/to/blas" -DLAPACK_LIBRARIES="/path/to/lapack" + +The paths given should be to the directory which contains the libraries, +not to the libraries themselves. + +.. _cmake_unix: + +CMake with Make for Linux/macOS +------------------------------- +After reading :ref:`understanding_cmake`, proceed with +configuring OpenFAST. The CMake project is well developed for Linux and +macOS systems, so the default settings should work as given. These settings +should only be changed when a custom build is required. + +The procedure for configuring CMake and compiling with GNU Make on Linux +and macOS systems is given below. + +.. code-block:: bash + + # Clone the repository from GitHub using git + git clone https://github.com/OpenFAST/OpenFAST.git + + # Move into the OpenFAST directory + cd OpenFAST + + # Create the build directory and move into it + mkdir build + cd build + + # Execute CMake with the default options; + # this step creates the Makefiles + cmake .. + + # Execute the Make-help command to list all available targets + make help + + # Choose a particular target or give no target to compile everything + make + +.. tip:: + + Compile in parallel by adding "-jN" where N is the number of parallel + processes to use + +This will build the OpenFAST project in the ``build`` directory. Binaries are +located in ``openfast/build/glue-codes/`` and ``openfast/build/modules/``. Since +all build-related files are located in the ``build`` directory, a new fresh build +process can be accomplished by simply deleting the build directory and starting +again. + +.. _cmake_windows: + +CMake with Visual Studio for Windows +------------------------------------ +After reading :ref:`understanding_cmake`, proceed with +configuring OpenFAST. The result of this configuration process will be +a Visual Studio solution which will be fully functional for compiling +any of the targets within OpenFAST. However, this method lacks support +for continued active development. Specifically, any settings that are +configured in the Visual Studio solution directly will be lost any time +CMake is executed. Therefore, this method should only be used to compile +binaries, and the procure described in :ref:`vs_windows` should be used +for active OpenFAST development on Windows. + +The procedure for configuring CMake and compiling with Visual Studio +on Windows systems is given below. + +.. code-block:: bash + + # Clone the repository from GitHub using git + git clone https://github.com/OpenFAST/OpenFAST.git + + # Move into the OpenFAST directory + cd OpenFAST + + # Create the build directory and move into it + mkdir build + cd build + + # Execute CMake with the default options and a specific Visual Studio version + # and build architecture. For a list of available CMake generators, run + # ``cmake .. -G``. + # This step creates the Visual Studio solution. + cmake .. -G "Visual Studio 14 2015 Win64" + + # Open the generated Visual Studio solution + start OpenFAST.sln + +Visual Studio will open a solution containing all of the OpenFAST projects, +and any module library, module driver, or glue-code can be compiled from there. +The compiled binaries are located within a directory determined by the Visual +Studio build type (Release, Debug, or RelWithDebInfo) in +``openfast/build/glue-codes/`` and ``openfast/build/modules/``. For example, the +OpenFAST executable will be located at ``openfast/build/glue-codes/Release/openfast.exe`` +when compiling in *Release* mode. + +**The CMake-generated Visual Studio build is not currently fully functional.** +Any configurations made to the Solution in the Visual Studio UI will be +lost when CMake is executed, and this can happen whenever a change is made to +the structure of the file system or if the CMake configuration is changed. It +is recommended that this method **not** be used for debugging or active +development on Windows. Instead, see :ref:`vs_windows`. + +.. _installation_appendix: + +Appendix +~~~~~~~~ +The following are additional methods for installation which may not be fully +test or may be deprecated in the future. .. toctree:: :maxdepth: 1 - install_cmake_windows.rst - install_vs_windows.rst - install_cmake_cygwin.rst + install_spack.rst + install_cygwin.rst + +.. TODO: Check the windows paths: math library command, installation location diff --git a/docs/source/install/install_cmake_cygwin.rst b/docs/source/install/install_cmake_cygwin.rst deleted file mode 100644 index b4fd1a595..000000000 --- a/docs/source/install/install_cmake_cygwin.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _install_cmake_cygwin: - -Building OpenFAST on Windows with CMake and Cygwin 64-bit -========================================================= -WARNING: This build process takes a significantly long amount of time. If GNU tools are not required, -it is recommended that Windows users follow the instructions at :ref:`install_cmake_windows` or :ref:`install_vs_windows`. - -Installing prerequisites ------------------------- - -1. Download and install `Cygwin - 64-bit `__. You will need to - ``Run as Administrator`` to complete the installation process. - - - Choose ``Install from internet`` - - Choose the default install location - - Choose the default package download location - - Choose ``Direct connection`` - - Choose a download site - - See next step for ``select packages``. Alternately, you can skip this - step and run ``setup-x86_64.exe`` anytime later to select and install - required software. - -2. Select packages necessary for compiling ``OpenFAST``. Choose - ``binary`` packages and not the source option. - - - Choose ``Category`` view, we will be installing packages from - ``Devel`` and ``Math`` - - From ``Devel`` mark the following packages for installation - - - ``cmake`` - - ``cmake-doc`` - - ``cmake-gui`` - - ``cygwin-devel`` - - ``gcc-core`` - - ``gcc-fortran`` - - ``gcc-g++`` - - ``git`` - - ``make`` - - ``makedepend`` - - - From ``Math`` mark the following packages for installation - - - ``liblapack-devel`` - - ``libopenblas`` - - - To run the test suite, install these optional packages from ``Python``: - - - ``python3`` - - ``Python3-numpy`` - - - Click ``Next`` and accept all additional packages that the setup - process requests to install to satisfy dependencies - -3. It is *recommended* that you reboot the machine after installing - ``Cygwin`` and all the necessary packages. - -Compiling OpenFAST ------------------- -From here, pick up from the Linux with CMake instructions at :ref:`cmake-build-instructions`. - -Other tips ----------- - -- If you desire to be able to run ``openfast.exe`` from the ``cmd`` - window, then you must add the ``C:\cygwin64\lib\lapack`` and - ``C:\cygwin64\home\\software\bin`` to your ``%PATH%`` - variable in environment setting. Replace ```` with your - account name on windows system. diff --git a/docs/source/install/install_cmake_linux.rst b/docs/source/install/install_cmake_linux.rst deleted file mode 100644 index 020e9c2f1..000000000 --- a/docs/source/install/install_cmake_linux.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _install_cmake_linux: - -Building OpenFAST with CMake on Linux and Mac -============================================= - -We describe here how to install OpenFAST (or any of its modules) using the `CMake `_ -build system on Linux or Mac OS systems. Separate CMake documentation is -provided for Windows users at :numref:`install_cmake_windows` and Cygwin users at :numref:`install_cmake_cygwin`. -Also, some template build scripts are available in ``openfast/share``. - -Required software for building OpenFAST ---------------------------------------- - -In order to build OpenFAST using CMake, one needs the following minimum set of packages installed: - -- Fortran compiler (GNU compiler version above 4.6.0 or Intel compiler version above 11) - -- C/C++ compiler - -- GNU Make (version 3.81 or later) - -- CMake (version 2.8.12 or later) - -OpenFAST third party library dependencies ------------------------------------------ - -OpenFAST has the following dependencies: - -- LAPACK libraries. Users should set ``BLAS_LIBRARIES`` and ``LAPACK_LIBRARIES`` appropriately for CMake if the library is not found in standard paths. Use `BLASLIB` as an example when using Intel MKL. - -- **Optional:** For the C++ API, `HDF5 `_ (provided by ``HDF5_ROOT``) and `yaml-cpp `_ (provided by ``YAML_ROOT``) - -- **Optional:** For the testing framework, Python 3+ - -.. _cmake-build-instructions: - -CMake build instructions ------------------------- - -If one has the appropriate third party libraries, CMake, and git installed, obtaining and building OpenFAST can be accomplished as follows: - -.. code-block:: bash - - # obtain the source code; e.g., from the command line using git: - git clone https://github.com/OpenFAST/OpenFAST.git - - # go to the OpenFAST directory - cd OpenFAST - - # create a directory called `build` - mkdir build - - # go to the build directory - cd build - - # execute CMake with the default options, which will create a series of Makefiles - cmake ../ - - # execute a make command (with no target provided, equivalent to `make all` - make - -This will build the OpenFAST suite in the ``build`` directory, which can be deleted for a clean build. - -There are many ``Makefile`` targets (besides ``all``), which can be listed via ``help``: - -.. code-block:: bash - - # list available make targets - make help - - # make a specific target, e.g. - make beamdyn_driver - - - -Current CMake options -~~~~~~~~~~~~~~~~~~~~~ - -Below is a list of current CMake options including their default settings (which will effect, e.g., the targets in a resulting ``Makefile``. - -- ``BUILD_DOCUMENTATION`` - Build documentation (Default: OFF) -- ``BUILD_OPENFAST_CPP_API`` - Enable building OpenFAST - C++ API (Default: OFF) -- ``BUILD_SHARED_LIBS`` - Enable building shared libraries (Default: OFF) -- ``BUILD_TESTING`` - Build the testing tree (Default: OFF) -- ``CMAKE_BUILD_TYPE`` - Choose the build type: Debug Release (Default: Release) -- ``CMAKE_INSTALL_PREFIX`` - Install path prefix, prepended onto install directories. -- ``DOUBLE_PRECISION`` - Treat REAL as double precision (Default: ON) -- ``FPE_TRAP_ENABLED`` - Enable Floating Point Exception (FPE) trap in compiler options (Default: OFF) -- ``ORCA_DLL_LOAD`` - Enable OrcaFlex library load (Default: OFF) -- ``USE_DLL_INTERFACE`` - Enable runtime loading of dynamic libraries (Default: ON) - -CMake options can be configured through command line, e.g. - -.. code-block:: bash - - # to enable Makefile for local building of sphinx-based documentation - cmake .. -DBUILD_DOCUMENTATION:BOOL=ON - - # to compile OpenFAST in single precision - cmake .. -DDOUBLE_PRECISION:BOOL=OFF - - -Custom CMake builds -~~~~~~~~~~~~~~~~~~~ - -The CMake configuration and resulting build can be customized easily through explicitly setting CMake variables. In general, -this is done by passing a flag in the CMake configuration command - -.. code-block:: bash - - cmake .. -D=ON - cmake .. -D=/usr/local/bin/this_thing - -This syntax is the same as in setting a CMake option and the result is used very similarly in the CMake configuration files. -Common customizations revolve around choosing a compiler or math library; for example - -.. code-block:: bash - - cmake .. -DCMAKE_Fortran_COMPILER=/usr/local/bin/gfortran-8 -DLAPACK_LIBRARIES=/System/Library/Frameworks/Accelerate.framework -DLAPACK_LIBRARIES=/System/Library/Frameworks/Accelerate.framework - -**NOTE** Many CMake configurations can also be set through an environment variable. -For example, when using Intel's MKL, the math libraries can be discovered automatically by setting the ``MKLROOT`` -environment variable. The Fortran compiler can also be set explicitly with the ``FC`` environment variable. - -Here is a good resource for useful CMake variables: `GitLab useful cmake variables `_. -The `CMake documentation `_ is also helpful for searching -through variables and determining the resulting action. - - -Parallel build -~~~~~~~~~~~~~~ - -GNU Make has a parellel build option with the ``-jobs`` or ``-j`` flag, and the OpenFAST -CMake configuration handles setting up the dependencies for Make so the build can be -parallelized. However, it is important to note that the only parallel portion -of the build process is in compiling the modules. Due to some interdependency between -modules, the max parallel level is around 12. The remaining portion of the build, -mainly compiling the OpenFAST library itself, takes a considerable amount of time -and cannot be parallelized. - -An example parallel build command is ``make -j 8``. - diff --git a/docs/source/install/install_cmake_windows.rst b/docs/source/install/install_cmake_windows.rst deleted file mode 100644 index cde27e76d..000000000 --- a/docs/source/install/install_cmake_windows.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _install_cmake_windows: - -Building OpenFAST on Windows with CMake and Visual Studio -========================================================= - -We describe here how to install OpenFAST (or any of its modules) using the `CMake `_ -build system on Windows systems. Separate CMake documentation is -provided for Cygwin users at :numref:`install_cmake_cygwin` and Linux/Mac users at :numref:`install_cmake_linux`. -A standalone Visual Studio solution also exists at `openfast/vs-build` and documentation is at :numref:`install_vs_windows`. - -Required software for building OpenFAST ---------------------------------------- - -In order to build OpenFAST using CMake, one needs the following minimum set of packages installed: - -- Fortran compiler (GNU compiler version above 4.6.0 or Intel compiler version above 11) - -- C/C++ compiler - -- Visual Studio - -- CMake (version 2.8.12 or later) - -OpenFAST third party library dependencies ------------------------------------------ - -OpenFAST has the following dependencies: - -- LAPACK libraries. Users should set ``BLAS_LIBRARIES`` and ``LAPACK_LIBRARIES`` appropriately for CMake if the library is not found in standard paths. Use `BLASLIB` as an example when using Intel MKL. - -- **Optional:** For the C++ API, `HDF5 `_ (provided by ``HDF5_ROOT``) and `yaml-cpp `_ (provided by ``YAML_ROOT``) - -- **Optional:** For the testing framework, Python 3+ - -CMake build instructions ------------------------- - -If one has the appropriate third party libraries, CMake, and git installed, obtaining and building OpenFAST can be accomplished as follows: - -.. code-block:: bash - - # Obtain the source code; e.g., from the command line using git: - git clone https://github.com/OpenFAST/OpenFAST.git - - # Go to the OpenFAST directory - cd OpenFAST - - # Create a directory called `build` - mkdir build - - # Go to the build directory - cd build - - # Execute CMake with the default options and a specific Visual Studio version - # and build architecture. For a list of available CMake generators, run - # `cmake .. -G` - cmake .. -G "Visual Studio 14 2015 Win64" - - # Open the generated Visual Studio solution - start OpenFAST.sln - -Visual Studio will open a solution containing all of the OpenFAST projects, and you -can then build any module library, module driver, or glue code. Note that any time -CMake is rerun, the Visual Studio solution will be regenerated causing the Visual Studio -GUI to lag momentarily while it reloads the data. - -CMake options -~~~~~~~~~~~~~ - -Below is a list of current CMake options including their default settings (which will effect, e.g., the targets in a resulting ``Makefile``. - -- ``BUILD_DOCUMENTATION`` - Build documentation (Default: OFF) -- ``BUILD_OPENFAST_CPP_API`` - Enable building OpenFAST - C++ API (Default: OFF) -- ``BUILD_SHARED_LIBS`` - Enable building shared libraries (Default: OFF) -- ``BUILD_TESTING`` - Build the testing tree (Default: OFF) -- ``CMAKE_BUILD_TYPE`` - Choose the build type: Debug Release (Default: Release) -- ``CMAKE_INSTALL_PREFIX`` - Install path prefix, prepended onto install directories. -- ``DOUBLE_PRECISION`` - Treat REAL as double precision (Default: ON) -- ``FPE_TRAP_ENABLED`` - Enable Floating Point Exception (FPE) trap in compiler options (Default: OFF) -- ``ORCA_DLL_LOAD`` - Enable OrcaFlex library load (Default: OFF) -- ``USE_DLL_INTERFACE`` - Enable runtime loading of dynamic libraries (Default: ON) - -CMake options can be configured through command line, e.g. - -.. code-block:: bash - - # to enable Makefile for local building of sphinx-based documentation - cmake .. -DBUILD_DOCUMENTATION:BOOL=ON - - # to compile OpenFAST in single precision - cmake .. -DDOUBLE_PRECISION:BOOL=OFF - - -Custom CMake builds -~~~~~~~~~~~~~~~~~~~ - -The CMake configuration and resulting build can be customized easily by explicitly setting CMake variables. In general, -this is done by passing a flag in the CMake configuration command - -.. code-block:: bash - - cmake .. -D=ON - cmake .. -D=\home\user\Desktop\this_thing - -This syntax is the same as in setting a CMake option and the result is used very similarly in the CMake configuration files. -Common customizations revolve around choosing a compiler or math library; for example - -.. code-block:: bash - - cmake .. -DCMAKE_Fortran_COMPILER=/usr/local/bin/gfortran-8 -DLAPACK_LIBRARIES=/System/Library/Frameworks/Accelerate.framework -DLAPACK_LIBRARIES=/System/Library/Frameworks/Accelerate.framework - -**NOTE** Many CMake configurations can also be set through an environment variable. -For example, when using Intel's MKL, the math libraries can be discovered automatically by setting the ``MKLROOT`` -environment variable. The Fortran compiler can also be set explicitly with the ``FC`` environment variable. - -Here is a good resource for useful CMake variables: `GitLab useful cmake variables `_. -The `CMake documentation `_ is also helpful for searching -through variables and determining the resulting action. diff --git a/docs/source/install/install_cygwin.rst b/docs/source/install/install_cygwin.rst new file mode 100644 index 000000000..a08d4f105 --- /dev/null +++ b/docs/source/install/install_cygwin.rst @@ -0,0 +1,81 @@ +.. _install_cygwin: + +Building OpenFAST on Windows with CMake and Cygwin 64-bit +========================================================= +WARNING: This build process takes a significantly long amount of time. +If GNU tools are not required, it is recommended that Windows users see one +of the following sections: + +- :ref:`download_binaries` +- :ref:`cmake_windows` +- :ref:`install_vs_windows`. + +Installing prerequisites +------------------------ + +1. Download and install `Cygwin 64-bit `__. + You will need to ``Run as Administrator`` to complete the installation + process. + + - Choose ``Install from internet`` + - Choose the default install location + - Choose the default package download location + - Choose ``Direct connection`` + - Choose a download site + - See next step for ``select packages``. Alternately, you can skip this + step and run ``setup-x86_64.exe`` anytime later to select and install + required software. + +2. Select packages necessary for compiling ``OpenFAST``. Choose ``binary`` + packages and not the source option. + + - Choose ``Category`` view, we will be installing packages from + ``Devel`` and ``Math`` + - From ``Devel`` mark the following packages for installation + + - ``cmake`` + - ``cmake-doc`` + - ``cmake-gui`` + - ``cygwin-devel`` + - ``gcc-core`` + - ``gcc-fortran`` + - ``gcc-g++`` + - ``git`` + - ``make`` + - ``makedepend`` + + - From ``Math`` mark the following packages for installation + + - ``liblapack-devel`` + - ``libopenblas`` + + - To run the test suite, install these optional packages from ``Python``: + + - ``python3`` + - ``Python3-numpy`` + + - Click ``Next`` and accept all additional packages that the setup + process requests to install to satisfy dependencies + +3. It is *recommended* that you reboot the machine after installing + ``Cygwin`` and all the necessary packages. + +Compiling OpenFAST +------------------ +From here, pick up from the Linux with CMake instructions at +:ref:`cmake_unix`. + +Other tips +---------- +- If you would like to run ``openfast.exe`` from the ``cmd`` terminal, then you + must add the ``C:\cygwin64\lib\lapack`` and + ``C:\cygwin64\home\\software\bin`` to your ``%PATH%`` variable in + environment setting. Replace ```` with your account name on Windows + system. + +- It is suggested to compile with optimization level 2 for Cygwin. Do this by + changing the build mode in the cmake command + + .. code-block:: bash + + cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo diff --git a/docs/source/install/install_spack.rst b/docs/source/install/install_spack.rst index 51ea8dbaa..bc5d3091f 100644 --- a/docs/source/install/install_spack.rst +++ b/docs/source/install/install_spack.rst @@ -3,27 +3,32 @@ Building OpenFAST with Spack ============================ -The process to build and install OpenFAST with `Spack `__ -on Linux or macOS is described here. +The process to build and install OpenFAST with +`Spack `__ on Linux or macOS is +described here. Dependencies ------------ - OpenFAST has the following dependencies: -- LAPACK libraries. Users should set ``BLAS_LIBRARIES`` and ``LAPACK_LIBRARIES`` appropriately for cmake if the library isn't found in standard paths. Use `BLASLIB` as an example when using Intel MKL. -- For the optional C++ API, `HDF5 `__ (provided by ``HDF5_ROOT``) and `yaml-cpp `__ (provided by ``YAML_ROOT``) +- LAPACK libraries. Users should set ``BLAS_LIBRARIES`` and + ``LAPACK_LIBRARIES`` appropriately for CMake if the library isn't found + in standard paths. Use `BLASLIB` as an example when using Intel MKL. +- For the optional C++ API, `HDF5 `__ + (provided by ``HDF5_ROOT``) and + `yaml-cpp `__ (provided by ``YAML_ROOT``) - For the optional testing framework, Python 3+ and Numpy Building OpenFAST Semi-Automatically Using Spack on macOS or Linux ---------------------------------------------------------------------- +------------------------------------------------------------------ The following describes how to build OpenFAST and its dependencies -mostly automatically on your Mac using `Spack `_. -This can also be used as a template to build OpenFAST on any -Linux system with Spack. +mostly automatically on macOS using +`Spack `_. This can also be used as a +template to build OpenFAST on any Linux system with Spack. -These instructions were developed on macOS 10.11 with the following tools installed via Homebrew: +These instructions were developed on macOS 10.11 with the following tools +installed via Homebrew: - GCC 6.3.0 - CMake 3.6.1 @@ -31,40 +36,39 @@ These instructions were developed on macOS 10.11 with the following tools instal Step 1 ~~~~~~ +Checkout the official Spack repo from github (we will checkout into +``${HOME}``): -Checkout the official Spack repo from github (we will checkout into ``${HOME}``): +.. code-block:: bash -``cd ${HOME} && git clone https://github.com/LLNL/spack.git`` + cd ${HOME} && git clone https://github.com/LLNL/spack.git Step 2 ~~~~~~ - Add Spack shell support to your ``.profile`` by adding the lines: -:: +.. code-block:: bash export SPACK_ROOT=${HOME}/spack . $SPACK_ROOT/share/spack/setup-env.sh Step 3 ~~~~~~ - Copy the https://raw.githubusercontent.com/OpenFAST/openfast/dev/share/spack/package.py file to your installation of Spack: -:: - +.. code-block:: bash + mkdir ${SPACK_ROOT}/var/spack/repos/builtin/packages/openfast cd ${SPACK_ROOT}/var/spack/repos/builtin/packages/openfast wget --no-check-certificate https://raw.githubusercontent.com/OpenFAST/openfast/dev/share/spack/package.py Step 4 ~~~~~~ - Try ``spack info openfast`` to see if Spack works. If it does, check the compilers you have available by: -:: +.. code-block:: bash machine:~ user$ spack compilers ==> Available compilers @@ -76,32 +80,32 @@ compilers you have available by: Step 5 ~~~~~~ - Install OpenFAST with your chosen version of GCC: -:: +.. code-block:: bash spack install openfast %gcc@6.3.0 To install OpenFAST with the C++ API, do: -:: +.. code-block:: bash spack install openfast+cxx %gcc@6.3.0 - -That should be it! Spack will automatically use the most up-to-date dependencies -unless otherwise specified. For example to constrain OpenFAST to use some specific -versions of dependencies you could issue the Spack install command: -:: +That should be it! Spack will automatically use the most up-to-date +dependencies unless otherwise specified. For example to constrain OpenFAST +to use some specific versions of dependencies you could issue the Spack +install command: - spack install openfast %gcc@6.3.0 ^hdf5@1.8.16 +.. code-block:: bash + + spack install openfast %gcc@6.3.0 ^hdf5@1.8.16 The executables and libraries will be located at -:: - +.. code-block:: bash + spack location -i openfast - -Add the appropriate paths to your ``PATH`` and ``LD_LIBRARY_PATH`` to run OpenFAST. +Add the appropriate paths to your ``PATH`` and ``LD_LIBRARY_PATH`` to run +OpenFAST. diff --git a/docs/source/install/install_vs_windows.rst b/docs/source/install/install_vs_windows.rst index 0c904bc94..a682d4d5e 100644 --- a/docs/source/install/install_vs_windows.rst +++ b/docs/source/install/install_vs_windows.rst @@ -4,8 +4,7 @@ Building OpenFAST on Windows with Visual Studio =============================================== These instructions are specifically for the standalone Visual Studio project at `openfast/vs-build`. -Separate CMake documentation is provided for Windows users at :numref:`install_cmake_windows` and -Cygwin users at :numref:`install_cmake_cygwin`. +Separate CMake documentation is provided for Windows users at :numref:`cmake_windows`. Prerequisites ------------------------ diff --git a/docs/source/testing/index.rst b/docs/source/testing/index.rst index 79c40b97d..ab1cfb87a 100644 --- a/docs/source/testing/index.rst +++ b/docs/source/testing/index.rst @@ -3,35 +3,35 @@ Testing OpenFAST ================ -The OpenFAST test suite consists of system and module level regression tests and -unit tests. The regression test compares locally generated solutions to a set of -baseline solutions. The unit tests ensure that individual subroutines are -functioning as intended. +The OpenFAST test suite consists of glue code and module level regression tests +and unit tests. The regression tests compare locally generated solutions to +a set of baseline solutions. The unit tests ensure that individual subroutines +are functioning as intended. -All of the necessary files corresponding to the regression test are contained in -the ``reg_tests`` directory. The unit test framework is housed in ``unit_tests`` -while the actual tests are contained in the directory corresponding to the tested -module. +All of the necessary files corresponding to the regression tests are contained +in the ``reg_tests`` directory. The unit test framework is housed in +``unit_tests`` while the actual tests are contained in the directory +corresponding to the tested module. Configuring the test suite -------------------------- -Portions of the test suite are linked to the OpenFAST repository through -``git submodule``. Specifically, +Portions of the test suite are linked to the OpenFAST repository through a +`git submodule`. Specifically, - `r-test `__ -- `pFUnit `__ +- `pFUnit `__ -Be sure to clone the repo with the ``--recursive`` flag or execute -``git submodule update --init --recursive`` after cloning. +.. tip:: -The test suite can be built with `CMake `__ similar to -OpenFAST. The default CMake configuration is useful, but may need customization -for particular build environments. See the installation documentation at :numref:`installation` -for more details on configuring the CMake targets. + Be sure to clone the repo with the ``--recursive`` flag or execute + ``git submodule update --init --recursive`` after cloning. -While the unit tests must be built with CMake due to its external dependencies, -the regression test may be executed without building with CMake. :numref:`unit_test` and :numref:`regression_test` -have more information on unit testing and regression testing, respectively. +The test suite can be configured with CMake similar to OpenFAST. The default +CMake configuration is suitable for most systems, but may need customization +for particular build environments. See the :ref:`understanding_cmake` section +for more details on configuring the CMake targets. While the unit tests must +be built with CMake due to its external dependencies, the regression test +may be executed without CMake. Test specific documentation --------------------------- @@ -40,20 +40,17 @@ Test specific documentation unit_test.rst regression_test.rst - regression_test_windows.rst -Continuous Integration +Continuous integration ---------------------- A TravisCI configuration file is included with the OpenFAST source code at ``openfast/.travis.yml``. -The continuous integration infrastructure is still under development, but the status for all branches -and pull requests can be found on the `TravisCI OpenFAST page `_. +The continuous integration infrastructure is still under development, but the +status for all branches and pull requests can be found on the +`TravisCI OpenFAST page `_. -Note that if you use the included TravisCI configuration, you will need to add your own Intel compiler -license serial number to your TravisCI project. Otherwise, simply remove the ``ifort`` line from the -environment list. - -For development and testing purposes, a version of the TravisCI test can be run locally with Docker. -Below is a guide which should be modified depending on the particular build being replicated +For development and testing purposes, a version of the TravisCI test can be run +locally with Docker. The code snippet below outlines starting a TravisCI image +on Docker. .. code-block:: bash @@ -78,8 +75,7 @@ Below is a guide which should be modified depending on the particular build bein git checkout -qf FETCH_HEAD git submodule update --init --recursive - export INTEL_SERIAL_NUMBER=VFGH-65656FTH - export FC=ifort + export FC=/usr/bin/gfortran-7 export DOUBLE_PRECISION=ON export TRAVIS_BUILD_INTEL=YES export TRAVIS_COMPILER=gcc @@ -87,9 +83,6 @@ Below is a guide which should be modified depending on the particular build bein gcc --version pyenv shell 3.6.3 - wget 'https://raw.githubusercontent.com/nemequ/icc-travis/master/install-icc.sh' # installs from http://registrationcenter-download.intel.com/akdlm/irc_nas/9061/parallel_studio_xe_2016_update3_online.sh - chmod 755 install-icc.sh - ./install-icc.sh --components ifort,icc,mkl source ~/.bashrc pip3 install numpy mkdir build && cd build diff --git a/docs/source/testing/regression_test.rst b/docs/source/testing/regression_test.rst index f856c26c7..57aab2c19 100644 --- a/docs/source/testing/regression_test.rst +++ b/docs/source/testing/regression_test.rst @@ -2,222 +2,393 @@ Regression test =============== +The regression test executes a series of test cases which intend to fully +describe OpenFAST and its module's capabilities. Jump to one of the following +sections for instructions on running the regression +tests: + +- :ref:`python_driver` +- :ref:`ctest_driver` +- :ref:`regression_test_example` +- :ref:`regression_test_windows` -The regression test executes a series of test cases which intend to fully describe -OpenFAST and its module's capabilities. - -Jump to :ref:`regression_test_ctest`, :ref:`regression_test_example`, or :ref:`regression_test_windows` -for instructions on running the regression tests locally. - -Each locally computed result is compared -to a static set of baseline results. To account for system, hardware, and compiler +Each locally computed result is compared to a static set of baseline +results. To account for system, hardware, and compiler differences, the regression test attempts to match the current machine and compiler type to the appropriate solution set from these combinations: -- macOS with GNU compiler (default) -- Red Hat Enterprise Linux with Intel compiler -- Windows with Intel compiler +================== ========== ============================ + Operating System Compiler Hardware +================== ========== ============================ + **macOS** **GNU** **2017 MacbookPro** + CentOS 7 Intel NREL Eagle - Intel Skylake + CentOS 7 GNU NREL Eagle - Intel Skylake + Windows 10 Intel Dell Precision 3530 +================== ========== ============================ + +The compiler versions, specific math libraries, and more info on hardware used +to generate the baseline solutions are documented in the +`r-test repository documentation `__. Currently, +the regression test supports only double precision builds. + +The regression test system can be executed with CMake (through its included +test driver, CTest) or manually with +a custom Python driver. Both systems provide similar functionality with +respect to testing, but CTest integration provides access to multithreading, +automation, and test reporting via CDash. Both modes of execution require some +configuration as described in the following sections. + +In both modes of execution a directory is created in the build directory +called ``reg_tests`` where all of the input files for the test cases are copied +and all of the locally generated outputs are stored. Ultimately, both CTest and +the manual execution program call a series of Python scripts and libraries in +``reg_tests`` and ``reg_tests/lib``. One such script is ``lib/pass_fail.py`` +which reads the output files and computes a norm on each channel reported. If +the maximum norm is greater than the given tolerance, that particular test is +reported as failed. The failure criteria is outlined below. + +.. code-block:: python + + difference = abs(testData - baselineData) + for i in nChannels: + if channelRange < 1: + norm[i] = MaxNorm( difference[:,i] ) + else: + norm[i] = MaxNorm( difference[:,i] ) / channelRange + + if max(norm) < tolerance: + pass = True + else: + pass = False -The compiler versions, specific math libraries, and hardware used to generate these baseline -solutions are documented in the -`r-test repository documentation `__. Currently, -the regression test supports only double precision solutions, so it is required -to build OpenFAST in double precision for testing. All baseline solutions are generated -with a double precision build. +Dependencies +------------ +The following packages are required for regression testing: -The regression test system can be executed with CMake and CTest or manually with -an included Python driver. Both systems provide similar functionality with respect -to testing, but CTest integration provides access to multithreading, automation, -and test reporting via CDash. Both modes of execution require some configuration -as outlined below. +- Python 3+ +- Numpy +- CMake and CTest (Optional) +- matplotlib (Optional) -In both modes of execution a subdirectory is created in the build directory -called ``reg_tests`` where all of the input files for the test cases are copied -and all of the locally generated outputs are stored. +.. _python_driver: -Ultimately, both CTest and the manual execution program call a series of Python -scripts and libraries in ``reg_tests`` and ``reg_tests/lib``. One such script is -``lib/pass_fail.py`` which reads the output files and computes a norm on each -channel reported. If the maximum norm is greater than a preset tolerance, that particular -test is reported as failed. The failure criteria is outlined in pseudocode below. +Executing with Python driver +---------------------------- +The regression test can be executed manually with the included driver at +``openfast/reg_tests/manualRegressionTest.py``. This program reads a case list +file at ``openfast/reg_tests/r-test/glue-codes/openfast/CaseList.md``. Cases +can be removed or ignored by starting that line with a ``#``. The driver +program includes multiple optional flags which can be obtained by +executing with the help option: :: - difference = abs(testData-baselineData) - for i in nChannels - if channelRange < 1 { - norm[i] = MaxNorm( difference[:,i] ) - } else { - norm[i] = MaxNorm( difference[:,i] ) / channelRange - } + >>>$ python manualRegressionTest.py -h + usage: manualRegressionTest.py [-h] [-p [Plotting-Flag]] [-n [No-Execution]] + [-v [Verbose-Flag]] [-case [Case-Name]] + OpenFAST System-Name Compiler-Id Test-Tolerance + + Executes OpenFAST and a regression test for a single test case. + + positional arguments: + OpenFAST path to the OpenFAST executable + System-Name current system's name: [Darwin,Linux,Windows] + Compiler-Id compiler's id: [Intel,GNU] + Test-Tolerance tolerance defining pass or failure in the regression + test + + optional arguments: + -h, --help show this help message and exit + -p [Plotting-Flag], -plot [Plotting-Flag] + bool to include matplotlib plots in failed cases + -n [No-Execution], -no-exec [No-Execution] + bool to prevent execution of the test cases + -v [Verbose-Flag], -verbose [Verbose-Flag] + bool to include verbose system output + -case [Case-Name] single case name to execute + +.. note:: + + For the NREL 5MW turbine test cases, an external ServoDyn controller must + be compiled and included in the appropriate directory or all NREL 5MW + cases will fail without starting. More information is available in the + documentation for the `r-test repository `__, + but be aware that these three DISCON controllers must exist + + .. code-block:: bash + + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON.dll + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_ITIBarge.dll + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_OC3Hywind.dll + +.. _ctest_driver: + +Executing with CTest +-------------------- +CTest is included with CMake and is primarily a set of preconfigured targets +and commands. To use the CTest driver for the regression test, execute CMake as +described in :ref:`installation`, but with this additional flag: +``-DBUILD_TESTING=ON``. - if max(norm) < tolerance: - success +The regression test specific CMake variables are -Dependencies ------------- - - Python 3+ - - Numpy - - CMake and CTest (Optional) - - matplotlib (Optional) +:: -Manual driver configuration ---------------------------- + BUILD_TESTING + CTEST_OPENFAST_EXECUTABLE + CTEST_[MODULE]_EXECUTABLE where [MODULE] is the module name + CTEST_PLOT_ERRORS + CTEST_REGRESSION_TOL -The regression test can be executed manually with the included driver -``openfast/reg_tests/manualRegressionTest.py``. This program reads a case list file at -``openfast/reg_tests/r-test/glue-codes/openfast/CaseList.md``. Cases can be removed -or ignored with a ``#``. This driver program includes multiple optional flags -which can be obtained by executing with the help option: -``openfast/reg_tests/manualRegressionTest.py -h`` +Some additional resources that are required for the full regression test suite +are included in the CMake project. Specifically, external ServoDyn controllers +must be compiled for a given system and placed in a particular location. Thus, +be sure to execute the build command with the ``install`` target: -For the NREL 5MW turbine test cases, an external ServoDyn controller must be compiled and -included in the appropriate directory or all NREL 5MW cases will fail without starting. -More information is available in the documentation for the -`r-test repository `__. +.. code-block:: bash -CTest configuration -------------------- + # Configure CMake with testing enabled and accept the default + # values for all other test-specific CMake variables + cmake .. -DBUILD_TESTING=ON -CTest is included with CMake and is mostly a set of preconfigured targets and -commands. To use the CTest driver for the regression test, CMake must be run with -one of two ``CMakeLists.txt``'s: + # Build and install + make install -- openfast/CMakeList.txt -- openfast/reg_tests/CMakeLists.txt +.. note:: -CMake variables can be configured in the `CMake -GUI `__ or through the command line interface with -``ccmake``. + REMINDER: For the NREL 5MW turbine test cases, an external ServoDyn controller must + be compiled and included in the appropriate directory or all NREL 5MW + cases will fail without starting. More information is available in the + documentation for the `r-test repository `__, + but be aware that these three DISCON controllers must exist -The regression test specific CMake variables are + .. code-block:: bash -- BUILD_TESTING -- CTEST_OPENFAST_EXECUTABLE -- CTEST_[MODULE]_EXECUTABLE -- CTEST_PLOT_ERRORS -- CTEST_REGRESSION_TOL + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON.dll + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_ITIBarge.dll + openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_OC3Hywind.dll -**IT IS IMPORTANT** to verify that NREL 5MW turbine external controllers are compiled -and placed in the correct location. More information is available in the documentation for the -`r-test repository `__, -but be aware that these three DISCON controllers must exist +After CMake configuration and compiling, the automated regression test can be +executed by running either of the commands ``make test`` or ``ctest`` from the +``build`` directory. If the entire OpenFAST package is to be built, CMake will +configure CTest to find the new binary at +``openfast/build/glue-codes/openfast/openfast``. However, if the intention is +to build only the test suite, the OpenFAST binary should be specified in the +CMake configuration under the ``CTEST_OPENFAST_EXECUTABLE`` flag. There is +also a corresponding ``CTEST_[MODULE]_NAME`` flag for each module included in +the regression test. + +When driven by CTest, the regression test can be executed by running various +forms of the command ``ctest`` from the build directory. The basic commands +are: .. code-block:: bash - openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON.dll - openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_ITIBarge.dll - openfast/build/reg_tests/glue-codes/openfast/5MW_Baseline/ServoData/DISCON_OC3Hywind.dll - -This can be accomplished manually with the CMake projects included with the DISCON source codes -at ``openfast/reg_tests/r-test/glue-codes/openfast/5MW_Baseline/ServoData/`` -or during CMake configuration by setting the ``CMAKE_INSTALL_PREFIX`` CMake variable. -If using this method, the install prefix variable should point to an existing and appropriate -location for CMake to place the compiled binaries. This is important because the NREL 5MW turbine external -controller CMake projects are preconfigured to install themselves in the appropriate -location in the build directory. Then, it is important to execute ``make install`` -rather than simply ``make``. If ``CMAKE_INSTALL_PREFIX`` is not appropriately configured, -the install step may fail or openfast binaries may be placed in some inappropriate default location. - -After CMake configuration, the automated regression test can be executed -by running either of the commands ``make test`` or ``ctest`` from the build -directory. If the entire OpenFAST package is to be built, CMake will configure -CTest to find the new binary at ``openfast/build/glue-codes/openfast/openfast``. -However, if the intention is to build only the test suite, the OpenFAST binary -should be specified in the CMake configuration under the ``CTEST_OPENFAST_EXECUTABLE`` -flag. There is also a corresponding ``CTEST_[MODULE]_NAME`` flag for each module -included in the regression test. - -.. _regression_test_ctest: - -Running the regression test with CTest --------------------------------------- + # Run the entire regression test + ctest -When driven by CTest, the regression test can be executed by running various -forms of the command ``ctest`` from the build directory. The basic commands are + # Disable actual execution of tests; + # this is helpful in formulating a particular ctest command + ctest -N + + # Run the entire regression test with verbose output + ctest -V -- ``ctest`` - Run the entire regression test -- ``ctest -N`` - Disable actual execution of tests; this is helpful in formulating a particular ctest command -- ``ctest -V`` - Run the entire regression test with verbose output -- ``ctest -R [TestName]`` - Run a test by name where TestName is a regex to search -- ``ctest -j [N]`` - Run all tests with N tests executing in parallel + # Run tests by name where TestName is a regular expression (regex) + ctest -R [TestName] + + # Run all tests with N tests executing in parallel + ctest -j [N] Each regression test case contains a series of labels associating all of the modules used. The labeling can be seen in the test instantiation in -``reg_tests/CTestList.cmake`` or with the command +``reg_tests/CTestList.cmake`` or with the command: + +.. code-block:: bash + + # Print all available test labels + ctest --print-labels + +The test cases corresponding to a particular label can be executed with this +command: + +.. code-block:: bash + + # Filter the test cases corresponding to a particular label + ctest -L [Label] -- ``ctest --print-labels`` - Print all available test labels +Flags can be compounded making useful variations such as -Labels can be called directly with +.. code-block:: bash + + # Run all cases that use AeroDyn14 with verbose output + ctest -V -L aerodyn14 + + # Run all cases that use AeroDyn14 in 16 concurrent processes + ctest -j 16 -L aerodyn14 + + # Run the case with name "5MW_DLL_Potential_WTurb" with verbose output + ctest -V -R 5MW_DLL_Potential_WTurb -- ``ctest -L [Label]`` + # List all tests with the "beamdyn" label + ctest -N -L beamdyn -These flags can be compounded making useful variations of ``ctest`` such as + # List the labels included in all tests matching the regex "bd" + ctest -N -R bd --print-labels -- ``ctest -V -L aerodyn14`` - Runs all cases that use AeroDyn14 with verbose output -- ``ctest -j 16 -L aerodyn14`` - Runs all cases that use AeroDyn14 in 16 concurrent processes -- ``ctest -V -R 5MW_DLL_Potential_WTurb`` - Runs the case with name "5MW_DLL_Potential_WTurb" -- ``ctest -N -L beamdyn`` - Lists all tests with the "beamdyn" label -- ``ctest -N -R bd --print-labels`` - Lists the labels included in all tests matching the regex "bd" -The automated regression test writes new files only into the build directory. Specifically, -all locally generated solutions are located in the corresponding glue-code or module within -``openfast/build/reg_tests``. The baseline solutions contained in ``openfast/reg_tests/r-test`` -are strictly read not modified by the automated process. +The automated regression test writes new files only into the build directory. +Specifically, all locally generated solutions are located in the corresponding +glue-code or module within ``openfast/build/reg_tests``. The baseline solutions +contained in ``openfast/reg_tests/r-test`` are strictly read and are not +modified by the automated process. .. _regression_test_example: -Regression test example ------------------------ +Regression test examples +------------------------ +The following examples illustrate methods of running the regression tests +on Unix-based systems. However, similar procedures can be used +on Windows with CMake and CTest. An alternate method of running the +regression tests on Windows is given in :ref:`reg_test_windows`. -- Build OpenFAST and the test suite +Compile OpenFAST and execute with CTest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following example assumes the user is starting completely from scratch. +The commands below download the source code, configure the OpenFAST project +with CMake, compile all executables, and execute the full regression test +suite. .. code-block:: bash - git clone --recursive https://github.com/openfast/openfast.git - # The default git branch is 'master'. If necessary, switch to your target branch: - # git checkout dev - mkdir build install && cd build - # Configure CMake with openfast/CMakeLists.txt - # - BUILD_TESTING - # - CTEST_OPENFAST_EXECUTABLE - # - CTEST_[MODULE]_EXECUTABLE - cmake .. -DBUILD_TESTING=ON - make install - ctest + # Download the source code from GitHub + # Note: The default branch is 'master' + git clone --recursive https://github.com/openfast/openfast.git + cd openfast -- Build only the test suite if an openfast binary already exists + # If necessary, switch to another target branch and update r-test + git checkout dev + git submodule update -.. code-block:: bash + # Create the build and install directories and move into build + mkdir build install && cd build - git clone --recursive https://github.com/openfast/openfast.git - # The default git branch is 'master'. If necessary, switch to your target branch: - # git checkout dev - mkdir build install && cd build - # Configure CMake with openfast/reg_tests/CMakeLists.txt - # - BUILD_TESTING - # - CTEST_OPENFAST_EXECUTABLE - # - CTEST_[MODULE]_EXECUTABLE - cmake ../reg_tests - make install - ctest + # Configure CMake for testing + # - BUILD_TESTING - turn ON + # - CTEST_OPENFAST_EXECUTABLE - accept the default + # - CTEST_[MODULE]_EXECUTABLE - accept the default + cmake .. -DBUILD_TESTING=ON -- :ref:`regression_test_windows` + # Compile and install + make install -Follow the link above for a detailed procedure. It is summarized below though -excluding the procedure to build OpenFAST itself. + # Execute the full test suite with 4 concurrent processes + ctest -j4 + +Configure with CMake and a given executable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This example assumes the user has a fully functional OpenFAST executable +available along with any necessary libraries, but does not have the source +code repository downloaded. This might be the case when executables are +distributed within an organization or downloaded from an +`OpenFAST Release `__. +Here, nothing will be compiled, but the test suite will be configured +with CMake for use with the CTest command. .. code-block:: bash - git clone --recursive https://github.com/openfast/openfast.git - cd openfast + # Download the source code from GitHub + # Note: The default branch is 'master' + git clone --recursive https://github.com/openfast/openfast.git + cd openfast + + # If necessary, switch to another target branch and update r-test + git checkout dev + git submodule update + + # Create the build directory and move into it + mkdir build && cd build + + # Configure CMake with openfast/reg_tests/CMakeLists.txt for testing + # - BUILD_TESTING - turn ON + # - CTEST_OPENFAST_EXECUTABLE - provide a path + # - CTEST_[MODULE]_EXECUTABLE - provide a path + cmake ../reg_tests \ + -DBUILD_TESTING=ON \ + -DCTEST_OPENFAST_EXECUTABLE=/home/user/Desktop/openfast_executable \ + -DCTEST_BEAMDYN_EXECUTABLE=/home/user/Desktop/beamdyn_driver + + # Install required files + make install + + # Execute the full test suite with 4 concurrent processes + ctest -j4 + +.. _example_python_driver: + +Python driver with a given executable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This example assumes the user has a fully functional OpenFAST executable +available along with any necessary libraries, but does not have the source +code repository downloaded. This might be the case when executables are +distributed within an organization or downloaded from an +`OpenFAST Release `__. +Nothing will be compiled, but the test suite will be executed with the +included Python driver. - ## Build the ServoDyn external controller libraries - # Open the Visual Studio Solution (DISCON.sln) located in 'openfast\vs-build\DISCON' - # Choose Release and x64 for the Solutions Configuration and Solutions Platform - # Build Solution +.. code-block:: bash - ## Execute the OpenFAST regression Tests - # Open a command prompt which is configured for Python (like Anaconda) - cd openfast\reg_tests - python manualRegressionTest.py ..\build\bin\openfast_x64.exe Windows Intel 1e-5 + # Download the source code from GitHub + # Note: The default branch is 'master' + git clone --recursive https://github.com/openfast/openfast.git + cd openfast + + # If necessary, switch to another target branch and update r-test + git checkout dev + git submodule update + + # Execute the Python driver + cd reg_tests + python manualRegressionTest.py -h + # usage: manualRegressionTest.py [-h] [-p [Plotting-Flag]] [-n [No-Execution]] + # [-v [Verbose-Flag]] [-case [Case-Name]] + # OpenFAST System-Name Compiler-Id Test-Tolerance + # + # Executes OpenFAST and a regression test for a single test case. + # + # positional arguments: + # OpenFAST path to the OpenFAST executable + # System-Name current system's name: [Darwin,Linux,Windows] + # Compiler-Id compiler's id: [Intel,GNU] + # Test-Tolerance tolerance defining pass or failure in the regression + # test + # + # optional arguments: + # -h, --help show this help message and exit + # -p [Plotting-Flag], -plot [Plotting-Flag] + # bool to include matplotlib plots in failed cases + # -n [No-Execution], -no-exec [No-Execution] + # bool to prevent execution of the test cases + # -v [Verbose-Flag], -verbose [Verbose-Flag] + # bool to include verbose system output + # -case [Case-Name] single case name to execute + + python manualRegressionTest.py \ + ..\build\bin\openfast_x64_Double.exe \ + Windows \ + Intel \ + 1e-5 + +.. _reg_test_windows: + +Detailed example of running on Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :ref:`example_python_driver` example can be used for running the +regression tests on a Windows computer. However, a more detailed, step-by-step +description is given in :ref:`regression_test_windows`. + +.. toctree:: + :maxdepth: 1 + :hidden: + + regression_test_windows.rst diff --git a/docs/source/testing/unit_test.rst b/docs/source/testing/unit_test.rst index 2308a2c33..1ccfafcd3 100644 --- a/docs/source/testing/unit_test.rst +++ b/docs/source/testing/unit_test.rst @@ -2,120 +2,119 @@ Unit test ========= - -In a software package as dynamic and collaborative as OpenFAST, confidence in multiple -layers of code is best accomplished with a strong system of unit tests. -Through robust testing practices, the entire OpenFAST community can +In a software package as dynamic and collaborative as OpenFAST, confidence in +multiple layers of code is best accomplished with a strong system of unit +tests. Through robust testing practices, the entire OpenFAST community can understand the intention behind code blocks and debug or expand functionality quicker and with more confidence and stability. -Unit testing in OpenFAST modules is accomplished through `pFUnit `__. -This framework provides a Fortran abstraction to the popular `xUnit `__ -structure. pFUnit is compiled along with OpenFAST through CMake when -the CMake variable ``BUILD_TESTING`` is turned on. +Unit testing in OpenFAST modules is accomplished through `pFUnit `__. +This framework provides a Fortran abstraction to the popular +`xUnit `__ structure. pFUnit is compiled +along with OpenFAST through CMake when the CMake variable ``BUILD_TESTING`` is +turned on. -The BeamDyn module has been unit tested and should serve as a reference for future -development and testing. +The BeamDyn module has been unit tested and should serve as a reference for +future development and testing. Dependencies ------------ - - Python 3+ - - CMake and CTest - - Numpy and matplotlib (Optional) - - pFUnit (Included in unit test suite) +The following packages are required for unit testing: -Compiling the unit tests ------------------------- +- Python 3+ +- CMake +- pFUnit - Included in OpenFAST repo through a git-submodule -Compiling the unit tests is handled with CMake similar to compiling OpenFAST in general. -After configuring CMake with ``BUILD_TESTING`` on, new make targets are created for each -module included in the unit test framework named ``[module]_utest``. Then, simply make the target to test +Compiling +--------- +Compiling the unit tests is handled with CMake similar to compiling OpenFAST +in general. After configuring CMake with ``BUILD_TESTING`` turned on, new +build targets are created for each module included in the unit test +framework named ``[module]_utest``. Then, ``make`` the target to test: -:: - - cmake .. -DBUILD_TESTING=ON - make beamdyn_utest - -This creates a binary unit test executable at -``openfast/build/unit_tests/[module]_utest``. - - -Executing the unit tests ------------------------- - -To execute a module's unit test, simply run the unit test binary. For example, -:: - - >>>$ ./openfast/build/unit_tests/beamdyn_utest - ............. - Time: 0.018 seconds - - OK - (13 tests) +.. code-block:: bash + + cmake .. -DBUILD_TESTING=ON + make beamdyn_utest + +This creates a unit test executable at +``openfast/build/unit_tests/beamdyn_utest``. + +Executing +--------- +To execute a module's unit test, simply run the unit test binary. For example: + +.. code-block:: bash + + >>>$ ./openfast/build/unit_tests/beamdyn_utest + ............. + Time: 0.018 seconds + + OK + (14 tests) pFUnit will display a ``.`` for each unit test successfully completed -and a ``F`` for each failing test. If any tests do fail, the failure -criteria will be displayed listing which particular value caused -the failure. Failure cases display the following output +and a ``F`` for each failing test. If any tests do fail, the failure +criteria will be displayed listing which particular value caused +the failure. Failure cases display the following output: + +.. code-block:: bash + + >>>$ ./unit_tests/beamdyn_utest + .....F....... + Time: 0.008 seconds + + Failure + in: + test_BD_CrvMatrixH_suite.test_BD_CrvMatrixH + Location: + [test_BD_CrvMatrixH.F90:48] + simple rotation with known parameters: Pi on xaxis expected +0.5000000 but found: +0.4554637; difference: |+0.4453627E-01| > tolerance:+0.1000000E-13; first difference at element [1, 1]. + + FAILURES!!! + Tests run: 13, Failures: 1, Errors: 0 + Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG IEEE_DIVIDE_BY_ZERO + ERROR STOP *** Encountered 1 or more failures/errors during testing. *** + + Error termination. Backtrace: + #0 0x1073b958c + #1 0x1073ba295 + #2 0x1073bb1b6 + #3 0x106ecdd4f + #4 0x1063fabee + #5 0x10706691e -:: - - >>>$ ./unit_tests/beamdyn_utest - .....F....... - Time: 0.008 seconds - - Failure - in: - test_BD_CrvMatrixH_suite.test_BD_CrvMatrixH - Location: - [test_BD_CrvMatrixH.F90:48] - simple rotation with known parameters: Pi on xaxis expected +0.5000000 but found: +0.4554637; difference: |+0.4453627E-01| > tolerance:+0.1000000E-13; first difference at element [1, 1]. - - FAILURES!!! - Tests run: 13, Failures: 1, Errors: 0 - Note: The following floating-point exceptions are signalling: IEEE_INVALID_FLAG IEEE_DIVIDE_BY_ZERO - ERROR STOP *** Encountered 1 or more failures/errors during testing. *** - - Error termination. Backtrace: - #0 0x1073b958c - #1 0x1073ba295 - #2 0x1073bb1b6 - #3 0x106ecdd4f - #4 0x1063fabee - #5 0x10706691e - - Adding unit tests ----------------- - -Unit tests should be included for each new, *testable* code block (subroutine or function). -What is testable is the discretion of the developer, but a portion -of the pull request review process will be evaluating test coverage. +Unit tests should be included for each new, *testable* code block (subroutine +or function). What is testable is the discretion of the developer, but an +element of the pull request review process will be evaluating test coverage. New unit tests can be added to a ``tests`` directory alongside the ``src`` directory included in each module. For example, the BeamDyn module directory is structured as :: - + openfast/ - |-- modules/ - |-- beamdyn/ - |-- src/ - |-- BeamDyn.f90 - `-- BeamDyn_Subs.f90 - `-- tests/ - |-- test_BD_Subroutine1.F90 - |-- test_BD_Subroutine2.F90 - `-- test_BD_Subroutine3.F90 - -Each unit test must be contained in a unique file called ``test_[SUBROUTINE].F90`` where -``[SUBROUTINE]`` is the code block being tested. Finally, update the CMake configuration -for building a module's unit test executable with the appropriate list of test subroutines -in ``openfast/unit_tests/CMakeLists.txt`` using the following format + └── modules/ + └── beamdyn/ + ├── src/ + │ ├── BeamDyn.f90 + │ └── BeamDyn_Subs.f90 + └── tests/ + ├── test_BD_Subroutine1.F90 + ├── test_BD_Subroutine2.F90 + └── test_BD_Subroutine3.F90 + +Each unit test must be contained in a unique file called +``test_[SUBROUTINE].F90`` where ``[SUBROUTINE]`` is the code block being +tested. Finally, update the CMake configuration for building a module's unit +test executable with the appropriate list of test subroutines +in ``openfast/unit_tests/CMakeLists.txt`` using the following format: + +.. code-block:: cmake -:: - set(testlist test_SUBROUTINE1 test_SUBROUTINE2 @@ -123,11 +122,11 @@ in ``openfast/unit_tests/CMakeLists.txt`` using the following format ) # it is important to keep the quotes around "${testlist}" in the call below build_utest("module_name" "${testlist}") - -For reference, a template unit test file is included at ``openfast/unit_tests/test_SUBROUTINE.F90``. -Each unit test should fully test the target code block. If full test coverage -is not easily achievable, it may be an indication that refactoring would be beneficial. +For reference, a template unit test file is included at +``openfast/unit_tests/test_SUBROUTINE.F90``. Each unit test should fully test +the target code block. If full test coverage is not easily achievable, it may +be an indication that refactoring would be beneficial. Some useful topics to consider when developing and testing for OpenFAST are: diff --git a/docs/source/this_doc.rst b/docs/source/this_doc.rst index a08d8d369..24ff4bf36 100644 --- a/docs/source/this_doc.rst +++ b/docs/source/this_doc.rst @@ -4,27 +4,33 @@ This documentation ================== OpenFAST documentation is hosted on -`readthedocs `_, and is automatically +`readthedocs `_, and is automatically generated from both the `master `_ and `dev `_ branches whenever -new commits are added. A PDF of the documentation can be retrieved from -`readthedocs `_ by clicking the arrow on the -lower left corner of the page next to ``v:master`` or ``v:dev``. +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), +and link to other relevant websites. + +.. image:: ../_static/docs_options.png + :width: 30% + :align: center While OpenFAST developer documentation is being enhanced here, developers are encouraged to consult the legacy FAST v8 `Programmer's Handbook `_. +Instructions on obtaining and installing OpenFAST are available in +:ref:`installation`, and documentation for verifying an installation with the +automated tests is at :ref:`testing`. -This documentation is divided into two parts: +The majority of this documentation is divided into two parts: :ref:`user_guide` Directed towards end-users, this part provides detailed documentation - regarding installation and usage of the OpenFAST and its underlying modules, - as well as theory and verification documentation. Also included are - instructions for using the automated test suite, which serves as a suite of - examples. + regarding usage of the OpenFAST and its underlying modules, + as well as theory and verification documentation. :ref:`dev_guide` diff --git a/docs/source/user/fast_to_openfast.rst b/docs/source/user/fast_to_openfast.rst index fb49d20d8..9f84b18b3 100644 --- a/docs/source/user/fast_to_openfast.rst +++ b/docs/source/user/fast_to_openfast.rst @@ -48,7 +48,7 @@ OpenFAST includes the following organizational changes relative to FAST v8.16: * An online documentation system has been established to replace existing documentation of FAST v8: http://openfast.readthedocs.io/; during the transition to OpenFAST, most user-related documentation is still provided through the NWTC Information Portal, https://nwtc.nrel.gov -* Cross platform compiling is accomplished with CMake on Mac, Linux, and Cygwin (Windows) systems +* Cross platform compiling is accomplished with CMake on macOS, Linux, and Cygwin (Windows) systems * Visual Studio Projects (VS-Build) are provided for compiling OpenFAST on Windows (starting from OpenFAST v1.0.0), but the development team is working to automate the generation of Visual Studio build files via CMake in a future release @@ -73,7 +73,7 @@ Algorithmically, OpenFAST v0.1.0 is the release most closely related to FAST v8. * The OpenFAST glue codes, modules, module drivers, and compiling tools are contained within a single repository: https://github.com/openfast/openfast - * Cross platform compiling is accomplished with CMake on Mac, Linux, and Cygwin (Windows) systems + * Cross platform compiling is accomplished with CMake on macOS, Linux, and Cygwin (Windows) systems * An online documentation system has been established to replace existing documentation of FAST v8: http://openfast.readthedocs.io/ @@ -123,7 +123,7 @@ v1.0.0 (September 2017) * The online documentation (http://openfast.readthedocs.io/en/latest/index.html) has been extensively updated with additions for installation, testing, user (AeroDyn BeamDyn, transition from FAST v8, release notes), and developer guides, etc - * The scripts for compiling OpenFAST using CMake on Mac, Linux, and Cygwin (Windows) systems have been updated, including the ability to compile in single precision and building with Spack + * The scripts for compiling OpenFAST using CMake on macOS, Linux, and Cygwin (Windows) systems have been updated, including the ability to compile in single precision and building with Spack * Visual Studio Projects (VS-Build) are provided for compiling OpenFAST on Windows