diff --git a/pvlib/spectrum/mismatch.py b/pvlib/spectrum/mismatch.py index d2fc4dcf1d..61e0957ff4 100644 --- a/pvlib/spectrum/mismatch.py +++ b/pvlib/spectrum/mismatch.py @@ -531,26 +531,68 @@ def spectral_factor_firstsolar(precipitable_water, airmass_absolute, def spectral_factor_sapm(airmass_absolute, module): """ - Calculates the SAPM spectral loss coefficient, F1. + Calculates the spectral mismatch factor, :math:`f_1`, + using the Sandia Array Performance Model approach. + + The SAPM spectral factor function is part of the broader Sandia Array + Performance Model, which defines five points on an IV curve using empirical + module-specific coefficients. Module coefficients for the SAPM are + available in the SAPM database and can be retrieved for use in the + ``module`` parameter through + :py:func:`pvlib.pvsystem.retrieve_sam()`. More details on the + SAPM can be found in [1]_, while a full description of the procedure to + determine the empirical model coefficients, including those for the SAPM + spectral correction, can be found in [2]_. Parameters ---------- airmass_absolute : numeric - Absolute airmass + Absolute airmass [unitless] + + Note: ``np.nan`` airmass values will result in 0 output. module : dict-like - A dict, Series, or DataFrame defining the SAPM performance - parameters. See the :py:func:`sapm` notes section for more - details. + A dict, Series, or DataFrame defining the SAPM parameters. + Must contain keys `'A0'` through `'A4'`. + See the :py:func:`pvlib.pvsystem.sapm` notes section for more details. Returns ------- - F1 : numeric + f1 : numeric The SAPM spectral loss coefficient. Notes ----- - nan airmass values will result in 0 output. + The SAPM spectral correction functions parameterises :math:`f_1` as a + fourth order polynomial function of absolute air mass: + + .. math:: + + f_1 = a_0 + a_1 AM_a + a_2 AM_a^2 + a_3 AM_a^3 + a_4 AM_a^4, + + where :math:`f_1` is the spectral mismatch factor, :math:`a_{0-4}` are + the module-specific coefficients, and :math:`AM_a` is the absolute airmass, + which is calculated by applying a pressure correction to the relative + airmass. More detail on how this spectral correction function was developed + can be found in [3]_. + + References + ---------- + .. [1] King, D., Kratochvil, J., and Boyson W. (2004), "Sandia + Photovoltaic Array Performance Model", (No. SAND2004-3535), Sandia + National Laboratories, Albuquerque, NM (United States). + :doi:`10.2172/919131` + .. [2] King, B., Hansen, C., Riley, D., Robinson, C., and Pratt, L. + (2016). Procedure to determine coefficients for the Sandia Array + Performance Model (SAPM) (No. SAND2016-5284). Sandia National + Laboratories, Albuquerque, NM (United States). + :doi:`10.2172/1256510` + .. [3] King, D., Kratochvil, J., and Boyson, W. "Measuring solar spectral + and angle-of-incidence effects on photovoltaic modules and solar + irradiance sensors." Conference Record of the 26th IEEE Potovoltaic + Specialists Conference (PVSC). IEEE, 1997. + :doi:`10.1109/PVSC.1997.654283` + """ am_coeff = [module['A4'], module['A3'], module['A2'], module['A1'], @@ -581,7 +623,7 @@ def spectral_factor_caballero(precipitable_water, airmass_absolute, aod500, available here via the ``module_type`` parameter were determined by fitting the model equations to spectral factors calculated from global tilted spectral irradiance measurements taken in the city of - Jaén, Spain. See [1]_ for details. + Jaén, Spain. See [1]_ for details. Parameters ----------