Provide an option to initialize FLORIS with preset defaults and no input files

[rafmudaf]

When using FLORIS, we generally get an input file from somewhere (probably the examples/ directory in the repository) and modify it to fit our needs. We use the new input file to initialize FlorisModel, and then we generally start changing the inputs programmatically. For example, for anything but a trivial study, we'll always change the layout and wind conditions. Consider the characteristic workflow from Example 10:

fmodel.set(layout_x=layout_x, layout_y=layout_y)

# Define a simple inflow with just 1 wind speed
wd_array = np.arange(0, 360, 4.0)
ws_array = 8.0 * np.ones_like(wd_array)
turbulence_intensities = 0.06 * np.ones_like(wd_array)
fmodel.set(
    wind_directions=wd_array, wind_speeds=ws_array, turbulence_intensities=turbulence_intensities
)

Therefore, we could classify the inputs to FLORIS as:

• Tier 1: Layout and wind condition
• Tier 2: Turbine definition, primarily the power and Ct curves
• Tier 3: Tunable settings like wake model parameters

Where FLORIS is used within another software, the FLORIS inputs have to be copied, supplied by the user, or somehow retrieved in order for FLORIS to function as a library (see flasc1, flasc2, WAVES). Instead, I propose to provide a method for using FLORIS as a library within a calling code with a logical set of default inputs (i.e. one of the existing example input files + NREL 5 MW turbine). Possible solutions for this are:

• Modify FlorisModel to load a predefined input file if selected: FlorisModel(configuration="defaults")
• Modify FlorisModel to use a predefined input set if no configuration is given: FlorisModel() See Provide an option to initialize FLORIS with preset defaults and no input files #1037 (comment)
• Provide a mechanism for retrieving an input set from FLORIS and to then use for initialization:

from floris import FlorisModel, default_inputs
fmodel = FlorisModel(configuration=default_inputs)

[misi9170]

I really like this idea. Although setting up a default with an empty configuration (fmodel = FlorisModel()) would be very clean, that is maybe a bit dangerous in that it really isn't clear what is being loaded. I quite like the first option: FlorisModel(configuration="defaults") (or, simply FlorisModel("defaults")) because it saves the user having to import a dictionary, but it's still fairly explicit. Internally, we could still import the default_inputs from a special file.

[rafmudaf]

Thanks for the feedback, this is very helpful. I agree that the empty initializer is too vague and will probably lead to unintended errors. After sitting on it for a few days, I think a combination of the other two options would be useful.

## Option 1; both forms are equivalent since it's the only argument
fmodel = FlorisModel(configuration="defaults")
fmodel = FlorisModel("defaults")

## Option 2
from floris import FlorisModel
default_inputs = FlorisModel.get_default_inputs()    # static method; returns a deep copy of the default input dict

