From db1e875e46ee1242907bbc197e0b913dd6a862c9 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 11 Sep 2024 10:07:16 +0100
Subject: [PATCH 01/22] Create average_photon_energy.py

---
 .../spectrum/average_photon_energy.py         | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 docs/examples/spectrum/average_photon_energy.py

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
new file mode 100644
index 0000000000..b717e7be02
--- /dev/null
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -0,0 +1,93 @@
+"""
+Spectral Mismatch Estimation
+============================
+
+Calculation of the Average Photon Energy from Spectrl2 output.
+"""
+
+# %%
+# Introduction
+# ------------
+# This example demonstrates how to use the
+# :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
+# Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
+# irradiance distributions simulated using :pyfunc:`~pvlib.spectrum.spectrl2`.
+# More information on the SPECTRL2 model can be found in [2]_
+# The APE parameter is a useful indicator of the overall shape of the solar
+# spectrum [1]_. Higher (lower) APE values indicate a blue (red) shift in the
+# spectrum and is one of a variety of such characterisation indexes that are
+# used in the PV performance literature [3]_.
+#
+# To demonstrate this functionality, first we need to simulate some spectra
+# using :py:func:`~pvlib.spectrum.spectrl2`. In this example, we will simulate
+# spectra following a similar structure to that which is followed in
+# XX link example XX, which reproduces a figure from [4]_. The first step is to
+# import the required packages and define some basic system parameters and
+# and meteorological conditions.
+# %%
+from pvlib import spectrum, solarposition, irradiance, atmosphere
+import pandas as pd
+import matplotlib.pyplot as plt
+
+lat, lon = 39.742, -105.18 # NREL SRRL location
+tilt = 25
+azimuth = 180 # south-facing system
+pressure = 81190  # at 1828 metres AMSL, roughly
+water_vapor_content = 0.5  # cm
+tau500 = 0.1
+ozone = 0.31  # atm-cm
+albedo = 0.2
+
+times = pd.date_range('2023-01-01 12:00', freq='D', periods=7,
+                      tz='America/Denver')
+solpos = solarposition.get_solarposition(times, lat, lon)
+aoi = irradiance.aoi(tilt, azimuth, solpos.apparent_zenith, solpos.azimuth)
+
+relative_airmass = atmosphere.get_relative_airmass(solpos.apparent_zenith,
+                                                   model='kastenyoung1989')
+
+# %%
+# Spectral simulation
+# -------------------------
+# With all the necessary inputs now defined, we can model spectral irradiance
+# using :py:func:`pvlib.spectrum.spectrl2`. As we are calculating spectra for
+# more than one set of conditions, the function will return a dictionary of
+# 2-D arrays with the exception of wavelength, which has shape (122, N), where
+# N is the length of the input ``apparent_zenith``. For each of the 2-D arrays,
+# one dimension is allocated for wavelength and one is for irradiance in Wm⁻².
+# The next section will show how to convert this output into a suitable
+# input for :pyfunc:`~average_photon_energy`.
+
+spectra = spectrum.spectrl2(
+    apparent_zenith=solpos.apparent_zenith,
+    aoi=aoi,
+    surface_tilt=tilt,
+    ground_albedo=albedo,
+    surface_pressure=pressure,
+    relative_airmass=relative_airmass,
+    precipitable_water=water_vapor_content,
+    ozone=ozone,
+    aerosol_turbidity_500nm=tau500,
+)
+# %%
+# another section
+# --------------------------------
+# %%
+#
+
+# %%
+# 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).
+# .. [2] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
+#        direct and diffuse irradiance on horizontal and tilted planes at the
+#        earth's surface for cloudless atmospheres", NREL Technical Report
+#        TR-215-2436 :doi:`10.2172/5986936`.
+# .. [3] Daxini, R., and Wu, Y., 2023. "Review of methods to account
+#        for the solar spectral influence on photovoltaic device performance."
+#        Energy 286 :doi:`10.1016/j.energy.2023.129461`
+# .. [4] Bird Simple Spectral Model: spectrl2_2.c.
+#        https://www.nrel.gov/grid/solar-resource/spectral.html
+

From 78a8e13143b38473a28ad739efc7f888631a4f9a Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 11 Sep 2024 13:33:48 +0100
Subject: [PATCH 02/22] Update average_photon_energy.py

---
 docs/examples/spectrum/average_photon_energy.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index b717e7be02..a335285a3d 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -51,10 +51,10 @@
 # -------------------------
 # With all the necessary inputs now defined, we can model spectral irradiance
 # using :py:func:`pvlib.spectrum.spectrl2`. As we are calculating spectra for
-# more than one set of conditions, the function will return a dictionary of
-# 2-D arrays with the exception of wavelength, which has shape (122, N), where
-# N is the length of the input ``apparent_zenith``. For each of the 2-D arrays,
-# one dimension is allocated for wavelength and one is for irradiance in Wm⁻².
+# more than one set of conditions, the function will return a dictionary
+# containing 2-D arrays for the spectral irradiance components and a 1-D array
+# of shape (122,) for wavelength. For each of the 2-D arrays, one dimension is
+# for wavelength in nm and one is for irradiance in Wm⁻².
 # The next section will show how to convert this output into a suitable
 # input for :pyfunc:`~average_photon_energy`.
 

From 2c3bb4a145d4a47e414d1ef79b06ef4afd754d1e Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 11 Sep 2024 13:35:03 +0100
Subject: [PATCH 03/22] Update average_photon_energy.py

---
 docs/examples/spectrum/average_photon_energy.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index a335285a3d..5e8e606c5e 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -1,8 +1,8 @@
 """
-Spectral Mismatch Estimation
+Average Photon Energy Calculation
 ============================
 
-Calculation of the Average Photon Energy from Spectrl2 output.
+Calculation of the Average Photon Energy from SPECTRL2 output.
 """
 
 # %%

