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

pvlib/__init__.py

@@ -1,10 +1,12 @@
 from pvlib.version import __version__  # noqa: F401
 
 from pvlib import (  # noqa: F401
+    # list spectrum first so it's available for atmosphere & pvsystem (GH 1628)
+    spectrum,
+
     atmosphere,
     bifacial,
     clearsky,
-    # forecast
     iam,
     inverter,
     iotools,
@@ -20,7 +22,6 @@ from pvlib import (  # noqa: F401
     soiling,
     solarposition,
     spa,
-    spectrum,
     temperature,
     tools,
     tracking,

pvlib/atmosphere.py

@@ -3,11 +3,11 @@ The ``atmosphere`` module contains methods to calculate relative and
 absolute airmass and to determine pressure from altitude or vice versa.
 """
 
-from warnings import warn
-
 import numpy as np
 import pandas as pd
+import pvlib
 
+from pvlib._deprecation import deprecated
 
 APPARENT_ZENITH_MODELS = ('simple', 'kasten1966', 'kastenyoung1989',
                           'gueymard1993', 'pickering2002')
@@ -158,9 +158,11 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
         * 'gueymard1993' - See reference [4] -
           requires apparent sun zenith
         * 'young1994' - See reference [5] -
-          requries true sun zenith
+          requires true sun zenith
         * 'pickering2002' - See reference [6] -
           requires apparent sun zenith
+        * 'gueymard2003' - See references [7] and [8] -
+          requires apparent sun zenith
 
     Returns
     -------
@@ -196,7 +198,17 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
 
     .. [6] Keith A. Pickering. "The Ancient Star Catalog". DIO 12:1, 20,
 
-    .. [7] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global
+    .. [7] C. Gueymard, "Direct solar transmittance and irradiance
+       predictions with broadband models. Part I: detailed theoretical
+       performance assessment". Solar Energy, vol 74, pp. 355-379, 2003.
+       :doi:`10.1016/S0038-092X(03)00195-6`
+
+    .. [8] C. Gueymard (2019). Clear-Sky Radiation Models and Aerosol Effects.
+       In: Polo, J., Martín-Pomares, L., Sanfilippo, A. (eds) Solar Resources
+       Mapping. Green Energy and Technology. Springer, Cham.
+       :doi:`10.1007/978-3-319-97484-2_5`
+
+    .. [9] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global
        Horizontal Irradiance Clear Sky Models: Implementation and Analysis"
        Sandia Report, (2012).
     '''
@@ -229,6 +241,9 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
     elif 'gueymard1993' == model:
         am = (1.0 / (np.cos(zenith_rad) +
               0.00176759*(z)*((94.37515 - z) ** - 1.21563)))
+    elif 'gueymard2003' == model:
+        am = (1.0 / (np.cos(zenith_rad) +
+              0.48353*(z**0.095846)/(96.741 - z)**1.754))
     else:
         raise ValueError('%s is not a valid model for relativeairmass', model)
 
@@ -321,175 +336,10 @@ def gueymard94_pw(temp_air, relative_humidity):
     return pw
 
 
-def first_solar_spectral_correction(pw, airmass_absolute,
-                                    module_type=None, coefficients=None,
-                                    min_pw=0.1, max_pw=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
-    ----------
-    pw : array-like
-        atmospheric precipitable water. [cm]
-
-    airmass_absolute : array-like
-        absolute (pressure-adjusted) airmass. [unitless]
-
-    min_pw : float, default 0.1
-        minimum atmospheric precipitable water. Any pw value lower than min_pw
-        is set to min_pw to avoid model divergence. [cm]
-
-    max_pw : float, default 8
-        maximum atmospheric precipitable water. Any pw value higher than max_pw
-        is set to NaN to avoid model divergence. [cm]
-
-    module_type : None or string, default None
-        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 : None or array-like, default None
-        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.
-
-    Returns
-    -------
-    modifier: array-like
-        spectral mismatch factor (unitless) which is 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(pw)
-    pw = pw.astype('float64')
-    if np.min(pw) < min_pw:
-        pw = np.maximum(pw, min_pw)
-        warn(f'Exceptionally low pw values replaced with {min_pw} cm to '
-             'prevent model divergence')
-
-    # Warn user about Pw data that is exceptionally high
-    if np.max(pw) > max_pw:
-        pw[pw > max_pw] = 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
+first_solar_spectral_correction = deprecated(
+    since='0.10.0',
+    alternative='pvlib.spectrum.spectral_factor_firstsolar'
+)(pvlib.spectrum.spectral_factor_firstsolar)
 
 
 def bird_hulstrom80_aod_bb(aod380, aod500):