pvlib 0.9.4a1__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/shading.py

@@ -8,6 +8,47 @@ import pandas as pd
 from pvlib.tools import sind, cosd
 
 
+def ground_angle(surface_tilt, gcr, slant_height):
+    """
+    Angle from horizontal of the line from a point on the row slant length
+    to the bottom of the facing row.
+
+    The angles are clockwise from horizontal, rather than the usual
+    counterclockwise direction.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : float
+        ground coverage ratio, ratio of row slant length to row spacing.
+        [unitless]
+    slant_height : numeric
+        The distance up the module's slant height to evaluate the ground
+        angle, as a fraction [0-1] of the module slant height [unitless].
+
+    Returns
+    -------
+    psi : numeric
+        Angle [degree].
+    """
+    #  : \\            \
+    #  :  \\            \
+    #  :   \\            \
+    #  :    \\            \  facing row
+    #  :     \\.___________\
+    #  :       \  ^*-.  psi \
+    #  :        \  x   *-.   \
+    #  :         \  v      *-.\
+    #  :          \<-----P---->\
+
+    x1 = gcr * slant_height * sind(surface_tilt)
+    x2 = gcr * slant_height * cosd(surface_tilt) + 1
+    psi = np.arctan2(x1, x2)  # do this before rad2deg because it handles 0 / 0
+    return np.rad2deg(psi)
+
+
 def masking_angle(surface_tilt, gcr, slant_height):
     """
     The elevation angle below which diffuse irradiance is blocked.
@@ -52,8 +93,8 @@ def masking_angle(surface_tilt, gcr, slant_height):
     # The original equation (8 in [1]) requires pitch and collector width,
     # but it's easy to non-dimensionalize it to make it a function of GCR
     # by factoring out B from the argument to arctan.
-    numerator = (1 - slant_height) * sind(surface_tilt)
-    denominator = 1/gcr - (1 - slant_height) * cosd(surface_tilt)
+    numerator = gcr * (1 - slant_height) * sind(surface_tilt)
+    denominator = 1 - gcr * (1 - slant_height) * cosd(surface_tilt)
     phi = np.arctan(numerator / denominator)
     return np.degrees(phi)
 

pvlib/singlediode.py

@@ -2,15 +2,17 @@
 Low-level functions for solving the single diode equation.
 """
 
-from functools import partial
 import numpy as np
 from pvlib.tools import _golden_sect_DataFrame
 
 from scipy.optimize import brentq, newton
 from scipy.special import lambertw
 
-# set keyword arguments for all uses of newton in this module
-newton = partial(newton, tol=1e-6, maxiter=100, fprime2=None)
+# newton method default parameters for this module
+NEWTON_DEFAULT_PARAMS = {
+    'tol': 1e-6,
+    'maxiter': 100
+}
 
 # intrinsic voltage per cell junction for a:Si, CdTe, Mertens et al.
 VOLTAGE_BUILTIN = 0.9  # [V]
@@ -206,7 +208,7 @@ def bishop88_i_from_v(voltage, photocurrent, saturation_current,
                       resistance_series, resistance_shunt, nNsVth,
                       d2mutau=0, NsVbi=np.Inf, breakdown_factor=0.,
                       breakdown_voltage=-5.5, breakdown_exp=3.28,
-                      method='newton'):
+                      method='newton', method_kwargs=None):
     """
     Find current given any voltage.
 
@@ -247,22 +249,59 @@ def bishop88_i_from_v(voltage, photocurrent, saturation_current,
     method : str, default 'newton'
        Either ``'newton'`` or ``'brentq'``. ''method'' must be ``'newton'``
        if ``breakdown_factor`` is not 0.
+    method_kwargs : dict, optional
+        Keyword arguments passed to root finder method. See
+        :py:func:`scipy:scipy.optimize.brentq` and
+        :py:func:`scipy:scipy.optimize.newton` parameters.
+        ``'full_output': True`` is allowed, and ``optimizer_output`` would be
+        returned. See examples section.
 
     Returns
     -------
     current : numeric
         current (I) at the specified voltage (V). [A]
+    optimizer_output : tuple, optional, if specified in ``method_kwargs``
+        see root finder documentation for selected method.
+        Found root is diode voltage in [1]_.
+
+    Examples
+    --------
+    Using the following arguments that may come from any
+    `calcparams_.*` function in :py:mod:`pvlib.pvsystem`:
+
+    >>> args = {'photocurrent': 1., 'saturation_current': 9e-10, 'nNsVth': 4.,
+    ...         'resistance_series': 4., 'resistance_shunt': 5000.0}
+
+    Use default values:
+
+    >>> i = bishop88_i_from_v(0.0, **args)
+
+    Specify tolerances and maximum number of iterations:
+
+    >>> i = bishop88_i_from_v(0.0, **args, method='newton',
+    ...     method_kwargs={'tol': 1e-3, 'rtol': 1e-3, 'maxiter': 20})
+
+    Retrieve full output from the root finder:
+
+    >>> i, method_output = bishop88_i_from_v(0.0, **args, method='newton',
+    ...     method_kwargs={'full_output': True})
     """
     # collect args
     args = (photocurrent, saturation_current, resistance_series,
             resistance_shunt, nNsVth, d2mutau, NsVbi,
             breakdown_factor, breakdown_voltage, breakdown_exp)