From 27a92b0e90371453d31462b163e863096681e5ee Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 11 Sep 2024 20:08:09 +0100
Subject: [PATCH 04/22] Update average_photon_energy.py

continuing creation
---
 .../spectrum/average_photon_energy.py         | 93 +++++++++++++++++--
 1 file changed, 86 insertions(+), 7 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 5e8e606c5e..42f771eae5 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -25,9 +25,11 @@
 # import the required packages and define some basic system parameters and
 # and meteorological conditions.
 # %%
-from pvlib import spectrum, solarposition, irradiance, atmosphere
+import numpy as np
 import pandas as pd
 import matplotlib.pyplot as plt
+from scipy.integrate import trapezoid
+from pvlib import spectrum, solarposition, irradiance, atmosphere
 
 lat, lon = 39.742, -105.18 # NREL SRRL location
 tilt = 25
@@ -38,7 +40,7 @@
 ozone = 0.31  # atm-cm
 albedo = 0.2
 
-times = pd.date_range('2023-01-01 12:00', freq='D', periods=7,
+times = pd.date_range('2023-01-01 08:00', freq='h', periods=9,
                       tz='America/Denver')
 solpos = solarposition.get_solarposition(times, lat, lon)
 aoi = irradiance.aoi(tilt, azimuth, solpos.apparent_zenith, solpos.azimuth)
@@ -58,7 +60,7 @@
 # The next section will show how to convert this output into a suitable
 # input for :pyfunc:`~average_photon_energy`.
 
-spectra = spectrum.spectrl2(
+spectra_components = spectrum.spectrl2(
     apparent_zenith=solpos.apparent_zenith,
     aoi=aoi,
     surface_tilt=tilt,
@@ -69,11 +71,89 @@
     ozone=ozone,
     aerosol_turbidity_500nm=tau500,
 )
+
 # %%
-# another section
-# --------------------------------
+# Visualising the spectral data
+# -----------------------------
+# Let's take a look at the spectral irradiance data simulated on the hour for
+# eight hours on the first day of 2023.
+
+plt.figure()
+plt.plot(spectra_components['wavelength'], spectra_components['poa_global'])
+plt.xlim(200, 2700)
+plt.ylim(0, 1.8)
+plt.ylabel(r"Irradiance (Wm⁻²nm⁻¹")
+plt.xlabel(r"Wavelength (nm)")
+time_labels = times.strftime("%H:%M")
+labels = [
+    "{}, AM {:0.02f}".format(*vals)
+    for vals in zip(time_labels, relative_airmass)
+]
+plt.legend(labels)
+plt.show()
+
+# Given the changing irradiance throughout the day, it is not obvious from
+# inspection how the relative distribution of light changes as a function of
+# wavelength. We can normalise the spectral irradiance curves to get an idea
+# of this shift in the shape of the spectrum over the course of the day. In
+# this example, we normalise by dividing each spectral irradiance value by the
+# total irradiance, as calculated by integrating the entire spectral irradiance
+# distribution with respect to wavelength.
+
+poa_global = spectra_components['poa_global']
+wavelength = spectra_components['wavelength']
+
+broadband_irradiance = np.array([trapezoid(poa_global[:, i], wavelength)
+                                 for i in range(poa_global.shape[1])])
+
+poa_global_normalised = poa_global / broadband_irradiance
+
+# Plot the normalised spectra
+
+plt.figure()
+plt.plot(wavelength, poa_global_normalised)
+plt.xlim(200, 2700)
+plt.ylim(0, 0.0018)
+plt.ylabel(r"Normalised Irradiance (nm⁻¹)")
+plt.xlabel(r"Wavelength (nm)")
+time_labels = times.strftime("%H:%M")
+labels = [
+    "{}, AM {:0.02f}".format(*vals)
+    for vals in zip(time_labels, relative_airmass)
+]
+plt.legend(labels)
+plt.show()
+
+# Now we can see from XX figure numbers? XX that at the start and end of the
+# day, the spectrum is red shifted, meaning there is a greater proportion of
+# longer wavelength radiation. Meanwhile, during the middle of the day there is
+# a blue shift in the spectral distribution, indicating a greater prevalence of
+# shorter wavelength radiation.
+
+# How can we quantify this shift? That is where the average photon energy comes
+# into play.
+
 # %%
-#
+# Calculating the average photon energy
+# -------------------------------------
+# To calculate the APE, first we must convert our output spectra from from the
+# simulation into a compatible input for
+# :pyfunc:`pvlib.spectrum.average_photon_energy`. Since we have more than one
+# spectral irradiance distribution, a :py:class:`pandas.DataFrame` is
+# appropriate. We also need to set the column headers as wavelength, so each
+# row is a single spectral irradiance distribution. It is important to remember
+# here that the calculation of APE is dependent on the integration limits, i.e.
+# the wavelength range of the spectral irradiance input. APE values are only
+# comparable if calculated between the same integration limits. In this case,
+# our APE values are calculated between 300nm and 4000nm.
+
+spectra = pd.DataFrame(poa_global).T  # convert to dataframe and transpose
+spectra.index = time_labels  # add time index
+spectra.columns = wavelength  # add wavelength column headers
+
+ape = spectrum.average_photon_energy(spectra)
+
+# XX table? add values /  arrow(s) to graph XX
 
 # %%
 # References
@@ -90,4 +170,3 @@
 #        Energy 286 :doi:`10.1016/j.energy.2023.129461`
 # .. [4] Bird Simple Spectral Model: spectrl2_2.c.
 #        https://www.nrel.gov/grid/solar-resource/spectral.html
-

From 9fcf1800663e2986828d6c1aae2ff63c519b4143 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Thu, 12 Sep 2024 18:44:04 +0100
Subject: [PATCH 05/22] Update average_photon_energy.py

---
 .../spectrum/average_photon_energy.py         | 27 ++++++++++++-------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 42f771eae5..4141df2f10 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -11,7 +11,7 @@
 # This example demonstrates how to use the
 # :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
 # Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
-# irradiance distributions simulated using :pyfunc:`~pvlib.spectrum.spectrl2`.
+# irradiance distributions simulated using :py:func:`~pvlib.spectrum.spectrl2`.
 # More information on the SPECTRL2 model can be found in [2]_
 # The APE parameter is a useful indicator of the overall shape of the solar
 # spectrum [1]_. Higher (lower) APE values indicate a blue (red) shift in the
@@ -20,10 +20,13 @@
 #
 # To demonstrate this functionality, first we need to simulate some spectra
 # using :py:func:`~pvlib.spectrum.spectrl2`. In this example, we will simulate
-# spectra following a similar structure to that which is followed in
-# XX link example XX, which reproduces a figure from [4]_. The first step is to
+# spectra following a similar method to that which is followed in the
+# `Modelling Spectral Irradiance
+# <https://pvlib-python.readthedocs.io/en/stable/gallery/spectrum/plot_spectrl2_fig51A.html>`_
+# example, which reproduces a figure from [4]_. The first step is to
 # import the required packages and define some basic system parameters and
 # and meteorological conditions.
+
 # %%
 import numpy as np
 import pandas as pd
@@ -31,9 +34,9 @@
 from scipy.integrate import trapezoid
 from pvlib import spectrum, solarposition, irradiance, atmosphere
 
-lat, lon = 39.742, -105.18 # NREL SRRL location
+lat, lon = 39.742, -105.18  # NREL SRRL location
 tilt = 25
-azimuth = 180 # south-facing system
+azimuth = 180  # south-facing system
 pressure = 81190  # at 1828 metres AMSL, roughly
 water_vapor_content = 0.5  # cm
 tau500 = 0.1
@@ -56,9 +59,9 @@
 # more than one set of conditions, the function will return a dictionary
 # containing 2-D arrays for the spectral irradiance components and a 1-D array
 # of shape (122,) for wavelength. For each of the 2-D arrays, one dimension is
-# for wavelength in nm and one is for irradiance in Wm⁻².
-# The next section will show how to convert this output into a suitable
-# input for :pyfunc:`~average_photon_energy`.
+# for wavelength in nm and one is for irradiance in Wm⁻²nm⁻¹. The next section
+# will show how to convert this output into a suitable input for
+# :py:func:`~average_photon_energy`.
 
 spectra_components = spectrum.spectrl2(
     apparent_zenith=solpos.apparent_zenith,
@@ -92,6 +95,7 @@
 plt.legend(labels)
 plt.show()
 
+# %%
 # Given the changing irradiance throughout the day, it is not obvious from
 # inspection how the relative distribution of light changes as a function of
 # wavelength. We can normalise the spectral irradiance curves to get an idea
@@ -109,7 +113,6 @@
 poa_global_normalised = poa_global / broadband_irradiance
 
 # Plot the normalised spectra
-
 plt.figure()
 plt.plot(wavelength, poa_global_normalised)
 plt.xlim(200, 2700)
@@ -124,6 +127,10 @@
 plt.legend(labels)
 plt.show()
 
+
+# XX figure layout --- one on top of another? increase size/readability
+
+# %%
 # Now we can see from XX figure numbers? XX that at the start and end of the
 # day, the spectrum is red shifted, meaning there is a greater proportion of
 # longer wavelength radiation. Meanwhile, during the middle of the day there is
@@ -138,7 +145,7 @@
 # -------------------------------------
 # To calculate the APE, first we must convert our output spectra from from the
 # simulation into a compatible input for
-# :pyfunc:`pvlib.spectrum.average_photon_energy`. Since we have more than one
+# :py:func:`pvlib.spectrum.average_photon_energy`. Since we have more than one
 # spectral irradiance distribution, a :py:class:`pandas.DataFrame` is
 # appropriate. We also need to set the column headers as wavelength, so each
 # row is a single spectral irradiance distribution. It is important to remember

From 19791cf6a730e06125108f7ef8ababa9d9560825 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Thu, 12 Sep 2024 19:11:42 +0100
Subject: [PATCH 06/22] Update average_photon_energy.py

---
 .../spectrum/average_photon_energy.py         | 25 ++++++++-----------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 4141df2f10..ee088b479b 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -98,11 +98,11 @@
 # %%
 # Given the changing irradiance throughout the day, it is not obvious from
 # inspection how the relative distribution of light changes as a function of
-# wavelength. We can normalise the spectral irradiance curves to get an idea
-# of this shift in the shape of the spectrum over the course of the day. In
+# wavelength. We can normalise the spectral irradiance curves to visualise
+# this shift in the shape of the spectrum over the course of the day. In
 # this example, we normalise by dividing each spectral irradiance value by the
-# total irradiance, as calculated by integrating the entire spectral irradiance
-# distribution with respect to wavelength.
+# total broadband irradiance, which we calculate by integrating the entire
+# spectral irradiance distribution with respect to wavelength.
 
 poa_global = spectra_components['poa_global']
 wavelength = spectra_components['wavelength']
@@ -127,16 +127,13 @@
 plt.legend(labels)
 plt.show()
 
-
-# XX figure layout --- one on top of another? increase size/readability
-
 # %%
-# Now we can see from XX figure numbers? XX that at the start and end of the
-# day, the spectrum is red shifted, meaning there is a greater proportion of
-# longer wavelength radiation. Meanwhile, during the middle of the day there is
-# a blue shift in the spectral distribution, indicating a greater prevalence of
-# shorter wavelength radiation.
-
+# We can now see from the normalised irradiance curves that at the start and
+# end of the day, the spectrum is red shifted, meaning there is a greater
+# proportion of longer wavelength radiation. Meanwhile, during the middle of
+# the day, there is a blue shift in the spectral distribution, indicating a
+# greater prevalence of shorter wavelength radiation.
+#
 # How can we quantify this shift? That is where the average photon energy comes
 # into play.
 
@@ -149,7 +146,7 @@
 # spectral irradiance distribution, a :py:class:`pandas.DataFrame` is
 # appropriate. We also need to set the column headers as wavelength, so each
 # row is a single spectral irradiance distribution. It is important to remember
-# here that the calculation of APE is dependent on the integration limits, i.e.
+# here that the resulting APE values depend on the integration limits, i.e.
 # the wavelength range of the spectral irradiance input. APE values are only
 # comparable if calculated between the same integration limits. In this case,
 # our APE values are calculated between 300nm and 4000nm.

From fdc7532d06231a9ff2183625e3997e00efb203b3 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Fri, 13 Sep 2024 12:51:51 +0100
Subject: [PATCH 07/22] Update average_photon_energy.py

---
 docs/examples/spectrum/average_photon_energy.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index ee088b479b..dbf51e5932 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -136,6 +136,9 @@
 #
 # How can we quantify this shift? That is where the average photon energy comes
 # into play.
+#
+# XX shifted relative to what --- itself, reference // clarify --- e.g. AM1.5
+# below
 
 # %%
 # Calculating the average photon energy
@@ -157,8 +160,10 @@
 
 ape = spectrum.average_photon_energy(spectra)
 
+# %%
 # XX table? add values /  arrow(s) to graph XX
-
+# XX add AM1.5 graph/ape value
+# plot hourly ape with AM1.5 APE constant line?
 # %%
 # References
 # ----------

From 61ea9a92b8ba16a8522b2af2e75e477d33bb2288 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Sun, 15 Sep 2024 16:35:49 +0100
Subject: [PATCH 08/22] Update average_photon_energy.py

---
 .../spectrum/average_photon_energy.py         | 48 +++++++++++++++++--
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index dbf51e5932..d5c44d1722 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -161,9 +161,51 @@
 ape = spectrum.average_photon_energy(spectra)
 
 # %%
-# XX table? add values /  arrow(s) to graph XX
-# XX add AM1.5 graph/ape value
-# plot hourly ape with AM1.5 APE constant line?
+# We can update the normalised spectral irradiance plot to include each
+# spectrum's irradiance distribution APE value in the legend. Note that the
+# units of the average photon energy here are electronvolts (eV).
+
+plt.figure()
+plt.plot(wavelength, poa_global_normalised)
+plt.xlim(200, 2700)
+plt.ylim(0, 0.0018)
+plt.ylabel(r"Normalised Irradiance (nm⁻¹)")
+plt.xlabel(r"Wavelength (nm)")
+time_labels = times.strftime("%H:%M")
+labels = [
+    "{}, APE {:0.02f}".format(*vals)
+    for vals in zip(time_labels, ape)
+]
+plt.legend(labels)
+plt.show()
+
+# %%
+# The table below summarises the hourly APE values observed throughout the day.
+# .. list-table:: Hourly APE values
+#   :widths: 25 25
+#   :header-rows: 1
+#
+#   * - Time
+#     - APE (eV)
+#   * - 08:00
+#     - 1.25
+#   * - 09:00
+#     - 1.37
+#   * - 10:00
+#     - 1.40
+#   * - 11:00
+#     - 1.41
+#   * - 12:00
+#     - 1.42
+#   * - 13:00
+#     - 1.41
+#   * - 14:00
+#     - 1.40
+#   * - 15:00
+#     - 1.38
+#   * - 16:00
+#     - 1.28
+
 # %%
 # References
 # ----------

From 5690774a5c90156cda591b631f9858abf76f2a99 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Sun, 15 Sep 2024 16:54:45 +0100
Subject: [PATCH 09/22] Update average_photon_energy.py

add interpretation of APE values underneath table
---
 docs/examples/spectrum/average_photon_energy.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index d5c44d1722..ea9327dcc2 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -205,7 +205,10 @@
 #     - 1.38
 #   * - 16:00
 #     - 1.28
-
+#
+# %%
+# As expected, the morning and evening spectra have a lower APE while a higher
+# APE is observed closer to the middle of the day.
 # %%
 # References
 # ----------

From 5b2008849111b38efe2b3011f6ae2f5e3c4537b7 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 18 Sep 2024 13:23:53 +0100
Subject: [PATCH 10/22] Update average_photon_energy.py

---
 .../spectrum/average_photon_energy.py         | 33 ++++---------------
 1 file changed, 6 insertions(+), 27 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index ea9327dcc2..b22fbc11c4 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -179,36 +179,15 @@
 plt.legend(labels)
 plt.show()
 
-# %%
-# The table below summarises the hourly APE values observed throughout the day.
-# .. list-table:: Hourly APE values
-#   :widths: 25 25
-#   :header-rows: 1
-#
-#   * - Time
-#     - APE (eV)
-#   * - 08:00
-#     - 1.25
-#   * - 09:00
-#     - 1.37
-#   * - 10:00
-#     - 1.40
-#   * - 11:00
-#     - 1.41
-#   * - 12:00
-#     - 1.42
-#   * - 13:00
-#     - 1.41
-#   * - 14:00
-#     - 1.40
-#   * - 15:00
-#     - 1.38
-#   * - 16:00
-#     - 1.28
-#
 # %%
 # As expected, the morning and evening spectra have a lower APE while a higher
 # APE is observed closer to the middle of the day.
+# XXX for reference am1.5 between 300 and 4000 nm is 1.4501 eV
+# =============================================================================
+# am15 = spectrum.get_am15g()
+# am15 = am15[am15.index>=300]
+# ape_am15 = spectrum.average_photon_energy(am15)
+# =============================================================================
 # %%
 # References
 # ----------

From 1fdd0e486a90216b4cb65098a249b45ce45c0251 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 18 Sep 2024 13:33:54 +0100
Subject: [PATCH 11/22] Update average_photon_energy.py

add ape table
---
 .../spectrum/average_photon_energy.py         | 31 +++++++++++++------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index b22fbc11c4..19e3ed5c70 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -59,9 +59,7 @@
 # more than one set of conditions, the function will return a dictionary
 # containing 2-D arrays for the spectral irradiance components and a 1-D array
 # of shape (122,) for wavelength. For each of the 2-D arrays, one dimension is
-# for wavelength in nm and one is for irradiance in Wm⁻²nm⁻¹. The next section
-# will show how to convert this output into a suitable input for
-# :py:func:`~average_photon_energy`.
+# for wavelength in nm and one is for irradiance in Wm⁻²nm⁻¹.
 
 spectra_components = spectrum.spectrl2(
     apparent_zenith=solpos.apparent_zenith,
@@ -181,13 +179,26 @@
 
 # %%
 # As expected, the morning and evening spectra have a lower APE while a higher
-# APE is observed closer to the middle of the day.
-# XXX for reference am1.5 between 300 and 4000 nm is 1.4501 eV
-# =============================================================================
-# am15 = spectrum.get_am15g()
-# am15 = am15[am15.index>=300]
-# ape_am15 = spectrum.average_photon_energy(am15)
-# =============================================================================
+# APE is observed closer to the middle of the day. For reference, AM1.5 between
+# 300 and 4000 nm is 1.4501 eV. This indicates that the simulated spectra are
+# slightly red shifted with respect to the AM1.5 standard reference spectrum.
+# The table below summarises the APE values calculated for our day under the
+# specified atmospheric conditions.
+
+#    =================== ==========
+#    Time                 APE (eV)
+#    =================== ==========
+#    08:00               1.25
+#    09:00               1.37
+#    10:00               1.40
+#    11:00               1.41
+#    12:00               1.42
+#    13:00               1.41
+#    14:00               1.40
+#    15:00               1.38
+#    16:00               1.28
+#    =================== ==========
+
 # %%
 # References
 # ----------

From 698eea95a699bd67385f4f3315f283045248b260 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 18 Sep 2024 13:34:54 +0100
Subject: [PATCH 12/22] Update average_photon_energy.py

add last accessed to references
---
 docs/examples/spectrum/average_photon_energy.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 19e3ed5c70..dacba0c1d7 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -204,13 +204,14 @@
 # ----------
 # .. [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).
+#        Photovoltaic in Europe Conference (pp. 1756-1759)
 # .. [2] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
 #        direct and diffuse irradiance on horizontal and tilted planes at the
 #        earth's surface for cloudless atmospheres", NREL Technical Report
-#        TR-215-2436 :doi:`10.2172/5986936`.
+#        TR-215-2436 :doi:`10.2172/5986936`
 # .. [3] Daxini, R., and Wu, Y., 2023. "Review of methods to account
 #        for the solar spectral influence on photovoltaic device performance."
 #        Energy 286 :doi:`10.1016/j.energy.2023.129461`
-# .. [4] Bird Simple Spectral Model: spectrl2_2.c.
+# .. [4] Bird Simple Spectral Model: spectrl2_2.c
 #        https://www.nrel.gov/grid/solar-resource/spectral.html
+#        (Last accessed: 18/09/2024)

From ab71926833dfcf2e9d952294f87bc390fe50f046 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 18 Sep 2024 13:53:13 +0100
Subject: [PATCH 13/22] Update average_photon_energy.py

wording, remove table
---
 .../spectrum/average_photon_energy.py         | 43 ++++++-------------
 1 file changed, 12 insertions(+), 31 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index dacba0c1d7..12e4f8099a 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -12,10 +12,10 @@
 # :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
 # Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
 # irradiance distributions simulated using :py:func:`~pvlib.spectrum.spectrl2`.
-# More information on the SPECTRL2 model can be found in [2]_
+# More information on the SPECTRL2 model can be found in [2]_.
 # The APE parameter is a useful indicator of the overall shape of the solar
 # spectrum [1]_. Higher (lower) APE values indicate a blue (red) shift in the
-# spectrum and is one of a variety of such characterisation indexes that are
+# spectrum and is one of a variety of such characterisation methods that is
 # used in the PV performance literature [3]_.
 #
 # To demonstrate this functionality, first we need to simulate some spectra
@@ -83,7 +83,7 @@
 plt.plot(spectra_components['wavelength'], spectra_components['poa_global'])
 plt.xlim(200, 2700)
 plt.ylim(0, 1.8)
-plt.ylabel(r"Irradiance (Wm⁻²nm⁻¹")
+plt.ylabel(r"Spectral irradiance (Wm⁻²nm⁻¹)")
 plt.xlabel(r"Wavelength (nm)")
 time_labels = times.strftime("%H:%M")
 labels = [
@@ -94,9 +94,9 @@
 plt.show()
 
 # %%
-# Given the changing irradiance throughout the day, it is not obvious from
-# inspection how the relative distribution of light changes as a function of
-# wavelength. We can normalise the spectral irradiance curves to visualise
+# Given the changing broadband irradiance throughout the day, it is not obvious
+# from inspection how the relative distribution of light changes as a function
+# of wavelength. We can normalise the spectral irradiance curves to visualise
 # this shift in the shape of the spectrum over the course of the day. In
 # this example, we normalise by dividing each spectral irradiance value by the
 # total broadband irradiance, which we calculate by integrating the entire
@@ -129,14 +129,11 @@
 # We can now see from the normalised irradiance curves that at the start and
 # end of the day, the spectrum is red shifted, meaning there is a greater
 # proportion of longer wavelength radiation. Meanwhile, during the middle of
-# the day, there is a blue shift in the spectral distribution, indicating a
-# greater prevalence of shorter wavelength radiation.
+# the day, there is a greater prevalence of shorter wavelength radiation — a
+# blue shifted spectrum.
 #
-# How can we quantify this shift? That is where the average photon energy comes
+# How can we quantify this shift? This is where the average photon energy comes
 # into play.
-#
-# XX shifted relative to what --- itself, reference // clarify --- e.g. AM1.5
-# below
 
 # %%
 # Calculating the average photon energy
@@ -159,9 +156,9 @@
 ape = spectrum.average_photon_energy(spectra)
 
 # %%
-# We can update the normalised spectral irradiance plot to include each
-# spectrum's irradiance distribution APE value in the legend. Note that the
-# units of the average photon energy here are electronvolts (eV).
+# We can update the normalised spectral irradiance plot to include the APE
+# value of each spectral irradiance distribution in the legend. Note that the
+# units of the APE are electronvolts (eV).
 
 plt.figure()
 plt.plot(wavelength, poa_global_normalised)
@@ -182,22 +179,6 @@
 # APE is observed closer to the middle of the day. For reference, AM1.5 between
 # 300 and 4000 nm is 1.4501 eV. This indicates that the simulated spectra are
 # slightly red shifted with respect to the AM1.5 standard reference spectrum.
-# The table below summarises the APE values calculated for our day under the
-# specified atmospheric conditions.
-
-#    =================== ==========
-#    Time                 APE (eV)
-#    =================== ==========
-#    08:00               1.25
-#    09:00               1.37
-#    10:00               1.40
-#    11:00               1.41
-#    12:00               1.42
-#    13:00               1.41
-#    14:00               1.40
-#    15:00               1.38
-#    16:00               1.28
-#    =================== ==========
 
 # %%
 # References

From 737d8bb86217794d0c1390929344eecf71872aa3 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Wed, 18 Sep 2024 14:07:51 +0100
Subject: [PATCH 14/22] Update average_photon_energy.py

reference order
---
 docs/examples/spectrum/average_photon_energy.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 12e4f8099a..7e858de8ab 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -12,9 +12,9 @@
 # :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
 # Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
 # irradiance distributions simulated using :py:func:`~pvlib.spectrum.spectrl2`.
-# More information on the SPECTRL2 model can be found in [2]_.
+# More information on the SPECTRL2 model can be found in [1]_.
 # The APE parameter is a useful indicator of the overall shape of the solar
-# spectrum [1]_. Higher (lower) APE values indicate a blue (red) shift in the
+# spectrum [2]_. Higher (lower) APE values indicate a blue (red) shift in the
 # spectrum and is one of a variety of such characterisation methods that is
 # used in the PV performance literature [3]_.
 #
@@ -183,13 +183,13 @@
 # %%
 # 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)
-# .. [2] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
+# .. [1] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
 #        direct and diffuse irradiance on horizontal and tilted planes at the
 #        earth's surface for cloudless atmospheres", NREL Technical Report
 #        TR-215-2436 :doi:`10.2172/5986936`
+# .. [2] 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)
 # .. [3] Daxini, R., and Wu, Y., 2023. "Review of methods to account
 #        for the solar spectral influence on photovoltaic device performance."
 #        Energy 286 :doi:`10.1016/j.energy.2023.129461`

From 9ab21f179a217741f8ff067e6d157d33909413a5 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Mon, 23 Sep 2024 18:57:45 +0100
Subject: [PATCH 15/22] Apply suggestions from code review

Co-authored-by: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
---
 docs/examples/spectrum/average_photon_energy.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 7e858de8ab..ab4979a933 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -24,7 +24,7 @@
 # `Modelling Spectral Irradiance
 # <https://pvlib-python.readthedocs.io/en/stable/gallery/spectrum/plot_spectrl2_fig51A.html>`_
 # example, which reproduces a figure from [4]_. The first step is to
-# import the required packages and define some basic system parameters and
+# import the required packages and define some basic system parameters
 # and meteorological conditions.
 
 # %%
@@ -119,7 +119,7 @@
 plt.xlabel(r"Wavelength (nm)")
 time_labels = times.strftime("%H:%M")
 labels = [
-    "{}, AM {:0.02f}".format(*vals)
+    "{}, AM={:0.02f}".format(*vals)
     for vals in zip(time_labels, relative_airmass)
 ]
 plt.legend(labels)
@@ -138,7 +138,7 @@
 # %%
 # Calculating the average photon energy
 # -------------------------------------
-# To calculate the APE, first we must convert our output spectra from from the
+# To calculate the APE, first we must convert our output spectra from the
 # simulation into a compatible input for
 # :py:func:`pvlib.spectrum.average_photon_energy`. Since we have more than one
 # spectral irradiance distribution, a :py:class:`pandas.DataFrame` is
@@ -168,7 +168,7 @@
 plt.xlabel(r"Wavelength (nm)")
 time_labels = times.strftime("%H:%M")
 labels = [
-    "{}, APE {:0.02f}".format(*vals)
+    "{}, APE={:0.02f}".format(*vals)
     for vals in zip(time_labels, ape)
 ]
 plt.legend(labels)

From 22744a84edfdcb07513c284ef9191b47216e5d8e Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Mon, 23 Sep 2024 19:00:22 +0100
Subject: [PATCH 16/22] Update average_photon_energy.py

---
 docs/examples/spectrum/average_photon_energy.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index ab4979a933..d87762b2bf 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -76,8 +76,8 @@
 # %%
 # Visualising the spectral data
 # -----------------------------
-# Let's take a look at the spectral irradiance data simulated on the hour for
-# eight hours on the first day of 2023.
+# Let's take a look at the spectral irradiance data simulated hourly for eight
+# hours on the first day of 2023.
 
 plt.figure()
 plt.plot(spectra_components['wavelength'], spectra_components['poa_global'])

From 5d6f7e6ec0bbef05a7ecc81a2a034536191096a3 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 13:28:08 +0100
Subject: [PATCH 17/22] Apply suggestions from code review

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>
---
 docs/examples/spectrum/average_photon_energy.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index d87762b2bf..a1d3359cc3 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -11,14 +11,16 @@
 # This example demonstrates how to use the
 # :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
 # Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
-# irradiance distributions simulated using :py:func:`~pvlib.spectrum.spectrl2`.
+# irradiance distributions.  This example uses spectral irradiance simulated
+# using :py:func:`~pvlib.spectrum.spectrl2`, but the same method is
+# applicable to spectral irradiance from any source.
 # More information on the SPECTRL2 model can be found in [1]_.
 # The APE parameter is a useful indicator of the overall shape of the solar
 # spectrum [2]_. Higher (lower) APE values indicate a blue (red) shift in the
 # spectrum and is one of a variety of such characterisation methods that is
 # used in the PV performance literature [3]_.
 #
-# To demonstrate this functionality, first we need to simulate some spectra
+# To demonstrate this functionality, first we will simulate some spectra
 # using :py:func:`~pvlib.spectrum.spectrl2`. In this example, we will simulate
 # spectra following a similar method to that which is followed in the
 # `Modelling Spectral Irradiance
@@ -105,8 +107,7 @@
 poa_global = spectra_components['poa_global']
 wavelength = spectra_components['wavelength']
 
-broadband_irradiance = np.array([trapezoid(poa_global[:, i], wavelength)
-                                 for i in range(poa_global.shape[1])])
+broadband_irradiance = trapezoid(poa_global, wavelength, axis=0)
 
 poa_global_normalised = poa_global / broadband_irradiance
 

From b2164d7833440499de9496246e3eb3e82520eccf Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 13:31:39 +0100
Subject: [PATCH 18/22] Update average_photon_energy.py

add =
variable names
remove unused package
---
 docs/examples/spectrum/average_photon_energy.py | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index a1d3359cc3..1851c52285 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -30,7 +30,6 @@
 # and meteorological conditions.
 
 # %%
-import numpy as np
 import pandas as pd
 import matplotlib.pyplot as plt
 from scipy.integrate import trapezoid
@@ -89,7 +88,7 @@
 plt.xlabel(r"Wavelength (nm)")
 time_labels = times.strftime("%H:%M")
 labels = [
-    "{}, AM {:0.02f}".format(*vals)
+    "{}, AM={:0.02f}".format(*vals)
     for vals in zip(time_labels, relative_airmass)
 ]
 plt.legend(labels)
@@ -104,16 +103,16 @@
 # total broadband irradiance, which we calculate by integrating the entire
 # spectral irradiance distribution with respect to wavelength.
 
-poa_global = spectra_components['poa_global']
+spectral_poa = spectra_components['poa_global']
 wavelength = spectra_components['wavelength']
 
-broadband_irradiance = trapezoid(poa_global, wavelength, axis=0)
+broadband_irradiance = trapezoid(spectral_poa, wavelength, axis=0)
 
-poa_global_normalised = poa_global / broadband_irradiance
+spectral_poa_normalised = spectral_poa / broadband_irradiance
 
 # Plot the normalised spectra
 plt.figure()
-plt.plot(wavelength, poa_global_normalised)
+plt.plot(wavelength, spectral_poa_normalised)
 plt.xlim(200, 2700)
 plt.ylim(0, 0.0018)
 plt.ylabel(r"Normalised Irradiance (nm⁻¹)")
@@ -150,7 +149,7 @@
 # comparable if calculated between the same integration limits. In this case,
 # our APE values are calculated between 300nm and 4000nm.
 
-spectra = pd.DataFrame(poa_global).T  # convert to dataframe and transpose
+spectra = pd.DataFrame(spectral_poa).T  # convert to dataframe and transpose
 spectra.index = time_labels  # add time index
 spectra.columns = wavelength  # add wavelength column headers
 
@@ -162,7 +161,7 @@
 # units of the APE are electronvolts (eV).
 
 plt.figure()
-plt.plot(wavelength, poa_global_normalised)
+plt.plot(wavelength, spectral_poa_normalised)
 plt.xlim(200, 2700)
 plt.ylim(0, 0.0018)
 plt.ylabel(r"Normalised Irradiance (nm⁻¹)")

From 8bfc2cf35f3714d310dca71e0be9917d05f1b4a2 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 13:34:46 +0100
Subject: [PATCH 19/22] Update average_photon_energy.py

gallery example ref
---
 docs/examples/spectrum/average_photon_energy.py | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 1851c52285..1ddb21dc01 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -11,7 +11,7 @@
 # This example demonstrates how to use the
 # :py:func:`~pvlib.spectrum.average_photon_energy` function to calculate the
 # Average Photon Energy (APE, :math:`\overline{E_\gamma}`) of spectral
-# irradiance distributions.  This example uses spectral irradiance simulated
+# irradiance distributions. This example uses spectral irradiance simulated
 # using :py:func:`~pvlib.spectrum.spectrl2`, but the same method is
 # applicable to spectral irradiance from any source.
 # More information on the SPECTRL2 model can be found in [1]_.
@@ -23,11 +23,10 @@
 # To demonstrate this functionality, first we will simulate some spectra
 # using :py:func:`~pvlib.spectrum.spectrl2`. In this example, we will simulate
 # spectra following a similar method to that which is followed in the
-# `Modelling Spectral Irradiance
-# <https://pvlib-python.readthedocs.io/en/stable/gallery/spectrum/plot_spectrl2_fig51A.html>`_
-# example, which reproduces a figure from [4]_. The first step is to
-# import the required packages and define some basic system parameters
-# and meteorological conditions.
+# :ref:`sphx_glr_gallery_spectrum_plot_spectrl2_fig51A.py` example, which
+# reproduces a figure from [4]_. The first step is to import the required
+# packages and define some basic system parameters and meteorological
+# conditions.
 
 # %%
 import pandas as pd

From a955ded4587ac8f590b60ecc322a2241024b36ee Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 13:37:53 +0100
Subject: [PATCH 20/22] Update v0.11.1.rst

---
 docs/sphinx/source/whatsnew/v0.11.1.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/sphinx/source/whatsnew/v0.11.1.rst b/docs/sphinx/source/whatsnew/v0.11.1.rst
index beaca6c466..396da31e2c 100644
--- a/docs/sphinx/source/whatsnew/v0.11.1.rst
+++ b/docs/sphinx/source/whatsnew/v0.11.1.rst
@@ -41,6 +41,9 @@ Documentation
   several spectral mismatch factor models.
   (:issue:`2107`, :pull:`2114`)
 
+* Added gallery example demonstrating the application of
+  :py:func:`average_photon_energy`. (:issue:`2194`, :pull:`2206`)
+
 * Added gallery example on calculating cell temperature for
   floating PV. (:pull:`2110`)
 

From 7687ddbde06e270a847425feff72e1fa7f42804a Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 14:09:28 +0100
Subject: [PATCH 21/22] Update docs/sphinx/source/whatsnew/v0.11.1.rst

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>
---
 docs/sphinx/source/whatsnew/v0.11.1.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/sphinx/source/whatsnew/v0.11.1.rst b/docs/sphinx/source/whatsnew/v0.11.1.rst
index 396da31e2c..510d17a52c 100644
--- a/docs/sphinx/source/whatsnew/v0.11.1.rst
+++ b/docs/sphinx/source/whatsnew/v0.11.1.rst
@@ -42,7 +42,7 @@ Documentation
   (:issue:`2107`, :pull:`2114`)
 
 * Added gallery example demonstrating the application of
-  :py:func:`average_photon_energy`. (:issue:`2194`, :pull:`2206`)
+  :py:func:`~pvlib.spectrum.average_photon_energy`. (:issue:`2194`, :pull:`2206`)
 
 * Added gallery example on calculating cell temperature for
   floating PV. (:pull:`2110`)

From 5cfc22db38a8863d3d084857df13a671bb1748d6 Mon Sep 17 00:00:00 2001
From: RDaxini <143435106+RDaxini@users.noreply.github.com>
Date: Tue, 24 Sep 2024 16:08:25 +0100
Subject: [PATCH 22/22] Update average_photon_energy.py

update legend

Co-Authored-By: Kevin Anderson <57452607+kandersolar@users.noreply.github.com>
Co-Authored-By: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>
---
 .../spectrum/average_photon_energy.py         | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/examples/spectrum/average_photon_energy.py b/docs/examples/spectrum/average_photon_energy.py
index 1ddb21dc01..a883f929ea 100644
--- a/docs/examples/spectrum/average_photon_energy.py
+++ b/docs/examples/spectrum/average_photon_energy.py
@@ -1,6 +1,6 @@
 """
 Average Photon Energy Calculation
-============================
+=================================
 
 Calculation of the Average Photon Energy from SPECTRL2 output.
 """
@@ -85,12 +85,12 @@
 plt.ylim(0, 1.8)
 plt.ylabel(r"Spectral irradiance (Wm⁻²nm⁻¹)")
 plt.xlabel(r"Wavelength (nm)")
-time_labels = times.strftime("%H:%M")
+time_labels = times.strftime("%H%M")
 labels = [
-    "{}, AM={:0.02f}".format(*vals)
-    for vals in zip(time_labels, relative_airmass)
+    f"{t}, {am_:0.02f}"
+    for t, am_ in zip(time_labels, relative_airmass)
 ]
-plt.legend(labels)
+plt.legend(labels, title="Time, AM")
 plt.show()
 
 # %%
@@ -116,12 +116,12 @@
 plt.ylim(0, 0.0018)
 plt.ylabel(r"Normalised Irradiance (nm⁻¹)")
 plt.xlabel(r"Wavelength (nm)")
-time_labels = times.strftime("%H:%M")
+time_labels = times.strftime("%H%M")
 labels = [
-    "{}, AM={:0.02f}".format(*vals)
-    for vals in zip(time_labels, relative_airmass)
+    f"{t}, {am_:0.02f}"
+    for t, am_ in zip(time_labels, relative_airmass)
 ]
-plt.legend(labels)
+plt.legend(labels, title="Time, AM")
 plt.show()
 
 # %%
@@ -165,12 +165,12 @@
 plt.ylim(0, 0.0018)
 plt.ylabel(r"Normalised Irradiance (nm⁻¹)")
 plt.xlabel(r"Wavelength (nm)")
-time_labels = times.strftime("%H:%M")
+time_labels = times.strftime("%H%M")
 labels = [
-    "{}, APE={:0.02f}".format(*vals)
-    for vals in zip(time_labels, ape)
+    f"{t}, {ape_:0.02f}"
+    for t, ape_ in zip(time_labels, ape)
 ]
-plt.legend(labels)
+plt.legend(labels,  title="Time, APE (eV)")
 plt.show()
 
 # %%