Overview of included examples

[rafmudaf]

This discussion thread is meant to guide the development of the examples included with the FLORIS repository. These are the scripts and notebooks located at floris/examples/. While good user and developer documentation is ideal, it is often more efficient to include examples for how we use FLORIS directly within the repo to serve alongside the official documentation. We tend to create these examples while we are building a new feature or using FLORIS for an analysis, so it is almost free documentation. However, the consequence of continuously adding examples without an overarching direction is that the content becomes less effective as documentation and functions more like a reference for building new scripts. While this is useful, the intended purpose of examples-as-documentation is lost due to excess information. Here, I propose a high level architecture for the included examples so that the community can discuss and make suggestions.

Guiding Idea

The examples should serve the following purposes:

• Hands-on material describing key concepts in the FLORIS software
• Real use cases and scripts for analysis and design
• NREL style guide for code

Teaching Material

The examples for teaching new users about FLORIS may be best delivered through Jupiter Notebooks. This allows us to write notes alongside code while manipulating data. These notebooks will have very little sections of code that could be copied to run through a complete FLORIS simulation. Instead, they will have blocks that do specific parts of the simulation.

Analysis and Design References

The real-world examples demonstrating methods for analysis and design are best represented through Python scripts. These should contain in-code comments describing the methods used and decisions made. They should describe a complete concept rather than a subset of a concept and the objective of the example should be described in detail at the beginning. This set of examples should have very little overlap on content covered. The goal is to effectively describe the use cases and features of FLORIS in as few lines of code as possible. Generally, the examples should be difficult to write but easy to read since the burden of thorough explanation is on the author rather than the reader.

Proposed Examples

flowchart TD
  id1(Learning Notebooks) --> id10(Key Concepts)
  id1(Learning Notebooks) --> id11(Pre-Processing)
  id1(Learning Notebooks) --> id12(Post Processing)

  id2(Analysis and Design Scripts) --> id20(AEP Calculation)
  id20(AEP Calculation) --> id21(Yaw Optimization)
   id20(AEP Calculation) --> id22(Layout Optimization)

Loading

[paulf81]

hi @rafmudaf this seems like a really good partitioning of the example material, I agree with this approach! My additional thoughts:

• All the notebooks should exist both as executable notebooks, as well as already-run websites within the main documentation
• (perhaps this could be scripted/automated so changes to the notebooks shows up in the website upon pulling into main?)
• Maybe following the change we can rename the examples so they don't start with a number (which contains less and less meaning) and just give a descriptive name.
• Perhaps the examples could also be viewable through a website with a TOC?