+    method = method.lower()
+
+    # method_kwargs create dict if not provided
+    # this pattern avoids bugs with Mutable Default Parameters
+    if not method_kwargs:
+        method_kwargs = {}
 
     def fv(x, v, *a):
         # calculate voltage residual given diode voltage "x"
         return bishop88(x, *a)[1] - v
 
-    if method.lower() == 'brentq':
+    if method == 'brentq':
         # first bound the search using voc
         voc_est = estimate_voc(photocurrent, saturation_current, nNsVth)
 
@@ -274,27 +313,37 @@ def bishop88_i_from_v(voltage, photocurrent, saturation_current,
             return brentq(fv, 0.0, voc,
                           args=(v, iph, isat, rs, rsh, gamma, d2mutau, NsVbi,
                                 breakdown_factor, breakdown_voltage,
-                                breakdown_exp))
+                                breakdown_exp),
+                          **method_kwargs)
 
         vd_from_brent_vectorized = np.vectorize(vd_from_brent)
         vd = vd_from_brent_vectorized(voc_est, voltage, *args)
-    elif method.lower() == 'newton':
+    elif method == 'newton':
         # make sure all args are numpy arrays if max size > 1
         # if voltage is an array, then make a copy to use for initial guess, v0
-        args, v0 = _prepare_newton_inputs((voltage,), args, voltage)
+        args, v0, method_kwargs = \
+            _prepare_newton_inputs((voltage,), args, voltage, method_kwargs)
         vd = newton(func=lambda x, *a: fv(x, voltage, *a), x0=v0,
                     fprime=lambda x, *a: bishop88(x, *a, gradients=True)[4],
-                    args=args)
+                    args=args,
+                    **method_kwargs)
     else:
         raise NotImplementedError("Method '%s' isn't implemented" % method)
