Implement Caballero et al. spectral factor model

docs/sphinx/source/api.rst

@@ -126,6 +126,7 @@ Airmass and atmospheric models
    atmosphere.kasten96_lt
    atmosphere.angstrom_aod_at_lambda
    atmosphere.angstrom_alpha
+   atmosphere.caballero_spectral_correction
 
 
 Irradiance

pvlib/atmosphere.py

@@ -683,3 +683,151 @@ 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:`MM` 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 'pervovskite'. 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
+        TODO: description
+
+    pw_ref : numeric, default 1.42
+        TODO: description
+
+    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 TypeError('Invalid input provided, both module_type'
+                        + 'and coefficients are None')
+    elif module_type is not None and coefficients is None:
+        raise TypeError('Cannot resolve input, providing the'
+                        + ' coefficients input is mandatory')
+    else:
+        pass
+
+    # Evaluate Spectral Shift
+    coeff = coefficients
+    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

pvlib/tests/test_atmosphere.py

@@ -187,3 +187,48 @@ 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)
+    expected = 1.0021964
+    assert_allclose(out, expected, atol=1e-3)
+
+
+def test_caballero_spectral_correction_supplied_ambiguous():
+    dummy_coeffs = (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1)
+    with pytest.raises(TypeError):
+        atmosphere.caballero_spectral_correction(1, 1, 1,
+                                                 module_type='cdte',
+                                                 coefficients=dummy_coeffs)
+
+
+def test_caballero_spectral_correction_supplied_ambiguous_1():
+    with pytest.raises(TypeError):
+        atmosphere.caballero_spectral_correction(1, 1, 1,
+                                                 module_type=None,
+                                                 coefficients=None)