Source code for pvlib.spectrum.mismatch

The ``mismatch`` module provides functions for spectral mismatch calculations.

import pvlib
import numpy as np
import pandas as pd
from scipy.interpolate import interp1d
import os

from warnings import warn

[docs]def get_example_spectral_response(wavelength=None): ''' Generate a generic smooth spectral response (SR) for tests and experiments. Parameters ---------- wavelength: 1-D sequence of numeric, optional Wavelengths at which spectral response values are generated. By default ``wavelength`` is from 280 to 1200 in 5 nm intervals. [nm] Returns ------- spectral_response : pandas.Series The relative spectral response indexed by ``wavelength`` in nm. [-] Notes ----- This spectral response is based on measurements taken on a c-Si cell. A small number of points near the measured curve are used to define a cubic spline having no undue oscillations, as shown in [1]_. The spline can be interpolated at arbitrary wavelengths to produce a continuous, smooth curve , which makes it suitable for experimenting with spectral data of different resolutions. References ---------- .. [1] Driesse, Anton, and Stein, Joshua. "Global Normal Spectral Irradiance in Albuquerque: a One-Year Open Dataset for PV Research". United States 2020. :doi:`10.2172/1814068`. ''' # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Aug. 2022 SR_DATA = np.array([[ 290, 0.00], [ 350, 0.27], [ 400, 0.37], [ 500, 0.52], [ 650, 0.71], [ 800, 0.88], [ 900, 0.97], [ 950, 1.00], [1000, 0.93], [1050, 0.58], [1100, 0.21], [1150, 0.05], [1190, 0.00]]).transpose() if wavelength is None: resolution = 5.0 wavelength = np.arange(280, 1200 + resolution, resolution) interpolator = interp1d(SR_DATA[0], SR_DATA[1], kind='cubic', bounds_error=False, fill_value=0.0, copy=False, assume_sorted=True) sr = pd.Series(data=interpolator(wavelength), index=wavelength) = 'wavelength' = 'spectral_response' return sr
[docs]def get_am15g(wavelength=None): ''' Read the ASTM G173-03 AM1.5 global spectrum on a 37-degree tilted surface, optionally interpolated to the specified wavelength(s). Global (tilted) irradiance includes direct and diffuse irradiance from sky and ground reflections, and is more formally called hemispherical irradiance (on a tilted surface). In the context of photovoltaic systems the irradiance on a flat receiver is frequently called plane-of-array (POA) irradiance. Parameters ---------- wavelength: 1-D sequence of numeric, optional Wavelengths at which the spectrum is interpolated. By default the 2002 wavelengths of the standard are returned. [nm] Returns ------- am15g: pandas.Series The AM1.5g standard spectrum indexed by ``wavelength``. [(W/m^2)/nm] Notes ----- If ``wavelength`` is specified this function uses linear interpolation. If the values in ``wavelength`` are too widely spaced, the integral of the spectrum may deviate from the standard value of 1000.37 W/m^2. The values in the data file provided with pvlib-python are copied from an Excel file distributed by NREL, which is found here: More information about reference spectra is found here: References ---------- .. [1] ASTM "G173-03 Standard Tables for Reference Solar Spectral Irradiances: Direct Normal and Hemispherical on 37° Tilted Surface." ''' # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Aug. 2022 pvlib_path = pvlib.__path__[0] filepath = os.path.join(pvlib_path, 'data', 'astm_g173_am15g.csv') am15g = pd.read_csv(filepath, index_col=0).squeeze() if wavelength is not None: interpolator = interp1d(am15g.index, am15g, kind='linear', bounds_error=False, fill_value=0.0, copy=False, assume_sorted=True) am15g = pd.Series(data=interpolator(wavelength), index=wavelength) = 'wavelength' = 'am15g' return am15g
[docs]def calc_spectral_mismatch_field(sr, e_sun, e_ref=None): """ Calculate spectral mismatch between a test device and broadband reference device under specified solar spectral irradiance conditions. Parameters ---------- sr: pandas.Series The relative spectral response of one (photovoltaic) test device. The index of the Series must contain wavelength values in nm. [-] e_sun: pandas.DataFrame or pandas.Series One or more measured solar irradiance spectra in a pandas.DataFrame having wavelength in nm as column index. A single spectrum may be be given as a pandas.Series having wavelength in nm as index. [(W/m^2)/nm] e_ref: pandas.Series, optional The reference spectrum to use for the mismatch calculation. The index of the Series must contain wavelength values in nm. The default is the ASTM G173-03 global tilted spectrum. [(W/m^2)/nm] Returns ------- smm: pandas.Series or float if a single measured spectrum is provided. [-] Notes ----- Measured solar spectral irradiance usually covers a wavelength range that is smaller than the range considered as broadband irradiance. The infrared limit for the former typically lies around 1100 or 1600 nm, whereas the latter extends to around 2800 or 4000 nm. To avoid imbalance between the magnitudes of the integrated spectra (the broadband values) this function truncates the reference spectrum to the same range as the measured (or simulated) field spectra. The assumption implicit in this truncation is that the energy in the unmeasured wavelength range is the same fraction of the broadband energy for both the measured spectra and the reference spectrum. If the default reference spectrum is used it is linearly interpolated to the wavelengths of the measured spectrum, but if a reference spectrum is provided via the parameter ``e_ref`` it is used without change. This makes it possible to avoid interpolation, or to use a different method of interpolation, or to avoid truncation. The spectral response is linearly interpolated to the wavelengths of each spectrum with which is it multiplied internally (``e_sun`` and ``e_ref``). If the wavelengths of the spectral response already match one or both of these spectra interpolation has no effect; therefore, another type of interpolation could be used to process ``sr`` before calling this function. The standards describing mismatch calculations focus on indoor laboratory applications, but are applicable to outdoor performance as well. The 2016 version of ASTM E973 [1]_ is somewhat more difficult to read than the 2010 version [2]_ because it includes adjustments for the temperature dependency of spectral response, which led to a formulation using quantum efficiency (QE). IEC 60904-7 is clearer and also discusses the use of a broadband reference device. [3]_ References ---------- .. [1] ASTM "E973-16 Standard Test Method for Determination of the Spectral Mismatch Parameter Between a Photovoltaic Device and a Photovoltaic Reference Cell" :doi:`10.1520/E0973-16R20` .. [2] ASTM "E973-10 Standard Test Method for Determination of the Spectral Mismatch Parameter Between a Photovoltaic Device and a Photovoltaic Reference Cell" :doi:`10.1520/E0973-10` .. [3] IEC 60904-7 "Computation of the spectral mismatch correction for measurements of photovoltaic devices" """ # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Aug. 2022 # get the reference spectrum at wavelengths matching the measured spectra if e_ref is None: e_ref = get_am15g(wavelength=e_sun.T.index) # interpolate the sr at the wavelengths of the spectra # reference spectrum wavelengths may differ if e_ref is from caller sr_sun = np.interp(e_sun.T.index, sr.index, sr, left=0.0, right=0.0) sr_ref = np.interp(e_ref.T.index, sr.index, sr, left=0.0, right=0.0) # a helper function to make usable fraction calculations more readable def integrate(e): return np.trapz(e, x=e.T.index, axis=-1) # calculate usable fractions uf_sun = integrate(e_sun * sr_sun) / integrate(e_sun) uf_ref = integrate(e_ref * sr_ref) / integrate(e_ref) # mismatch is the ratio or quotient of the usable fractions smm = uf_sun / uf_ref if isinstance(e_sun, pd.DataFrame): smm = pd.Series(smm, index=e_sun.index) return smm
[docs]def spectral_factor_firstsolar(precipitable_water, airmass_absolute, module_type=None, coefficients=None, min_precipitable_water=0.1, max_precipitable_water=8): r""" Spectral mismatch modifier based on precipitable water and absolute (pressure-adjusted) airmass. Estimates a spectral mismatch modifier :math:`M` representing the effect on module short circuit current of variation in the spectral irradiance. :math:`M` is estimated from absolute (pressure currected) air mass, :math:`AM_a`, and precipitable water, :math:`Pw`, using the following function: .. math:: M = c_1 + c_2 AM_a + c_3 Pw + c_4 AM_a^{0.5} + c_5 Pw^{0.5} + c_6 \frac{AM_a} {Pw^{0.5}} Default coefficients are determined for several cell types with known quantum efficiency curves, by using the Simple Model of the Atmospheric Radiative Transfer of Sunshine (SMARTS) [1]_. Using SMARTS, spectrums are simulated with all combinations of AMa and Pw where: * :math:`0.5 \textrm{cm} <= Pw <= 5 \textrm{cm}` * :math:`1.0 <= AM_a <= 5.0` * Spectral range is limited to that of CMP11 (280 nm to 2800 nm) * spectrum simulated on a plane normal to the sun * All other parameters fixed at G173 standard From these simulated spectra, M is calculated using the known quantum efficiency curves. Multiple linear regression is then applied to fit Eq. 1 to determine the coefficients for each module. Based on the PVLIB Matlab function ``pvl_FSspeccorr`` by Mitchell Lee and Alex Panchula of First Solar, 2016 [2]_. Parameters ---------- precipitable_water : numeric atmospheric precipitable water. [cm] airmass_absolute : numeric absolute (pressure-adjusted) airmass. [unitless] module_type : str, optional a string specifying a cell type. Values of 'cdte', 'monosi', 'xsi', 'multisi', and 'polysi' (can be lower or upper case). If provided, module_type selects default coefficients for the following modules: * 'cdte' - First Solar Series 4-2 CdTe module. * 'monosi', 'xsi' - First Solar TetraSun module. * 'multisi', 'polysi' - anonymous multi-crystalline silicon module. * 'cigs' - anonymous copper indium gallium selenide module. * 'asi' - anonymous amorphous silicon module. The module used to calculate the spectral correction coefficients corresponds to the Multi-crystalline silicon Manufacturer 2 Model C from [3]_. The spectral response (SR) of CIGS and a-Si modules used to derive coefficients can be found in [4]_ coefficients : array-like, optional Allows for entry of user-defined spectral correction coefficients. Coefficients must be of length 6. Derivation of coefficients requires use of SMARTS and PV module quantum efficiency curve. Useful for modeling PV module types which are not included as defaults, or to fine tune the spectral correction to a particular PV module. Note that the parameters for modules with very similar quantum efficiency should be similar, in most cases limiting the need for module specific coefficients. min_precipitable_water : float, default 0.1 minimum atmospheric precipitable water. Any ``precipitable_water`` value lower than ``min_precipitable_water`` is set to ``min_precipitable_water`` to avoid model divergence. [cm] max_precipitable_water : float, default 8 maximum atmospheric precipitable water. Any ``precipitable_water`` value greater than ``max_precipitable_water`` is set to ``np.nan`` to avoid model divergence. [cm] Returns ------- modifier: array-like spectral mismatch factor (unitless) which can be 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] Gueymard, Christian. SMARTS2: a simple model of the atmospheric radiative transfer of sunshine: algorithms and performance assessment. Cocoa, FL: Florida Solar Energy Center, 1995. .. [2] Lee, Mitchell, and Panchula, Alex. "Spectral Correction for Photovoltaic Module Performance Based on Air Mass and Precipitable Water." IEEE Photovoltaic Specialists Conference, Portland, 2016 .. [3] Marion, William F., et al. User's Manual for Data for Validating Models for PV Module Performance. National Renewable Energy Laboratory, 2014. .. [4] Schweiger, M. and Hermann, W, Influence of Spectral Effects on Energy Yield of Different PV Modules: Comparison of Pwat and MMF Approach, TUV Rheinland Energy GmbH report 21237296.003, January 2017 """ # --- Screen Input Data --- # *** Pw *** # Replace Pw Values below 0.1 cm with 0.1 cm to prevent model from # diverging" pw = np.atleast_1d(precipitable_water) pw = pw.astype('float64') if np.min(pw) < min_precipitable_water: pw = np.maximum(pw, min_precipitable_water) warn('Exceptionally low pw values replaced with ' f'{min_precipitable_water} cm to prevent model divergence') # Warn user about Pw data that is exceptionally high if np.max(pw) > max_precipitable_water: pw[pw > max_precipitable_water] = np.nan warn('Exceptionally high pw values replaced by np.nan: ' 'check input data.') # *** AMa *** # Replace Extremely High AM with AM 10 to prevent model divergence # AM > 10 will only occur very close to sunset if np.max(airmass_absolute) > 10: airmass_absolute = np.minimum(airmass_absolute, 10) # Warn user about AMa data that is exceptionally low if np.min(airmass_absolute) < 0.58: warn('Exceptionally low air mass: ' + 'model not intended for extra-terrestrial use') # pvl_absoluteairmass(1,pvl_alt2pres(4340)) = 0.58 Elevation of # Mina Pirquita, Argentian = 4340 m. Highest elevation city with # population over 50,000. _coefficients = {} _coefficients['cdte'] = ( 0.86273, -0.038948, -0.012506, 0.098871, 0.084658, -0.0042948) _coefficients['monosi'] = ( 0.85914, -0.020880, -0.0058853, 0.12029, 0.026814, -0.0017810) _coefficients['xsi'] = _coefficients['monosi'] _coefficients['polysi'] = ( 0.84090, -0.027539, -0.0079224, 0.13570, 0.038024, -0.0021218) _coefficients['multisi'] = _coefficients['polysi'] _coefficients['cigs'] = ( 0.85252, -0.022314, -0.0047216, 0.13666, 0.013342, -0.0008945) _coefficients['asi'] = ( 1.12094, -0.047620, -0.0083627, -0.10443, 0.098382, -0.0033818) if module_type is not None and coefficients is None: coefficients = _coefficients[module_type.lower()] elif module_type is None and coefficients is not None: pass elif module_type is None and coefficients is None: raise TypeError('No valid input provided, both module_type and ' + 'coefficients are None') else: raise TypeError('Cannot resolve input, must supply only one of ' + 'module_type and coefficients') # Evaluate Spectral Shift coeff = coefficients ama = airmass_absolute modifier = ( coeff[0] + coeff[1]*ama + coeff[2]*pw + coeff[3]*np.sqrt(ama) + coeff[4]*np.sqrt(pw) + coeff[5]*ama/np.sqrt(pw)) return modifier
[docs]def spectral_factor_sapm(airmass_absolute, module): """ Calculates the SAPM spectral loss coefficient, F1. Parameters ---------- airmass_absolute : numeric Absolute airmass module : dict-like A dict, Series, or DataFrame defining the SAPM performance parameters. See the :py:func:`sapm` notes section for more details. Returns ------- F1 : numeric The SAPM spectral loss coefficient. Notes ----- nan airmass values will result in 0 output. """ am_coeff = [module['A4'], module['A3'], module['A2'], module['A1'], module['A0']] spectral_loss = np.polyval(am_coeff, airmass_absolute) spectral_loss = np.where(np.isnan(spectral_loss), 0, spectral_loss) spectral_loss = np.maximum(0, spectral_loss) if isinstance(airmass_absolute, pd.Series): spectral_loss = pd.Series(spectral_loss, airmass_absolute.index) return spectral_loss
[docs]def spectral_factor_caballero(precipitable_water, airmass_absolute, aod500, module_type=None, coefficients=None): r""" Estimate a technology-specific spectral mismatch modifier from airmass, aerosol optical depth, and atmospheric precipitable water, using the Caballero model. The model structure was motivated by examining the effect of these three atmospheric parameters on simulated irradiance spectra and spectral modifiers. However, the coefficient values reported in [1]_ and 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. Parameters ---------- precipitable_water : numeric atmospheric precipitable water. [cm] airmass_absolute : numeric absolute (pressure-adjusted) airmass. [unitless] aod500 : numeric atmospheric aerosol optical depth at 500 nm. [unitless] module_type : str, optional One of the following PV technology strings from [1]_: * ``'cdte'`` - anonymous CdTe module. * ``'monosi'``, - anonymous sc-si module. * ``'multisi'``, - anonymous mc-si- module. * ``'cigs'`` - anonymous copper indium gallium selenide module. * ``'asi'`` - anonymous amorphous silicon module. * ``'perovskite'`` - anonymous pervoskite module. coefficients : array-like, optional user-defined coefficients, if not using one of the default 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] Caballero, J.A., Fernández, E., Theristis, M., Almonacid, F., and Nofuentes, G. "Spectral Corrections Based on Air Mass, Aerosol Optical Depth and Precipitable Water for PV Performance Modeling." IEEE Journal of Photovoltaics 2018, 8(2), 552-558. :doi:`10.1109/jphotov.2017.2787019` """ 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') # Experimental coefficients from [1]_. # The extra 0/1 coefficients at the end are used to enable/disable # terms to match the different equation forms in Table 1. _coefficients = {} _coefficients['cdte'] = ( 1.0044, 0.0095, -0.0037, 0.0002, 0.0000, -0.0046, -0.0182, 0, 0.0095, 0.0068, 0, 1) _coefficients['monosi'] = ( 0.9706, 0.0377, -0.0123, 0.0025, -0.0002, 0.0159, -0.0165, 0, -0.0016, -0.0027, 1, 0) _coefficients['multisi'] = ( 0.9836, 0.0254, -0.0085, 0.0016, -0.0001, 0.0094, -0.0132, 0, -0.0002, -0.0011, 1, 0) _coefficients['cigs'] = ( 0.9801, 0.0283, -0.0092, 0.0019, -0.0001, 0.0117, -0.0126, 0, -0.0011, -0.0019, 1, 0) _coefficients['asi'] = ( 1.1060, -0.0848, 0.0302, -0.0076, 0.0006, -0.1283, 0.0986, -0.0254, 0.0156, 0.0146, 1, 0) _coefficients['perovskite'] = ( 1.0637, -0.0491, 0.0180, -0.0047, 0.0004, -0.0773, 0.0583, -0.0159, 0.01251, 0.0109, 1, 0) if module_type is not None: coeff = _coefficients[module_type] else: coeff = coefficients # Evaluate spectral correction factor ama = airmass_absolute aod500_ref = 0.084 pw_ref = 1.4164 f_AM = ( coeff[0] + coeff[1] * ama + coeff[2] * ama**2 + coeff[3] * ama**3 + coeff[4] * ama**4 ) # Eq 6, with Table 1 f_AOD = (aod500 - aod500_ref) * ( coeff[5] + coeff[10] * coeff[6] * ama + coeff[11] * coeff[6] * np.log(ama) + coeff[7] * ama**2 ) # Eq 7, with Table 1 f_PW = (precipitable_water - pw_ref) * ( coeff[8] + coeff[9] * np.log(ama) ) modifier = f_AM + f_AOD + f_PW # Eq 5 return modifier