pvlib 0.11.1__py3-none-any.whl → 0.12.0__py3-none-any.whl

pvlib/pvsystem.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass
 from abc import ABC, abstractmethod
 from typing import Optional, Union
 
-from pvlib._deprecation import deprecated, warn_deprecated
+from pvlib._deprecation import deprecated
 
 import pvlib  # used to avoid albedo name collision in the Array class
 from pvlib import (atmosphere, iam, inverter, irradiance,
@@ -29,11 +29,10 @@ import pvlib.tools as tools
 # a dict of required parameter names for each DC power model
 _DC_MODEL_PARAMS = {
     'sapm': {
-        'A0', 'A1', 'A2', 'A3', 'A4', 'B0', 'B1', 'B2', 'B3',
-        'B4', 'B5', 'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6',
-        'C7', 'Isco', 'Impo', 'Voco', 'Vmpo', 'Aisc', 'Aimp', 'Bvoco',
+        'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7',
+        'Isco', 'Impo', 'Voco', 'Vmpo', 'Aisc', 'Aimp', 'Bvoco',
         'Mbvoc', 'Bvmpo', 'Mbvmp', 'N', 'Cells_in_Series',
-        'IXO', 'IXXO', 'FD'},
+        'IXO', 'IXXO'},
     'desoto': {
         'alpha_sc', 'a_ref', 'I_L_ref', 'I_o_ref',
         'R_sh_ref', 'R_s'},
@@ -104,22 +103,22 @@ class PVSystem:
     ----------
     arrays : Array or iterable of Array, optional
         An Array or list of arrays that are part of the system. If not
-        specified a single array is created from the other parameters (e.g.
+        specified, a single array is created from the other parameters (e.g.
         `surface_tilt`, `surface_azimuth`). If specified as a list, the list
         must contain at least one Array;
         if length of arrays is 0 a ValueError is raised. If `arrays` is
         specified the following PVSystem parameters are ignored:
 
-        - `surface_tilt`
-        - `surface_azimuth`
-        - `albedo`
-        - `surface_type`
-        - `module`
-        - `module_type`
-        - `module_parameters`
-        - `temperature_model_parameters`
-        - `modules_per_string`
-        - `strings_per_inverter`
+        - ``surface_tilt``
+        - ``surface_azimuth``
+        - ``albedo``
+        - ``surface_type``
+        - ``module``
+        - ``module_type``
+        - ``module_parameters``
+        - ``temperature_model_parameters``
+        - ``modules_per_string``
+        - ``strings_per_inverter``
 
     surface_tilt: float or array-like, default 0
         Surface tilt angles in decimal degrees.
@@ -127,7 +126,7 @@ class PVSystem:
         (e.g. surface facing up = 0, surface facing horizon = 90)
 
     surface_azimuth: float or array-like, default 180
-        Azimuth angle of the module surface.
+        Azimuth angle of the module surface in decimal degrees.
         North=0, East=90, South=180, West=270.
 
     albedo : float, optional
@@ -142,8 +141,6 @@ class PVSystem:
 
     module : string, optional
         The model name of the modules.
-        May be used to look up the module_parameters dictionary
-        via some other method.
 
     module_type : string, default 'glass_polymer'
          Describes the module's construction. Valid strings are 'glass_polymer'
@@ -154,7 +151,8 @@ class PVSystem:
 
     temperature_model_parameters : dict or Series, optional
         Temperature model parameters as required by one of the models in
-        pvlib.temperature (excluding poa_global, temp_air and wind_speed).
+        :py:mod:`pvlib.temperature` (excluding ``poa_global``, ``temp_air`` and
+        ``wind_speed``).
 
     modules_per_string: int or float, default 1
         See system topology discussion above.
@@ -164,15 +162,17 @@ class PVSystem:
 
     inverter : string, optional
         The model name of the inverters.
-        May be used to look up the inverter_parameters dictionary
-        via some other method.
 
     inverter_parameters : dict or Series, optional
         Inverter parameters as defined by the SAPM, CEC, or other.
 
-    racking_model : string, default 'open_rack'
-        Valid strings are 'open_rack', 'close_mount', and 'insulated_back'.
-        Used to identify a parameter set for the SAPM cell temperature model.
+    racking_model : string, optional
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst cell
+        temperature model.
+        See :py:func:`~pvlib.temperature.sapm_module` and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     losses_parameters : dict or Series, optional
         Losses parameters as defined by PVWatts or other.
@@ -186,7 +186,7 @@ class PVSystem:
     Raises
     ------
     ValueError
-        If `arrays` is not None and has length 0.
+        If ``arrays`` is not None and has length 0.
 
     See also
     --------
@@ -312,7 +312,7 @@ class PVSystem:
                        dni_extra=None, airmass=None, albedo=None,
                        model='haydavies', **kwargs):
         """
-        Uses the :py:func:`irradiance.get_total_irradiance` function to
+        Uses :py:func:`pvlib.irradiance.get_total_irradiance` to
         calculate the plane of array irradiance components on the tilted
         surfaces defined by each array's ``surface_tilt`` and
         ``surface_azimuth``.
@@ -323,11 +323,11 @@ class PVSystem:
             Solar zenith angle.
         solar_azimuth : float or Series
             Solar azimuth angle.
-        dni : float or Series or tuple of float or Series
+        dni : float, Series, or tuple of float or Series
             Direct Normal Irradiance. [W/m2]
-        ghi : float or Series or tuple of float or Series
+        ghi : float, Series, or tuple of float or Series
             Global horizontal irradiance. [W/m2]
-        dhi : float or Series or tuple of float or Series
+        dhi : float, Series, or tuple of float or Series
             Diffuse horizontal irradiance. [W/m2]
         dni_extra : float, Series or tuple of float or Series, optional
             Extraterrestrial direct normal irradiance. [W/m2]
@@ -339,15 +339,22 @@ class PVSystem:
             Irradiance model.
 
         kwargs
-            Extra parameters passed to :func:`irradiance.get_total_irradiance`.
+            Extra parameters passed to
+            :py:func:`pvlib.irradiance.get_total_irradiance`.
 
         Notes
         -----
-        Each of `dni`, `ghi`, and `dni` parameters may be passed as a tuple
-        to provide different irradiance for each array in the system. If not
-        passed as a tuple then the same value is used for input to each Array.
-        If passed as a tuple the length must be the same as the number of
-        Arrays.
+        Each of ``dni``, ``ghi``, and ``dni`` may be passed as a float, Series,
+        or tuple of float or Series. If passed as a float or Series, these
+        values are used for all Arrays. If passed as a tuple, the tuple length
+        must be the same as the number of Arrays. The first tuple element is
+        used for the first Array, the second tuple element for the second
+        Array, and so forth.
+
+        Some sky irradiance models require ``dni_extra``. For these models,
+        if ``dni_extra`` is not provided and ``solar_zenith`` has a
+        ``DatetimeIndex``, then ``dni_extra`` is calculated.
+        Otherwise, ``dni_extra=1367`` is assumed.
 
         Returns
         -------
@@ -1077,7 +1084,7 @@ class Array:
         """
         Get plane of array irradiance components.
 
-        Uses the :py:func:`pvlib.irradiance.get_total_irradiance` function to
+        Uses :py:func:`pvlib.irradiance.get_total_irradiance` to
         calculate the plane of array irradiance components for a surface
         defined by ``self.surface_tilt`` and ``self.surface_azimuth``.
 
@@ -1112,6 +1119,13 @@ class Array:
             Column names are: ``'poa_global', 'poa_direct', 'poa_diffuse',
             'poa_sky_diffuse', 'poa_ground_diffuse'``.
 
+        Notes
+        -----
+        Some sky irradiance models require ``dni_extra``. For these models,
+        if ``dni_extra`` is not provided and ``solar_zenith`` has a
+        ``DatetimeIndex``, then ``dni_extra`` is calculated.
+        Otherwise, ``dni_extra=1367`` is assumed.
+
         See also
         --------
         :py:func:`pvlib.irradiance.get_total_irradiance`
@@ -1119,9 +1133,16 @@ class Array:
         if albedo is None:
             albedo = self.albedo
 
-        # not needed for all models, but this is easier
+        # dni_extra is not needed for all models, but this is easier
         if dni_extra is None:
-            dni_extra = irradiance.get_extra_radiation(solar_zenith.index)
+            if (hasattr(solar_zenith, 'index') and
+                    isinstance(solar_zenith.index, pd.DatetimeIndex)):
+                # calculate extraterrestrial irradiance
+                dni_extra = irradiance.get_extra_radiation(
+                    solar_zenith.index)
+            else:
+                # use the solar constant
+                dni_extra = 1367.0
 
         if airmass is None:
             airmass = atmosphere.get_relative_airmass(solar_zenith)
@@ -1374,8 +1395,12 @@ class FixedMount(AbstractMount):
         West=270. [degrees]
 
     racking_model : str, optional
-        Valid strings are 'open_rack', 'close_mount', and 'insulated_back'.
-        Used to identify a parameter set for the SAPM cell temperature model.
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst cell
+        temperature model.
+        See :py:func:`~pvlib.temperature.sapm_module`  and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     module_height : float, optional
        The height above ground of the center of the module [m]. Used for
@@ -1451,8 +1476,13 @@ class SingleAxisTrackerMount(AbstractMount):
         `cross_axis_tilt`. [degrees]
 
     racking_model : str, optional
-        Valid strings are 'open_rack', 'close_mount', and 'insulated_back'.
-        Used to identify a parameter set for the SAPM cell temperature model.
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst cell
+        temperature model. ``'open_rack'`` or ``'freestanding'`` should
+        be used for systems with single-axis trackers.
+        See :py:func:`~pvlib.temperature.sapm_module` and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     module_height : float, optional
        The height above ground of the center of the module [m]. Used for
@@ -1679,6 +1709,8 @@ def calcparams_desoto(effective_irradiance, temp_cell,
     Rs = R_s
 
     numeric_args = (effective_irradiance, temp_cell)
+    # IL: photocurrent, I0: saturation_current, Rs: resistance_series,
+    # Rsh: resistance_shunt
     out = (IL, I0, Rs, Rsh, nNsVth)
 
     if all(map(np.isscalar, numeric_args)):
@@ -1945,6 +1977,8 @@ def calcparams_pvsyst(effective_irradiance, temp_cell,
     Rs = R_s
 
     numeric_args = (effective_irradiance, temp_cell)
+    # IL: photocurrent, I0: saturation_current, Rs: resistance_series,
+    # Rsh: resistance_shunt
     out = (IL, I0, Rs, Rsh, nNsVth)
 
     if all(map(np.isscalar, numeric_args)):
@@ -1965,10 +1999,10 @@ def retrieve_sam(name=None, path=None):
 
     This function will retrieve either:
 
-        * CEC module database
-        * Sandia Module database
-        * CEC Inverter database
-        * Anton Driesse Inverter database
+    * CEC module database
+    * Sandia Module database
+    * CEC Inverter database
+    * Anton Driesse Inverter database
 
     and return it as a pandas DataFrame.
 
@@ -1981,20 +2015,20 @@ def retrieve_sam(name=None, path=None):
         Use one of the following strings to retrieve a database bundled with
         pvlib:
 
-        * 'CECMod' - returns the CEC module database
-        * 'CECInverter' - returns the CEC Inverter database
-        * 'SandiaInverter' - returns the CEC Inverter database
+        * ``'CECMod'`` - returns the CEC module database
+        * ``'CECInverter'`` - returns the CEC Inverter database
+        * ``'SandiaInverter'`` - returns the CEC Inverter database
           (CEC is only current inverter db available; tag kept for
           backwards compatibility)
-        * 'SandiaMod' - returns the Sandia Module database
-        * 'ADRInverter' - returns the ADR Inverter database
+        * ``'SandiaMod'`` - returns the Sandia Module database
+        * ``'ADRInverter'`` - returns the ADR Inverter database
 
     path : string, optional
         Path to a CSV file or a URL.
 
     Returns
     -------
-    samfile : DataFrame
+    DataFrame
         A DataFrame containing all the elements of the desired database.
         Each column represents a module or inverter, and a specific
         dataset can be retrieved by the command
@@ -2012,14 +2046,13 @@ def retrieve_sam(name=None, path=None):
     -----
     Files available at
         https://github.com/NREL/SAM/tree/develop/deploy/libraries
-    Documentation for module and inverter data sets:
-        https://sam.nrel.gov/photovoltaic/pv-sub-page-2.html
 
     Examples
     --------
+    Using a database bundled with pvlib:
 
     >>> from pvlib import pvsystem
-    >>> invdb = pvsystem.retrieve_sam('CECInverter')
+    >>> invdb = pvsystem.retrieve_sam(name='CECInverter')
     >>> inverter = invdb.AE_Solar_Energy__AE6_0__277V_
     >>> inverter
     Vac                          277
@@ -2039,7 +2072,15 @@ def retrieve_sam(name=None, path=None):
     CEC_Date                     NaN
     CEC_Type     Utility Interactive
     Name: AE_Solar_Energy__AE6_0__277V_, dtype: object
-    """
+
+    Using a remote database, via URL:
+
+    >>> url = "https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv"
+    >>> inv_db = pvsystem.retrieve_sam(path=url)
+    >>> inv_db.keys()
+    Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...],
+          dtype='object', length=...)
+    """  # noqa: E501
     # error: path was previously silently ignored if name was given GH#2018
     if name is not None and path is not None:
         raise ValueError("Please provide either 'name' or 'path', not both.")
@@ -2273,12 +2314,6 @@ def sapm(effective_irradiance, temp_cell, module):
     return out
 
 
-sapm_spectral_loss = deprecated(
-    since='0.10.0',
-    alternative='pvlib.spectrum.spectral_factor_sapm'
-)(spectrum.spectral_factor_sapm)
-
-
 def sapm_effective_irradiance(poa_direct, poa_diffuse, airmass_absolute, aoi,
                               module):
     r"""
@@ -2871,46 +2906,49 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
 def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent,
                          modules_per_string=1,
                          strings=1):
-    """
-    Calculates the equivalent resistance of the wires from a percent
-    ohmic loss at STC.
-
-    Equivalent resistance is calculated with the function:
-
-    .. math::
-        Rw = (L_{stc} / 100) * (Varray / Iarray)
-
-    :math:`Rw` is the equivalent resistance in ohms
-    :math:`Varray` is the Vmp of the modules times modules per string
-    :math:`Iarray` is the Imp of the modules times strings per array
-    :math:`L_{stc}` is the input dc loss percent
+    r"""
+    Calculate the equivalent resistance of the conductors from the percent
+    ohmic loss of an array at reference conditions.
 
     Parameters
     ----------
     vmp_ref: numeric
-        Voltage at maximum power in reference conditions [V]
+        Maximum power voltage of one module at reference conditions. [V]
     imp_ref: numeric
-        Current at maximum power in reference conditions [V]
-    dc_ohmic_percent: numeric, default 0
-        input dc loss as a percent, e.g. 1.5% loss is input as 1.5
+        Maximum power current of one module at reference conditions. [A]
+    dc_ohmic_percent: numeric
+        Array DC power loss as a percent of DC power loss at reference
+        conditions. In percent, e.g. 1.5% loss is input as 1.5.
     modules_per_string: int, default 1
-        Number of modules per string in the array.
+        Number of series-connected modules per string in the array.
     strings: int, default 1
         Number of parallel strings in the array.
 
     Returns
     ----------
     Rw: numeric
-        Equivalent resistance [ohm]
+        Equivalent resistance. [ohm]
 
     See Also
     --------
     pvlib.pvsystem.dc_ohmic_losses
 
-    References
-    ----------
-    .. [1] PVsyst 7 Help. "Array ohmic wiring loss".
-       https://www.pvsyst.com/help/ohmic_loss.htm
+    Notes
+    -----
+    Equivalent resistance is calculated as:
+
+    .. math::
+
+        R_w = \left(\frac{L_{stc}}{100}\right) \times \left(\frac{
+        V_{array}}{I_{array}}\right)
+
+    :math:`R_w` is the equivalent resistance in ohms.
+    :math:`V_{array}` is the array voltage, equal to ``vmp_ref`` times
+    ``modules_per_string``.
+    :math:`I_{array}` is the array current, equal to ``imp_ref`` times
+    ``strings``.
+    :math:`L_{stc}` is the input DC loss percent at reference conditions.
+
     """
     vmp = modules_per_string * vmp_ref
 
@@ -2922,30 +2960,37 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent,
 
 
 def dc_ohmic_losses(resistance, current):
-    """
+    r"""
     Returns ohmic losses in units of power from the equivalent
     resistance of the wires and the operating current.
 
     Parameters
     ----------
     resistance: numeric
-        Equivalent resistance of wires [ohm]
+        Equivalent resistance of wires. [ohm]
     current: numeric, float or array-like
-        Operating current [A]
+        Operating current. [A]
 
     Returns
     ----------
     loss: numeric
-        Power Loss [W]
+        Power loss. [W]
 
     See Also
     --------
     pvlib.pvsystem.dc_ohms_from_percent
 
-    References
-    ----------
-    .. [1] PVsyst 7 Help. "Array ohmic wiring loss".
-       https://www.pvsyst.com/help/ohmic_loss.htm
+    Notes
+    -----
+    Ohmic (also termed joule or heat) loss is the power lost due to current
+    flowing through a conductor. Ohmic loss, :math:`L`, is computed as
+
+    .. math::
+
+        L = I^2 \times R
+
+    where :math:`I` is the current (A) and :math:`R` is the resistance of the
+    conductor (ohms).
     """
     return resistance * current * current
 

pvlib/snow.py

@@ -13,30 +13,38 @@ def _time_delta_in_hours(times):
     return delta.dt.total_seconds().div(3600)
 
 
-def fully_covered_nrel(snowfall, threshold_snowfall=1.):
+def fully_covered_nrel(snowfall, snow_depth=None, threshold_snowfall=1.,
+                       threshold_depth=1.):
     '''
-    Calculates the timesteps when the row's slant height is fully covered
-    by snow.
+    Calculates the timesteps when modules are fully covered by snow.
 
     Parameters
     ----------
-    snowfall : Series
-        Accumulated snowfall in each time period [cm]
-
-    threshold_snowfall : float, default 1.0
-        Hourly snowfall above which snow coverage is set to the row's slant
-        height. [cm/hr]
+    snowfall: Series
+        Snowfall in each time period. [cm]
+    snow_depth: Series, optional
+        Snow depth on the ground at the beginning of each time period.
+        Must have the same index as ``snowfall``. [cm]
+    threshold_snowfall: float, default 1.0
+        Hourly snowfall above which the row is fully covered for that hour.
+        [cm/hr]
+    threshold_depth: float, default 1.0
+        Snow depth on the ground, above which snow can affect the modules. [cm]
 
     Returns
     ----------
-    boolean: Series
-        True where the snowfall exceeds the defined threshold to fully cover
-        the panel.
+    covered: Series
+        A Series of boolean, True where the snowfall exceeds the defined
+        threshold to fully cover the panel.
 
     Notes
     -----
     Implements the model described in [1]_ with minor improvements in [2]_.
 
+    ``snow_depth`` is used to return `False` (not fully covered) when snow
+    is less than ``threshold_depth``. This check is described in [2]_ as needed
+    for systems with low tilt angle.
+
     References
     ----------
     .. [1] Marion, B.; Schaefer, R.; Caine, H.; Sanchez, G. (2013).
@@ -56,15 +64,20 @@ def fully_covered_nrel(snowfall, threshold_snowfall=1.):
         hourly_snow_rate.iloc[0] = snowfall.iloc[0] / timedelta
     else:  # can't infer frequency from index
         hourly_snow_rate.iloc[0] = 0  # replaces NaN
-    return hourly_snow_rate > threshold_snowfall
+    covered = (hourly_snow_rate > threshold_snowfall)
+    # no coverage when no snow on the ground
+    if snow_depth is not None:
+        covered = covered & (snow_depth >= threshold_depth)
+    return covered
 
 
 def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
-                  initial_coverage=0, threshold_snowfall=1.,
-                  can_slide_coefficient=-80., slide_amount_coefficient=0.197):
+                  snow_depth=None, initial_coverage=0, threshold_snowfall=1.,
+                  threshold_depth=1., can_slide_coefficient=-80.,
+                  slide_amount_coefficient=0.197):
     '''
-    Calculates the fraction of the slant height of a row of modules covered by
-    snow at every time step.
+    Calculates the fraction of the slant height of a row of modules that is
+    covered by snow at every time step.
 
     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
@@ -74,7 +87,7 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     Parameters
     ----------
     snowfall : Series
-        Accumulated snowfall within each time period. [cm]
+        Snowfall within each time period. [cm]
     poa_irradiance : Series
         Total in-plane irradiance [W/m^2]
     temp_air : Series
@@ -82,12 +95,17 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     surface_tilt : numeric
         Tilt of module's from horizontal, e.g. surface facing up = 0,
         surface facing horizon = 90. [degrees]
+    snow_depth : Series, optional
+        Snow depth on the ground at the beginning of each time period.
+        Must have the same index as ``snowfall``. [cm]
     initial_coverage : float, default 0
         Fraction of row's slant height that is covered with snow at the
         beginning of the simulation. [unitless]
-    threshold_snowfall : float, default 1.0
-        Hourly snowfall above which snow coverage is set to the row's slant
-        height. [cm/hr]
+    threshold_snowfall: float, default 1.0
+        Hourly snowfall above which the row is fully covered for that hour.
+        [cm/hr]
+    threshold_depth: float, default 1.0
+        Snow depth on the ground, above which snow can affect the modules. [cm]
     can_slide_coefficient : float, default -80.
         Coefficient to determine if snow can slide given irradiance and air
         temperature. [W/(m^2 C)]
@@ -103,8 +121,12 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
 
     Notes
     -----
-    In [1]_, `can_slide_coefficient` is termed `m`, and the value of
-    `slide_amount_coefficient` is given in tenths of a module's slant height.
+    In [1]_, ``can_slide_coefficient`` is termed `m`, and the value of
+    ``slide_amount_coefficient`` is given in tenths of a module's slant height.
+
+    ``snow_depth`` is used to set ``snow_coverage`` to 0 (not fully covered)
+    when snow is less than ``threshold_depth``. This check is described in
+    [2]_ as needed for systems with low tilt angle.
 
     References
     ----------
@@ -117,7 +139,8 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     '''
 
     # find times with new snowfall
-    new_snowfall = fully_covered_nrel(snowfall, threshold_snowfall)
+    new_snowfall = fully_covered_nrel(snowfall, snow_depth, threshold_snowfall,
+                                      threshold_depth)
 
     # set up output Series
     snow_coverage = pd.Series(np.nan, index=poa_irradiance.index)
@@ -132,6 +155,13 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     # don't slide in the interval preceding the snowfall data
     slide_amt.iloc[0] = 0
 
+    if snow_depth is not None:
+        # All slides off if snow on the ground is less than threshold_depth.
+        # Described in [2] to avoid non-sliding snow for low-tilt systems.
+        # Default threshold_depth of 1cm is from [2[ and SAM's implementation.
+        # https://github.com/NREL/ssc/issues/1265
+        slide_amt[snow_depth < threshold_depth] = 1.
+
     # build time series of cumulative slide amounts
     sliding_period_ID = new_snowfall.cumsum()
     cumulative_sliding = slide_amt.groupby(sliding_period_ID).cumsum()
@@ -143,7 +173,6 @@ def coverage_nrel(snowfall, poa_irradiance, temp_air, surface_tilt,
     snow_coverage.ffill(inplace=True)
     snow_coverage -= cumulative_sliding
 
-    # clean up periods where row is completely uncovered
     return snow_coverage.clip(lower=0)
 
 
@@ -278,9 +307,8 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     axis to the module edge.
 
     The parameter `string_factor` is an enhancement added to the model after
-    publication of [1]_ per private communication with the model's author. The
-    definition for snow events documented above is also based on private
-    communication with the model's author.
+    publication of [1]_, as described in [2]_.
+    The definition for snow events documented above is based on [3]_.
 
     References
     ----------
@@ -288,6 +316,14 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
        update from two winters of measurements in the SIERRA. 37th IEEE
        Photovoltaic Specialists Conference, Seattle, WA, USA.
        :doi:`10.1109/PVSC.2011.6186627`
+    .. [2] Townsend, T. and Previtali, J. (2023). A Fresh Dusting: Current
+        Uses of the Townsend Snow Model. In "Photovoltaic Reliability
+        Workshop (PVRW) 2023 Proceedings: Posters.", ed. Silverman,
+        T. J. Dec. 2023. NREL/CP-5900-87918.
+        Available at: https://www.nrel.gov/docs/fy25osti/90585.pdf
+    .. [3] Townsend, T. (2013). Predicting PV Energy Loss Caused by Snow.
+        Solar Power International, Chicago IL.
+        :doi:`10.13140/RG.2.2.14299.68647`
     '''
 
     # unit conversions from cm and m to in, from C to K, and from % to fraction