rename function and move to pvlib.spectrum

kandersolar · kandersolar · commit f2292552a73e · 2023-06-12T09:11:21.000-04:00
following the conventions set out in pvlib#1628
diff --git a/docs/sphinx/source/reference/airmass_atmospheric.rst b/docs/sphinx/source/reference/airmass_atmospheric.rst
@@ -17,4 +17,3 @@ Airmass and atmospheric models
    atmosphere.kasten96_lt
    atmosphere.angstrom_aod_at_lambda
    atmosphere.angstrom_alpha
-   atmosphere.caballero_spectral_correction
diff --git a/docs/sphinx/source/reference/effects_on_pv_system_output/spectrum.rst b/docs/sphinx/source/reference/effects_on_pv_system_output/spectrum.rst
@@ -10,5 +10,6 @@ Spectrum
    spectrum.get_example_spectral_response
    spectrum.get_am15g
    spectrum.calc_spectral_mismatch_field
+   spectrum.spectral_factor_caballero
    spectrum.spectral_factor_firstsolar
    spectrum.spectral_factor_sapm
diff --git a/docs/sphinx/source/whatsnew/v0.9.6.rst b/docs/sphinx/source/whatsnew/v0.9.6.rst
@@ -33,8 +33,8 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-* `Added a function :py:func:`pvlib.atmosphere.caballero_spectral_correction` to estimate a spectral mismatch modifier based on absolute (pressure-adjusted)
-   airmass (AM), aerosol optical depth (AOD) at 500 nm and precipitable water (PW). (:pull:`1296`)
+* Added a function :py:func:`pvlib.spectrum.spectral_factor_caballero`
+  to estimate spectral mismatch modifiers from atmospheric conditions. (:pull:`1296`)
 * Added a new irradiance decomposition model :py:func:`pvlib.irradiance.louche`. (:pull:`1705`)
 * Add optional encoding parameter to :py:func:`pvlib.iotools.read_tmy3`.
   (:issue:`1732`, :pull:`1737`)
diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py
@@ -533,153 +533,3 @@ def angstrom_alpha(aod1, lambda1, aod2, lambda2):
     pvlib.atmosphere.angstrom_aod_at_lambda
     """
     return - np.log(aod1 / aod2) / np.log(lambda1 / lambda2)
-
-
-def caballero_spectral_correction(airmass_absolute, aod500, pw,
-                                  module_type=None, coefficients=None,
-                                  aod500_ref=0.084, pw_ref=1.42):
-    r"""
-    Spectral mismatch modifier based on absolute (pressure-adjusted)
-    airmass (AM), aerosol optical depth (AOD) at 500 nm and
-    precipitable water (PW).
-
-    Estimates a spectral mismatch modifier :math:`M` representing
-    the effect on module short circuit current of variation in the
-    spectral irradiance. :math:`M` is estimated from absolute
-    (pressure-adjusted) AM, :math:`ama`, AOD at 500 nm, :math:`aod500`
-    and PW, :math:`pw` [1]_.
-
-    The best fit polynomial for each atmospheric parameter (AM, AOD, PW)
-    and PV technology under study has been obtained from synthetic spectra
-    generated with SMARTS [2]_, considering the following boundary
-    conditions:
-
-       * :math:`1.0 <= ama <= 5.0`
-       * :math:`0.05 <= aod500 <= 0.6`
-       * :math:`0.25 \textrm{cm} <= pw <= 4 \textrm{cm}`
-       * Spectral range is limited to that of CMP11 (280 nm to 2800 nm)
-       * All other parameters fixed at G173 standard
-
-    Elevation (deg), AOD and PW data were recorded in the city of Jaén,
-    Spain for one year synchronously with both, broadband and
-    spectroradiometric measurements of 30º tilted global irradiance
-    south-facing logged in 5-min intervals. AM was estimated through
-    elevation data.
-
-    Finally, the spectral mismatch factor was calculated for each
-    of the PV technologies and a multivariable regression adjustment
-    as a function of AM, AOD and PW was performed according to [3] and [1]_.
-    As such, the polynomial adjustment coefficients included in [1]
-    were obtained.
-
-
-    Parameters
-    ----------
-    airmass_absolute : array-like
-        absolute (pressure-adjusted) airmass. [unitless]
-
-    aod500 : array-like
-        atmospheric aerosol optical depth at 500 nm. [unitless]
-
-    pw : array-like
-        atmospheric precipitable water. [cm]
-
-    module_type : None or string, default None
-        a string specifying a cell type. Values of 'cdte', 'monosi', 'cigs',
-        'multisi','asi' and 'perovskite'. If provided,
-        module_type selects default coefficients for the following modules:
-
-            * 'cdte' - anonymous CdTe module.
-            * 'monosi', - anonymous sc-si module.
-            * 'multisi', - anonymous mc-si- module.
-            * 'cigs' - anonymous copper indium gallium selenide module.
-            * 'asi' - anonymous amorphous silicon module.
-            * 'perovskite' - anonymous pervoskite module.
-
-    coefficients : None or array-like, optional
-        the coefficients employed have been obtained with experimental
-        data in the city of Jaén, Spain. It is pending to verify if such
-        coefficients vary in places with extreme climates where AOD and
-        pw values are frequently high.
-
-    aod500_ref : numeric, default 0.084
-        atmospheric aerosol optical depth at 500nm value related to the
-        AM1.5G ASTMG-173-03 reference spectrum. [unitless]
-
-    pw_ref : numeric, default 1.42
-        atmospheric precipitable water value related to the AM1.5G ASTMG-173-03
-        reference spectrum. [cm]
-
-    Returns
-    -------
-    modifier: array-like
-        spectral mismatch factor (unitless) which is can be multiplied
-        with broadband irradiance reaching a module's cells to estimate
-        effective irradiance, i.e., the irradiance that is converted to
-        electrical current.
-
-    References
-    ----------
-    .. [1] Caballero, J.A., Fernández, E., Theristis, M.,
-        Almonacid, F., and Nofuentes, G. "Spectral Corrections Based on
-        Air Mass, Aerosol Optical Depth and Precipitable Water
-        for PV Performance Modeling."
-        IEEE Journal of Photovoltaics 2018, 8(2), 552-558.
-        https://doi.org/10.1109/jphotov.2017.2787019
-    .. [2] Gueymard, Christian. SMARTS2: a simple model of the
-        atmospheric radiative transfer of sunshine: algorithms
-        and performance assessment. Cocoa, FL:
-        Florida Solar Energy Center, 1995.
-    .. [3] Theristis, M., Fernández, E., Almonacid, F., and
-       Pérez-Higueras, Pedro. "Spectral Corrections Based
-       on Air Mass, Aerosol Optical Depth and Precipitable
-       Water for CPV Performance Modeling."
-       IEEE Journal of Photovoltaics 2016, 6(6), 1598-1604.
-       https://doi.org/10.1109/jphotov.2016.2606702
-
-        """
-
-    # Experimental coefficients
-
-    _coefficients = {}
-    _coefficients['cdte'] = (
-        1.0044, 0.0095, -0.0037, 0.0002, 0.0000, -0.0046,
-        -0.0182, 0, 0.0095, 0.0068, 0, 1)
-    _coefficients['monosi'] = (
-        0.9706, 0.0377, -0.0123, 0.0025, -0.0002, 0.0159,
-        -0.0165, 0, -0.0016, -0.0027, 1, 0)
-    _coefficients['multisi'] = (
-        0.9836, 0.0254, -0.0085, 0.0016, -0.0001, 0.0094,
-        -0.0132, 0, -0.0002, -0.0011, 1, 0)
-    _coefficients['cigs'] = (
-        0.9801, 0.0283, -0.0092, 0.0019, -0.0001, 0.0117,
-        -0.0126, 0, -0.0011, -0.0019, 1, 0)
-    _coefficients['asi'] = (
-        1.1060, -0.0848, 0.0302, -0.0076, 0.0006, -0.1283,
-        0.0986, -0.0254, 0.0156, 0.0146, 1, 0)
-    _coefficients['perovskite'] = (
-        1.0637, -0.0491, 0.0180, -0.0047, 0.0004, -0.0773,
-        0.0583, -0.0159, 0.01251, 0.0109, 1, 0)
-
-    if module_type is None and coefficients is None:
-        raise ValueError('Must provide either `module_type` or `coefficients`')
-    if module_type is not None and coefficients is not None:
-        raise ValueError('Only one of `module_type` and `coefficients` should '
-                         'be provided')
-    if module_type is not None:
-        coeff = _coefficients[module_type]
-    else:
-        coeff = coefficients
-
-    # Evaluate spectral correction factor
-    ama = airmass_absolute
-    modifier = (
-        coeff[0] + (ama) * coeff[1] + (ama * ama) * coeff[2]
-        + (ama * ama * ama) * coeff[3] + (ama * ama * ama * ama) * coeff[4]
-        + (aod500 - aod500_ref) * coeff[5]
-        + ((aod500 - aod500_ref) * (ama) * coeff[6]) * coeff[10]
-        + ((aod500 - aod500_ref) * (np.log(ama)) * coeff[6]) * coeff[11]
-        + (aod500 - aod500_ref) * (ama * ama) * coeff[7]
-        + (pw - pw_ref) * coeff[8] + (pw - pw_ref) * (np.log(ama)) * coeff[9])
-
-    return modifier
diff --git a/pvlib/spectrum/__init__.py b/pvlib/spectrum/__init__.py
@@ -3,6 +3,7 @@
     calc_spectral_mismatch_field,
     get_am15g,
     get_example_spectral_response,
+    spectral_factor_caballero,
     spectral_factor_firstsolar,
     spectral_factor_sapm,
 )
diff --git a/pvlib/spectrum/mismatch.py b/pvlib/spectrum/mismatch.py
@@ -446,3 +446,153 @@ def spectral_factor_sapm(airmass_absolute, module):
         spectral_loss = pd.Series(spectral_loss, airmass_absolute.index)
 
     return spectral_loss
+
+
+def caballero_spectral_correction(airmass_absolute, aod500, pw,
+                                  module_type=None, coefficients=None,
+                                  aod500_ref=0.084, pw_ref=1.42):
+    r"""
+    Spectral mismatch modifier based on absolute (pressure-adjusted)
+    airmass (AM), aerosol optical depth (AOD) at 500 nm and
+    precipitable water (PW).
+
+    Estimates a spectral mismatch modifier :math:`M` representing
+    the effect on module short circuit current of variation in the
+    spectral irradiance. :math:`M` is estimated from absolute
+    (pressure-adjusted) AM, :math:`ama`, AOD at 500 nm, :math:`aod500`
+    and PW, :math:`pw` [1]_.
+
+    The best fit polynomial for each atmospheric parameter (AM, AOD, PW)
+    and PV technology under study has been obtained from synthetic spectra
+    generated with SMARTS [2]_, considering the following boundary
+    conditions:
+
+       * :math:`1.0 <= ama <= 5.0`
+       * :math:`0.05 <= aod500 <= 0.6`
+       * :math:`0.25 \textrm{cm} <= pw <= 4 \textrm{cm}`
+       * Spectral range is limited to that of CMP11 (280 nm to 2800 nm)
+       * All other parameters fixed at G173 standard
+
+    Elevation (deg), AOD and PW data were recorded in the city of Jaén,
+    Spain for one year synchronously with both, broadband and
+    spectroradiometric measurements of 30º tilted global irradiance
+    south-facing logged in 5-min intervals. AM was estimated through
+    elevation data.
+
+    Finally, the spectral mismatch factor was calculated for each
+    of the PV technologies and a multivariable regression adjustment
+    as a function of AM, AOD and PW was performed according to [3] and [1]_.
+    As such, the polynomial adjustment coefficients included in [1]
+    were obtained.
+
+
+    Parameters
+    ----------
+    airmass_absolute : array-like
+        absolute (pressure-adjusted) airmass. [unitless]
+
+    aod500 : array-like
+        atmospheric aerosol optical depth at 500 nm. [unitless]
+
+    pw : array-like
+        atmospheric precipitable water. [cm]
+
+    module_type : None or string, default None
+        a string specifying a cell type. Values of 'cdte', 'monosi', 'cigs',
+        'multisi','asi' and 'perovskite'. If provided,
+        module_type selects default coefficients for the following modules:
+
+            * 'cdte' - anonymous CdTe module.
+            * 'monosi', - anonymous sc-si module.
+            * 'multisi', - anonymous mc-si- module.
+            * 'cigs' - anonymous copper indium gallium selenide module.
+            * 'asi' - anonymous amorphous silicon module.
+            * 'perovskite' - anonymous pervoskite module.
+
+    coefficients : None or array-like, optional
+        the coefficients employed have been obtained with experimental
+        data in the city of Jaén, Spain. It is pending to verify if such
+        coefficients vary in places with extreme climates where AOD and
+        pw values are frequently high.
+
+    aod500_ref : numeric, default 0.084
+        atmospheric aerosol optical depth at 500nm value related to the
+        AM1.5G ASTMG-173-03 reference spectrum. [unitless]
+
+    pw_ref : numeric, default 1.42
+        atmospheric precipitable water value related to the AM1.5G ASTMG-173-03
+        reference spectrum. [cm]
+
+    Returns
+    -------
+    modifier: array-like
+        spectral mismatch factor (unitless) which is can be multiplied
+        with broadband irradiance reaching a module's cells to estimate
+        effective irradiance, i.e., the irradiance that is converted to
+        electrical current.
+
+    References
+    ----------
+    .. [1] Caballero, J.A., Fernández, E., Theristis, M.,
+        Almonacid, F., and Nofuentes, G. "Spectral Corrections Based on
+        Air Mass, Aerosol Optical Depth and Precipitable Water
+        for PV Performance Modeling."
+        IEEE Journal of Photovoltaics 2018, 8(2), 552-558.
+        https://doi.org/10.1109/jphotov.2017.2787019
+    .. [2] Gueymard, Christian. SMARTS2: a simple model of the
+        atmospheric radiative transfer of sunshine: algorithms
+        and performance assessment. Cocoa, FL:
+        Florida Solar Energy Center, 1995.
+    .. [3] Theristis, M., Fernández, E., Almonacid, F., and
+       Pérez-Higueras, Pedro. "Spectral Corrections Based
+       on Air Mass, Aerosol Optical Depth and Precipitable
+       Water for CPV Performance Modeling."
+       IEEE Journal of Photovoltaics 2016, 6(6), 1598-1604.
+       https://doi.org/10.1109/jphotov.2016.2606702
+
+        """
+
+    # Experimental coefficients
+
+    _coefficients = {}
+    _coefficients['cdte'] = (
+        1.0044, 0.0095, -0.0037, 0.0002, 0.0000, -0.0046,
+        -0.0182, 0, 0.0095, 0.0068, 0, 1)
+    _coefficients['monosi'] = (
+        0.9706, 0.0377, -0.0123, 0.0025, -0.0002, 0.0159,
+        -0.0165, 0, -0.0016, -0.0027, 1, 0)
+    _coefficients['multisi'] = (
+        0.9836, 0.0254, -0.0085, 0.0016, -0.0001, 0.0094,
+        -0.0132, 0, -0.0002, -0.0011, 1, 0)
+    _coefficients['cigs'] = (
+        0.9801, 0.0283, -0.0092, 0.0019, -0.0001, 0.0117,
+        -0.0126, 0, -0.0011, -0.0019, 1, 0)
+    _coefficients['asi'] = (
+        1.1060, -0.0848, 0.0302, -0.0076, 0.0006, -0.1283,
+        0.0986, -0.0254, 0.0156, 0.0146, 1, 0)
+    _coefficients['perovskite'] = (
+        1.0637, -0.0491, 0.0180, -0.0047, 0.0004, -0.0773,
+        0.0583, -0.0159, 0.01251, 0.0109, 1, 0)
+
+    if module_type is None and coefficients is None:
+        raise ValueError('Must provide either `module_type` or `coefficients`')
+    if module_type is not None and coefficients is not None:
+        raise ValueError('Only one of `module_type` and `coefficients` should '
+                         'be provided')
+    if module_type is not None:
+        coeff = _coefficients[module_type]
+    else:
+        coeff = coefficients
+
+    # Evaluate spectral correction factor
+    ama = airmass_absolute
+    modifier = (
+        coeff[0] + (ama) * coeff[1] + (ama * ama) * coeff[2]
+        + (ama * ama * ama) * coeff[3] + (ama * ama * ama * ama) * coeff[4]
+        + (aod500 - aod500_ref) * coeff[5]
+        + ((aod500 - aod500_ref) * (ama) * coeff[6]) * coeff[10]
+        + ((aod500 - aod500_ref) * (np.log(ama)) * coeff[6]) * coeff[11]
+        + (aod500 - aod500_ref) * (ama * ama) * coeff[7]
+        + (pw - pw_ref) * coeff[8] + (pw - pw_ref) * (np.log(ama)) * coeff[9])
+
+    return modifier
diff --git a/pvlib/tests/test_atmosphere.py b/pvlib/tests/test_atmosphere.py
@@ -131,56 +131,3 @@ def test_bird_hulstrom80_aod_bb():
     aod380, aod500 = 0.22072480948195175, 0.1614279181106312
     bird_hulstrom = atmosphere.bird_hulstrom80_aod_bb(aod380, aod500)
     assert np.isclose(0.11738229553812768, bird_hulstrom)
-
-
-@pytest.mark.parametrize("module_type,expected", [
-    ('asi', np.array([0.9108, 0.9897, 0.9707, 1.0265, 1.0798, 0.9537])),
-    ('perovskite', np.array([0.9422, 0.9932, 0.9868, 1.0183, 1.0604, 0.9737])),
-    ('cdte', np.array([0.9824, 1.0000, 1.0065, 1.0117, 1.042, 0.9979])),
-    ('multisi', np.array([0.9907, 0.9979, 1.0203, 1.0081, 1.0058, 1.019])),
-    ('monosi', np.array([0.9935, 0.9987, 1.0264, 1.0074, 0.9999, 1.0263])),
-    ('cigs', np.array([1.0014, 1.0011, 1.0270, 1.0082, 1.0029, 1.026])),
-])
-def test_caballero_spectral_correction(module_type, expected):
-    ams = np.array([3.0, 1.5, 3.0, 1.5, 1.5, 3.0])
-    aods = np.array([1.0, 1.0, 0.02, 0.02, 0.08, 0.08])
-    pws = np.array([1.42, 1.42, 1.42, 1.42, 4.0, 1.0])
-    out = atmosphere.caballero_spectral_correction(ams, aods, pws,
-                                                   module_type=module_type,
-                                                   aod500_ref=0.084,
-                                                   pw_ref=1.42)
-    assert np.allclose(expected, out, atol=1e-3)
-
-
-def test_caballero_spectral_correction_supplied():
-    # use the cdte coeffs
-    coeffs = (
-        1.0044, 0.0095, -0.0037, 0.0002, 0.0000, -0.0046,
-        -0.0182, 0, 0.0095, 0.0068, 0, 1)
-    out = atmosphere.caballero_spectral_correction(1, 1, 1,
-                                                   coefficients=coeffs,
-                                                   aod500_ref=0.084,
-                                                   pw_ref=1.42)
-    expected = 1.0021964
-    assert_allclose(out, expected, atol=1e-3)
-
-
-def test_caballero_spectral_correction_supplied_redundant():
-    # Error when specifying both module_type and coefficients
-    coeffs = (
-        1.0044, 0.0095, -0.0037, 0.0002, 0.0000, -0.0046,
-        -0.0182, 0, 0.0095, 0.0068, 0, 1)
-    with pytest.raises(ValueError):
-        atmosphere.caballero_spectral_correction(1, 1, 1,
-                                                 module_type='cdte',
-                                                 coefficients=coeffs,
-                                                 aod500_ref=0.084, pw_ref=1.42)
-
-
-def test_caballero_spectral_correction_supplied_ambiguous():
-    # Error when specifying neither module_type nor coefficients
-    with pytest.raises(ValueError):
-        atmosphere.caballero_spectral_correction(1, 1, 1,
-                                                 module_type=None,
-                                                 coefficients=None,
-                                                 aod500_ref=0.084, pw_ref=1.42)
diff --git a/pvlib/tests/test_spectrum.py b/pvlib/tests/test_spectrum.py

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`	`calc_spectral_mismatch_field,`
`4`	`4`	`get_am15g,`
`5`	`5`	`get_example_spectral_response,`
	`6`	`+ spectral_factor_caballero,`
`6`	`7`	`spectral_factor_firstsolar,`
`7`	`8`	`spectral_factor_sapm,`
`8`	`9`	`)`