Snow coverage model from SAM

pvlib/snowcoverage.py

@@ -0,0 +1,229 @@
+"""
+The ``snowcoverage`` module contains functions that model snow coverage on
+solar modules. The model was first proposed in Marion et al. 2013 and was
+later validated and implemented into NREL's SAM.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def snow_slide_amount(surface_tilt, sliding_coefficient=1.97):
+    '''
+    Calculates the amount of snow that slides off of the surface of a module
+    following the model first described in [1] and later implemented with minor
+    improvements in SAM [2].
+
+    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
+        Another empirically determined coefficient used in [1]. It determines
+        how much snow slides off of the panel if a sliding event occurs.
+
+    Returns
+    ----------
+    slide_amount : numeric
+        The amount of snow that slides off of the panel
+        in tenths of the panel area at each time step.
+
+    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
+    '''
+
+    tilt_radians = np.radians(surface_tilt)
+    slide_amount = sliding_coefficient * np.sin(tilt_radians)
+    return slide_amount
+
+
+def snow_slide_event(poa_irradiance, temperature,
+                     m=-80):
+    '''
+    Calculates when snow sliding events will occur following the model first
+    described in [1] and later implemented in SAM [2].
+
+    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]. It is an
+        empirically determined value given in W/m^2.
+
+    Returns
+    ----------
+    slide_event : boolean array
+        True if the condiditions are suitable for a snow slide event.
+        False elsewhere.
+
+    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
+    '''
+
+    slide_event = temperature > poa_irradiance / m
+    return slide_event
+
+
+def fully_covered_panel(snow_data, time_step_hours=1,
+                        snow_data_type="snowfall"):
+    '''
+    Calculates the timesteps where the panel is presumed to be fully covered
+    by snow. Follows the same model first described in [1] and later
+    implemented in SAM [2].
+
+    Parameters
+    ----------
+    snow_data : numeric
+        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)
+
+    time_step_hours: float
+        Period of the data in hours. (hours between data points)
+
+    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.
+
+    Returns
+    ----------
+    fully_covered_mask : boolean array
+        True where the snowfall exceeds the defined threshold to fully cover
+        the panel. False elsewhere.
+
+    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.
+    '''
+    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_hours
+    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_hours=1, m=-80, sliding_coefficient=1.97):
+    '''
+    Calculates the fraction of a module covered by snow at every time step
+    following the same model first described in [1] and later
+    implemented in SAM [2]. Currently only implemented for fixed tilt systems
+    but could be generalized for tracking systems.
+
+    Parameters
+    ----------
+    snow_data : numeric
+        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.
+
+    poa_irradiance : numeric
+        Total in-plane irradiance (W/m^2)
+
+    temperature : numeric
+        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_hours: float
+        Period of the data in hours. (hours between data points)
+
+    sliding coefficient : numeric
+        Another empirically determined coefficient used in [1]. It determines
+        how much snow slides off of the panel if a sliding event occurs.
+    m : numeric
+        A coefficient used in the model described in [1]. It is an
+        empirically determined value given in W/m^2.
+
+    Returns
+    -------
+    snow_coverage : numeric
+        The fraction of a module covered by snow at each time step.
+    '''
+
+    full_coverage_events = fully_covered_panel(snow_data,
+                                               time_step_hours=time_step_hours,
+                                               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)
+    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*.1
+        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)
+    snow_coverage[snow_coverage < 0] = 0
+    return snow_coverage
+
+
+def DC_loss_factor(snow_coverage, num_strings_per_row):
+    '''
+    Calculates the DC loss due to snow coverage. Assumes that if a string is
+    even partially covered by snow, it produces 0W.
+
+    Parameters
+    ----------
+    snow_coverage : numeric
+        The fraction of a module covered by snow at each time step.
+
+    num_strings_per_row: int
+        The number of separate strings per module/row.
+
+    Returns
+    -------
+    loss : numeric
+        DC loss due to snow coverage at each time step.
+    '''
+    loss = np.ceil(snow_coverage * num_strings_per_row) / num_strings_per_row
+    return loss

pvlib/test/test_snowcoverage.py

@@ -0,0 +1,76 @@
+import numpy as np
+import pandas as pd
+
+from numpy.testing import assert_almost_equal
+
+from pandas.util.testing import assert_series_equal
+
+from pvlib import snowcoverage
+
+
+def test_snow_slide_amount():
+    tilt = 45
+    sc = 2
+    expected_specified = 2**.5
+    expected_default = 1.97/2*2**.5
+    actual_default = snowcoverage.snow_slide_amount(tilt)
+    assert_almost_equal(expected_default, actual_default)
+    actual_specified = snowcoverage.snow_slide_amount(tilt,
+                                                      sliding_coefficient=sc)
+    assert_almost_equal(expected_specified, actual_specified)
+
+
+def test_snow_slide_event():
+    poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982])
+    temperature = pd.Series([10, 2, -10, 1234, 34, -982])
+    expected = pd.Series([True, True, False, True, True, False])
+    actual = snowcoverage.snow_slide_event(poa_irradiance, temperature)
+    assert_series_equal(expected, actual)
+
+
+def test_fully_covered_panel():
+    snowfall_data = pd.Series([1, 5, .6, 4, .23, -5, 19])
+    expected_snowfall = pd.Series([True, True, False, True,
+                                   False, False, True])
+    actual_snowfall = snowcoverage.fully_covered_panel(snowfall_data)
+    assert_series_equal(actual_snowfall, expected_snowfall)
+
+    snowdepth_data = pd.Series([.5, 1, 2, 4, .23, 4, 19])
+    expected_snowdepth = pd.Series([False, False, True, True,
+                                    False, True, True])
+    actual = snowcoverage.fully_covered_panel(snowdepth_data,
+                                              snow_data_type="snow_depth")
+    assert_series_equal(actual, expected_snowdepth)
+
+
+def test_snow_coverage_model():
+    tilt = 45
+    poa_irradiance = pd.Series([400, 200, 100, 1234, 134, 982, 100, 100])
+    temperature = pd.Series([10, 2, 10, 1234, 34, 982, 10, 10])
+    slide = snowcoverage.snow_slide_amount(tilt)*.1
+
+    snowfall_data = pd.Series([1, .5, .6, .4, .23, -5, .1, .1])
+    snow_coverage = snowcoverage.snow_coverage_model(snowfall_data, "snowfall",
+                                                     poa_irradiance,
+                                                     temperature,
+                                                     tilt)
+    expected = pd.Series(1-slide*np.array([1, 2, 3, 4, 5, 6, 7, 1.0/slide]))
+    assert_series_equal(snow_coverage, expected)
+
+    snowdepth_data = pd.Series([.5, 1, 2, 4, .23, 4, 11, .1])
+    snow_coverage = snowcoverage.snow_coverage_model(snowdepth_data,
+                                                     "snow_depth",
+                                                     poa_irradiance,
+                                                     temperature,
+                                                     tilt)
+    expected = pd.Series(1-slide*np.array([1.0/slide, 1.0/slide, 1,
+                                           1, 2, 1, 1, 2]))
+    assert_series_equal(snow_coverage, expected)
+
+
+def test_DC_loss_factor():
+    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.DC_loss_factor(snow_coverage, num_strings)
+    assert_series_equal(expected, actual)