Merge pull request #726 from NREL/develop

FLORIS v3.5

README.md

@@ -3,7 +3,7 @@
 FLORIS is a controls-focused wind farm simulation software incorporating
 steady-state engineering wake models into a performance-focused Python
 framework. It has been in active development at NREL since 2013 and the latest
-release is [FLORIS v3.4.1](https://github.com/NREL/floris/releases/latest).
+release is [FLORIS v3.5](https://github.com/NREL/floris/releases/latest).
 Online documentation is available at https://nrel.github.io/floris.
 
 The software is in active development and engagement with the development team
@@ -71,7 +71,7 @@ and importing FLORIS:
         version
 
     VERSION
-        3.4
+        3.5
 
     FILE
         ~/floris/floris/__init__.py

docs/architecture.md

@@ -1,17 +1,29 @@
 
 # Architecture and Design
 
-Two fundamental ideas define the design of the FLORIS software:
+At the outset of the design of the FLORIS software, a few fundamental ideas were identified
+that should continue to guide future design decisions. These characteristics should never
+be violated, and ongoing work should strive to meet these ideas and expand on them as much
+as possible.
 
-- Modularity in wake model formulation
-    - Mathematical formulation should be straightforward to include
+- Modularity in wake model formulation:
+    - New mathematical formulation should be straightforward to incorporate.
     - Requisite solver and grid data structures should not conflict with other existing
-        wake models
-- Management of abstraction
+        wake models.
+- Any new feature or work should not affect an existing feature:
+    - Low level code should be reused as much as possible, but high level code should rarely
+        be repurposed.
+    - It is expected that a new feature will include a new user entry point
+        at the highest level.
+    - Avoid flags and if-statements that allow using one high-level routine for multiple unrelated
+        tasks.
+    - When in doubt, create a new pipeline from the user-level API to the low level implementation
+        and refactor to consolidate, if necessary, afterwards.
+- Management of abstraction:
     - Low level code is opaque but well tested and exercised; it should be very computationally
-        efficient with low algorithmic complexity
+        efficient with low algorithmic complexity.
     - High level code should be expressive and clear even if it results in verbose or less
-        efficient code
+        efficient code.
 
 The FLORIS software consists of two primary high-level packages and a few other low level
 packages. The internal structure and hierarchy is described below.

docs/dev_guide.md

@@ -216,7 +216,7 @@ compiling, a file should be located at ``docs/_build/html/index.html``.
 This file can be opened in any browser.
 
 ```bash
-pip install -e .["docs"]
+pip install -e ".[docs]"
 jupyter-book build docs/
 
 # Lots of output to the terminal here...

docs/empirical_gauss_model.md

@@ -10,7 +10,9 @@ have been reorganized to provide simpler tuning and data fitting.
 
 The velocity deficit at a point $(x, y, z)$ in the wake follows a Gaussian
 curve, i.e.,
+
 $$ \frac{u}{U_\infty} = 1 - Ce^{-\frac{(y-\delta_y)^2}{2\sigma_y^2} -\frac{(z-z_h-\delta_z)^2}{2\sigma_z^2}} $$
+
 where the $(x, y, z)$ origin is at the turbine location (at ground level).
 The terms $C$, $\sigma_y$, $\sigma_z$, $\delta_y$, and $\delta_z$ all depend
 on the downstream location $x$.

docs/examples.md

@@ -84,8 +84,19 @@ Define non-uniform (heterogeneous) atmospheric conditions by specifying
 speedups at locations throughout the farm. Show plots of the
 impact on wind turbine wakes.
 
-### 16b_heterogenaity_multiple_ws_wd.py
-Illustrate usage of heterogenaity with multiple wind speeds and directions.
+### 16b_heterogeneity_multiple_ws_wd.py
+Illustrate usage of heterogeneity with multiple wind speeds and directions.
+
+## 16c_optimize_layout_with_heterogeneity.py
+This example shows a layout optimization using the geometric yaw option. It
+combines elements of examples 15 (layout optimization) and 16 (heterogeneous
+inflow) for demonstrative purposes. If you haven't yet run those examples,
+we recommend you try them first.
+
+Heterogeneity in the inflow provides the necessary driver for coupled yaw
+and layout optimization to be worthwhile. First, a layout optimization is
+run without coupled yaw optimization; then a coupled optimization is run to
+show the benefits of coupled optimization when flows are heterogeneous.
 
 ### 17_multiple_turbine_types.py
 Load an input file that describes a wind farm with two turbines
@@ -99,6 +110,10 @@ of a turbine layout within FLORIS.
 Demonstrates the definition of a floating turbine and how to enable the effects of tilt
 on Cp and Ct.
 
+For further examples on floating wind turbines, see also examples
+25 (vertical wake deflection by a forced tilt angle) and 29 (comparison between
+a fixed-bottom and floating wind farm).
+
 ### 25_tilt_driven_vertical_wake_deflection.py
 
 This example demonstrates vertical wake deflections due to the tilt angle when running
@@ -107,6 +122,10 @@ vertical deflections at this time. Also be aware that this example uses a potent
 unrealistic tilt angle, 15 degrees, to highlight the wake deflection. Moreover, the magnitude
 of vertical deflections due to tilt has not been validated.
 
+For further examples on floating wind turbines, see also examples
+24 (effects of tilt on turbine power and thrust coefficients) and 29
+(comparison between a fixed-bottom and floating wind farm).
+
 ### 26_empirical_gauss_velocity_deficit_parameters.py
 
 This example illustrates the main parameters of the Empirical Gaussian
@@ -127,6 +146,32 @@ mast across all wind directions (at a fixed free stream wind speed).
 Try different values for met_mast_option to vary the location of the met mast within
 the two-turbine farm.
 
+### 29_floating_vs_fixedbottom_farm.py
+
+Compares a fixed-bottom wind farm (with a gridded layout) to a floating
+wind farm with the same layout. Includes:
+- Turbine-by-turbine power comparison for a single wind speed and direction
+- Flow visualizations for a single wind speed and direction
+- AEP calculations based on an example wind rose.
+
+For further examples on floating wind turbines, see also examples
+24 (effects of tilt on turbine power and thrust coefficients) and 25
+(vertical wake deflection by a forced tilt angle).
+
+### 30_multi_dimensional_cp_ct.py
+
+This example showcases the capability of using multi-dimensional Cp/Ct data in turbine defintions
+dependent on external conditions. Specifically, fictional data for varying Cp/Ct values based on
+wave period, Ts, and wave height, Hs, is used, showing the user how to setup the turbine
+definition and input file. Also demonstrated is the different method for getting turbine
+powers when using multi-dimensional Cp/Ct data.
+
+### 31_multi_dimensional_cp_ct_2Hs.py
+
+This example builds on example 30. Specifically, fictional data for varying Cp/Ct values based on
+wave period, Ts, and wave height, Hs, is used to show the difference in power performance for
+different wave heights.
+
 ## Optimization
 
 These examples demonstrate use of the optimization routines

examples/01_opening_floris_computing_power.py

@@ -51,7 +51,7 @@
 print(turbine_powers)
 print("Shape: ",turbine_powers.shape)
 
-# Single wind speed and wind direction
+# Single wind speed and multiple wind directions
 print('\n========================= Single Wind Direction and Multiple Wind Speeds ===============')
 
 
@@ -64,7 +64,7 @@
 print(turbine_powers)
 print("Shape: ",turbine_powers.shape)
 
-# Single wind speed and wind direction
+# Multiple wind speeds and multiple wind directions
 print('\n========================= Multiple Wind Directions and Multiple Wind Speeds ============')
 
 wind_directions = np.array([260., 270., 280.])

examples/02_visualizations.py

@@ -18,10 +18,6 @@
 
 import floris.tools.visualization as wakeviz
 from floris.tools import FlorisInterface
-from floris.tools.visualization import (
-    calculate_horizontal_plane_with_turbines,
-    visualize_cut_plane,
-)
 
 
 """
@@ -78,23 +74,39 @@
 # Create the plots
 fig, ax_list = plt.subplots(3, 1, figsize=(10, 8))
 ax_list = ax_list.flatten()
-wakeviz.visualize_cut_plane(horizontal_plane, ax=ax_list[0], title="Horizontal")
-wakeviz.visualize_cut_plane(y_plane, ax=ax_list[1], title="Streamwise profile")
-wakeviz.visualize_cut_plane(cross_plane, ax=ax_list[2], title="Spanwise profile")
+wakeviz.visualize_cut_plane(
+    horizontal_plane,
+    ax=ax_list[0],
+    label_contours=True,
+    title="Horizontal"
+)
+wakeviz.visualize_cut_plane(
+    y_plane,
+    ax=ax_list[1],
+    label_contours=True,
+    title="Streamwise profile"
+)
+wakeviz.visualize_cut_plane(
+    cross_plane,
+    ax=ax_list[2],
+    label_contours=True,
+    title="Spanwise profile"
+)
 
 # Some wake models may not yet have a visualization method included, for these cases can use
 # a slower version which scans a turbine model to produce the horizontal flow
-horizontal_plane_scan_turbine = calculate_horizontal_plane_with_turbines(
+horizontal_plane_scan_turbine = wakeviz.calculate_horizontal_plane_with_turbines(
     fi,
     x_resolution=20,
     y_resolution=10,
     yaw_angles=np.array([[[25.,0.,0.]]]),
 )
 
 fig, ax = plt.subplots()
-visualize_cut_plane(
+wakeviz.visualize_cut_plane(
     horizontal_plane_scan_turbine,
     ax=ax,
+    label_contours=True,
     title="Horizontal (coarse turbine scan method)",
 )
 

examples/12_optimize_yaw_in_parallel.py

@@ -67,12 +67,13 @@ def load_windrose():
     )
 
     # Pour this into a parallel computing interface
+    parallel_interface = "concurrent"
     fi_aep_parallel = ParallelComputingInterface(
         fi=fi_aep,
         max_workers=max_workers,
         n_wind_direction_splits=max_workers,
         n_wind_speed_splits=1,
-        use_mpi4py=False,
+        interface=parallel_interface,
         print_timings=True,
     )
 
@@ -113,7 +114,7 @@ def load_windrose():
         max_workers=max_workers,
         n_wind_direction_splits=max_workers,
         n_wind_speed_splits=1,
-        use_mpi4py=False,
+        interface=parallel_interface,
         print_timings=True,
     )