-    return bishop88(vd, *args)[0]
+
+    # When 'full_output' parameter is specified, returned 'vd' is a tuple with
+    # many elements, where the root is the first one. So we use it to output
+    # the bishop88 result and return tuple(scalar, tuple with method results)
+    if method_kwargs.get('full_output') is True:
+        return (bishop88(vd[0], *args)[0], vd)
+    else:
+        return bishop88(vd, *args)[0]
 
 
 def bishop88_v_from_i(current, photocurrent, saturation_current,
                       resistance_series, resistance_shunt, nNsVth,
                       d2mutau=0, NsVbi=np.Inf, breakdown_factor=0.,
                       breakdown_voltage=-5.5, breakdown_exp=3.28,
-                      method='newton'):
+                      method='newton', method_kwargs=None):
     """
     Find voltage given any current.
 
@@ -335,16 +384,54 @@ def bishop88_v_from_i(current, photocurrent, saturation_current,
     method : str, default 'newton'
        Either ``'newton'`` or ``'brentq'``. ''method'' must be ``'newton'``
        if ``breakdown_factor`` is not 0.
+    method_kwargs : dict, optional
+        Keyword arguments passed to root finder method. See
+        :py:func:`scipy:scipy.optimize.brentq` and
+        :py:func:`scipy:scipy.optimize.newton` parameters.
+        ``'full_output': True`` is allowed, and ``optimizer_output`` would be
+        returned. See examples section.
 
     Returns
     -------
     voltage : numeric
         voltage (V) at the specified current (I) in volts [V]
+    optimizer_output : tuple, optional, if specified in ``method_kwargs``
+        see root finder documentation for selected method.
+        Found root is diode voltage in [1]_.
+
+    Examples
+    --------
+    Using the following arguments that may come from any
+    `calcparams_.*` function in :py:mod:`pvlib.pvsystem`:
+
+    >>> args = {'photocurrent': 1., 'saturation_current': 9e-10, 'nNsVth': 4.,
+    ...         'resistance_series': 4., 'resistance_shunt': 5000.0}
+
+    Use default values:
+
+    >>> v = bishop88_v_from_i(0.0, **args)
+
+    Specify tolerances and maximum number of iterations:
+
+    >>> v = bishop88_v_from_i(0.0, **args, method='newton',
+    ...     method_kwargs={'tol': 1e-3, 'rtol': 1e-3, 'maxiter': 20})
+
+    Retrieve full output from the root finder:
+
+    >>> v, method_output = bishop88_v_from_i(0.0, **args, method='newton',
+    ...     method_kwargs={'full_output': True})
     """
     # collect args
     args = (photocurrent, saturation_current, resistance_series,
             resistance_shunt, nNsVth, d2mutau, NsVbi, breakdown_factor,
             breakdown_voltage, breakdown_exp)
+    method = method.lower()
+
+    # method_kwargs create dict if not provided
+    # this pattern avoids bugs with Mutable Default Parameters
+    if not method_kwargs:
+        method_kwargs = {}
+
     # first bound the search using voc
     voc_est = estimate_voc(photocurrent, saturation_current, nNsVth)
 
@@ -352,7 +439,7 @@ def bishop88_v_from_i(current, photocurrent, saturation_current,
         # calculate current residual given diode voltage "x"
         return bishop88(x, *a)[0] - i
 
-    if method.lower() == 'brentq':
+    if method == 'brentq':
         # brentq only works with scalar inputs, so we need a set up function
         # and np.vectorize to repeatedly call the optimizer with the right
         # arguments for possible array input
@@ -361,26 +448,36 @@ def bishop88_v_from_i(current, photocurrent, saturation_current,
             return brentq(fi, 0.0, voc,
                           args=(i, iph, isat, rs, rsh, gamma, d2mutau, NsVbi,
                                 breakdown_factor, breakdown_voltage,
-                                breakdown_exp))
+                                breakdown_exp),
+                          **method_kwargs)
 
         vd_from_brent_vectorized = np.vectorize(vd_from_brent)
         vd = vd_from_brent_vectorized(voc_est, current, *args)
-    elif method.lower() == 'newton':
+    elif method == 'newton':
         # make sure all args are numpy arrays if max size > 1
         # if voc_est is an array, then make a copy to use for initial guess, v0
-        args, v0 = _prepare_newton_inputs((current,), args, voc_est)
+        args, v0, method_kwargs = \
+            _prepare_newton_inputs((current,), args, voc_est, method_kwargs)
         vd = newton(func=lambda x, *a: fi(x, current, *a), x0=v0,
                     fprime=lambda x, *a: bishop88(x, *a, gradients=True)[3],
-                    args=args)
+                    args=args,
+                    **method_kwargs)
     else:
         raise NotImplementedError("Method '%s' isn't implemented" % method)
