Harmonize IAM and spectral correction and update IAM inference

Author: markcampanelli

pvlib/iam.py

@@ -17,66 +17,6 @@
 from pvlib.tools import cosd, sind, acosd
 
 
-def _get_builtin_models():
-    """
-    Get builtin IAM models' usage information.
-
-    Returns
-    -------
-    info : dict
-        A dictionary of dictionaries keyed by builtin IAM model name, with
-        each model dictionary containing:
-
-        * 'func': callable
-            The callable model function
-        * 'params_required': set of str
-            The model function's required parameters
-        * 'params_optional': set of str
-            The model function's optional parameters
-
-    See Also
-    --------
-    pvlib.iam.ashrae
-    pvlib.iam.interp
-    pvlib.iam.martin_ruiz
-    pvlib.iam.physical
-    pvlib.iam.sapm
-    pvlib.iam.schlick
-    """
-    return {
-        'ashrae': {
-            'func': ashrae,
-            'params_required': set(),
-            'params_optional': {'b'},
-        },
-        'interp': {
-            'func': interp,
-            'params_required': {'theta_ref', 'iam_ref'},
-            'params_optional': {'method', 'normalize'},
-        },
-        'martin_ruiz': {
-            'func': martin_ruiz,
-            'params_required': set(),
-            'params_optional': {'a_r'},
-        },
-        'physical': {
-            'func': physical,
-            'params_required': set(),
-            'params_optional': {'n', 'K', 'L', 'n_ar'},
-        },
-        'sapm': {
-            'func': sapm,
-            'params_required': {'B0', 'B1', 'B2', 'B3', 'B4', 'B5'},
-            'params_optional': {'upper'},
-        },
-        'schlick': {
-            'func': schlick,
-            'params_required': set(),
-            'params_optional': set(),
-        },
-    }
-
-
 def ashrae(aoi, b=0.05):
     r"""
     Determine the incidence angle modifier using the ASHRAE transmission
@@ -370,7 +310,7 @@ def martin_ruiz(aoi, a_r=0.16):
 
 def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
     '''
-    Determine the incidence angle modifiers (iam) for diffuse sky and
+    Determine the incidence angle modifiers (IAM) for diffuse sky and
     ground-reflected irradiance using the Martin and Ruiz incident angle model.
 
     Parameters
@@ -557,54 +497,88 @@ def interp(aoi, theta_ref, iam_ref, method='linear', normalize=True):
 
 def sapm(aoi, B0, B1, B2, B3, B4, B5, upper=None):
     r"""
-    Determine the incidence angle modifier (IAM) using the SAPM model.
+    Caclulate the incidence angle modifier (IAM), :math:`f_2`, using the
+    Sandia Array Performance Model (SAPM).
+
+    The SAPM incidence angle modifier is part of the broader Sandia Array
+    Performance Model, which defines five points on an IV curve using empirical
+    module-specific coefficients. Module coefficients for the SAPM are
+    available in the SAPM database and can be retrieved for use through
+    :py:func:`pvlib.pvsystem.retrieve_sam()`. More details on the SAPM can be
+    found in [1]_, while a full description of the procedure to determine the
+    empirical model coefficients, including those for the SAPM incidence angle
+    modifier, can be found in [2]_.
 
     Parameters
     ----------
     aoi : numeric
         Angle of incidence in degrees. Negative input angles will return
         zeros.
 
-    B0 : The coefficient of the degree-0 polynomial term.
+    B0 : float
+        The coefficient of the degree-0 polynomial term.
 
-    B1 : The coefficient of the degree-1 polynomial term.
+    B1 : float
+        The coefficient of the degree-1 polynomial term.
 
-    B2 : The coefficient of the degree-2 polynomial term.
+    B2 : float
+        The coefficient of the degree-2 polynomial term.
 
-    B3 : The coefficient of the degree-3 polynomial term.
+    B3 : float
+        The coefficient of the degree-3 polynomial term.
 
-    B4 : The coefficient of the degree-4 polynomial term.
+    B4 : float
+        The coefficient of the degree-4 polynomial term.
 
-    B5 : The coefficient of the degree-5 polynomial term.
+    B5 : float
+        The coefficient of the degree-5 polynomial term.
 
     upper : float, optional
         Upper limit on the results. None means no upper limiting.
 
     Returns
     -------
     iam : numeric
-        The SAPM angle of incidence loss coefficient, termed F2 in [1]_.
+        The SAPM angle of incidence loss coefficient, :math:`f_2` in [1]_.
 
     Notes
     -----
