Examples Directory

[rafmudaf]

We currently maintain a set of examples demonstrating various tasks within and around FLORIS. They are stored in the repository at https://github.com/NREL/floris/tree/main/examples. We have gotten great feedback about the impact of these examples. It seems like a great way for new users to very quickly understand how to interact within the FLORIS environment, and it's an easy place for us to define and demonstrate the workflows and semantics that we expect and have used to define the API's.

Initially in the v3 redevelopment, we settled on a set of 9 examples, and the story was fairly clear: starting from the very basic tasks of initializing FLORIS, build up to an AEP calculation and yaw optimization. That list is mostly a linear progression in complexity even though there is some redundancy (i.e. 4,5,6,7 could be combined and 8,9 could be combined). The list grew to 12 by the last v3 pre-release, 17 by v3.0, 18 in v3.1, 23 in v3.2, 25 in v3.3, and 26 in the develop branch. Pull requests #641, #639, #638, #628, #627, #533 add collectively 9 more examples including two 18b's. If these are all merged, then the number of examples would increase to 44.

At this point, I see the examples directory following the same path as it did in v2 where we ended up with a loosely correlated set of examples including two directories called "other" and very little context for how to approach the set. I'm opening this discussion with the hope that we can come to a consensus on the purpose of the examples and design them in such a way to meet that purpose.

Please comment below and I'll incorporate it into either the "Purpose" or "Suggestions" section.

Purpose

What is the purpose of the set of examples? What question are they intended to answer?

I see the set of examples primarily as a learning tool, a combination of explanation and tutorial. Each example does not need to cover exactly one task, but instead each example might cover a complete topic. For example, we currently differentiate between sweeping over wind directions (04), wind speeds (05), and wind conditions (06). Separately, these examples serve as a script to copy / paste and build on top. Collectively, they serve as an explanation of the architecture of the data structures in FLORIS and how to navigate them. In fact, 04 and 05 primarily differ only by their use of the words "wind speed" and "wind direction" in a few places (see the collapsed diff below).

diff 04_sweep_wind_directions.py 05_sweep_wind_speeds.py

(floris) >>mbp@~/Development/floris/examples (develop $)$ diff 04_sweep_wind_directions.py 05_sweep_wind_speeds.py 
23c23
< 04_sweep_wind_directions
---
> 05_sweep_wind_speeds
25,26c25,26
< This example demonstrates vectorization of wind direction.
< A vector of wind directions is passed to the intialize function
---
> This example demonstrates vectorization of wind speed.
> A vector of wind speeds is passed to the intialize function
28c28
< wind directions in one call
---
> wind speeds in one call
30c30
< The power of both turbines for each wind direction is then plotted
---
> The power of both turbines for each wind speed is then plotted
33a34
> 
45,46c46,47
< wd_array = np.arange(250,291,1.)
< fi.reinitialize(wind_directions=wd_array)
---
> ws_array = np.arange(5,25,0.5)
> fi.reinitialize(wind_speeds=ws_array)
51,53c52,54
< num_wd = len(wd_array) # Number of wind directions
< num_ws = 1 # Number of wind speeds
< num_turbine = len(layout_x) #  Number of turbines
---
> num_wd = 1
> num_ws = len(ws_array)
> num_turbine = len(layout_x)
68,69c69,70
< ax.plot(wd_array,pow_t0,color='k',label='Upstream Turbine')
< ax.plot(wd_array,pow_t1,color='r',label='Downstream Turbine')
---
> ax.plot(ws_array,pow_t0,color='k',label='Upstream Turbine')
> ax.plot(ws_array,pow_t1,color='r',label='Downstream Turbine')
72c73
< ax.set_xlabel('Wind Direction (deg)')
---
> ax.set_xlabel('Wind Speed (m/s)')
74d74
< 

If composed correctly, I think it would be equally as simple to build on top of a script that contains the information in 04, 05, and 06 and simply delete what you don't want. This is a focus on these three examples, but I think they illustrate the general point well.

The examples allow the NREL team to guide users in the way we designed the API's to be used. While we regularly talk about API design and often make improvements, we don't typically document it very well. The examples are where we can implicitly document the usage and API's that we've intentionally developed.

Suggestions

Some ideas to improve the handling of examples:

• Decide that they're meant to be references rather than explanation / tutorials and accept the added burden of maintaining a larger set
• Create longer examples and consolidate where possible
• Expand the Background and Concepts section of the docs and remove the first few examples

Ultimately, I think a mapping of the ideas and progression of teaching would be great for the examples that we currently have and those we'd like to have.

[Bartdoekemeijer]

Hi Raf,

Thanks for starting this discussion. I agree with you that the examples should primarily function as tutorials for new users to understand how the interact with the code. Its secondary function is being a template upon which more advanced/tailored code can be built, e.g., commonly for the yaw optimizations and for AEP evaluations.

I am a big proponent of consolidating various examples together to get back to a manageable set of examples. Examples 04, 05 and 06 that you refer to are great examples of codes that are unnecessarily repeated and can be consolidated to a single code. We also don't need a separate code to demonstrate UncertaintyInterface or ParallelComputingInterface -- rather, they can be included in other examples. FLORIS v3 started with 9 examples, and I think that's a good number of examples to aim for.

[paulf81]

Thank you for starting the discussion @rafmudaf ! I think, maybe more for arguments sake, at least on the issue of how many examples, I might take the point of view that more can be better. Maybe I'll start with a quote from Frasier:

Niles: Haven't you ever heard of less is more?
Frasier: Ah! But if less is more, just think how of much more more is

In seriousness though, I think a lot of learning any code comes from running and then adapting examples, so a rich set of examples seems like a positive, versus a smaller, but neater set. @Bartdoekemeijer I think you do capture this with you primary function as teaching, and secondary as a template so maybe we aren't disagreeing too much.

But I can be persuaded! Just wanted to voice this side!

[rafmudaf]

I think of these differing perspectives as the experience of going down the nut butter aisle at a Trader Joes and any other grocery store in Boulder. For example, there was a healthy variety of nut butter options at the Boulder Lucky's (RIP). At TJ's, there's crunch vs creamy and salty vs not for peanut butters, and two or three other types of nut options like almond butter. I trust that they've distilled the relevant information for me so that I can focus on the # 1 decision: crunch or creamy. For a more visceral experience, consider the options for nutrition bars (i.e. like a clif bar) at Colorado grocery store.

I see the value in a rich set of examples, but quantity of information and accessibility of information are not necessarily correlated. It takes a lot of work to make a body of information easily understandable. This is not too different than writing a paper where we typically go through a well established and fairly rigorous review and editing process to ensure that they're efficient and effective. I propose that we should identify a story to tell in the collection of examples and ensure that it is accessible to people who do not have the context that we do when we wrote the example scripts.

[paulf81]

Ok this is a great point, I'm on board

[Bartdoekemeijer]

Another idea here, where we split the examples into FLORIS and FLASC_Cookiecutter_Template:

• FLORIS contains a set of examples and tutorials with the purpose of demonstrating functionality and educating users. Users can copy and modify these examples for one-off calculations and basic/simple usage.
• More developed workflow examples and scripts better suited as a template for professional use cases are placed in flasc_cookiecutter_template. This is the right place for more thorough wind farm studies using FLORIS, like AEP evaluations and wake steering AEP uplift evaluations.

I guess this is also closely related to our discussion of the hierarchy of repositories.

[rafmudaf]

As noted in #739 (review), the collection of examples should either require to be run from the examples/ directory or support running from any directory. This is currently not possible due to requiring that some relative paths exist.