-    return bishop88(vd, *args)[1]
+
+    # When 'full_output' parameter is specified, returned 'vd' is a tuple with
+    # many elements, where the root is the first one. So we use it to output
+    # the bishop88 result and return tuple(scalar, tuple with method results)
+    if method_kwargs.get('full_output') is True:
+        return (bishop88(vd[0], *args)[1], vd)
+    else:
+        return bishop88(vd, *args)[1]
 
 
 def bishop88_mpp(photocurrent, saturation_current, resistance_series,
                  resistance_shunt, nNsVth, d2mutau=0, NsVbi=np.Inf,
                  breakdown_factor=0., breakdown_voltage=-5.5,
-                 breakdown_exp=3.28, method='newton'):
+                 breakdown_exp=3.28, method='newton', method_kwargs=None):
     """
     Find max power point.
 
@@ -419,43 +516,91 @@ def bishop88_mpp(photocurrent, saturation_current, resistance_series,
     method : str, default 'newton'
        Either ``'newton'`` or ``'brentq'``. ''method'' must be ``'newton'``
        if ``breakdown_factor`` is not 0.
+    method_kwargs : dict, optional
+        Keyword arguments passed to root finder method. See
+        :py:func:`scipy:scipy.optimize.brentq` and
+        :py:func:`scipy:scipy.optimize.newton` parameters.
+        ``'full_output': True`` is allowed, and ``optimizer_output`` would be
+        returned. See examples section.
 
     Returns
     -------
-    OrderedDict or pandas.DataFrame
+    tuple
         max power current ``i_mp`` [A], max power voltage ``v_mp`` [V], and
         max power ``p_mp`` [W]
+    optimizer_output : tuple, optional, if specified in ``method_kwargs``
+        see root finder documentation for selected method.
+        Found root is diode voltage in [1]_.
+
+    Examples
+    --------
+    Using the following arguments that may come from any
+    `calcparams_.*` function in :py:mod:`pvlib.pvsystem`:
+
+    >>> args = {'photocurrent': 1., 'saturation_current': 9e-10, 'nNsVth': 4.,
+    ...         'resistance_series': 4., 'resistance_shunt': 5000.0}
+
+    Use default values:
+
+    >>> i_mp, v_mp, p_mp = bishop88_mpp(**args)
+
+    Specify tolerances and maximum number of iterations:
+
+    >>> i_mp, v_mp, p_mp = bishop88_mpp(**args, method='newton',
+    ...     method_kwargs={'tol': 1e-3, 'rtol': 1e-3, 'maxiter': 20})
+
+    Retrieve full output from the root finder:
+
+    >>> (i_mp, v_mp, p_mp), method_output = bishop88_mpp(**args,
+    ...     method='newton', method_kwargs={'full_output': True})
     """
     # collect args
     args = (photocurrent, saturation_current, resistance_series,
             resistance_shunt, nNsVth, d2mutau, NsVbi, breakdown_factor,
             breakdown_voltage, breakdown_exp)
+    method = method.lower()
+
+    # method_kwargs create dict if not provided
+    # this pattern avoids bugs with Mutable Default Parameters
+    if not method_kwargs:
+        method_kwargs = {}
+
     # first bound the search using voc
     voc_est = estimate_voc(photocurrent, saturation_current, nNsVth)
 
     def fmpp(x, *a):
         return bishop88(x, *a, gradients=True)[6]
 
-    if method.lower() == 'brentq':
+    if method == 'brentq':
         # break out arguments for numpy.vectorize to handle broadcasting
         vec_fun = np.vectorize(
             lambda voc, iph, isat, rs, rsh, gamma, d2mutau, NsVbi, vbr_a, vbr,
             vbr_exp: brentq(fmpp, 0.0, voc,
                             args=(iph, isat, rs, rsh, gamma, d2mutau, NsVbi,
-                                  vbr_a, vbr, vbr_exp))
+                                  vbr_a, vbr, vbr_exp),
+                            **method_kwargs)
         )
         vd = vec_fun(voc_est, *args)
-    elif method.lower() == 'newton':
+    elif method == 'newton':
         # make sure all args are numpy arrays if max size > 1
         # if voc_est is an array, then make a copy to use for initial guess, v0
-        args, v0 = _prepare_newton_inputs((), args, voc_est)
+        args, v0, method_kwargs = \
+            _prepare_newton_inputs((), args, voc_est, method_kwargs)
         vd = newton(
             func=fmpp, x0=v0,
-            fprime=lambda x, *a: bishop88(x, *a, gradients=True)[7], args=args
-        )
+            fprime=lambda x, *a: bishop88(x, *a, gradients=True)[7], args=args,
+            **method_kwargs)
     else:
         raise NotImplementedError("Method '%s' isn't implemented" % method)
-    return bishop88(vd, *args)
+
+    # When 'full_output' parameter is specified, returned 'vd' is a tuple with
+    # many elements, where the root is the first one. So we use it to output
+    # the bishop88 result and return
+    # tuple(tuple with bishop88 solution, tuple with method results)
+    if method_kwargs.get('full_output') is True:
+        return (bishop88(vd[0], *args), vd)
+    else:
+        return bishop88(vd, *args)
 
 
 def _get_size_and_shape(args):