+    The SAPM spectral correction functions parameterises :math:`f_2` as a
+    fifth-order polynomial function of angle of incidence:
+
+    .. math::
+
+        f_2 = b_0 + b_1 AOI + b_2 AOI^2 + b_3 AOI^3 + b_4 AOI^4 + b_5 AOI^5.
+
+    where :math:`f_2` is the spectral mismatch factor, :math:`b_{0-5}` are
+    the module-specific coefficients, and :math:`AOI` is the angle of
+    incidence. More detail on how this incidence angle modifier function was
+    developed can be found in [3]_. Its measurement is described in [4]_.
+
     The SAPM [1]_ traditionally does not define an upper limit on the AOI
     loss function and values slightly exceeding 1 may exist for moderate
     angles of incidence (15-40 degrees). However, users may consider
     imposing an upper limit of 1.
 
     References
     ----------
-    .. [1] King, D. et al, 2004, "Sandia Photovoltaic Array Performance
-       Model", SAND Report 3535, Sandia National Laboratories, Albuquerque,
-       NM.
-
-    .. [2] B.H. King et al, "Procedure to Determine Coefficients for the
-       Sandia Array Performance Model (SAPM)," SAND2016-5284, Sandia
-       National Laboratories (2016).
-
-    .. [3] B.H. King et al, "Recent Advancements in Outdoor Measurement
-       Techniques for Angle of Incidence Effects," 42nd IEEE PVSC (2015).
-       :doi:`10.1109/PVSC.2015.7355849`
+    .. [1] King, D., Kratochvil, J., and Boyson W. (2004), "Sandia
+           Photovoltaic Array Performance Model", (No. SAND2004-3535), Sandia
+           National Laboratories, Albuquerque, NM (United States).
+           :doi:`10.2172/919131`
+    .. [2] King, B., Hansen, C., Riley, D., Robinson, C., and Pratt, L.
+           (2016). Procedure to determine coefficients for the Sandia Array
+           Performance Model (SAPM) (No. SAND2016-5284). Sandia National
+           Laboratories, Albuquerque, NM (United States).
+           :doi:`10.2172/1256510`
+    .. [3] King, D., Kratochvil, J., and Boyson, W. "Measuring solar spectral
+           and angle-of-incidence effects on photovoltaic modules and solar
+           irradiance sensors." Conference Record of the 26th IEEE Potovoltaic
+           Specialists Conference (PVSC). IEEE, 1997.
+           :doi:`10.1109/PVSC.1997.654283`
+    .. [4] B.H. King et al, "Recent Advancements in Outdoor Measurement
+           Techniques for Angle of Incidence Effects," 42nd IEEE PVSC (2015).
+           :doi:`10.1109/PVSC.2015.7355849`
 
     See Also
     --------
@@ -1022,6 +996,66 @@ def schlick_diffuse(surface_tilt):
     return cuk, cug
 
 