# modify as needed
default_inputs["..."] = {"asdf": [i for i in range(10), "fdsa": [i for i in range(10)]}

# init
fmodel = FlorisModel(configuration=default_inputs)

[rafmudaf]

Another consideration here is that this might lead to an unclear state of FLORIS if users are not required to look at an input file. On one hand, it's on you if you don't read the docs to see what options are available in the inputs and what are their defaults. On the other hand, you don't know what you don't know when you're getting started. Considering this, it could be helpful to add an option to print both a condensed form of the current configuration options and a long form with all configuration options.

fmodel = FlorisModel("defaults")
fmodel.configs_short()
> Python version: 3.10
> FLORIS version: 4.2
> Configuration summary:
> solver:
>   type: turbine_grid
>   turbine_grid_points: 3
> 
> farm:
>   turbine_count: 3
>   turbine_type:
>   - nrel_5MW
> 
> flow_field:
>   findex_count: 20
> 
> wake:
>   model_strings:
>     combination_model: sosfs
>     deflection_model: gauss
>     turbulence_model: crespo_hernandez
>     velocity_model: gauss
> 
>   enable_secondary_steering: true
>   enable_yaw_added_recovery: true
>   enable_active_wake_mixing: false
>   enable_transverse_velocities: true



fmodel.configs_full()
> Python version: 3.10
> FLORIS version: 4.2
> Date: 25 Nov 2024
> Time: 10:00 AM
> Configuration:
> name: GCH
> description: Three turbines using Gauss Curl Hybrid model
> floris_version: v4
> 
> logging:
>   console:
>     enable: true
>     level: WARNING
>   file:
>     enable: false
>     level: WARNING
> 
> solver:
>   type: turbine_grid
>   turbine_grid_points: 3
> 
> farm:
>   layout_x:
>   - 0.0
>   - 630.0
>   - 1260.0
>   layout_y:
>   - 0.0
>   - 0.0
>   - 0.0
>   turbine_type:
>   - nrel_5MW
> 
> flow_field:
>   air_density: 1.225
>   reference_wind_height: -1
>   turbulence_intensities:
>   - 0.06
>   wind_directions:
>   - 270.0
>   wind_shear: 0.12
>   wind_speeds:
>   - 8.0
> 
> wake:
>   model_strings:
>     combination_model: sosfs
>     deflection_model: gauss
>     turbulence_model: crespo_hernandez
>     velocity_model: gauss
> 
>   enable_secondary_steering: true
>   enable_yaw_added_recovery: true
>   enable_active_wake_mixing: false
>   enable_transverse_velocities: true
> 
>   wake_deflection_parameters:
>     gauss:
>       ad: 0.0
>       alpha: 0.58
>       bd: 0.0
>       beta: 0.077
>       dm: 1.0
>       ka: 0.38
>       kb: 0.004
>   wake_velocity_parameters:
>     gauss:
>       alpha: 0.58
>       beta: 0.077
>       ka: 0.38
>       kb: 0.004
>   wake_turbulence_parameters:
>     crespo_hernandez:
>       initial: 0.1
>       constant: 0.5
>       ai: 0.8
>       downstream: -0.32

[kikocorreoso]

To me FlorisModel should be a constructor with its args and kwargs. Explicit is better than implicit is almost always a good idea.

A defaults is possibly very generic and prone to errors. The actual situation, having to use a config file not very well documented and then update many things of this config file using the .set method, is even worse than the defaults approach.

So, my proposal would be something more classic and pythonic like:

fmodel = FlorisModel(
    layout_x. # this is mandatory
    layout_y, # this is mandatory
    wtg_type,  # this is mandatory (one value or one per wtg location)
    hub_height, ,  # this is mandatory (one value or one per wtg location)
    ## **kwargs # most of the defaults but as kwargs but also with the option to change whatever when you instantiate the class
    air_density=1.225,
    ...
    solver_type="turbine_grid",
    ...
    wake_deflection_model="gauss",
    ...
    etc
)

I.e., mandatory arguments for the inputs that change between simulations and sane defaults defined as keywords. This way all the defaults are better tracked, included in docstrings, etc:

• Park1 is defined via mandatory arguments and Case1 of Park1 is defined via keywords.

I don't know is this makes sense and I know this would require more effort and breaking changes,...

[misi9170]

@kikocorreoso thank you very much for the valuable feedback here. You raise some really interesting points here, and I'd like to try to respond to each of them as I can.

Although I agree that it is best to be as explicit as possible, we have users who use FLORIS to model fleets of wind farms, and I understand the yaml file configuration to be the most convenient for them. In particular, they can keep a yaml config file for each farm in their fleet, with the full farm layout, !include paths to their wind turbine models, and potentially any site-specific wake model parameters, stored on that yaml. For these users, it is much more convenient to instantiate an FlorisModel from those preset yamls, and then likely use .set() only to set the wind conditions (although these too could reasonably be stored on the floris yaml file).

As well as that, and as you point out, moving away from a config file would be a major breaking change, and is not something we'll likely step towards in the near future.

All of that being said, I really do agree that the concept of having implicit defaults is dangerous. I like @rafmudaf 's idea that there should be an option to display those defaults, and perhaps, that printout should happen automatically when the defaults are loaded unless the user provides an explicit command not to display them.

Further, I wonder whether it would be possible to load defaults with empty layout_x, layout_y, turbine_type, wind_speeds, wind_directions, and turbulence_intensities entries; that is, the defaults would mostly load the wake model, and leave the state of FlorisModel.core.state as UNINITIALIZED. Users would then be required to provide those inputs explicitly before being able to call FlorisModel.run(). My feeling is that it is OK to provide the model_strings with default values, but perhaps these should be explicitly printed every time, e.g.

> wake:
>   model_strings:
>     combination_model: sosfs
>     deflection_model: gauss
>     turbulence_model: crespo_hernandez
>     velocity_model: gauss

Another small point that deserves discussion, although it is possibly a slight tangent, is that of how to specify turbine_type. We currently have (to me) a slightly inconsistent approach, where we allow users to specify turbine_type using either a list of strings of length n_turbines (that is, the same as the length of layout_x and layout_y) OR a list of length 1 with a single string, which is applied to all turbine locations. To me, it would be cleaner if the options were: a list of strings of length n_turbines OR a string, which is applied to all turbine locations; that is, a list of length 1 would not be allowed (unless layout_x and layout_y happen to be one only location). This would also be a breaking change, but we could introduce the string option and raise a deprecation warning for the list-of-length-1 option. We have discussed this somewhere else, I think, but I haven't been able to track that down.