@@ -482,7 +627,7 @@ def _get_size_and_shape(args):
     return size, shape
 
 
-def _prepare_newton_inputs(i_or_v_tup, args, v0):
+def _prepare_newton_inputs(i_or_v_tup, args, v0, method_kwargs):
     # broadcast arguments for newton method
     # the first argument should be a tuple, eg: (i,), (v,) or ()
     size, shape = _get_size_and_shape(i_or_v_tup + args)
@@ -492,15 +637,20 @@ def _prepare_newton_inputs(i_or_v_tup, args, v0):
     # copy v0 to a new array and broadcast it to the shape of max size
     if shape is not None:
         v0 = np.broadcast_to(v0, shape).copy()
-    return args, v0
+
+    # set abs tolerance and maxiter from method_kwargs if not provided
+    # apply defaults, but giving priority to user-specified values
+    method_kwargs = {**NEWTON_DEFAULT_PARAMS, **method_kwargs}
+
+    return args, v0, method_kwargs
 
 
-def _lambertw_v_from_i(resistance_shunt, resistance_series, nNsVth, current,
-                       saturation_current, photocurrent):
+def _lambertw_v_from_i(current, photocurrent, saturation_current,
+                       resistance_series, resistance_shunt, nNsVth):
     # Record if inputs were all scalar
     output_is_scalar = all(map(np.isscalar,
-                               [resistance_shunt, resistance_series, nNsVth,
-                                current, saturation_current, photocurrent]))
+                               (current, photocurrent, saturation_current,
+                                resistance_series, resistance_shunt, nNsVth)))
 
     # This transforms Gsh=1/Rsh, including ideal Rsh=np.inf into Gsh=0., which
     #  is generally more numerically stable
@@ -509,9 +659,9 @@ def _lambertw_v_from_i(resistance_shunt, resistance_series, nNsVth, current,
     # Ensure that we are working with read-only views of numpy arrays
     # Turns Series into arrays so that we don't have to worry about
     #  multidimensional broadcasting failing
-    Gsh, Rs, a, I, I0, IL = \
-        np.broadcast_arrays(conductance_shunt, resistance_series, nNsVth,
-                            current, saturation_current, photocurrent)
+    I, IL, I0, Rs, Gsh, a = \
+        np.broadcast_arrays(current, photocurrent, saturation_current,
+                            resistance_series, conductance_shunt, nNsVth)
 
     # Intitalize output V (I might not be float64)
     V = np.full_like(I, np.nan, dtype=np.float64)
@@ -572,12 +722,12 @@ def _lambertw_v_from_i(resistance_shunt, resistance_series, nNsVth, current,
         return V
 
 
-def _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth, voltage,
-                       saturation_current, photocurrent):
+def _lambertw_i_from_v(voltage, photocurrent, saturation_current,
+                       resistance_series, resistance_shunt, nNsVth):
     # Record if inputs were all scalar
     output_is_scalar = all(map(np.isscalar,
-                               [resistance_shunt, resistance_series, nNsVth,
-                                voltage, saturation_current, photocurrent]))
+                               (voltage, photocurrent, saturation_current,
+                                resistance_series, resistance_shunt, nNsVth)))
 
     # This transforms Gsh=1/Rsh, including ideal Rsh=np.inf into Gsh=0., which
     #  is generally more numerically stable
@@ -586,9 +736,9 @@ def _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth, voltage,
     # Ensure that we are working with read-only views of numpy arrays
     # Turns Series into arrays so that we don't have to worry about
     #  multidimensional broadcasting failing
-    Gsh, Rs, a, V, I0, IL = \
-        np.broadcast_arrays(conductance_shunt, resistance_series, nNsVth,
-                            voltage, saturation_current, photocurrent)
+    V, IL, I0, Rs, Gsh, a = \
+        np.broadcast_arrays(voltage, photocurrent, saturation_current,
+                            resistance_series, conductance_shunt, nNsVth)
 
     # Intitalize output I (V might not be float64)
     I = np.full_like(V, np.nan, dtype=np.float64)           # noqa: E741, N806
