pvlib 0.9.4a1__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/spectrum/__init__.py

@@ -1,3 +1,9 @@
 from pvlib.spectrum.spectrl2 import spectrl2  # noqa: F401
-from pvlib.spectrum.mismatch import (get_example_spectral_response, get_am15g,
-                                     calc_spectral_mismatch_field)
+from pvlib.spectrum.mismatch import (  # noqa: F401
+    calc_spectral_mismatch_field,
+    get_am15g,
+    get_example_spectral_response,
+    spectral_factor_caballero,
+    spectral_factor_firstsolar,
+    spectral_factor_sapm,
+)

pvlib/spectrum/mismatch.py

@@ -8,6 +8,8 @@ import pandas as pd
 from scipy.interpolate import interp1d
 import os
 
+from warnings import warn
+
 
 def get_example_spectral_response(wavelength=None):
     '''
@@ -235,3 +237,336 @@ def calc_spectral_mismatch_field(sr, e_sun, e_ref=None):
         smm = pd.Series(smm, index=e_sun.index)
 
     return smm
+
+
+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. http://www.nrel.gov/docs/fy14osti/61610.pdf
+    .. [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
+
+
+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
+
+
+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

pvlib/temperature.py

@@ -9,6 +9,7 @@ from pvlib.tools import sind
 from pvlib._deprecation import warn_deprecated
 from pvlib.tools import _get_sample_intervals
 import scipy
+import scipy.constants
 import warnings
 
 
@@ -290,7 +291,7 @@ def sapm_cell_from_module(module_temperature, poa_global, deltaT,
 
 
 def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
-                eta_m=None, module_efficiency=0.1, alpha_absorption=0.9):
+                module_efficiency=0.1, alpha_absorption=0.9):
     r"""
     Calculate cell temperature using an empirical heat loss factor model
     as implemented in PVsyst.
@@ -318,9 +319,7 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
     u_v : float, default 0.0
         Combined heat loss factor influenced by wind. Parameter :math:`U_{v}`
         in :eq:`pvsyst`.
-        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`  # noQA: E501
-
-    eta_m : numeric, default None (deprecated, use module_efficiency instead)
+        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`
 
     module_efficiency : numeric, default 0.1
         Module external efficiency as a fraction. Parameter :math:`\eta_{m}`
@@ -375,13 +374,8 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
     >>> params = TEMPERATURE_MODEL_PARAMETERS['pvsyst']['freestanding']
     >>> pvsyst_cell(1000, 10, **params)
     37.93103448275862
-    """
+    """  # noQA: E501
 
-    if eta_m:
-        warn_deprecated(
-            since='v0.9', message='eta_m overwriting module_efficiency',
-            name='eta_m', alternative='module_efficiency', removal='v0.10')
-        module_efficiency = eta_m
     total_loss_factor = u_c + u_v * wind_speed
     heat_input = poa_global * alpha_absorption * (1 - module_efficiency)
     temp_difference = heat_input / total_loss_factor
@@ -413,12 +407,14 @@ def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
 
     u0 : numeric, default 25.0
         Combined heat loss factor coefficient. The default value is one
-        determined by Faiman for 7 silicon modules.
+        determined by Faiman for 7 silicon modules
+        in the Negev desert on an open rack at 30.9° tilt.
         :math:`\left[\frac{\text{W}/{\text{m}^2}}{\text{C}}\right]`
 
     u1 : numeric, default 6.84
         Combined heat loss factor influenced by wind. The default value is one
-        determined by Faiman for 7 silicon modules.
+        determined by Faiman for 7 silicon modules
+        in the Negev desert on an open rack at 30.9° tilt.
         :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`
 
     Returns
@@ -434,6 +430,7 @@ def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
     ----------
     .. [1] Faiman, D. (2008). "Assessing the outdoor operating temperature of
        photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.
+       :doi:`10.1002/pip.813`
 
     .. [2] "IEC 61853-2 Photovoltaic (PV) module performance testing and energy
        rating - Part 2: Spectral responsivity, incidence angle and module
@@ -442,7 +439,12 @@ def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
     .. [3] "IEC 61853-3 Photovoltaic (PV) module performance testing and energy
        rating - Part 3: Energy rating of PV modules". IEC, Geneva, 2018.
 
-    '''
+    See also
+    --------
+    pvlib.temperature.faiman_rad
+
+    '''  # noQA: E501
+
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Dec., 2019
 
     # The following lines may seem odd since u0 & u1 are probably scalar,
@@ -457,6 +459,115 @@ def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
     return temp_air + temp_difference
 
 
+def faiman_rad(poa_global, temp_air, wind_speed=1.0, ir_down=None,
+               u0=25.0, u1=6.84, sky_view=1.0, emissivity=0.88):
+    r'''
+    Calculate cell or module temperature using the Faiman model augmented
+    with a radiative loss term.
+
+    The Faiman model uses an empirical heat loss factor model [1]_ and is
+    adopted in the IEC 61853 standards [2]_ and [3]_.  The radiative loss
+    term was proposed and developed by Driesse [4]_.
+
+    The model can be used to represent cell or module temperature.
+
+    Parameters
+    ----------
+    poa_global : numeric
+        Total incident irradiance [W/m^2].
+
+    temp_air : numeric
+        Ambient dry bulb temperature [C].
+
+    wind_speed : numeric, default 1.0
+        Wind speed measured at the same height for which the wind loss
+        factor was determined.  The default value 1.0 m/s is the wind
+        speed at module height used to determine NOCT. [m/s]
+
+    ir_down : numeric, default 0.0
+        Downwelling infrared radiation from the sky, measured on a horizontal
+        surface. [W/m^2]
+
+    u0 : numeric, default 25.0
+        Combined heat loss factor coefficient. The default value is one
+        determined by Faiman for 7 silicon modules
+        in the Negev desert on an open rack at 30.9° tilt.
+        :math:`\left[\frac{\text{W}/{\text{m}^2}}{\text{C}}\right]`
+
+    u1 : numeric, default 6.84
+        Combined heat loss factor influenced by wind. The default value is one
+        determined by Faiman for 7 silicon modules
+        in the Negev desert on an open rack at 30.9° tilt.
+        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`
+
+    sky_view : numeric, default 1.0
+        Effective view factor limiting the radiative exchange between the
+        module and the sky. For a tilted array the expressions
+        (1 + 3*cos(tilt)) / 4 can be used as a first estimate for sky_view
+        as discussed in [4]_. The default value is for a horizontal module.
+        [unitless]
+
+    emissivity : numeric, default 0.88
+        Infrared emissivity of the module surface facing the sky. The default
+        value represents the middle of a range of values found in the
+        literature. [unitless]
+
+    Returns
+    -------
+    numeric, values in degrees Celsius
+
+    Notes
+    -----
+    All arguments may be scalars or vectors. If multiple arguments
+    are vectors they must be the same length.
+
+    When only irradiance, air temperature and wind speed inputs are provided
+    (`ir_down` is `None`) this function calculates the same device temperature
+    as the original faiman model. When down-welling long-wave radiation data
+    are provided as well (`ir_down` is not None) the default u0 and u1 values
+    from the original model should not be used because a portion of the
+    radiative losses would be double-counted.
+
+    References
+    ----------
+    .. [1] Faiman, D. (2008). "Assessing the outdoor operating temperature of
+       photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.
+       :doi:`10.1002/pip.813`
+
+    .. [2] "IEC 61853-2 Photovoltaic (PV) module performance testing and energy
+       rating - Part 2: Spectral responsivity, incidence angle and module
+       operating temperature measurements". IEC, Geneva, 2018.
+
+    .. [3] "IEC 61853-3 Photovoltaic (PV) module performance testing and energy
+       rating - Part 3: Energy rating of PV modules". IEC, Geneva, 2018.
+
+    .. [4] Driesse, A. et al (2022) "Improving Common PV Module Temperature
+       Models by Incorporating Radiative Losses to the Sky". SAND2022-11604.
+       :doi:`10.2172/1884890`
+
+    See also
+    --------
+    pvlib.temperature.faiman
+
+    '''  # noQA: E501
+
+    # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2022
+
+    abs_zero = -273.15
+    sigma = scipy.constants.Stefan_Boltzmann
+
+    if ir_down is None:
+        qrad_sky = 0.0
+    else:
+        ir_up = sigma * ((temp_air - abs_zero)**4)
+        qrad_sky = emissivity * sky_view * (ir_up - ir_down)
+
+    heat_input = poa_global - qrad_sky
+    total_loss_factor = u0 + u1 * wind_speed
+    temp_difference = heat_input / total_loss_factor
+    return temp_air + temp_difference
+
+
 def ross(poa_global, temp_air, noct):
     r'''
     Calculate cell temperature using the Ross model.