rewrite, reduce helpers, remove while loop

Author: cwhanse

pvlib/snowcoverage.py

@@ -8,90 +8,33 @@
 from pvlib.tools import sind
 
 
-def _snow_slide_amount(surface_tilt, sliding_coefficient=1.97,
-                       time_step=1):
-    '''
-    Calculates the amount of snow that slides off in each time step.
-
-    Parameters
-    ----------
-    surface_tilt : numeric
-        Surface tilt angles in decimal degrees. Tilt must be >=0 and
-        <=180. The tilt angle is defined as degrees from horizontal
-        (e.g. surface facing up = 0, surface facing horizon = 90).
-
-
-    sliding_coefficient : numeric
-        An empirically determined coefficient used in [1] to determine
-        how much snow slides off if a sliding event occurs.
-
-    time_step: float
-        Period of the data. [hour]
-
-    Returns
-    ----------
-    slide_amount : numeric
-        The fraction of panel slant height from which snow slides off
-        at each time step, in tenths of the panel's slant height.
-    '''
-
-    return sliding_coefficient / 10 * sind(surface_tilt) * time_step
-
-
-def _snow_slide_event(poa_irradiance, temperature,
-                      m=-80):
-    '''
-    Calculates when snow sliding events will occur.
-
-    Parameters
-    ----------
-    poa_irradiance : numeric
-        Total in-plane irradiance [W/m^2]
-
-    temperature : numeric
-        Ambient air temperature at the surface [C]
-
-    m : numeric
-        A coefficient used in the model described in [1]. [W/m^2 C]
-
-    Returns
-    ----------
-    slide_event : boolean array
-        True if the condiditions are suitable for a snow slide event.
-        False elsewhere.
-    '''
-
-    return temperature > poa_irradiance / m
+def _time_delta_in_hours(times):
+    delta = times.to_series().diff()
+    return delta.dt.seconds.div(3600)
 
 
-def fully_covered_panel(snow_data, time_step=1,
-                        snow_data_type="snowfall"):
+def fully_covered(snowfall, threshold=1.):
     '''
-    Calculates the timesteps when the panel is presumed to be fully covered
+    Calculates the timesteps when the row's slant height is fully covered
     by snow.
 
     Parameters
     ----------
-    snow_data : numeric
-        Time series data on either snowfall (cm/hr) or ground snow depth (cm).
-        The type of data should be specified in snow_data_type.
+    snowfall : Series
+        Accumulated snowfall in each time period [cm]
 
-    time_step: float
-        Period of the data. [hour]
-
-    snow_data_type : string
-        Defines what type of data is being passed as snow_data. Acceptable
-        values are "snowfall" and "snow_depth".
+    threshold : float, default 1.0
+        Minimum hourly snowfall to cover a row's slant height. [cm/hr]
 
     Returns
     ----------
-    fully_covered_mask : boolean array
+    boolean: Series
         True where the snowfall exceeds the defined threshold to fully cover
-        the panel. False elsewhere.
+        the panel.
 
     Notes
     -----
-    Implements the model described in [1] with minor improvements in [2].
+    Implements the model described in [1]_ with minor improvements in [2]_.
 
     References
     ----------
@@ -101,60 +44,38 @@ def fully_covered_panel(snow_data, time_step=1,
     .. [2] Ryberg, D; Freeman, J. "Integration, Validation, and Application
        of a PV Snow Coverage Model in SAM" (2017) NREL Technical Report
     '''
