Correct and add docstrings, comments and headers

Author: SabineHaas

windpowerlib/power_curves.py

@@ -1,6 +1,7 @@
 """
-The ``power_curves`` module contains functions for applying alterations to the
-power curve of a wind turbine, wind farm or wind turbine cluster.
+The ``power_curves`` module contains functions for applying alterations like
+power curve smoohting or reducing power values by an efficiency to the power
+curve of a wind turbine, wind farm or wind turbine cluster.
 
 """
 
@@ -21,22 +22,23 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
 
     Parameters
     ----------
-    power_curve_wind_speeds : pandas.Series
+    power_curve_wind_speeds : pandas.Series or numpy.array
         Wind speeds in m/s for which the power curve values are provided in
         `power_curve_values`.
     power_curve_values : pandas.Series or numpy.array
         Power curve values corresponding to wind speeds in
         `power_curve_wind_speeds`.
     block_width : float
-        Width of the moving block. Default: 0.5.
+        Width between the wind speeds in the sum of the equation shown below in
+        Notes. Default: 0.5.
     wind_speed_range : float
         The sum in the equation below is taken for this wind speed range below
         and above the power curve wind speed. Default: 15.0.
     standard_deviation_method : string
         Method for calculating the standard deviation for the Gauss
         distribution. Options: 'turbulence_intensity', 'Staffell_Pfenninger'.
         Default: 'turbulence_intensity'.
-    mean_gauss : float or integer
+    mean_gauss : float
         Mean of the Gaus distribution in
         :py:func:`~.tools.gauss_distribution`:. Default: 0.
 
@@ -49,9 +51,8 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
     Returns
     -------
     smoothed_power_curve_df : pd.DataFrame
-        Smoothed power curve. DataFrame has 'wind_speed' and
-        'power' columns with wind speeds in m/s and the corresponding power
-        curve value in W.
+        Smoothed power curve. DataFrame has 'wind_speed' and 'power' columns
+        with wind speeds in m/s and the corresponding power curve value in W.
 
     Notes
     -----
@@ -60,17 +61,19 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
         P_{smoothed}(v_{std}) = \sum\limits_{v_i}^{} \Delta v_i \cdot P(v_i)
         \cdot \frac{1}{\sigma \sqrt{2 \pi}}
         \exp \left[-\frac{(v_{std} - v_i -\mu)^2}{2 \sigma^2} \right]
-    
+
     with:
         P: power [W], v: wind speed [m/s],
-        :math:`\sigma`: standard deviation (Gauss), :math: `\mu`: mean (Gauss),
-        
+        :math:`\sigma`: standard deviation (Gauss), :math: `\mu`: mean (Gauss)
+
         :math:`P_{smoothed}` is the smoothed power curve value,
         :math:`v_{std}` is the standard wind speed in the power curve,
         :math: `\Delta v_i` is the interval length between
         :math: `$v_\text{i}$` and :math: `$v_\text{i+1}$`
-    
-    This way of smoothing power curves is also used in [2]_ and [3]_.
+
+    Power curve smoothing is applied to take account for the spatial
+    distribution of wind speed. This way of smoothing power curves is also used
+    in [2]_ and [3]_.
 
     References
     ----------
@@ -99,7 +102,7 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
         normalized_standard_deviation = 0.2
     # Initialize list for power curve values
     smoothed_power_curve_values = []
