For Developers

FLORIS is currently maintained at NREL’s National Wind Technology Center by Jen King, Paul Fleming, Chris Bay, and Rafael Mudafort. However, we are excited about community contribution, and this page outlines processes and procedures we’d like to follow when contributing to the source code.

Git and GitHub

The majority of the collaboration and development for FLORIS takes place in the GitHub repository. There, issues and pull requests are discussed and new versions are released. It is the best mechanism for engaging with the NREL team and other developers throughout the FLORIS community.

FLORIS 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 this workflow is critical to prevent remote changes from blocking your local development. The Git Flow process is detailed nicely here.

Syncing a local repository with NREL/FLORIS

The “main” FLORIS repository is continuously updated along with ongoing research at NREL. From time to time, developers of FLORIS using their own “local” repositories (versions of the software that exist on a local computer) may want to sync with NREL/FLORIS. To do this, use the following git commands:

# Move into the FLORIS source code directory;
# this may be named differently on your computer.
cd floris/

# Find the remote name that corresponds to
# NREL/FLORIS; usually "origin" or "upstream".
git remote -v

# Fetch the changes on all remotes.
git fetch --all

# Decide which branch to sync with
# NREL/FLORIS. Generally, this will be "master".
git checkout master
git pull origin master

# Update any local working branches with the
# latest from NREL/FLORIS.
git checkout feature/working_branch
git merge master

Note that the example above is a general case and may need to be modified to fit a specific use case or purpose. If significant development has happened locally, then merge conflicts are likely and should be resolved as soon as possible.

Building Documentation Locally

This documentation is generated with Sphinx and hosted on readthedocs. However, it can be built locally by running this command in the floris/docs/ directory:

Important

A few additional dependencies required to build the documentation locally are listed at floris/docs/requirements.txt.

cd floris/docs
pip install -r requirements.txt
make html

This will create a file at floris/docs/_build/html/index.html which can be opened in any web browser.

This will create a file at floris/docs/_build/html/index.html which can be opened in any web browser.

Testing

In order to maintain a level of confidence in the software, FLORIS is expected to maintain a reasonable level of test coverage. To that end, unit tests for a small subset of the simulation package are included.

The full testing suite can by executed by running the command pytest from the highest directory in the repository. A testing-only class is included to provide consistent and convenient inputs to modules at floris/tests/sample_inputs.py.

Unit Tests

Unit tests are integrated into FLORIS with the pytest framework. These can be executed by running the command pytest tests/*_unit_test.py from the highest directory in the repository.

Regression Tests

Note

The regression tests have been disabled. Before reenabling, the baseline tests should be reworked to test against deliberate and meaningful data. The result of the tests should also be tightly integrated into the dev team’s workflow.

Regression tests are included in FLORIS through the same pytest framework as the unit tests. Functionally, the only difference is that the regression tests take more time to execute and exercise a large portion of the software. These can be executed by running the command pytest tests/*_regression_test.py from the highest directory in the repository.

Continuous Integration

Continuous integration is configured with TravisCI and executes all of the existing tests for every commit. The configuration file is located in the top directory at floris/.travis.yml.

If forked, continuous integration can be included with TravisCI by simply creating an account, linking to a GitHub account, and turning on the switch to test the FLORIS fork.

Deploying to pip

Generally, only NREL developers will have appropriate permissions to deploy FLORIS updates. When the time comes, here is a great reference on doing it: https://medium.freecodecamp.org/how-to-publish-a-pyton-package-on-pypi-a89e9522ce24