-    if snow_data_type == "snow_depth":
-        prev_data = snow_data.shift(1)
-        prev_data[0] = 0
-        snowfall = snow_data - prev_data
-    elif snow_data_type == "snowfall":
-        snowfall = snow_data
-    else:
-        raise ValueError('snow_data_type was not specified or was not set to a'
-                         'valid option (snowfall, snow_depth).')
-
-    time_adjusted = snowfall / time_step
-    fully_covered_mask = time_adjusted >= 1
-    return fully_covered_mask
-
-
-def snow_coverage_model(snow_data, snow_data_type,
-                        poa_irradiance, temperature, surface_tilt,
-                        time_step=1, m=-80, sliding_coefficient=1.97):
+    delta = snowfall.index.to_series().diff()  # [0] will be NaT
+    timestep = delta.dt.seconds.div(3600)  # convert to hours
+    time_adjusted = snowfall / timestep
+    time_adjusted.iloc[0] = 0  # replace NaN from NaT / timestep
+    return time_adjusted >= threshold
+
+
+def snow_coverage_nrel(snowfall, poa_irradiance, temperature, surface_tilt,
+                       threshold_snowfall=1., m=-80,
+                       sliding_coefficient=0.197):
     '''
     Calculates the fraction of the slant height of a row of modules covered by
     snow at every time step.
 
     Parameters
     ----------
-    snow_data : Series
-        Time series data on either snowfall or ground snow depth. The type of
-        data should be specified in snow_data_type. The original model was
-        designed for ground snowdepth only. (cm/hr or cm)
-
-    snow_data_type : string
-        Defines what type of data is being passed as snow_data. Acceptable
-        values are "snowfall" and "snow_depth". "snowfall" will be in units of
-        cm/hr. "snow_depth" is in units of cm.
-
+    snowfall : Series
+        Accumulated snowfall at the end of each time period. [cm]
     poa_irradiance : Series
-        Total in-plane irradiance (W/m^2)
-
+        Total in-plane irradiance [W/m^2]
     temperature : Series
-        Ambient air temperature at the surface (C)
-
+        Ambient air temperature at the surface [C]
     surface_tilt : numeric
-        Surface tilt angles in decimal degrees. Tilt must be >=0 and
-        <=180. The tilt angle is defined as degrees from horizontal
-        (e.g. surface facing up = 0, surface facing horizon = 90).
-
-    time_step: float
-        Period of the data. [hour]
-
-    sliding coefficient : numeric
-        Empirically determined coefficient used in [1] to determine how much
-        snow slides off if a sliding event occurs.
-
+        Tilt of module's from horizontal, e.g. surface facing up = 0,
+        surface facing horizon = 90. Must be between 0 and 180. [degrees]
+    threshold_snowfall : float, default 1.0
+        Minimum hourly snowfall to cover a row's slant height. [cm/hr]
     m : numeric
-        A coefficient used in the model described in [1]. [W/(m^2 C)]
+        A coefficient used in the model described in [1]_. [W/(m^2 C)]
+    sliding coefficient : numeric
+        Empirically determined coefficient used in [1]_ to determine how much
+        snow slides off in each time period. [unitless]
 
     Returns
     -------
@@ -164,50 +85,50 @@ def snow_coverage_model(snow_data, snow_data_type,
 
     Notes
     -----
-    Implements the model described in [1] with minor improvements in [2].
-    Currently only validated for fixed tilt systems.
+    Initial snow coverage is assumed to be zero. Implements the model described
+    in [1]_ with minor improvements in [2]_. Validated for fixed tilt systems.
 
     References
     ----------
     .. [1] Marion, B.; Schaefer, R.; Caine, H.; Sanchez, G. (2013).
        “Measured and modeled photovoltaic system energy losses from snow for
        Colorado and Wisconsin locations.” Solar Energy 97; pp.112-121.
-    .. [2] Ryberg, D; Freeman, J. "Integration, Validation, and Application
-       of a PV Snow Coverage Model in SAM" (2017) NREL Technical Report
+    .. [2] Ryberg, D; Freeman, J. (2017). "Integration, Validation, and
+       Application of a PV Snow Coverage Model in SAM" NREL Technical Report
+       NREL/TP-6A20-68705 
     '''
 
-    full_coverage_events = fully_covered_panel(snow_data,
-                                               time_step=time_step,
-                                               snow_data_type=snow_data_type)
-    snow_coverage = pd.Series(np.full(len(snow_data), np.nan))
-    snow_coverage = snow_coverage.reindex(snow_data.index)
-    snow_coverage[full_coverage_events] = 1
-    slide_events = _snow_slide_event(poa_irradiance, temperature)
-    slide_amount = _snow_slide_amount(surface_tilt, sliding_coefficient,
-                                      time_step)
-    slidable_snow = ~np.isnan(snow_coverage)
-    while(np.any(slidable_snow)):
-        new_slides = np.logical_and(slide_events, slidable_snow)
-        snow_coverage[new_slides] -= slide_amount
-        new_snow_coverage = snow_coverage.fillna(method="ffill", limit=1)
-        slidable_snow = np.logical_and(~np.isnan(new_snow_coverage),
-                                       np.isnan(snow_coverage))
-        slidable_snow = np.logical_and(slidable_snow, new_snow_coverage > 0)
-        snow_coverage = new_snow_coverage
-
-    new_slides = np.logical_and(slide_events, slidable_snow)
-    snow_coverage[new_slides] -= slide_amount
-
-    snow_coverage = snow_coverage.fillna(method="ffill")
-    snow_coverage = snow_coverage.fillna(value=0)
+    # set up output Series
+    snow_coverage = pd.Series(index=poa_irradiance.index, data=np.nan)
+    snow_events = snowfall[fully_covered(snowfall, threshold_snowfall)]
+
+    can_slide = temperature > poa_irradiance / m
+    slide_amt = sliding_coefficient * sind(surface_tilt) * \
+        _time_delta_in_hours(poa_irradiance.index)
+
+    uncovered = pd.Series(0.0, index=poa_irradiance.index)
+    uncovered[can_slide] = slide_amt[can_slide]
+
+    windows = [(ev, ne) for (ev, ne) in
+        zip(snow_events.index[:-1], snow_events.index[1:])]
+    # add last time window
+    windows.append((snow_events.index[-1], snowfall.index[-1]))
+
+    for (ev, ne) in windows:
+        filt = (snow_coverage.index > ev) & (snow_coverage.index <= ne)
+        snow_coverage[ev] = 1.0
+        snow_coverage[filt] = 1.0 - uncovered[filt].cumsum()
+
+    # clean up periods where row is completely uncovered
     snow_coverage[snow_coverage < 0] = 0
+    snow_coverage = snow_coverage.fillna(value=0.)
     return snow_coverage
 
 
-def DC_loss_factor(snow_coverage, num_strings):
+def snow_loss_factor(snow_coverage, num_strings):
     '''
     Calculates the DC loss due to snow coverage. Assumes that if a string is
-    even partially covered by snow, it produces 0W.
+    partially covered by snow, it produces 0W.
 
     Parameters
     ----------
@@ -220,6 +141,6 @@ def DC_loss_factor(snow_coverage, num_strings):
     Returns
     -------
     loss : numeric
-        DC loss due to snow coverage at each time step.
+        fraction of DC capacity loss due to snow coverage at each time step.
     '''
     return np.ceil(snow_coverage * num_strings) / num_strings