Turbine Library

[rafmudaf]

FLORIS includes an internal turbine library in addition to the option to specify a user-defined library since #568. The user-defined library interface is well established and described in the pull request. The internal turbine library, however, is opaque for users who have installed floris without cloning the repository from GitHub (i.e. pip install floris). Presenting this information to users would be helpful in understanding how to configure turbines, evaluate their properties, and create new models. Currently, there are two methods to view a list of turbines available:

• Navigate into the turbine library directory in the source code to view the list of input files
• Identify that example 18 lists the turbine types, run the example, and understand the plots generated

Proposed solution

I propose two paths for bringing this information closer to the user.

First, the turbine library should be accessible within the code something like this:

import floris.turbine_library as floris_turbines

# Print specific info from each available turbine model
for turbine in floris_turbines:
    print(f"Turbine Type" {turbine.name}")
    print(f"    - rotor diameter: {turbine.rotor_diameter}")

# Show the power curve for the NREL 5MW turbine
floris_turbines.nrel_5MW.plot_power_curve()

This would provide an in-code interface to interact with these turbine models directly. It can be achieved by considering floris/turbine_library as a package alongside floris/simulation and floris/tools and including the necessary infrastructure.
The flow for loading turbines in the simulation code, whether from an internal or external turbine library, could leverage floris.turbine_library rather than reimplementing the sequence for finding the turbine input files and creating the new objects.

Additionally, example 18 should be converted to a Jupyter Notebook format and incorporated into the online documentation either in the "User Reference" or "Theory and Background" sections. This sort of documentation would be a great tool for documenting methods to analyze the turbine input as well as document the included turbine properties themselves.

[paulf81]

Great idea! If I could pad one idea onto this, we should illustrate how to use a custom user-defined library. I had thought I would do this within the floating pull, but then found I couldn't figure out how to specify a relative path, and giving an absolute path in an example seemed tricky

[rafmudaf]

Good point. @RHammond2 included an example in the pull request for that feature (#568), but it should be expanded and included in the documentation.

[RHammond2]

@rafmudaf do you have a sense of how to properly do the relative folder referencing? I assume that it's going to be relative to floris/simulation/farm.py because that's where it's loaded, so you'd have to do an absolute path.

[paulf81]

Thanks @rafmudaf and @RHammond2 to jump in the middle, if you check this example in the floating pull:
https://github.com/NREL/floris/blob/76eeb8e380511100c19e13581230d05c88fa551c/examples/inputs_floating/gch_floating.yaml

You can see that in the !include syntax, the path is relative, which is convenient for examples:
!include turbine_files/nrel_5MW_floating.yaml

And we appear to be relative to the input yaml file, which is inside the folder "inputs_floating"

I had the idea that a neater solution, showing the new method, could be to add the path to the folder inputs_floating/turbine_files, but where I got stuck was I could only see how to do this using the absolute path, which I thought was a little brittle, people would have to change the value depending where they install floris if they want the example to run (I guess also CI would be an issue). Maybe this is the wrong use case, but wanted to explain a little more what I was wondering about

[rafmudaf]

@RHammond2 In my proposal above, the floris.turbine_library API provides access to the Turbine objects themselves rather than the yaml input file or dictionary representation of a Turbine. This requires some infrastructure in the new package (floris.turbine_library), but it simplifies other areas of the simulation code and can also provide some useful functionality to both floris.tools and floris.simulation.

[RHammond2]

I guess the primary question is how to ensure that we're able to include a library of turbines that aren't a part of FLORIS, and be able to define them in the YAML, so that import floris.turbine_library as floris_turbines could include external turbines once the primary input configuration is loaded?

In general, I think that's a good idea, but just want to make sure we're able to adequately include non-FLORIS turbines in this. In particular, I think Paul's question about relative paths in YAMLs to define where to look for the turbine files will be helpful for documenting the functionality.

[rafmudaf]

This is now more relevant since #733 and #737.

[RHammond2]

@rafmudaf and @paulf81, I did a little more digging on how to deal with relative paths in YAML files, which led to an idea on how to better handle specifying an external FLORIS turbine library. I just need to test it out in practice, and will circle back to this, now that it's a bit more urgent.

[paulf81]

sounds great! thank you

[RHammond2]

This issue is a little bit tricky, but I think the following works well with one caveat: The reference to the multi dimensional files would have to be converted from "../floris/turbine_library/iea_15MW_multi_dim_Tp_Hs.csv" to "iea_15MW_multi_dim_Tp_Hs.csv" because a relative path from the configuration file itself breaks with the proposed changes.

On my end, running an example from within FLORIS/examples/ and FLORIS/ operate exactly the same. I've also taken the examples test GH Action logic, and copied the examples folder to a new temporary location, then run from within it and outside it successfully (with the change in in mutli-dimensional turbine reference).

I'm curious if this is the kind of approach that fits within the FLORIS paradigm, or if it opens up a bit of a can of worms. I thought I'd at least post the solution here prior to opening up a draft PR in case there were any concerns.

Primary changes:

• type_dec.convert_to_path: https://github.com/RHammond2/floris/blob/7e7f8219dd9ba18c2c18952f185a53a85e0df07c/floris/type_dec.py#L91
• Farm.construct_turbine_map: https://github.com/RHammond2/floris/blob/enhancement/yaml-relative-file/floris/simulation/farm.py#L266-L274
• TurbineMultiDimensional
• https://github.com/RHammond2/floris/blob/enhancement/yaml-relative-file/floris/simulation/turbine_multi_dim.py#L430-L433
• https://github.com/RHammond2/floris/blob/enhancement/yaml-relative-file/floris/simulation/turbine_multi_dim.py#L456-L461
• FlorisInterface: https://github.com/RHammond2/floris/blob/7e7f8219dd9ba18c2c18952f185a53a85e0df07c/floris/tools/floris_interface.py#L58-L68

[RHammond2]

Actions results here

Without updating the CSV reference:

After updating:

[rafmudaf]

Hey @RHammond2 I think in general this looks good. Could you open a pull request and describe the change there?