move sapm aoi function, adjust ModelChain methods

pvlib · wholmgren · Oct 18, 2019 · Oct 2, 2019 · Oct 2, 2019 · Oct 2, 2019
commit 8505a0d0076647161cc561288b7a463ab1d7637d
diff --git a/pvlib/iam.py b/pvlib/iam.py
@@ -334,3 +334,64 @@ def interp(aoi, theta_ref, iam_ref, method='linear', normalize=True):
         iam = pd.Series(iam, index=aoi_input.index)
 
     return iam
+
+
+def sapm(aoi, module, upper=None):
+    """
+    Determine the incidence angle modifier (IAM) using the SAPM model.
+
+    Parameters
+    ----------
+    aoi : numeric
+        Angle of incidence in degrees. Negative input angles will return
+        zeros.
+
+    module : dict-like
+        A dict, Series, or DataFrame defining the SAPM performance
+        parameters. See the :py:func:`sapm` notes section for more
+        details.
+
+    upper : None or float, default None
+        Upper limit on the results.
+
+    Returns
+    -------
+    iam : numeric
+        The SAPM angle of incidence loss coefficient F2.
+
+    Notes
+    -----
+    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
+    """
+
+    aoi_coeff = [module['B5'], module['B4'], module['B3'], module['B2'],
+                 module['B1'], module['B0']]
+
+    iam = np.polyval(aoi_coeff, aoi)
+    iam = np.clip(iam, 0, upper)
+    # nan tolerant masking
+    aoi_lt_0 = np.full_like(aoi, False, dtype='bool')
+    np.less(aoi, 0, where=~np.isnan(aoi), out=aoi_lt_0)
+    iam = np.where(aoi_lt_0, 0, iam)
+
+    if isinstance(aoi, pd.Series):
+        iam = pd.Series(iam, aoi.index)
+
+    return iam
diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py
@@ -590,15 +590,15 @@ def infer_aoi_model(self):
                              'aoi_model="no_loss".')
 
     def ashrae_aoi_loss(self):
-        self.aoi_modifier = self.system.ashraeiam(self.aoi)
+        self.aoi_modifier = self.system.iam_ashrae(self.aoi)
         return self
 
     def physical_aoi_loss(self):
-        self.aoi_modifier = self.system.physicaliam(self.aoi)
+        self.aoi_modifier = self.system.iam_physical(self.aoi)
         return self
 
     def sapm_aoi_loss(self):
-        self.aoi_modifier = self.system.sapm_aoi_loss(self.aoi)
+        self.aoi_modifier = self.system.iam_sapm(self.aoi)
         return self
 
     def no_aoi_loss(self):

diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py
@@ -550,8 +550,18 @@ def sapm_spectral_loss(self, airmass_absolute):
 
     def sapm_aoi_loss(self, aoi):
         """
-        Use the :py:func:`sapm_aoi_loss` function, the input parameters,
-        and ``self.module_parameters`` to calculate F2.
+        Deprecated. Use ``PVSystem.iam_sapm`` instead.
+        """
+        import warnings
+        warnings.warn(
+        'PVSystem.sapm_aoi_loss is deprecated and will be removed in v0.8,'
+        ' use PVSystem.iam_sapm instead', pvlibDeprecationWarning)
+        return PVSystem.iam_sapm(self, aoi)
+
+    def iam_sapm(self, aoi):
+        """
+        Use the :py:func:`iam.sapm` function, the input parameters,
+        and ``self.module_parameters`` to calculate iam.
 
         Parameters
         ----------
@@ -560,10 +570,10 @@ def sapm_aoi_loss(self, aoi):
 
         Returns
         -------
-        F2 : numeric
-            The SAPM angle of incidence loss coefficient.
+        iam : numeric
+            The SAPM angle of incidence loss coefficient F2.
         """
