Create function to calculate average photon energy

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

@@ -18,3 +18,4 @@ Spectrum
    spectrum.spectral_factor_jrc
    spectrum.sr_to_qe
    spectrum.qe_to_sr
+   spectrum.average_photon_energy

pvlib/spectrum/__init__.py

@@ -10,5 +10,6 @@
     spectral_factor_pvspec,
     spectral_factor_jrc,
     sr_to_qe,
-    qe_to_sr
+    qe_to_sr,
+    average_photon_energy
 )

pvlib/spectrum/mismatch.py

@@ -10,6 +10,7 @@
 import scipy.constants
 from scipy.integrate import trapezoid
 from scipy.interpolate import interp1d
+from scipy import constants
 
 from pathlib import Path
 from warnings import warn
@@ -1100,3 +1101,95 @@ def qe_to_sr(qe, wavelength=None, normalize=False):
         spectral_responsivity = normalize_max2one(spectral_responsivity)
 
     return spectral_responsivity
+
+
+def average_photon_energy(spectral_irr):
+    r"""
+    Calculate the average photon energy of one or more spectral irradiance
+    distributions.
+
+    Parameters
+    ----------
+    spectral_irr : pandas.Series or pandas.DataFrame
+
+        Spectral irradiance, must be positive. [Wm⁻²nm⁻¹]
+
+        A single spectrum must be a :py:class:`pandas.Series` with wavelength
+        [nm] as the index, while multiple spectra must be a
+        :py:class:`pandas.DataFrame` with column headers as wavelength [nm].
+
+    Returns
+    -------
+    ape : numeric or array
+        Average Photon Energy [eV].
+
+    Notes
+    -----
+    The average photon energy (APE) is an index used to characterise the solar
+    spectrum. It has been used widely in the Physics literature since the
+    1900s, but its application for solar spectral irradiance characterisation
+    in the context of PV performance modelling was proposed in [1]_. The APE
+    is calculated based on the principle that a photon's wavelength is
+    inversely proportional to its energy:
+
+    .. math::
+
+        E_\gamma = \frac{hc}{\lambda},
+
+    where :math:`E_\gamma` is the energy of a photon with wavelength
+    :math:`\lambda`, :math:`h` is the Planck constant, and :math:`c` is the
+    speed of light. Therefore, the average energy of all photons within a
+    single spectral irradiance distribution provides an indication of the
+    general shape of the spectrum. A higher average photon energy
+    (shorter wavelength) indicates a blue-shifted spectrum, while a lower
+    average photon energy (longer wavelength) would indicate a red-shifted
+    spectrum. This value of the average photon energy can be calculated by
+    dividing the total number of photons in the spectrum by the total energy in
+    the spectrum as follows [1]_:
+
+    .. math::
+
+        \varphi = \frac{1}{q} \cdot \frac{\int_a^b \Phi_\lambda \, d\lambda}
+        {\int_a^b E_\lambda \, d\lambda}.
+
+    :math:`\Phi_\lambda` is the photon flux density as a function of
+    wavelength, :math:`q` is the elementary charge used here so that the
+    average photon energy, :math:`\varphi`, is expressed in electronvolts (eV).
+    The integration limits, :math:`a` and :math:`b`, define the wavelength
+    range within which the APE is calculated. By default, this function
+    calculates the value for APE based on full wavelength range of the
+    ``spectral_irr`` parameter.
+
+    References
+    ----------
+    .. [1] Jardine, C., et al., 2002, January. Influence of spectral effects on
+       the performance of multijunction amorphous silicon cells. In Proc.
+       Photovoltaic in Europe Conference (pp. 1756-1759).
+
+    """
+
+    si = spectral_irr
+
+    if not isinstance(si, (pd.Series, pd.DataFrame)):
+        raise TypeError('`spectral_irr` must be either a'
+                        ' pandas Series or DataFrame')
+    # check si type
+
+    if (si < 0).any().any():
+        raise ValueError('Spectral irradiance data must be positive')
+    # check if si contains any negative irradiance values
+
+    hclambda = pd.Series((constants.h*constants.c)/(si.T.index*1e-9))
+    hclambda.index = si.T.index  # set wavelength as the index
+    pfd = si.div(hclambda)  # calculate the photon flux density
+
+    def integrate(e):  # define a helper function
+        return trapezoid(e, x=e.T.index, axis=-1)
+
+    int_si = integrate(si)  # integrate spectral irradiance wrt wavelength
+    int_pfd = integrate(pfd)  # integrate photon flux density wrt wavelength
+
+    ape = (1/constants.elementary_charge)*int_si/int_pfd
+    # calculate the average photon energy (ape) in electronvolts (eV)
+
+    return ape

pvlib/tests/test_spectrum.py

@@ -576,3 +576,60 @@ def test_qe_and_sr_reciprocal_conversion(sr_and_eqe_fixture):
     assert_allclose(sr, sr_and_eqe_fixture["spectral_response"])
     qe = spectrum.sr_to_qe(sr)
     assert_allclose(qe, sr_and_eqe_fixture["quantum_efficiency"])
+
+
+def test_average_photon_energy_series():
+    # test that the APE is calculated correctly with single spectrum
+    # series input
+
+    si = spectrum.get_reference_spectra()
+    si = si['global']
+
+    ape = spectrum.average_photon_energy(si)
+
+    expected = 1.45017
+
+    assert_allclose(ape, expected, rtol=1e-4)
+
+
+def test_average_photon_energy_dataframe():
+    # test that the APE is calculated correctly with multiple spectra
+    # dataframe input
+
+    si = spectrum.get_reference_spectra().T
+    # Generate three spectra and orientate the dataframe according to the
+    # function requirements
+
+    ape = spectrum.average_photon_energy(si)
+
+    expected = [1.36848, 1.45017, 1.40885]
+
+    assert_allclose(ape, expected, rtol=1e-4)
+
+
+def test_average_photon_energy_invalid_type():
+    # test that spectral_irr argument is either a pandas Series or dataframe
+    spectral_irr = 5
+    with pytest.raises(TypeError, match='must be either a pandas Series or'
+                       ' DataFrame'):
+        spectrum.average_photon_energy(spectral_irr)
+
+
+def test_average_photon_energy_neg_irr_series():
+    # test for handling of negative spectral irradiance values with a
+    # pandas Series input
+
+    spectral_irr = spectrum.get_reference_spectra()['global']*-1
+
+    with pytest.raises(ValueError, match='must be positive'):
+        spectrum.average_photon_energy(spectral_irr)
+
+
+def test_average_photon_energy_neg_irr_dataframe():
+    # test for handling of negative spectral irradiance values with a
+    # pandas Series input
+
+    spectral_irr = spectrum.get_reference_spectra().T*-1
+
+    with pytest.raises(ValueError, match='must be positive'):
+        spectrum.average_photon_energy(spectral_irr)