Add spectral mismatch model comparison table

docs/sphinx/source/user_guide/index.rst

@@ -21,6 +21,7 @@ This user guide is an overview and explains some of the key features of pvlib.
    modeling_topics/pvsystem
    modeling_topics/modelchain
    modeling_topics/timetimezones
+   modeling_topics/spectrum
    modeling_topics/bifacial
    modeling_topics/clearsky
    modeling_topics/weather_data

docs/sphinx/source/user_guide/modeling_topics/spectrum.rst

@@ -0,0 +1,105 @@
+.. _spectrum_user_guide:
+.. currentmodule:: pvlib.spectrum
+
+
+Spectrum
+========
+
+The spectrum functionality of pvlib-python includes simulating clear sky
+spectral irradiance curves, calculating the spectral mismatch factor for
+a range of single-junction PV cell technologies, and other calculations
+such as converting between spectral response and EQE, and computing average
+photon energy values from spectral irradiance data.
+
+This user guide page summarizes some of pvlib-python's spectrum-related
+capabilities, starting with a summary of spectral mismatch estimation models
+available in pvlib-python.
+
+
+Spectral mismatch models
+------------------------
+The spectral mismatch factor is the ratio of a PV device's response under a
+given spectrum to its response under a reference spectrum, typically the
+AM1.5G spectrum. It represents the relative difference in the performance of
+a PV device under a spectrum different from the reference spectrum, and can be
+used to correct the measured power output of a PV system for spectral effects.
+
+pvlib-python contains several models to estimate the spectral mismatch factor
+using atmospheric variables such as air mass, or calculate it exactly using
+system and meteorological data such as spectral response and spectral
+irradiance. Examples demonstrating the application of several spectral
+mismatch models using pvlib-python are also available:
+:ref:`sphx_glr_gallery_spectrum_spectral_factor.py` and Reference [1]_, the
+latter of which also contains downloadable spectral response and spectral
+irradiance data.
+
+On this page, a comparison of spectral mismatch estimation models available in
+pvlib-python is presented. An extended review of a wider range of models
+available in the published literature may be found in Reference [2]_.
+
+The table below summarizes the models currently available in pvlib, their
+required inputs, cell technologies for which model coefficients have been
+published, and references. Note that while most models are validated for
+specific cell technologies, the Sandia Array Performance Model (SAPM) is
+validated for a range of commercial modules.
+
+
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+| Model                                               | Inputs                      | Default parameter availability                      | Reference |
++                                                     +                             +---------+---------+------+------+------+------------+           +
+|                                                     |                             | mono-Si | poly-Si | CdTe | CIGS | a-Si | perovskite |           |
++=====================================================+=============================+=========+=========+======+======+======+============+===========+
+| :py:func:`Caballero <spectral_factor_caballero>`    | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
+|                                                     +-----------------------------+         |         |      |      |      |            |           |
+|                                                     |:term:`precipitable_water`,  |   ✓     |    ✓    |  ✓   |   ✓  |  ✓   |     ✓      |   [2]_    |
+|                                                     +-----------------------------+         |         |      |      |      |            |           |
+|                                                     | :term:`aod`                 |         |         |      |      |      |            |           |
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+| :py:func:`First Solar <spectral_factor_firstsolar>` | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
+|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            |   [3]_    |
+|                                                     | :term:`precipitable_water`  |         |         |      |      |      |            |           |
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+| :py:func:`JRC <spectral_factor_jrc>`                | :term:`airmass_relative`,   |         |         |      |      |      |            |           |
+|                                                     +-----------------------------+         |    ✓    |  ✓   |      |      |            +   [4]_    |
+|                                                     | :term:`clearsky_index`      |         |         |      |      |      |            |           |
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+| :py:func:`PVSPEC <spectral_factor_pvspec>`          | :term:`airmass_absolute`,   |         |         |      |      |      |            |           |
+|                                                     +-----------------------------+   ✓     |    ✓    |  ✓   |  ✓   |  ✓   |            |   [5]_    |
+|                                                     | :term:`clearsky_index`      |         |         |      |      |      |            |           |
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+| :py:func:`SAPM <spectral_factor_sapm>`              | :term:`airmass_absolute`    |         |         |      |      |      |            |   [6]_    |
++-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
+
+
+References
+----------
+.. [1] A. Driesse, J. S. Stein, and M. Theristis, "Global horizontal spectral
+       irradiance and module spectral response measurements: an open dataset
+       for PV research Sandia National Laboratories, ALbuquerque, NM, USA, Rep.
+       SAND2023-02045, 2023. Available:
+       https://datahub.duramat.org/dataset/module-sr-library
+.. [2] R. Daxini and Y. Wu, "Review of methods to account for the solar
+       spectral influence on photovoltaic device performance," Energy, 
+       vol. 286, p. 129461, Jan. 2024. :doi:`10.1016/j.energy.2023.129461`
+.. [3] J. A. Caballero, E. Fernández, M. Theristis, F. Almonacid, and
+       G. Nofuentes, "Spectral Corrections Based on Air Mass, Aerosol Optical
+       Depth and Precipitable Water for PV Performance Modeling," IEEE Journal
+       of Photovoltaics, vol. 8, no. 2, pp. 552–558, Mar. 2018. 
+       :doi:`10.1109/JPHOTOV.2017.2787019`
+.. [4] S. Pelland, J. Remund, and J. Kleissl, "Development and Testing of the
+       PVSPEC Model of Photovoltaic Spectral Mismatch Factor," in Proc. 2020
+       IEEE 47th Photovoltaic Specialists Conference (PVSC), Calgary, AB,
+       Canada, 2020, pp. 1–6. :doi:`10.1109/PVSC45281.2020.9300932`
+.. [5] D. L. King, W. E. Boyson, and J. A. Kratochvil, Photovoltaic Array
+       Performance Model, Sandia National Laboratories, Albuquerque, NM, USA,
+       Tech. Rep. SAND2004-3535, Aug. 2004. :doi:`10.2172/919131`
+.. [6] M. Lee and A. Panchula, "Spectral Correction for Photovoltaic Module
+       Performance Based on Air Mass and Precipitable Water," 2016 IEEE 43rd
+       Photovoltaic Specialists Conference (PVSC), Portland, OR, USA, 2016,
+       pp. 3696-3699. :doi:`10.1109/PVSC.2016.7749836`
+.. [7] H. Thomas, S. Tony, and D. Ewan, “A Simple Model for Estimating the
+       Influence of Spectrum Variations on PV Performance,” pp. 3385–3389, Nov.
+       2009, :doi:`10.4229/24THEUPVSEC2009-4AV.3.27`
+.. [8] IEC 60904-7:2019, Photovoltaic devices — Part 7: Computation of the
+       spectral mismatch correction for measurements of photovoltaic devices, 
+       International Electrotechnical Commission, Geneva, Switzerland, 2019.

docs/sphinx/source/whatsnew/v0.13.1.rst

@@ -29,6 +29,10 @@ Documentation
 ~~~~~~~~~~~~~
 * Substantiate definitions of solar/surface azimuth/zenith and aoi on the
   :ref:`nomenclature` page. (:issue:`2448`, :pull:`2503`)
+* Add a new reference page for the spectrum (:ref:`_spectrum_user_guide`) to the
+  Modeling Topics section of the user guide, documenting pvlib-python's spectrum
+  functionality, which includes a comparison table of spectral mismatch estimation
+  models. (:issue:`2329`, :pull:`2353`)
 
 
 Testing