@@ -632,36 +782,36 @@ def _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth, voltage,
 
 def _lambertw(photocurrent, saturation_current, resistance_series,
               resistance_shunt, nNsVth, ivcurve_pnts=None):
+    # collect args
+    params = {'photocurrent': photocurrent,
+              'saturation_current': saturation_current,
+              'resistance_series': resistance_series,
+              'resistance_shunt': resistance_shunt, 'nNsVth': nNsVth}
+
     # Compute short circuit current
-    i_sc = _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth, 0.,
-                              saturation_current, photocurrent)
+    i_sc = _lambertw_i_from_v(0., **params)
 
     # Compute open circuit voltage
-    v_oc = _lambertw_v_from_i(resistance_shunt, resistance_series, nNsVth, 0.,
-                              saturation_current, photocurrent)
+    v_oc = _lambertw_v_from_i(0., **params)
 
-    params = {'r_sh': resistance_shunt,
-              'r_s': resistance_series,
-              'nNsVth': nNsVth,
-              'i_0': saturation_current,
-              'i_l': photocurrent}
+    # Set small elements <0 in v_oc to 0
+    if isinstance(v_oc, np.ndarray):
+        v_oc[(v_oc < 0) & (v_oc > -1e-12)] = 0.
+    elif isinstance(v_oc, (float, int)):
+        if v_oc < 0 and v_oc > -1e-12:
+            v_oc = 0.
 
     # Find the voltage, v_mp, where the power is maximized.
     # Start the golden section search at v_oc * 1.14
-    p_mp, v_mp = _golden_sect_DataFrame(params, 0., v_oc * 1.14,
-                                        _pwr_optfcn)
+    p_mp, v_mp = _golden_sect_DataFrame(params, 0., v_oc * 1.14, _pwr_optfcn)
 
     # Find Imp using Lambert W
-    i_mp = _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth,
-                              v_mp, saturation_current, photocurrent)
+    i_mp = _lambertw_i_from_v(v_mp, **params)
 
     # Find Ix and Ixx using Lambert W
-    i_x = _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth,
-                             0.5 * v_oc, saturation_current, photocurrent)
+    i_x = _lambertw_i_from_v(0.5 * v_oc, **params)
 
-    i_xx = _lambertw_i_from_v(resistance_shunt, resistance_series, nNsVth,
-                              0.5 * (v_oc + v_mp), saturation_current,
-                              photocurrent)
+    i_xx = _lambertw_i_from_v(0.5 * (v_oc + v_mp), **params)
 
     out = (i_sc, v_oc, i_mp, v_mp, p_mp, i_x, i_xx)
 
