Refactor examples

.github/workflows/check-working-examples.yaml

@@ -36,19 +36,22 @@ jobs:
         error_found=0  # 0 is false
         error_results="Error in example:"
 
-        # Run each Python script example
-        for i in *.py; do
-
-          # Skip these examples until the wind rose, optimization package, and
-          # uncertainty interface are update to v4
-          if [[ $i == *20* ]]; then
-            continue
+        # Now run the examples in root and  subdirectories
+        echo "Running examples"
+        for d in . $(find . -type d -name "*examples*"); do
+          cd $d
+          echo "========================= Example directory- $d"
+          for i in *.py; do
+            echo "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Running example- $i"
+            if ! python $i; then
+              error_results="${error_results}"$'\n'" - ${i}"
+              error_found=1
+            fi
+          done
+          if [ "$d" != "." ]; then
+            cd ..
           fi
 
-          if ! python $i; then
-            error_results="${error_results}"$'\n'" - ${i}"
-            error_found=1
-          fi
         done
 
         if [[ $error_found ]]; then

examples/01_opening_floris_computing_power.py → examples/001_opening_floris_computing_power.py

@@ -1,6 +1,6 @@
 """Example 1: Opening FLORIS and Computing Power
 
-This first example illustrates several of the key concepts in FLORIS. It:
+This example illustrates several of the key concepts in FLORIS. It:
 
   1) Initializing FLORIS
   2) Changing the wind farm layout
@@ -17,22 +17,22 @@
 from floris import FlorisModel
 
 
-# Initialize FLORIS with the given input file.
-# The Floris class is the entry point for most usage.
+# The FlorisModel class is the entry point for most usage.
+# Initialize using an input yaml file
 fmodel = FlorisModel("inputs/gch.yaml")
 
 # Changing the wind farm layout uses FLORIS' set method to a two-turbine layout
 fmodel.set(layout_x=[0, 500.0], layout_y=[0.0, 0.0])
 
-# Changing wind speed, wind direction, and turbulence intensity using the set method
+# Changing wind speed, wind direction, and turbulence intensity uses the set method
 # as well. Note that the wind_speeds, wind_directions, and turbulence_intensities
 # are all specified as arrays of the same length.
-fmodel.set(wind_directions=np.array([270.0]),
-       wind_speeds=[8.0],
-        turbulence_intensities=np.array([0.06]))
+fmodel.set(
+    wind_directions=np.array([270.0]), wind_speeds=[8.0], turbulence_intensities=np.array([0.06])
+)
 
 # Note that typically all 3, wind_directions, wind_speeds and turbulence_intensities
-# must be supplied to set.  However, the exception is if not changing the lenght
+# must be supplied to set.  However, the exception is if not changing the length
 # of the arrays, then only one or two may be supplied.
 fmodel.set(turbulence_intensities=np.array([0.07]))
 
@@ -42,9 +42,11 @@
 # be unique.  Internally in FLORIS, most data structures will have the findex as their
 # 0th dimension.  The value n_findex is the total number of conditions to be simulated.
 # This command would simulate 4 conditions (n_findex = 4).
-fmodel.set(wind_directions=np.array([270.0, 270.0, 270.0, 270.0]),
-        wind_speeds=[8.0, 8.0, 10.0, 10.0],
-        turbulence_intensities=np.array([0.06, 0.06, 0.06, 0.06]))
+fmodel.set(
+    wind_directions=np.array([270.0, 270.0, 270.0, 270.0]),
+    wind_speeds=[8.0, 8.0, 10.0, 10.0],
+    turbulence_intensities=np.array([0.06, 0.06, 0.06, 0.06]),
+)
 
 # After the set method, the run method is called to perform the simulation
 fmodel.run()

examples/002_visualizations.py

@@ -0,0 +1,91 @@
+"""Example 2: Visualizations
+
+This example demonstrates the use of the flow and layout visualizations in FLORIS.
+
+FLORIS includes two modules for visualization:
+  1) flow_visualization: for visualizing the flow field
+  2) layout_visualization: for visualizing the layout of the wind farm
+The two modules can be used together to visualize the flow field and the layout
+of the wind farm.
+
+"""
+
+
+import matplotlib.pyplot as plt
+
+import floris.layout_visualization as layoutviz
+from floris import FlorisModel
+from floris.flow_visualization import visualize_cut_plane
+
+
+fmodel = FlorisModel("inputs/gch.yaml")
+
+# Set the farm layout to have 8 turbines irregularly placed
+layout_x = [0, 500, 0, 128, 1000, 900, 1500, 1250]
+layout_y = [0, 300, 750, 1400, 0, 567, 888, 1450]
+fmodel.set(layout_x=layout_x, layout_y=layout_y)
+
+
+# Layout visualization contains the functions for visualizing the layout:
+# plot_turbine_points
+# plot_turbine_labels
+# plot_turbine_rotors
+# plot_waking_directions
+# Each of which can be overlaid to provide further information about the layout
+# This series of 4 subplots shows the different ways to visualize the layout
+
+# Create the plotting objects using matplotlib
+fig, axarr = plt.subplots(2, 2, figsize=(15, 10), sharex=False)
+axarr = axarr.flatten()
+
+ax = axarr[0]
+layoutviz.plot_turbine_points(fmodel, ax=ax)
+ax.set_title("Turbine Points")
+
+ax = axarr[1]
+layoutviz.plot_turbine_points(fmodel, ax=ax)
+layoutviz.plot_turbine_labels(fmodel, ax=ax)
+ax.set_title("Turbine Points and Labels")
+
+ax = axarr[2]
+layoutviz.plot_turbine_points(fmodel, ax=ax)
+layoutviz.plot_turbine_labels(fmodel, ax=ax)
+layoutviz.plot_waking_directions(fmodel, ax=ax, limit_num=2)
+ax.set_title("Turbine Points, Labels, and Waking Directions")
+
+# In the final subplot, use provided turbine names in place of the t_index
+ax = axarr[3]
+turbine_names = ["T1", "T2", "T3", "T4", "T9", "T10", "T75", "T78"]
+layoutviz.plot_turbine_points(fmodel, ax=ax)
+layoutviz.plot_turbine_labels(fmodel, ax=ax, turbine_names=turbine_names)
+layoutviz.plot_waking_directions(fmodel, ax=ax, limit_num=2)
+ax.set_title("Use Provided Turbine Names")
+
+
+# Visualizations of the flow field are made by using calculate plane methods.  In this example
+# we show the horizontal plane at hub height, further examples are provided within
+# the examples_visualizations folder
+
+# For flow visualizations, the FlorisModel must be set to run a single condition
+# (n_findex = 1)
+fmodel.set(wind_speeds=[8.0], wind_directions=[290.0], turbulence_intensities=[0.06])
+horizontal_plane = fmodel.calculate_horizontal_plane(
+    x_resolution=200,
+    y_resolution=100,
+    height=90.0,
+)
+
+# Plot the flow field with rotors
+fig, ax = plt.subplots()
+visualize_cut_plane(
+    horizontal_plane,
+    ax=ax,
+    label_contours=False,
+    title="Horizontal Flow with Turbine Rotors and labels",
+)
+
+# Plot the turbine rotors
+layoutviz.plot_turbine_rotors(fmodel, ax=ax)
+layoutviz.plot_turbine_labels(fmodel, ax=ax, turbine_names=turbine_names)
+
+plt.show()

examples/003_wind_data_objects.py

@@ -0,0 +1,217 @@
+"""Example 3: Wind Data Objects
+
+This example demonstrates the use of wind data objects in FLORIS:
+ TimeSeries,
+ WindRose, and WindTIRose.
+
+
+Main concept is introduce FLORIS and illustrate essential structure
+of most-used FLORIS calls
+"""
+
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from floris import (
+    FlorisModel,
+    TimeSeries,
+    WindRose,
+    WindTIRose,
+)
+
+
+##################################################
+# Initializing
+##################################################
+
+# FLORIS provides a set of wind data objects to hold the ambient wind conditions in a
+# convenient classes that include capabilities and methods to manipulate and visualize
+# the data.
+
+# The TimeSeries class is used to hold time series data, such as wind speed, wind direction,
+# and turbulence intensity.
+
+# Generate wind speeds, directions, and turbulence intensities via random signals
+N = 100
+wind_speeds = 8 + 2 * np.random.randn(N)
+wind_directions = 270 + 30 * np.random.randn(N)
+turbulence_intensities = 0.06 + 0.02 * np.random.randn(N)
+
+time_series = TimeSeries(
+    wind_directions=wind_directions,
+    wind_speeds=wind_speeds,
+    turbulence_intensities=turbulence_intensities,
+)
+
+# The WindRose class is used to hold wind rose data, such as wind speed, wind direction,
+# and frequency.  TI is represented as a bin average per wind direction and speed bin.
+wind_directions = np.arange(0, 360, 3.0)
+wind_speeds = np.arange(4, 20, 2.0)
+
+# Make TI table 6% TI for all wind directions and speeds
+ti_table = 0.06 * np.ones((len(wind_directions), len(wind_speeds)))
+
+# Uniform frequency
+freq_table = np.ones((len(wind_directions), len(wind_speeds)))
+freq_table = freq_table / np.sum(freq_table)
+
+wind_rose = WindRose(
+    wind_directions=wind_directions,
+    wind_speeds=wind_speeds,
+    ti_table=ti_table,
+    freq_table=freq_table,
+)
+
+# The WindTIRose class is similar to the WindRose table except that TI is also binned
+# making the frequency table a 3D array.
+turbulence_intensities = np.arange(0.05, 0.15, 0.01)
+
+# Uniform frequency
+freq_table = np.ones((len(wind_directions), len(wind_speeds), len(turbulence_intensities)))
+
+wind_ti_rose = WindTIRose(
+    wind_directions=wind_directions,
+    wind_speeds=wind_speeds,
+    turbulence_intensities=turbulence_intensities,
+    freq_table=freq_table,
+)
+
+##################################################
+# Broadcasting
+##################################################
+
+# A convenience method of the wind data objects is that, unlike the lower-level
+# FlorisModel.set() method, the wind data objects can broadcast upward data provided
+# as a scalar to the full array.  This is useful for setting the same wind conditions
+# for all turbines in a wind farm.
+
+# For TimeSeries, as long as one condition is given as an array, the other 2
+# conditions can be given as scalars.  The TimeSeries object will broadcast the
+# scalars to the full array (uniform)
+wind_directions = 270 + 30 * np.random.randn(N)
+time_series = TimeSeries(
+    wind_directions=wind_directions, wind_speeds=8.0, turbulence_intensities=0.06
+)
+
+
+# For WindRose, wind directions and wind speeds must be given as arrays, but the
+# ti_table can be supplied as a scalar which will apply uniformly to all wind
+# directions and speeds.  Not supplying a freq table will similarly generate
+# a uniform frequency table.
+wind_directions = np.arange(0, 360, 3.0)
+wind_speeds = np.arange(4, 20, 2.0)
+wind_rose = WindRose(wind_directions=wind_directions, wind_speeds=wind_speeds, ti_table=0.06)
+
+
+##################################################
+# Wind Rose from Time Series
+##################################################
+
+# The TimeSeries class has a method to generate a wind rose from a time series based on binning
+wind_rose = time_series.to_WindRose(wd_edges=np.arange(0, 360, 3.0), ws_edges=np.arange(4, 20, 2.0))
+
+##################################################
+# Wind Rose from long CSV FILE
+##################################################
+
+# The WindRose class can also be initialized from a long CSV file.  By long what is meant is
+# that the file has a column for each wind direction, wind speed combination.  The file can
+# also specify the mean TI per bin and the frequency of each bin as seperate columns.
+
+# If the TI is not provided, can specify a fixed TI for all bins using the ti_col_or_value
+# input
+wind_rose_from_csv = WindRose.read_csv_long(
+    "inputs/wind_rose.csv", wd_col="wd", ws_col="ws", freq_col="freq_val", ti_col_or_value=0.06
+)
+
+##################################################
+# Setting turbulence intensity
+##################################################
+
+# Each of the wind data objects also has the ability to set the turbulence intensity
+# according to a function of wind speed and direction.  This can be done using
+# a custom function by using the function assign_ti_using_IEC_method which assigns
+# TI based on the IEC 61400-1 standard
+wind_rose.assign_ti_using_IEC_method()  # Assign using default settings for Iref and offset
+
+
+##################################################
+# Plotting Wind Data Objects
+##################################################
+
+# Certain plotting methods are included to enable visualization of the wind data objects
+# Plotting a wind rose
+wind_rose.plot_wind_rose()
+
+# Showing TI over wind speed for a WindRose
+wind_rose.plot_ti_over_ws()
+
+##################################################
+# Assigning value to wind data objects
+##################################################
+
+# Wind data objects can also hold value information, such as the price of electricity for different
+# time periods or wind conditions.  These can then be used in later optimization methods to optimize
+# for quantities besides AEP.
+
+N = 100
+wind_speeds = 8 + 2 * np.random.randn(N)
+values = 1 / wind_speeds  # Assume Value is inversely proportional to wind speed
+
+time_series = TimeSeries(
+    wind_directions=270.0, wind_speeds=wind_speeds, turbulence_intensities=0.06, values=values
+)
+
+##################################################
+# Setting the FLORIS model via wind data
+##################################################
+
+# Each of the wind data objects can be used to set the FLORIS model by passing
+# them in as is to the set method.  The FLORIS model will then use the member functions
+# of the wind data to extract the wind conditions for the simulation.  Frequency tables
+# are also extracted for expected power and AEP-like calculations.
+# Similarly the value data is extracted and maintained.
+
+fmodel = FlorisModel("inputs/gch.yaml")
+
+# Set the wind conditions using the TimeSeries object
+fmodel.set(wind_data=time_series)
+
+# Set the wind conditions using the WindRose object
+fmodel.set(wind_data=wind_rose)
+
+# Note that in the case of the wind_rose, under the default settings, wind direction and wind speed
+# bins for which frequency is zero are not simulated.  This can be changed by setting the
+# compute_zero_freq_occurrence parameter to True.
+wind_directions = np.array([200.0, 300.0])
+wind_speeds = np.array([5.0, 1.00])
+freq_table = np.array([[0.5, 0], [0.5, 0]])
+wind_rose = WindRose(
+    wind_directions=wind_directions, wind_speeds=wind_speeds, ti_table=0.06, freq_table=freq_table
+)
+fmodel.set(wind_data=wind_rose)
+
+print(
+    f"Number of conditions to simulate with compute_zero_freq_occurrence"
+    f"False: {fmodel.n_findex}"
+)
+
+wind_rose = WindRose(
+    wind_directions=wind_directions,
+    wind_speeds=wind_speeds,
+    ti_table=0.06,
+    freq_table=freq_table,
+    compute_zero_freq_occurrence=True,
+)
+fmodel.set(wind_data=wind_rose)
+
+print(
+    f"Number of conditions to simulate with compute_zero_freq_occurrence"
+    f"True: {fmodel.n_findex}"
+)
+
+# Set the wind conditions using the WindTIRose object
+fmodel.set(wind_data=wind_ti_rose)
+
+plt.show()