Documentation

[rafmudaf]

There will be two main perspectives in developing the documentation: user-facing and developer-facing. Here, let's outline ideas and considerations for both. This is closely related to the examples discussion.

Reference

• Describe each wake model and their parameters
  • Show plots of the wake
  • Reference papers used in the implementation
  • Reference list of wake model parameters #469

User documentation

Describe important concepts:

• Add API change documentation to show how to modify input files for each new release
• Turbine library
  • Pick a turbine included in FLORIS or define your own
  • use !include <path> to point to your own turbine definition
  • Convert the turbine interface notebook and example 18 to docs; see Turbine Library #604
• The idea with vectorization of wind speeds and wind directions to understand the dimensions in the primary data structures

Description of turbine model definition

• How to define the power curve? Specifically, how to handle both ends of the power curve.
  • personalized turbine files to be changed with 3.1 #415
  • Feature: add IEA 15MW turbine #358

How to get wind speeds at each turbine (#422).
Describe the turbine models that are included. Link to https://nrel.github.io/turbine-models/index.html.

Using the public API (i.e. FlorisInterface.reinitialize and etc)

• fi.reinitialize can take multiple arguments or you can call it multiple times. It continuously modifies the same data unless you reinstantiate.

Developer documentation

Describe how all the classes are created using attrs from a dictionary

• Each field comes from a key-value in the dictionary
  • Optional arguments to field()
• There is some pre and post processing available

Generally, most input validation should occur in the FlorisInterface. This is where the "business logic" exists, and floris.simulation is maintained as a generic, parameterized simulation framework.

Implementation Details

Describe the meaning of the dimensions of the arrays.

Describe the _sorted vs unsorted variables.

• See Extracting Entire Flow FIeld #738 for some context on the ambiguity of these variables. In my response, I suggest to use FlowField.u,v,w and Grid.x_sorted,y_sorted,z_sorted. The description of these variables should either address why they're inconsistently named or make their names consistent.
  Describe inertial coordinates (vs wind-relative or rotated).
  Describe how the turbulence intensity is set and expanded throughout the calculation. Specifically, see Bug fix: sort turbulence intensity field in post-calculation step #564 and Bug fix: initialize TI array with correct dimensions #584.

[rafmudaf]

The documentation was migrated to Jupyter-book from Jekyll and content expanded in #514. That pull request was meant to mostly move to the new framework, but @RHammond2 gave good feedback on the content overall, so I've copied it here for reference.

FLORIS Intro

• Seems like this might be a good place to highlight the main FLORIS papers/tutorials (even if it's cross referencing from another section)
• Could be a nice place for some sleek imagery coming from FLORIS that's highlighting some of the capabilities (even the 2.x to 3.x performance comparisons)

Installation

• Break it into sections for pip, conda, and source with a short sentence or two describing each
• Additional/Optional dependencies section for pyoptparse, etc

Developer's Guide

• Might move that up to be just under the installation page
• The right sidebar isn't showing the subsections like Unit Testing
• The testing sections should just have the code one-liner for running that example as a code snippet
• It might be worthwhile to give a quick overview of the Git/GH workflow as a numbered list for a typical feature contribution workflow just to be exceedingly clear about what we want

Background and Concepts

Intro

• floris simulation and tools could go second after providing a little more high level details about interacting with FLORIS

Get turbine power

• Should we consider something like rich/tabulate to improve our standardized output printing in place of reimplementing the same workflows all the time. Essentially, a floris.tools.print module would be my proposal for this

Visualization

• If you put a ; after the plotting routines or add plt.show() as the last line then you'll be able to suppress those matplotlib outputs that show up just before the actual plots
• It seems like there should be subsections to this heading so that it's easier to follow
• Probably not the right place, but it seems like we should have the plot_rotor_values using the same color bar so it's easier to translate between wind speeds

API

• I find the layout a little bit awkward, which is probably more to do with the autosummary setup for automatically populating the pages, but it's not clear to me that the first thing a user sees should be the logging manager, which they don't directly interact with in any meaningful way.
• Building on that, I think that it'd more helpful if the API docs were broken down into the following topical areas (or something similar):
  • Base Classes, Mixins, and Configurations
    • logging, types, utilities, version, Base(?), BaseModel(?)
  • Simulation
    • Introduce the primary building blocks: turbine, farm, flow_field, and floris
    • Modeling components: grid, solver, and wake
    • Wake modeling: combination, deflection, turbulence, velocity
  • Tools

Code Quality

• I like this, but I feel like it could have a better home, maybe even at the end of the main page or with a changelog type page

[shubh007am]

Hey @rafmudaf where can I find the latest version's PDF copy of the release document? I am looking for something very similar to what has been provided here
https://media.readthedocs.org/pdf/floris/latest/floris.pdf

[rafmudaf]

@shubh007am the current documentation site does not automatically compile into a pdf. The one you references was built and hosted with readthedocs whereas we now use GitHub Pages. However, this is a feature we could add. What is the benefit to you for having a pdf vs using a website?

[shubh007am]

Thanks for the reply. I could access the website with equal ease, I just couldn't get it earlier. Thanks