Feature: External Turbine Library

[RHammond2]

Feature or improvement description
This PR is a new copy of #521, with the latest changes on develop, and adds support for using external turbine libraries for turbine defintions to floris.tools.FlorisInterface and floris.simulation.Farm.

Related issue, if one exists

This would bump up the priority of #345 and likely close it.
Closes #521 because it's outdated and got bungled in a merge resolution.
Addresses part of #513 by only loading a file once, logging the appropriate warning, and creating a deepcopy of the loaded turbine file for each turbine in the layout. The core issue raise there stems from the set up of the examples, upon closer inspection, so will not be closing the issue.

Impacted areas of the software

floris.simulation.Farm now has a turbine_library attribute that defaults to the currently assumed "floris/turbine_library" folder that ensures the input file path exists prior to loading in the data. Additionally this input was added to the floris.tools.FlorisInterface.reinitialize() method to ensure usage is consistent with the rest of the inputs. I've also added a few other tests and some test data to ensure this is working as expected.

Additional supporting information

I saw in #345 that this was marked as v3.3/v3.4 issue, however, in a separate project I'm running into an issue where the current workaround is a little bit clunky in practice, and am proposing the implemented solution here as a starting point.

Test results, if applicable

All previously existing and newly added tests pass.

Example Usage
The below demonstration shows how a user can define a separate turbine_library_path in their input YAML file:

...  # definitions before the farm inputs
farm:
  layout_x: 
    - 0
    - 500
    - 1000
  layout_y: 
    - 0
    - 0
    - 0
  turbine_type:
    - nrel_5MW  # included in FLORIS
    - nrel_5MW  # included in FLORIS
    - nrel_5MW_custom   # External turbine library; note that there is no overlap in turbine naming
  turbine_library_path: /path/to/custom/user/library/folder  # folder where nrel_5MW_custom is located
...  # definitions after the farm inputs

An alternative usage for this feature is available through the FlorisInterface.reinitialize() method, as seen in the example below.

from floris.tools import FlorisInterface


# Define an interface, assuming this uses the default internal turbine library
fi = FlorisInterface("path/to/input.yaml")

# Now, redefine, and add in a custom turbine model from an external library
fi.reinitialize(
    # 2 internally defined, and 1 externally defined turbines, just like file example above
    turbine_type=["nrel_5MW", "nrel_5MW", "nrel_5MW_custom"],
    turbine_library_path="/path/to/custom/library/folder",  # folder where "nrel_5MW_custom" is located
)

[rafmudaf]

The last comment I have is a request to add a simple example usage in the pull request description above. This will ultimately be included in the documentation, but it's good enough to include here initially.

Is this a feature that can only be used through a script or is there a way to set an external turbine library through the input file? If so, please provide the relevant blocks of the input file that would be used.

[RHammond2]

Good call on the example part, I'll add something that calls more attention to it, so users know it's available. As an aside, it was added to the documentation PR in the input reference sheet, so I'll leave that component alone.

[paulf81]

Thank you @RHammond2 , I think this is a really nice and general solution

[bayc]

Looks great!

[scottryn]

Hi all, I have an issue with this feature where turbines in /path/to/custom/user/library/folder raise the turbines exist in internal and external library error. Specifically check_turbine_type() in farm.py is saying my custom turbine file exists where it shouldn't. I've verified the location and contents of both directories as well as re-installed from source but the issue persists. Any help would be appreciated!

[rafmudaf]

@scottryn thanks for the info. Could you please open an issue and include a minimal script to reproduce the error?

[scottryn]

Hi @rafmudaf, thanks for getting back to me so quickly! I installed in a clean Conda environment and everything works as intended. I'll hold off on raising an issue since it appears I have ghosts in my other environment.