+def _get_builtin_models():
+    """
+    Get builtin IAM models' usage information.
+
+    Returns
+    -------
+    info : dict
+        A dictionary of dictionaries keyed by builtin IAM model name, with
+        each model dictionary containing:
+
+        * 'func': callable
+            The callable model function
+        * 'params_required': set of str
+            The model function's required parameters
+        * 'params_optional': set of str
+            The model function's optional parameters
+
+    See Also
+    --------
+    pvlib.iam.ashrae
+    pvlib.iam.interp
+    pvlib.iam.martin_ruiz
+    pvlib.iam.physical
+    pvlib.iam.sapm
+    pvlib.iam.schlick
+    """
+    return {
+        'ashrae': {
+            'func': ashrae,
+            'params_required': set(),
+            'params_optional': {'b'},
+        },
+        'interp': {
+            'func': interp,
+            'params_required': {'theta_ref', 'iam_ref'},
+            'params_optional': {'method', 'normalize'},
+        },
+        'martin_ruiz': {
+            'func': martin_ruiz,
+            'params_required': set(),
+            'params_optional': {'a_r'},
+        },
+        'physical': {
+            'func': physical,
+            'params_required': set(),
+            'params_optional': {'n', 'K', 'L', 'n_ar'},
+        },
+        'sapm': {
+            'func': sapm,
+            'params_required': {'B0', 'B1', 'B2', 'B3', 'B4', 'B5'},
+            'params_optional': {'upper'},
+        },
+        'schlick': {
+            'func': schlick,
+            'params_required': set(),
+            'params_optional': set(),
+        },
+    }
+
+
 def _get_fittable_or_convertable_model(builtin_model_name):
     # check that model is implemented and fittable or convertable
     implemented_builtin_models = {

pvlib/modelchain.py

@@ -782,62 +782,59 @@ def aoi_model(self, model):
                 self._aoi_model = self.schlick_aoi_loss
             else:
                 raise ValueError(model + ' is not a valid aoi loss model')
-        else:
-            # Assume callable model.
+        elif callable(model):
             self._aoi_model = partial(model, self)
+        else:
+            raise ValueError(model + ' is not a valid aoi loss model')
 
     def infer_aoi_model(self):
         """
-        Infer AOI model by checking for at least one required or optional
-        model parameter in module_parameter collected across all arrays.
+        Infer AOI model by checking for all required model paramters or at
+        least one optional model parameter in module_parameter collected
+        across all arrays.
         """
         module_parameters = tuple(
             array.module_parameters for array in self.system.arrays
         )
         params = _common_keys(module_parameters)
         builtin_models = pvlib.iam._get_builtin_models()
 
-        if any(
-            param in params for
-            param in builtin_models['ashrae']["params_required"].union(
-                builtin_models['ashrae']["params_optional"]
-            )
+        if (builtin_models['ashrae']["params_required"] and (
+            builtin_models['ashrae']["params_required"] <= params)) or (
+            not builtin_models['ashrae']["params_required"] and
+            (builtin_models['ashrae']["params_optional"] & params)
         ):
             return self.ashrae_aoi_loss
 
-        if any(
-            param in params for
-            param in builtin_models['interp']["params_required"].union(
-                builtin_models['interp']["params_optional"]
-            )
+        if (builtin_models['interp']["params_required"] and (
+            builtin_models['interp']["params_required"] <= params)) or (
+            not builtin_models['interp']["params_required"] and
+            (builtin_models['interp']["params_optional"] & params)
         ):
             return self.interp_aoi_loss
 
-        if any(
-            param in params for
-            param in builtin_models['martin_ruiz']["params_required"].union(
-                builtin_models['martin_ruiz']["params_optional"]
-            )
+        if (builtin_models['martin_ruiz']["params_required"] and (
+            builtin_models['martin_ruiz']["params_required"] <= params)) or (
+            not builtin_models['martin_ruiz']["params_required"] and
+            (builtin_models['martin_ruiz']["params_optional"] & params)
         ):
             return self.martin_ruiz_aoi_loss
 
-        if any(
-            param in params for
-            param in builtin_models['physical']["params_required"].union(
-                builtin_models['physical']["params_optional"]
-            )
+        if (builtin_models['physical']["params_required"] and (
+            builtin_models['physical']["params_required"] <= params)) or (
+            not builtin_models['physical']["params_required"] and
+            (builtin_models['physical']["params_optional"] & params)
         ):
             return self.physical_aoi_loss
 
-        if any(
-            param in params for
-            param in builtin_models['sapm']["params_required"].union(
-                builtin_models['sapm']["params_optional"]
-            )
+        if (builtin_models['sapm']["params_required"] and (
+            builtin_models['sapm']["params_required"] <= params)) or (
+            not builtin_models['sapm']["params_required"] and
+            (builtin_models['sapm']["params_optional"] & params)
         ):
             return self.sapm_aoi_loss
 
-        # schlick model has no parameters to distinguish.
+        # schlick model has no parameters to distinguish, esp. from no_loss.
 
         raise ValueError(
             'could not infer AOI model from '
@@ -909,8 +906,10 @@ def spectral_model(self, model):
                 self._spectral_model = self.no_spectral_loss
             else:
                 raise ValueError(model + ' is not a valid spectral loss model')
-        else:
+        elif callable(model):
             self._spectral_model = partial(model, self)
+        else:
+            raise ValueError(model + ' is not a valid spectral loss model')
 
     def infer_spectral_model(self):
         """Infer spectral model from system attributes."""

pvlib/pvsystem.py

@@ -633,9 +633,14 @@ def sapm_spectral_loss(self, airmass_absolute):
             The SAPM spectral loss coefficient.
         """
         return tuple(
-            spectrum.spectral_factor_sapm(airmass_absolute,
-                                          array.module_parameters)
-            for array in self.arrays
+            spectrum.spectral_factor_sapm(
+                airmass_absolute,
+                array.module_parameters["A0"],
+                array.module_parameters["A1"],
+                array.module_parameters["A2"],
+                array.module_parameters["A3"],
+                array.module_parameters["A4"],
+            ) for array in self.arrays
         )
 
     @_unwrap_single_value
@@ -2390,7 +2395,14 @@ def sapm_effective_irradiance(poa_direct, poa_diffuse, airmass_absolute, aoi,
     pvlib.pvsystem.sapm
     """
 
-    F1 = spectrum.spectral_factor_sapm(airmass_absolute, module)
+    F1 = spectrum.spectral_factor_sapm(
+        airmass_absolute,
+        module["A0"],
+        module["A1"],
+        module["A2"],
+        module["A3"],
+        module["A4"],
+    )
     F2 = iam.sapm(
         aoi,
         module["B0"],