Add polo-smm

docs/sphinx/source/reference/effects_on_pv_system_output/spectrum.rst

@@ -12,9 +12,10 @@ Spectrum
    spectrum.calc_spectral_mismatch_field
    spectrum.spectral_factor_caballero
    spectrum.spectral_factor_firstsolar
-   spectrum.spectral_factor_sapm
-   spectrum.spectral_factor_pvspec
    spectrum.spectral_factor_jrc
+   spectrum.spectral_factor_polo
+   spectrum.spectral_factor_pvspec
+   spectrum.spectral_factor_sapm
    spectrum.sr_to_qe
    spectrum.qe_to_sr
    spectrum.average_photon_energy

pvlib/spectrum/__init__.py

@@ -3,9 +3,10 @@
     calc_spectral_mismatch_field,
     spectral_factor_caballero,
     spectral_factor_firstsolar,
-    spectral_factor_sapm,
-    spectral_factor_pvspec,
     spectral_factor_jrc,
+    spectral_factor_polo,
+    spectral_factor_pvspec,
+    spectral_factor_sapm,
 )
 from pvlib.spectrum.irradiance import (  # noqa: F401
     get_reference_spectra,

pvlib/spectrum/mismatch.py

@@ -710,3 +710,90 @@ def spectral_factor_jrc(airmass, clearsky_index, module_type=None,
         + coeff[2] * (airmass - 1.5)
     )
     return mismatch
+
+
+def spectral_factor_polo(precipitable_water, airmass_absolute, aod500, aoi,
+                         altitude, module_type=None, coefficients=None,
+                         albedo=0.2):
+    """
+    Estimate the spectral mismatch for BIPV application in vertical facades.
+
+    Parameters
+    ----------
+    precipitable_water : numeric
+        atmospheric precipitable water. [cm]
+    airmass_absolute : numeric
+        absolute (pressure-adjusted) airmass. See :term:`airmass_absolute`.
+        [unitless]
+    aod500 : numeric
+        atmospheric aerosol optical depth at 500 nm. [unitless]
+    aoi : numeric
+        Angle of incidence on the vertical surface.  See :term:`aoi`.
+        [degrees]
+    altitude: numeric
+        altitude over sea level. [m]
+    module_type : str, optional
+        One of the following PV technology strings from [1]_:
+
+        * ``'cdte'`` - anonymous CdTe module.
+        * ``'monosi'`` - anonymous monocrystalline silicon module.
+        * ``'cigs'`` - anonymous copper indium gallium selenide module.
+        * ``'asi'`` - anonymous amorphous silicon module.
+    albedo : float, optional
+        Ground albedo (default value 0.2). See :term:`albedo`. [unitless]
+
+    coefficients : array-like, optional
+        user-defined coefficients, if not using one of the coefficient
+        sets via the ``module_type`` parameter.
+
+    Returns
+    -------
+    modifier: numeric
+        spectral mismatch factor (unitless) which is 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] J. Polo and C. Sanz-Saiz, 'Development of spectral mismatch models
+       for BIPV applications in building façades', Renewable Energy, vol. 245,
+       p. 122820, Jun. 2025, :doi:`10.1016/j.renene.2025.122820`
+    """
+    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')
+    am_aoi = pvlib.atmosphere.get_relative_airmass(aoi)
+    pressure = pvlib.atmosphere.alt2pres(altitude)
+    am90 = pvlib.atmosphere.get_absolute_airmass(am_aoi, pressure)
+    Ram = am90 / airmass_absolute
+    f_aoi_rel= pvlib.atmosphere.get_relative_airmass(aoi, model='kastenyoung1989')
+    pressure = pvlib.atmosphere.alt2pres(altitude)
+    f_aoi = pvlib.atmosphere.get_absolute_airmass(f_aoi_rel, pressure)
+    Ram = f_aoi / airmass_absolute
+    _coefficients = {
+        'cdte': (-0.0009, 46.80, 49.20, -0.87, 0.00041, 0.053),
+        'monosi': (0.0027, 10.34, 9.48, 0.307, 0.00077, 0.006),
+        'cigs': (0.0017, 2.33, 1.30, 0.11, 0.00098, -0.0177),
+        'asi': (0.0024, 7.32, 7.09, -0.72, -0.0013, 0.089),
+    }
+    c = {
+        'asi': (0.0056, -0.020, 1.014),
+        'cigs': (-0.0009, -0.0003, 1),
+        'cdte': (0.0021, -0.01, 1.01),
+        'monosi': (0, -0.003, 1.0),
+    }
+    if module_type is not None:
+        coeff = _coefficients[module_type]
+        c_albedo = c[module_type]
+    else:
+        coeff = coefficients
+        c_albedo = (0.0, 0.0, 1.0)  # 0.2 albedo assumed
+    smm = coeff[0] * Ram + coeff[1] / (coeff[2] + Ram**coeff[3]) \
+        + coeff[4] / aod500 + coeff[5]*np.sqrt(precipitable_water)
+    # Ground albedo correction
+    g = c_albedo[0] * (albedo/0.2)**2 \
+        + c_albedo[1] * (albedo/0.2) + c_albedo[2]
+    return g*smm

tests/spectrum/test_mismatch.py

@@ -302,3 +302,25 @@ def test_spectral_factor_jrc_supplied_ambiguous():
     with pytest.raises(ValueError, match='No valid input provided'):
         spectrum.spectral_factor_jrc(1.0, 0.8, module_type=None,
                                      coefficients=None)
+
+
+@pytest.mark.parametrize("module_type,expected", [
+    ('cdte', np.array(
+        [0.991926, 0.999809, 1.01108, 0.993319, 0.956621, 0.970872])),
+    ('monosi', np.array(
+        [1.00174, 0.971769, 0.986224, 1.01661, 1.02026, 1.0106])),
+    ('cigs', np.array(
+        [1.00769, 0.959666, 0.974438, 1.02861, 1.05203, 1.03117])),
+    ('asi', np.array(
+        [0.982133, 1.04674, 1.04859, 0.951109, 0.865328, 0.919515])),
+])
+def test_spectral_factor_polo(module_type, expected):
+    altitude = 500
+    pws = np.array([0.96, 0.96, 1.85, 1.88, 0.66, 0.66])
+    aods = np.array([0.085, 0.085, 0.16, 0.19, 0.088, 0.088])
+    ams = np.array([1.34, 1.34, 2.2, 2.2, 2.6, 2.6])
+    aois = np.array([46.0, 76.0, 74.0, 28.0, 24.0, 55.0])
+    alb = np.array([0.15, 0.2, 0.3, 0.18, 0.32, 0.26])
+    out = spectrum.spectral_factor_polo(
+        pws, ams, aods, aois, altitude, module_type=module_type, albedo=alb)
+    assert np.allclose(expected, out, atol=1e-8)