rename functions, review responses, add subhourly test

Author: cwhanse

pvlib/snowcoverage.py

@@ -10,10 +10,10 @@
 
 def _time_delta_in_hours(times):
     delta = times.to_series().diff()
-    return delta.dt.seconds.div(3600)
+    return delta.dt.total_seconds.div(3600)
 
 
-def fully_covered(snowfall, threshold=1.):
+def snow_nrel_fully_covered(snowfall, threshold=1.):
     '''
     Calculates the timesteps when the row's slant height is fully covered
     by snow.
@@ -39,29 +39,32 @@ def fully_covered(snowfall, threshold=1.):
     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.
+       "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
     '''
-    delta = snowfall.index.to_series().diff()  # [0] will be NaT
-    timestep = delta.dt.seconds.div(3600)  # convert to hours
+    timestep = _time_delta_in_hours(snowfall.index)
     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):
+def snow_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.
 
+    Initial snow coverage is assumed to be zero. Implements the model described
+    in [1]_ with minor improvements in [2]_, with the change that the output
+    is in fraction of the row's slant height rather than in tenths of the row
+    slant height. Validated for fixed tilt systems.
+
     Parameters
     ----------
     snowfall : Series
-        Accumulated snowfall at the end of each time period. [cm]
+        Accumulated snowfall within each time period. [cm]
     poa_irradiance : Series
         Total in-plane irradiance [W/m^2]
     temperature : Series
@@ -71,36 +74,33 @@ def snow_coverage_nrel(snowfall, poa_irradiance, temperature, surface_tilt,
         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)]
-    sliding coefficient : numeric
-        Empirically determined coefficient used in [1]_ to determine how much
+    m : float, default -80.
+        Coefficient used in [1]_ to determine if snow can slide given
+        irradiance and air temperature. [W/(m^2 C)]
+    sliding coefficient : float, default 0.197
+        Empirical coefficient used in [1]_ to determine how much
         snow slides off in each time period. [unitless]
 
     Returns
     -------
-    snow_coverage : numeric
-        The fraction of a the slant height of a row of modules that is covered
+    snow_coverage : Series
+        The fraction of the slant height of a row of modules that is covered
         by snow at each time step.
 
-    Notes
-    -----
-    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.
+       "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. (2017). "Integration, Validation, and
        Application of a PV Snow Coverage Model in SAM" NREL Technical Report
-       NREL/TP-6A20-68705 
+       NREL/TP-6A20-68705
     '''
 
     # set up output Series
     snow_coverage = pd.Series(index=poa_irradiance.index, data=np.nan)
-    snow_events = snowfall[fully_covered(snowfall, threshold_snowfall)]
+    snow_events = snowfall[snow_nrel_fully_covered(snowfall,
+                                                   threshold_snowfall)]
 
     can_slide = temperature > poa_irradiance / m
     slide_amt = sliding_coefficient * sind(surface_tilt) * \
@@ -109,8 +109,7 @@ def snow_coverage_nrel(snowfall, poa_irradiance, temperature, surface_tilt,
     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:])]
+    windows = list(zip(snow_events.index[:-1], snow_events.index[1:]))
     # add last time window
     windows.append((snow_events.index[-1], snowfall.index[-1]))
 
@@ -125,7 +124,7 @@ def snow_coverage_nrel(snowfall, poa_irradiance, temperature, surface_tilt,
     return snow_coverage
 
 
-def snow_loss_factor(snow_coverage, num_strings):
+def snow_nrel_dc_loss(snow_coverage, num_strings):
     '''
     Calculates the DC loss due to snow coverage. Assumes that if a string is
     partially covered by snow, it produces 0W.

pvlib/tests/test_snowcoverage.py

@@ -7,45 +7,57 @@
 from pvlib.tools import sind
 
 
-def test_fully_covered():
+def test_snow_nrel_fully_covered():
     dt = pd.date_range(start="2019-1-1 12:00:00", end="2019-1-1 18:00:00",
                        freq='1h')
     snowfall_data = pd.Series([1, 5, .6, 4, .23, -5, 19], index=dt)
     expected = pd.Series([False, True, False, True, False, False, True],
                          index=dt)
-    actual_snowfall = snowcoverage.fully_covered(snowfall_data)
+    actual_snowfall = snowcoverage.snow_nrel_fully_covered(snowfall_data)
     assert_series_equal(actual_snowfall, expected)
 
 
-def test_snow_coverage_nrel():
+def test_snow_nrel_hourly():
     surface_tilt = 45
     sliding_coefficient = 0.197
     dt = pd.date_range(start="2019-1-1 10:00:00", end="2019-1-1 17:00:00",
                        freq='1h')
-    poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982, 100, 100], index=dt)
+    poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982, 100, 100],
+                               index=dt)
     temperature = pd.Series([10, 2, 10, 1234, 34, 982, 10, 10], index=dt)
     slide_amt = sliding_coefficient * sind(surface_tilt)
     snowfall_data = pd.Series([1, .5, .6, .4, .23, -5, .1, .1], index=dt)
-    snow_coverage = snowcoverage.snow_coverage_nrel(
+    snow_coverage = snowcoverage.snow_nrel(
         snowfall_data, poa_irradiance, temperature, surface_tilt,
-        threshold_snowfall=0.0)
-    # covered every hour except when snowfall = -5
-    expected = pd.Series([1., 1., 1., 1., 1., 1. - slide_amt, 1., 1.], index=dt)
+        threshold_snowfall=0.6)
+    covered = np.append(np.array([0., 0.]),
+                        1.0 - slide_amt * np.array([0, 1, 2, 3, 4, 5]))
+    expected = pd.Series(covered, index=dt)
     assert_series_equal(snow_coverage, expected)
-    # snowfall_threshold = 0.6
-    snow_coverage = snowcoverage.snow_coverage_nrel(
+
+
+def test_snow_nrel_subhourly():
+    surface_tilt = 45
+    sliding_coefficient = 0.197
+    dt = pd.date_range(start="2019-1-1 11:00:00", end="2019-1-1 14:00:00",
+                       freq='15T')
+    poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982, 100, 100],
+                               index=dt)
+    temperature = pd.Series([10, 2, 10, 1234, 34, 982, 10, 10], index=dt)
+    slide_amt = sliding_coefficient * sind(surface_tilt)
+    snowfall_data = pd.Series([1, .5, .6, .4, .23, -5, .1, .1], index=dt)
+    snow_coverage = snowcoverage.snow_nrel(
         snowfall_data, poa_irradiance, temperature, surface_tilt,
         threshold_snowfall=0.6)
-    # covered every hour except when snowfall = -5
     covered = np.append(np.array([0., 0.]),
                         1.0 - slide_amt * np.array([0, 1, 2, 3, 4, 5]))
     expected = pd.Series(covered, index=dt)
     assert_series_equal(snow_coverage, expected)
 
 
-def test_snow_loss_factor():
+def test_snow_nrel_dc_loss():
     num_strings = 8
     snow_coverage = pd.Series([1, 1, .5, .6, .2, .4, 0])
     expected = pd.Series([1, 1, .5, .625, .25, .5, 0])
-    actual = snowcoverage.snow_loss_factor(snow_coverage, num_strings)
+    actual = snowcoverage.snow_nrel_dc_loss(snow_coverage, num_strings)
     assert_series_equal(expected, actual)