-    # Append wind speeds to `power_curve_wind_speeds` until last value + range
+    # Append wind speeds to `power_curve_wind_speeds`
     maximum_value = power_curve_wind_speeds.values[-1] + wind_speed_range
     while (power_curve_wind_speeds.values[-1] < maximum_value):
         power_curve_wind_speeds = power_curve_wind_speeds.append(
@@ -108,11 +111,10 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
         power_curve_values = power_curve_values.append(
             pd.Series(0.0, index=[power_curve_values.index[-1] + 1]))
     for power_curve_wind_speed in power_curve_wind_speeds:
-        # Create array of wind speeds for the moving block
-        wind_speeds_block = (np.arange(-wind_speed_range,
-                                       wind_speed_range + block_width,
-                                       block_width) +
-                             power_curve_wind_speed)
+        # Create array of wind speeds for the sum
+        wind_speeds_block = (np.arange(
+            -wind_speed_range, wind_speed_range + block_width, block_width) +
+            power_curve_wind_speed)
         # Get standard deviation for Gauss function
         standard_deviation = (
             (power_curve_wind_speed * normalized_standard_deviation + 0.6)
@@ -126,15 +128,14 @@ def smooth_power_curve(power_curve_wind_speeds, power_curve_values,
                 power_curve_wind_speed - wind_speed,
                 standard_deviation, mean_gauss)
             for wind_speed in wind_speeds_block)
-        # Add value to list - add 0 if `smoothed_value` is nan. This occurs
-        # because the Gauss distribution is not defined for 0.
+        # Add value to list - add 0 if `smoothed_value` is nan.
         smoothed_power_curve_values.append(0 if np.isnan(smoothed_value)
                                            else smoothed_value)
-    # Create smoothed power curve DataFrame
+    # Create smoothed power curve data frame
     smoothed_power_curve_df = pd.DataFrame(
         data=[list(power_curve_wind_speeds.values),
               smoothed_power_curve_values]).transpose()
-    # Rename columns of DataFrame
+    # Rename columns of the data frame
     smoothed_power_curve_df.columns = ['wind_speed', 'power']
     return smoothed_power_curve_df
 
@@ -147,7 +148,7 @@ def wake_losses_to_power_curve(power_curve_wind_speeds, power_curve_values,
 
     Parameters
     ----------
-    power_curve_wind_speeds : pandas.Series
+    power_curve_wind_speeds : pandas.Series or numpy.array
         Wind speeds in m/s for which the power curve values are provided in
         `power_curve_values`.
     power_curve_values : pandas.Series or numpy.array
@@ -157,10 +158,9 @@ def wake_losses_to_power_curve(power_curve_wind_speeds, power_curve_values,
         Efficiency of the wind farm. Either constant (float) or efficiency
         curve (pd.DataFrame) containing 'wind_speed' and 'efficiency' columns
         with wind speeds in m/s and the corresponding dimensionless wind farm
-        efficiency (reduction of power).
-        Default: None.
+        efficiency (reduction of power). Default: None.
     wake_losses_model : String
-        Defines the method for talking wake losses within the farm into
+        Defines the method for taking wake losses within the farm into
         consideration. Options: 'power_efficiency_curve',
         'constant_efficiency'. Default: 'power_efficiency_curve'.
 
@@ -193,8 +193,8 @@ def wake_losses_to_power_curve(power_curve_wind_speeds, power_curve_values,
                     wake_losses_model, wind_farm_efficiency))
         df = pd.concat([power_curve_df.set_index('wind_speed'),
                         wind_farm_efficiency.set_index('wind_speed')], axis=1)
-        # Add by efficiency reduced power column (nan values of efficiency
-        # are interpolated)
+        # Add column with reduced power (nan values of efficiency are
+        # interpolated)
         df['reduced_power'] = df['power'] * df['efficiency'].interpolate(
             method='index')
         reduced_power = df['reduced_power'].dropna()

windpowerlib/tools.py

@@ -43,7 +43,8 @@ def linear_interpolation_extrapolation(df, target_height):
 
     For the inter- and extrapolation the following equation is used:
 
-    .. math:: f(x) = \frac{(f(x_2) - f(x_1))}{(x_2 - x_1)} \cdot (x - x_1) + f(x_1)
+    .. math:: f(x) = \frac{(f(x_2) - f(x_1))}{(x_2 - x_1)} \cdot
+        (x - x_1) + f(x_1)
 
     Examples
     ---------
@@ -106,7 +107,8 @@ def logarithmic_interpolation_extrapolation(df, target_height):
     For the logarithmic inter- and extrapolation the following equation is
     used [1]_:
 
-    .. math:: f(x) = \frac{\ln(x) \cdot (f(x_2) - f(x_1)) - f(x_2) \cdot \ln(x_1) + f(x_1) \cdot \ln(x_2)}{\ln(x_2) - \ln(x_1)}
+    .. math:: f(x) = \frac{\ln(x) \cdot (f(x_2) - f(x_1)) - f(x_2) \cdot
+        \ln(x_1) + f(x_1) \cdot \ln(x_2)}{\ln(x_2) - \ln(x_1)}
 
     References
     ----------
@@ -131,6 +133,9 @@ def gauss_distribution(function_variable, standard_deviation, mean=0):
     r"""
     Gauss distribution.
 
+    The Gauss distribution is used in the function
+    :py:func:`~.power_curves.smooth_power_curve`: for power curve smoothing.
+
     Parameters
     ----------
     function_variable : float
@@ -143,7 +148,8 @@ def gauss_distribution(function_variable, standard_deviation, mean=0):
     Returns
     -------
     pandas.Series or numpy.array
-        Wind speed at hub height. Data type depends on type of `wind_speed`.
+        Wind speed at hub height. Data type depends on the type of
+        `wind_speed`.
 
     Notes
     -----
@@ -160,8 +166,6 @@ def gauss_distribution(function_variable, standard_deviation, mean=0):
     .. [1] Berendsen, H.: "A Student's Guide to Data and Error Analysis".
              New York, Cambridge University Press, 2011, p. 37
 
-    # TODO: add references
-
     """
     return (1 / (standard_deviation * np.sqrt(2 * np.pi)) *
             np.exp(-(function_variable - mean)**2 /
@@ -170,11 +174,11 @@ def gauss_distribution(function_variable, standard_deviation, mean=0):
 
 def estimate_turbulence_intensity(height, roughness_length):
     """
-    Calculate turbulence intensity.
+    Estimate turbulence intensity by the roughness length.
 
     Parameters
     ----------
-    height : Float
+    height : float
         Height above ground in m at which the turbulence intensity is
         calculated.
     roughness_length : pandas.Series or numpy.array or float
@@ -184,7 +188,7 @@ def estimate_turbulence_intensity(height, roughness_length):
     -----
     The following equation is used [1]_:
 
-    .. math:: TI = \frac{1}{ln \left(\frac{h}{z_\text{0}} \right)}
+    .. math:: TI \approx \frac{1}{ln \left(\frac{h}{z_\text{0}} \right)}
 
     with:
         TI: turbulence intensity, h: height, :math:`z_{0}`: roughness length

windpowerlib/turbine_cluster_modelchain.py

@@ -17,29 +17,29 @@ class TurbineClusterModelChain(ModelChain):
 
     Parameters
     ----------
-    wind_object : WindFarm or WindTurbineCluster
+    power_plant : WindFarm or WindTurbineCluster
         A :class:`~.wind_farm.WindFarm` object representing the wind farm or
         a :class:`~.wind_turbine_cluster.WindTurbineCluster` object
         representing the wind turbine cluster.
-    wake_losses_model : String
+    wake_losses_model : string
         Defines the method for talking wake losses within the farm into
-        consideration. Options: 'power_efficiency_curve',
-        'constant_efficiency', 'dena_mean', 'knorr_mean', 'dena_extreme1',
-        'dena_extreme2', 'knorr_extreme1', 'knorr_extreme2', 'knorr_extreme3'
-        or None. Default: 'dena_mean'.
-    smoothing : Boolean
-        If True the power curves will be smoothed before the summation.
+        consideration. Options: None, 'power_efficiency_curve' or
+        'constant_efficiency' or the name of a wind efficiency curve like
+        'dena_mean'. Default: 'dena_mean'.
+        Use :py:func:`~.wake_losses.display_wind_efficiency_curves`: to see a
+        list of all provided wind efficiency curves.
+    smoothing : boolean
+        If True the power curves will be smoothed before or after the
+        aggregation of power curves depending on `smoothing_order`.
         Default: False.
-    block_width : Float, optional
-        Width of the moving block.
-        Default in :py:func:`~.power_curves.smooth_power_curve`: 0.5.
-    standard_deviation_method : String, optional
-        Method for calculating the standard deviation for the gaussian
-        distribution. Options: 'turbulence_intensity', 'Norgaard',
-        'Staffell_Pfenninger'.
-        Default in :py:func:`~.power_curves.smooth_power_curve`:
-        'turbulence_intensity'.
-    smoothing_order : String
+    block_width : float
+        Width between the wind speeds in the sum of the equation in
+        :py:func:`~.power_curves.smooth_power_curve`:. Default: 0.5.
+    standard_deviation_method : string
+        Method for calculating the standard deviation for the Gauss
+        distribution. Options: 'turbulence_intensity', 'Staffell_Pfenninger'.
+        Default: 'turbulence_intensity'.
+    smoothing_order : string
         Defines when the smoothing takes place if `smoothing` is True. Options:
         'turbine_power_curves' (to the single turbine power curves),
         'wind_farm_power_curves'. Default: 'wind_farm_power_curves'.
@@ -79,30 +79,32 @@ class TurbineClusterModelChain(ModelChain):
         A :class:`~.wind_farm.WindFarm` object representing the wind farm or
         a :class:`~.wind_turbine_cluster.WindTurbineCluster` object
         representing the wind turbine cluster.
-    wake_losses_model : String
+    wake_losses_model : string
         Defines the method for talking wake losses within the farm into
-        consideration. Options: 'power_efficiency_curve',
-        'constant_efficiency', 'dena_mean', 'knorr_mean', 'dena_extreme1',
-        'dena_extreme2', 'knorr_extreme1', 'knorr_extreme2', 'knorr_extreme3'
-        or None. Default: 'dena_mean'.
-    smoothing : Boolean
-        If True the power curves will be smoothed before the summation.
+        consideration. Options: None, 'power_efficiency_curve' or
+        'constant_efficiency' or the name of a wind efficiency curve like
+        'dena_mean'. Default: 'dena_mean'.
+        Use :py:func:`~.wake_losses.display_wind_efficiency_curves`: to see a
+        list of all provided wind efficiency curves.
+    smoothing : boolean
+        If True the power curves will be smoothed before or after the
+        aggregation of power curves depending on `smoothing_order`.
         Default: False.
-    block_width : Float, optional
-        Width of the moving block.
-        Default in :py:func:`~.power_curves.smooth_power_curve`: 0.5.
-    standard_deviation_method : String, optional
-        Method for calculating the standard deviation for the gaussian
-        distribution. Options: 'turbulence_intensity', 'Norgaard',
-        'Staffell_Pfenninger'.
-        Default in :py:func:`~.power_curves.smooth_power_curve`:
-        'turbulence_intensity'.
-    power_output : pandas.Series
-        Electrical power output of the wind turbine in W.
-    smoothing_order : String
+    block_width : float
+        Width between the wind speeds in the sum of the equation in
+        :py:func:`~.power_curves.smooth_power_curve`:. Default: 0.5.
+    standard_deviation_method : string
+        Method for calculating the standard deviation for the Gauss
+        distribution. Options: 'turbulence_intensity', 'Staffell_Pfenninger'.
+        Default: 'turbulence_intensity'.
+    smoothing_order : string
         Defines when the smoothing takes place if `smoothing` is True. Options:
         'turbine_power_curves' (to the single turbine power curves),
         'wind_farm_power_curves'. Default: 'wind_farm_power_curves'.
+    power_output : pandas.Series
+        Electrical power output of the wind turbine in W.
+    pandas.DataFrame or None
+        The calculated power curve of the wind farm.
     wind_speed_model : string
         Parameter to define which model to use to calculate the wind speed
         at hub height. Valid options are 'logarithmic', 'hellman' and