5. Developer Documentation
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 to work with the NREL OpenFAST team on code development.
If you’d like to help with general OpenFAST development or work on a particular feature, then first install OpenFAST following the installation instructions for your machine. Next, verify that your installation is valid by running the test suite following the testing instructions. While OpenFAST is compiling, we encourage reading through the Development Philosophy and Guidelines section to understand the general workflow for individual and coordinated development. Finally, be sure to review the GitHub workflow to avoid any merge or code conflicts.
With development happening in parallel between NREL, industry partners, and universities, NREL relies on GitHub to coordinate efforts:
GitHub Issues is the place to ask usage or development questions, report bugs, and suggest code enhancements
GitHub Pull Requests is the place for engaging with the OpenFAST team to have your new code merged into the main repository.
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:
5.1. Development Philosophy and Guidelines
OpenFAST is intended to be a self-sustaining, community developed software. While the NREL OpenFAST team serves as the gatekeeper of the repository, we actively encourage the community to share new ideas and contribute code. Considerations for contributing code are outlined here.
5.1.1. Engagement with NREL
The process for community code contribution starts with engaging directly with the NREL OpenFAST team to define the scope of the work and coordinate development efforts. This is particularly important since many groups work on OpenFAST simultaneously. By engaging early, all developers can stay up to date and minimize conflicts during the code merge. The prefered method of communication is GitHub Issues. An initial post should contain all relevant information about the planned development work, the areas of the software that will be impacted, and any model validation materials. See Development Plan / Implementation Plan for more information on describing the planned work.
The NREL OpenFAST team is always working on internal projects that require the majority of our attention, but we will make every effort to engage with the community and support development efforts in a reasonable time frame. After posting an Issue, the NREL OpenFAST team may reach out to schedule a meeting to talk through the details.
5.1.2. Development Plan / Implementation Plan
Significant code development efforts at NREL begin with the development of a detailed implementation plan, and a few such plans are available to download for reference:
Development Plan for the Aerodynamic Linearization of OpenFASTImplementation Plan - 2nd-order Wave Kinematics Within HydroDyn
A good plan within the modularization framework of OpenFAST will
follow the definitions and nomenclature used by the
NWTC Programmer's Handbook.
It should communication the following information:
State whether the module is intended for loose coupling, tight coupling for time marching, and/or linearization.
Define the module’s inputs (including initialization), outputs (including initialization), states (continous, discrete, and constraint), and parameters, including units.
Lay out an example input file for the module.
Explain the module’s mathemetical formulation, including Jacobians (for tight coupling and linearization), in the form required of the framework.
Prescribe how the module’s inputs are derived from the outputs of other specific modules
Identify any potential numerical problems and how to avoid them in the code.
Lay out the module’s subroutines using pseudocode (as opposed to actual code), including identifying which mathematical formulas are used by which subroutines, and describing the algorithms used in the solution process.
This information is very helpful since it is easier to review, iterate, and agree on a plan before making changes to source code. Additionally, an implementation plan will greatly aid in the programming effort and is a useful starting point for writing the user and develop documentation.
5.1.3. Qualities of a good submission
Development efforts should include adequate testing throughout the development process. When possible, new subroutines should include unit-level tests, and the existing regression tests should be run periodically to ensure that the full system behavior has not changed unintentionally. For new features, additional regression tests should be added to cover the new code. If the regression test results change in an expected manner, the baseline results should be updated locally and in the openfast/r-test repository. The r-test README describes updating the baselines and the Testing OpenFAST section in this documentation contains additional details on testing.
New code should consider robustness from both the developer and user perspectives. Here are some questions to consider during code development:
Is it clear to other developers how to use your subroutine?
Does your new code exhibit clear and predictable behavior?
How will your code perform under different qualities of data?
How does your code impact the performance of the simulation?
Additionally, user and developer documentation should be included with new code. User documentation includes theory, modeling guidance, and a description of any inputs and outputs. User documentation should be included as part of the online documentation described in Developing Documentation. Developer documentation is typically included in comments in the source code. This should describe subroutine API’s (inputs and outputs) as well as any algorithms or lines of code that are unclear. Ask yourself what you would need to know to fully understand your code if you don’t see it again for two years.
5.1.4. Submit for review and NREL feedback
New code can be submitted for review from the NREL OpenFAST team by opening a pull request as described in Working with OpenFAST on GitHub. We will review the code for accuracy, validity, quality, and robustness. Reviewing open source code contributions can be difficult, so it is worthwhile to review your own code and consider what information would help you to determine whether it is ready to merge.
The review process begins with simply ensuring that the automated tests pass in GitHub Actions. Please ensure that all automated tests pass prior to requesting a review. After that, the process will involve some communication between the reviewer and the submitter, possibly requests for more information on the background or validation, and comments in the pull request to gain additional insight into specific lines of code.
After a consensus is reached between the submitter and reviewer, the pull request will be merged into the target branch (typically dev) and the pull request will be closed. You’re done! This change will be included in the subsequent release of OpenFAST when the dev branch is merged into main.
5.1.5. Bug fixes
If you’ve found a bug in the code, it is important to fully describe it both in a GitHub Issue and through a minimal test. Before making a commit with the bug fix, commit the new test that exposes the bug. This test should fail. Then, commit the bug fix and show that the test passes. The git-commit history should look something like this (progresses bottom to top):
See Testing OpenFAST and Working with OpenFAST on GitHub for more information.
5.1.6. Additional guidance
The following sections provide extended guidance on developing source code, interacting with the NREL OpenFAST team and other community contributors, and generally debugging and building out features.
5.2. 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:
5.3. Other Documentation
Additional documentation exists that may be useful for developers seeking deeper understanding of the solver and mathematics.
NWTC Programmer's HandbookThis is an overview of programming guidelines for FAST 8. While some syntax and minor details have changed in OpenFAST, most of this guide is still relevant.
OutListParameters.xlsxThis Excel file contains the full list of outputs for each module. It is used to generate the Fortran code for the output channel list handling for each module (this code is generally in the _IO.f90 files). The MATLAB script available in the matlab-toolbox repository at Utilities/GetOutListParameters.m.