@@ -670,9 +820,7 @@ def _lambertw(photocurrent, saturation_current, resistance_series,
         ivcurve_v = (np.asarray(v_oc)[..., np.newaxis] *
                      np.linspace(0, 1, ivcurve_pnts))
 
-        ivcurve_i = _lambertw_i_from_v(resistance_shunt, resistance_series,
-                                       nNsVth, ivcurve_v.T, saturation_current,
-                                       photocurrent).T
+        ivcurve_i = _lambertw_i_from_v(ivcurve_v.T, **params).T
 
         out += (ivcurve_i, ivcurve_v)
 
@@ -684,7 +832,9 @@ def _pwr_optfcn(df, loc):
     Function to find power from ``i_from_v``.
     '''
 
-    I = _lambertw_i_from_v(df['r_sh'], df['r_s'],           # noqa: E741, N806
-                           df['nNsVth'], df[loc], df['i_0'], df['i_l'])
+    current = _lambertw_i_from_v(df[loc], df['photocurrent'],
+                                 df['saturation_current'],
+                                 df['resistance_series'],
+                                 df['resistance_shunt'], df['nNsVth'])
 
-    return I * df[loc]
+    return current * df[loc]

pvlib/snow.py

@@ -219,7 +219,7 @@ def _townsend_effective_snow(snow_total, snow_events):
 
 def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
                   temp_air, poa_global, slant_height, lower_edge_height,
-                  angle_of_repose=40):
+                  string_factor=1.0, angle_of_repose=40):
     '''
     Calculates monthly snow loss based on the Townsend monthly snow loss
     model [1]_.
@@ -230,7 +230,8 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         Snow received each month. Referred to as S in [1]_. [cm]
 
     snow_events : array-like
-        Number of snowfall events each month. Referred to as N in [1]_. [-]
+        Number of snowfall events each month. May be int or float type for
+        the average events in a typical month. Referred to as N in [1]_.
 
     surface_tilt : float
         Tilt angle of the array. [deg]
@@ -250,6 +251,11 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     lower_edge_height : float
         Distance from array lower edge to the ground. [m]
 
+    string_factor : float, default 1.0
+        Multiplier applied to monthly loss fraction. Use 1.0 if the DC array
+        has only one string of modules in the slant direction, use 0.75
+        otherwise. [-]
+
     angle_of_repose : float, default 40
         Piled snow angle, assumed to stabilize at 40°, the midpoint of
         25°-55° avalanching slope angles. [deg]
@@ -263,7 +269,12 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     -----
     This model has not been validated for tracking arrays; however, for
     tracking arrays [1]_ suggests using the maximum rotation angle in place
-    of ``surface_tilt``.
+    of ``surface_tilt``. The author of [1]_ recommends using one-half the
+    table width for ``slant_height``, i.e., the distance from the tracker
+    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.
 
     References
     ----------
@@ -273,13 +284,22 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
        :doi:`10.1109/PVSC.2011.6186627`
     '''
 
+    # unit conversions from cm and m to in, from C to K, and from % to fraction
+    # doing this early to facilitate comparison of this code with [1]
+    snow_total_inches = snow_total / 2.54  # to inches
+    relative_humidity_fraction = relative_humidity / 100.
+    poa_global_kWh = poa_global / 1000.
+    slant_height_inches = slant_height * 39.37
+    lower_edge_height_inches = lower_edge_height * 39.37
+    temp_air_kelvin = temp_air + 273.15
+
     C1 = 5.7e04
     C2 = 0.51
 
-    snow_total_prev = np.roll(snow_total, 1)
+    snow_total_prev = np.roll(snow_total_inches, 1)
     snow_events_prev = np.roll(snow_events, 1)
 
-    effective_snow = _townsend_effective_snow(snow_total, snow_events)
+    effective_snow = _townsend_effective_snow(snow_total_inches, snow_events)
     effective_snow_prev = _townsend_effective_snow(
         snow_total_prev,
         snow_events_prev
@@ -288,37 +308,38 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         1 / 3 * effective_snow_prev
         + 2 / 3 * effective_snow
     )
-    effective_snow_weighted_m = effective_snow_weighted / 100
 
-    lower_edge_height_clipped = np.maximum(lower_edge_height, 0.01)
+    # the lower limit of 0.1 in^2 is per private communication with the model's
+    # author. CWH 1/30/2023
+    lower_edge_distance = np.clip(
+        lower_edge_height_inches**2 - effective_snow_weighted**2, a_min=0.1,
+        a_max=None)
     gamma = (
-        slant_height
-        * effective_snow_weighted_m
+        slant_height_inches
+        * effective_snow_weighted
         * cosd(surface_tilt)
-        / (lower_edge_height_clipped**2 - effective_snow_weighted_m**2)
+        / lower_edge_distance
         * 2
         * tand(angle_of_repose)
     )
 
     ground_interference_term = 1 - C2 * np.exp(-gamma)
-    relative_humidity_fraction = relative_humidity / 100
-    temp_air_kelvin = temp_air + 273.15
-    effective_snow_weighted_in = effective_snow_weighted / 2.54
-    poa_global_kWh = poa_global / 1000
 
     # Calculate Eqn. 3 in the reference.
     # Although the reference says Eqn. 3 calculates percentage loss, the y-axis
     # of Figure 7 indicates Eqn. 3 calculates fractional loss. Since the slope
     # of the line in Figure 7 is the same as C1 in Eqn. 3, it is assumed that
     # Eqn. 3 calculates fractional loss.
+
     loss_fraction = (
         C1
-        * effective_snow_weighted_in
+        * effective_snow_weighted
         * cosd(surface_tilt)**2
         * ground_interference_term
         * relative_humidity_fraction
         / temp_air_kelvin**2
         / poa_global_kWh**0.67
+        * string_factor
     )
 
     return np.clip(loss_fraction, 0, 1)