-        return sapm_aoi_loss(aoi, self.module_parameters)
+        return iam.sapm(aoi, self.module_parameters)
 
     def sapm_effective_irradiance(self, poa_direct, poa_diffuse,
                                   airmass_absolute, aoi,
@@ -1846,67 +1856,6 @@ def sapm_spectral_loss(airmass_absolute, module):
     return spectral_loss
 
 
-def sapm_aoi_loss(aoi, module, upper=None):
-    """
-    Calculates the SAPM angle of incidence loss coefficient, F2.
-
-    Parameters
-    ----------
-    aoi : numeric
-        Angle of incidence in degrees. Negative input angles will return
-        zeros.
-
-    module : dict-like
-        A dict, Series, or DataFrame defining the SAPM performance
-        parameters. See the :py:func:`sapm` notes section for more
-        details.
-
-    upper : None or float, default None
-        Upper limit on the results.
-
-    Returns
-    -------
-    F2 : numeric
-        The SAPM angle of incidence loss coefficient.
-
-    Notes
-    -----
-    The SAPM 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
-    """
-
-    aoi_coeff = [module['B5'], module['B4'], module['B3'], module['B2'],
-                 module['B1'], module['B0']]
-
-    aoi_loss = np.polyval(aoi_coeff, aoi)
-    aoi_loss = np.clip(aoi_loss, 0, upper)
-    # nan tolerant masking
-    aoi_lt_0 = np.full_like(aoi, False, dtype='bool')
-    np.less(aoi, 0, where=~np.isnan(aoi), out=aoi_lt_0)
-    aoi_loss = np.where(aoi_lt_0, 0, aoi_loss)
-
-    if isinstance(aoi, pd.Series):
-        aoi_loss = pd.Series(aoi_loss, aoi.index)
-
-    return aoi_loss
-
-
 def sapm_effective_irradiance(poa_direct, poa_diffuse, airmass_absolute, aoi,
                               module, reference_irradiance=1000):
     """
@@ -1942,7 +1891,7 @@ def sapm_effective_irradiance(poa_direct, poa_diffuse, airmass_absolute, aoi,
     """
 
     F1 = sapm_spectral_loss(airmass_absolute, module)
-    F2 = sapm_aoi_loss(aoi, module)
+    F2 = _iam.sapm(aoi, module)
 
     E0 = reference_irradiance
 

diff --git a/pvlib/test/test_iam.py b/pvlib/test/test_iam.py
@@ -148,3 +148,24 @@ def test_iam_interp():
     # check exception clause
     with pytest.raises(ValueError):
         _iam.interp(0.0, [0, 90], [1, -1])
+
+
+def test_sapm(sapm_module_params, aoi, expected):
+
+    out = _iam.sapm(aoi, sapm_module_params)
+
+    if isinstance(aoi, pd.Series):
+        assert_series_equal(out, expected, check_less_precise=4)
+    else:
+        assert_allclose(out, expected, atol=1e-4)
+
+
+def test_sapm_limits():
+    module_parameters = {'B0': 5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
+    assert _iam.sapm_aoi_loss(1, module_parameters) == 5
+
+    module_parameters = {'B0': 5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
+    assert _iam.sapm_aoi_loss(1, module_parameters, upper=1) == 1
+
+    module_parameters = {'B0': -5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
+    assert _iam.sapm_aoi_loss(1, module_parameters) == 0
diff --git a/pvlib/test/test_pvsystem.py b/pvlib/test/test_pvsystem.py
@@ -293,33 +293,14 @@ def test_PVSystem_first_solar_spectral_loss(module_parameters, module_type,
      np.array([[0, 1.007572, 0, np.nan]])),
     (pd.Series([80]), pd.Series([0.597472]))
 ])
-def test_sapm_aoi_loss(sapm_module_params, aoi, expected):
 
-    out = pvsystem.sapm_aoi_loss(aoi, sapm_module_params)
 
-    if isinstance(aoi, pd.Series):
-        assert_series_equal(out, expected, check_less_precise=4)
-    else:
-        assert_allclose(out, expected, atol=1e-4)
-
-
-def test_sapm_aoi_loss_limits():
-    module_parameters = {'B0': 5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
-    assert pvsystem.sapm_aoi_loss(1, module_parameters) == 5
-
-    module_parameters = {'B0': 5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
-    assert pvsystem.sapm_aoi_loss(1, module_parameters, upper=1) == 1
-
-    module_parameters = {'B0': -5, 'B1': 0, 'B2': 0, 'B3': 0, 'B4': 0, 'B5': 0}
-    assert pvsystem.sapm_aoi_loss(1, module_parameters) == 0
-
-
-def test_PVSystem_sapm_aoi_loss(sapm_module_params, mocker):
+def test_PVSystem_aoi_sapm(sapm_module_params, mocker):
     system = pvsystem.PVSystem(module_parameters=sapm_module_params)
-    mocker.spy(pvsystem, 'sapm_aoi_loss')
+    mocker.spy(_iam, 'sapm')
     aoi = 0
-    out = system.sapm_aoi_loss(aoi)
-    pvsystem.sapm_aoi_loss.assert_called_once_with(aoi, sapm_module_params)
+    out = system.aoi_sapm(aoi)
+    _iam.sapm.assert_called_once_with(aoi, sapm_module_params)
     assert_allclose(out, 1.0, atol=0.01)