pvlib 0.11.1__py3-none-any.whl → 0.12.0__py3-none-any.whl

pvlib/__init__.py

@@ -27,4 +27,5 @@ from pvlib import (  # noqa: F401
     temperature,
     tools,
     tracking,
+    transformer,
 )

pvlib/_deprecation.py

@@ -316,3 +316,76 @@ def deprecated(since, message='', name='', alternative='', pending=False,
         return finalize(wrapper, new_doc)
 
     return deprecate
+
+
+def renamed_kwarg_warning(since, old_param_name, new_param_name, removal=""):
+    """
+    Decorator to mark a possible keyword argument as deprecated and replaced
+    with other name.
+
+    Raises a warning when the deprecated argument is used, and replaces the
+    call with the new argument name. Does not modify the function signature.
+
+    .. warning::
+        Ensure ``removal`` date with a ``fail_on_pvlib_version`` decorator in
+        the test suite.
+
+    .. note::
+        Not compatible with positional-only arguments.
+
+    .. note::
+        Documentation for the function may updated to reflect the new parameter
+        name; it is suggested to add a |.. versionchanged::| directive.
+
+    Parameters
+    ----------
+    since : str
+        The release at which this API became deprecated.
+    old_param_name : str
+        The name of the deprecated parameter.
+    new_param_name : str
+        The name of the new parameter.
+    removal : str, optional
+        The expected removal version, in order to compose the Warning message.
+
+    Examples
+    --------
+    >>> @renamed_kwarg_warning("1.4.0", "old_name", "new_name", "1.6.0")
+    >>> def some_function(new_name=None):
+    >>>     pass
+    >>> some_function(old_name=1)
+    Parameter 'old_name' has been renamed since 1.4.0. and
+    will be removed in 1.6.0. Please use 'new_name' instead.
+
+    >>> @renamed_kwarg_warning("1.4.0", "old_name", "new_name")
+    >>> def some_function(new_name=None):
+    >>>     pass
+    >>> some_function(old_name=1)
+    Parameter 'old_name' has been renamed since 1.4.0. and
+    will be removed soon. Please use 'new_name' instead.
+    """
+
+    def deprecate(func, old=old_param_name, new=new_param_name, since=since):
+        def wrapper(*args, **kwargs):
+            if old in kwargs:
+                if new in kwargs:
+                    raise ValueError(
+                        f"{func.__name__} received both '{old}' and '{new}', "
+                        "which are mutually exclusive since they refer to the "
+                        f"same parameter. Please remove deprecated '{old}'."
+                    )
+                warnings.warn(
+                    f"Parameter '{old}' has been renamed since {since}. "
+                    f"and will be removed "
+                    + (f"in {removal}" if removal else "soon")
+                    + f". Please use '{new}' instead.",
+                    _projectWarning,
+                    stacklevel=2,
+                )
+                kwargs[new] = kwargs.pop(old)
+            return func(*args, **kwargs)
+
+        wrapper = functools.wraps(func)(wrapper)
+        return wrapper
+
+    return deprecate

pvlib/atmosphere.py

@@ -6,9 +6,6 @@ speed at different heights.
 
 import numpy as np
 import pandas as pd
-import pvlib
-
-from pvlib._deprecation import deprecated
 
 APPARENT_ZENITH_MODELS = ('simple', 'kasten1966', 'kastenyoung1989',
                           'gueymard1993', 'pickering2002')
@@ -337,10 +334,83 @@ def gueymard94_pw(temp_air, relative_humidity):
     return pw
 
 
-first_solar_spectral_correction = deprecated(
-    since='0.10.0',
-    alternative='pvlib.spectrum.spectral_factor_firstsolar'
-)(pvlib.spectrum.spectral_factor_firstsolar)
+def rh_from_tdew(temp_air, temp_dew, coeff=(6.112, 17.62, 243.12)):
+    """
+    Calculate relative humidity from dewpoint temperature using the Magnus
+    equation.
+
+    Parameters
+    ----------
+    temp_air : numeric
+        Air temperature (dry-bulb temperature). [°C]
+    temp_dew : numeric
+        Dew-point temperature. [°C]
+    coeff : tuple, default (6.112, 17.62, 243.12)
+        Magnus equation coefficients (A, B, C).  The default values are those
+        recommended by the WMO [1]_.
+
+    Returns
+    -------
+    numeric
+        Relative humidity (0.0-100.0). [%]
+
+    References
+    ----------
+    .. [1] "Guide to Instruments and Methods of Observation",
+       World Meteorological Organization, WMO-No. 8, 2023.
+       https://library.wmo.int/idurl/4/68695
+    """
+
+    # Calculate vapor pressure (e) and saturation vapor pressure (es)
+    e = coeff[0] * np.exp((coeff[1] * temp_air) / (coeff[2] + temp_air))
+    es = coeff[0] * np.exp((coeff[1] * temp_dew) / (coeff[2] + temp_dew))
+
+    # Calculate relative humidity as percentage
+    relative_humidity = 100 * (es / e)
+
+    return relative_humidity
+
+
+def tdew_from_rh(temp_air, relative_humidity, coeff=(6.112, 17.62, 243.12)):
+    """
+    Calculate dewpoint temperature using the Magnus equation.
+    This is a reversal of the calculation in :py:func:`rh_from_tdew`.
+
+    Parameters
+    ----------
+    temp_air : numeric
+        Air temperature (dry-bulb temperature). [°C]
+    relative_humidity : numeric
+        Relative humidity (0-100). [%]
+    coeff: tuple, default (6.112, 17.62, 243.12)
+        Magnus equation coefficients (A, B, C).  The default values are those
+        recommended by the WMO [1]_.
+
+    Returns
+    -------
+    numeric
+        Dewpoint temperature. [°C]
+
+    References
+    ----------
+    .. [1] "Guide to Instruments and Methods of Observation",
+       World Meteorological Organization, WMO-No. 8, 2023.
+       https://library.wmo.int/idurl/4/68695
+    """
+    # Calculate the term inside the log
+    # From RH = 100 * (es/e), we get es = (RH/100) * e
+    # Substituting the Magnus equation and solving for dewpoint
+
+    # First calculate ln(es/A)
+    ln_term = (
+        (coeff[1] * temp_air) / (coeff[2] + temp_air)
+        + np.log(relative_humidity/100)
+    )
+
+    # Then solve for dewpoint
+    dewpoint = coeff[2] * ln_term / (coeff[1] - ln_term)
+
+    return dewpoint
 
 
 def bird_hulstrom80_aod_bb(aod380, aod500):

pvlib/bifacial/infinite_sheds.py

@@ -260,8 +260,9 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
     Returns
     -------
     output : dict or DataFrame
-        Output is a DataFrame when input ghi is a Series. See Notes for
-        descriptions of content.
+        Output is a ``pandas.DataFrame`` when ``ghi`` is a Series.
+        Otherwise it is a dict of ``numpy.ndarray``
+        See Notes for descriptions of content.
 
     Notes
     -----
@@ -372,7 +373,7 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
         'poa_global': poa_global, 'poa_direct': poa_direct,
         'poa_diffuse': poa_diffuse, 'poa_ground_diffuse': poa_gnd_pv,
         'poa_sky_diffuse': poa_sky_pv, 'shaded_fraction': f_x}
-    if isinstance(poa_global, pd.Series):
+    if isinstance(ghi, pd.Series):
         output = pd.DataFrame(output)
     return output
 

pvlib/bifacial/utils.py

@@ -87,7 +87,8 @@ def _unshaded_ground_fraction(surface_tilt, surface_azimuth, solar_zenith,
                                         surface_azimuth)
     f_gnd_beam = 1.0 - np.minimum(
         1.0, gcr * np.abs(cosd(surface_tilt) + sind(surface_tilt) * tan_phi))
-    np.where(solar_zenith > max_zenith, 0., f_gnd_beam)  # [1], Eq. 4
+    # [1], Eq. 4
+    f_gnd_beam = np.where(solar_zenith > max_zenith, 0., f_gnd_beam)
     return f_gnd_beam  # 1 - min(1, abs()) < 1 always
 
 

pvlib/clearsky.py

@@ -327,13 +327,13 @@ def haurwitz(apparent_zenith):
     '''
 
     cos_zenith = tools.cosd(apparent_zenith.values)
-    clearsky_ghi = np.zeros_like(apparent_zenith.values)
+    ghi_clear = np.zeros_like(apparent_zenith.values)
     cos_zen_gte_0 = cos_zenith > 0
-    clearsky_ghi[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
-                                   np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
+    ghi_clear[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
+                                np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
 
     df_out = pd.DataFrame(index=apparent_zenith.index,
-                          data=clearsky_ghi,
+                          data=ghi_clear,
                           columns=['ghi'])
 
     return df_out
@@ -683,22 +683,26 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
                     var_diff=0.005, slope_dev=8, max_iterations=20,
                     return_components=False):
     """
-    Detects clear sky times according to the algorithm developed by Reno
-    and Hansen for GHI measurements. The algorithm [1]_ was designed and
-    validated for analyzing GHI time series only. Users may attempt to
-    apply it to other types of time series data using different filter
-    settings, but should be skeptical of the results.
+    Detects clear sky times using the algorithm developed by Reno
+    and Hansen.
 
-    The algorithm detects clear sky times by comparing statistics for a
+    The algorithm [1]_ was designed and
+    validated for analyzing GHI time series. Jordan and Hansen [2]_ extended
+    the algorithm to plane-of-array (POA) irradiance measurements.
+
+    The algorithm [1]_ detects clear sky times by comparing statistics for a
     measured time series and an expected clearsky time series.
     Statistics are calculated using a sliding time window (e.g., 10
     minutes). An iterative algorithm identifies clear periods, uses the
     identified periods to estimate bias in the clearsky data, scales the
     clearsky data and repeats.
 
-    Clear times are identified by meeting 5 criteria. Default values for
+    Clear times are identified by meeting five criteria. Default values for
     these thresholds are appropriate for 10 minute windows of 1 minute
-    GHI data.
+    GHI data. For data at longer intervals, it is recommended
+    to set ``infer_limits=True`` to use the thresholds from [2]_.
+
+    For POA data, ``clearsky`` must be on the same plane as ``measured``.
 
     Parameters
     ----------
@@ -713,8 +717,8 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         If True, does not use passed in kwargs (or defaults), but instead
         interpolates these values from Table 1 in [2]_.
     window_length : int, default 10
-        Length of sliding time window in minutes. Must be greater than 2
-        periods.
+        Length of sliding time window in minutes. Each window must contain at
+        least three data points.
     mean_diff : float, default 75
         Threshold value for agreement between mean values of measured
         and clearsky in each interval, see Eq. 6 in [1]. [W/m2]
@@ -723,8 +727,6 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         clearsky values in each interval, see Eq. 7 in [1]. [W/m2]
     lower_line_length : float, default -5
         Lower limit of line length criterion from Eq. 8 in [1].
-        Criterion satisfied when lower_line_length < line length difference
-        < upper_line_length.
     upper_line_length : float, default 10
         Upper limit of line length criterion from Eq. 8 in [1].
     var_diff : float, default 0.005
@@ -736,7 +738,7 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         change in successive values, see Eqs. 12 through 14 in [1].
     max_iterations : int, default 20
         Maximum number of times to apply a different scaling factor to
-        the clearsky and redetermine clear_samples. Must be 1 or larger.
+        the clearsky and redetermine ``clear_samples``. Must be 1 or larger.
     return_components : bool, default False
         Controls if additional output should be returned. See below.
 
@@ -748,19 +750,23 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
 
     components : OrderedDict, optional
         Dict of arrays of whether or not the given time window is clear
-        for each condition. Only provided if return_components is True.
+        for each condition. Only provided if ``return_components`` is True.
 
     alpha : scalar, optional
-        Scaling factor applied to the clearsky_ghi to obtain the
-        detected clear_samples. Only provided if return_components is
+        Scaling factor applied to ``clearsky`` to obtain the
+        detected ``clear_samples``. Only provided if ``return_components`` is
         True.
 
     Raises
     ------
     ValueError
-        If measured is not a Series and times is not provided
+        If ``measured`` is not a Series and times is not provided.
+    ValueError
+        If a window contains less than three data points.
+    ValueError
+        If the measured data is not sufficient to fill a window.
     NotImplementedError
-        If timestamps are not equally spaced
+        If timestamps are not equally spaced.
 
     References
     ----------
@@ -812,6 +818,13 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
     sample_interval, samples_per_window = \
         tools._get_sample_intervals(times, window_length)
 
+    if samples_per_window < 3:
+        raise ValueError(f"Samples per window of {samples_per_window}"
+                         " found. Each window must contain at least 3 data"
+                         " points."
+                         f" Window length of {window_length} found; increase"
+                         f" window length to {3*sample_interval} or longer.")
+
     # if infer_limits, find threshold values using the sample interval
     if infer_limits:
         window_length, mean_diff, max_diff, lower_line_length, \

pvlib/iam.py

@@ -269,8 +269,8 @@ def martin_ruiz(aoi, a_r=0.16):
 
     which is presented as :math:`AL(\alpha) = 1 - IAM` in equation 4 of [1]_,
     with :math:`\alpha` representing the angle of incidence AOI. Thus IAM = 1
-    at AOI = 0, and IAM = 0 at AOI = 90.  This equation is only valid for
-    -90 <= aoi <= 90, therefore `iam` is constrained to 0.0 outside this
+    at AOI = 0°, and IAM = 0 at AOI = 90°.  This equation is only valid for
+    0° <= aoi <= 90°, therefore `iam` is constrained to 0.0 outside this
     interval.
 
     References
@@ -891,8 +891,8 @@ def schlick_diffuse(surface_tilt):
     implements only the integrated Schlick approximation.
 
     Note also that the output of this function (which is an exact integration)
-    can be compared with the output of :py:func:`marion_diffuse` which numerically
-    integrates the Schlick approximation:
+    can be compared with the output of :py:func:`marion_diffuse` which
+    numerically integrates the Schlick approximation:
 
     .. code::
 

pvlib/iotools/midc.py

@@ -193,7 +193,7 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
 
     See the MIDC_VARIABLE_MAP for collection of mappings by site.
     For a full list of pvlib variable names see the
-    :ref:`variables_style_rules`.
+    :ref:`nomenclature`.
 
     Be sure to check the units for the variables you will use on the
     `MIDC site <https://midcdmz.nrel.gov/>`_.

pvlib/iotools/psm3.py

@@ -49,7 +49,7 @@ REQUEST_VARIABLE_MAP = {
     'ghi_clear': 'clearsky_ghi',
     'dhi_clear': 'clearsky_dhi',
     'dni_clear': 'clearsky_dni',
-    'zenith': 'solar_zenith_angle',
+    'solar_zenith': 'solar_zenith_angle',
     'temp_air': 'air_temperature',
     'temp_dew': 'dew_point',
     'relative_humidity': 'relative_humidity',

pvlib/iotools/pvgis.py

@@ -467,16 +467,6 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     metadata : list or dict
         file metadata, ``None`` for basic
 
-    Note
-    ----
-    The PVGIS website uses 10 years of data to generate the TMY, whereas the
-    API accessed by this function defaults to using all available years. This
-    means that the TMY returned by this function may not be identical to the
-    one generated by the website. To replicate the website requests, specify
-    the corresponding 10 year period using ``startyear`` and ``endyear``.
-    Specifying ``endyear`` also avoids the TMY changing when new data becomes
-    available.
-
     Raises
     ------
     requests.HTTPError
@@ -569,9 +559,17 @@ def _parse_pvgis_tmy_csv(src):
     inputs['longitude'] = float(src.readline().split(b':')[1])
     # Elevation (m): 1389.0\r\n
     inputs['elevation'] = float(src.readline().split(b':')[1])
+
+    # TMY has an extra line here: Irradiance Time Offset (h): 0.1761\r\n
+    line = src.readline()
+    if line.startswith(b'Irradiance Time Offset'):
+        inputs['irradiance time offset'] = float(line.split(b':')[1])
+        src.readline()  # skip over the "month,year\r\n"
+    else:
+        # `line` is already the "month,year\r\n" line, so nothing to do
+        pass
     # then there's a 13 row comma separated table with two columns: month, year
-    # which contains the year used for that month in the
-    src.readline()  # get "month,year\r\n"
+    # which contains the year used for that month in the TMY
     months_selected = []
     for month in range(12):
         months_selected.append(

pvlib/iotools/tmy.py

@@ -3,8 +3,6 @@
 import datetime
 import re
 import pandas as pd
-import warnings
-from pvlib._deprecation import pvlibDeprecationWarning
 
 # Dictionary mapping TMY3 names to pvlib names
 VARIABLE_MAP = {
@@ -24,8 +22,7 @@ VARIABLE_MAP = {
 }
 
 
-def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None,
-              encoding=None):
+def read_tmy3(filename, coerce_year=None, map_variables=True, encoding=None):
     """Read a TMY3 file into a pandas dataframe.
 
     Note that values contained in the metadata dictionary are unchanged
@@ -44,13 +41,9 @@ def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None,
         If supplied, the year of the index will be set to ``coerce_year``, except
         for the last index value which will be set to the *next* year so that
         the index increases monotonically.
-    map_variables : bool, optional
+    map_variables : bool, default True
         When True, renames columns of the DataFrame to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
-    recolumn : bool (deprecated, use map_variables instead)
-        If ``True``, apply standard names to TMY3 columns. Typically this
-        results in stripping the units from the column name.
-        Cannot be used in combination with ``map_variables``.
     encoding : str, optional
         Encoding of the file. For files that contain non-UTF8 characters it may
         be necessary to specify an alternative encoding, e.g., for
@@ -233,74 +226,15 @@ def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None,
     # unit must be in (D,h,m,s,ms,us,ns), but pandas>=0.24 allows unit='hour'
     data.index = data_ymd + pd.to_timedelta(shifted_hour, unit='h') \
         + pd.to_timedelta(minutes, unit='min')
-    # shouldnt' specify both recolumn and map_variables
-    if recolumn is not None and map_variables is not None:
-        msg = "`map_variables` and `recolumn` cannot both be specified"
-        raise ValueError(msg)
-    elif map_variables is None and recolumn is not None:
-        warnings.warn(
-            'The recolumn parameter is deprecated and will be removed in '
-            'pvlib 0.11.0. Use `map_variables` instead, although note that '
-            'its behavior is different from `recolumn`.',
-            pvlibDeprecationWarning)
-    elif map_variables is None and recolumn is None:
-        warnings.warn(
-            'TMY3 variable names will be renamed to pvlib conventions by '
-            'default starting in pvlib 0.11.0. Specify map_variables=True '
-            'to enable that behavior now, or specify map_variables=False '
-            'to hide this warning.', pvlibDeprecationWarning)
+
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
-    elif recolumn or (recolumn is None and map_variables is None):
-        data = _recolumn(data)
 
     data = data.tz_localize(int(meta['TZ'] * 3600))
 
     return data, meta
 
 
-def _recolumn(tmy3_dataframe):
-    """
-    Rename the columns of the TMY3 DataFrame.
-
-    Parameters
-    ----------
-    tmy3_dataframe : DataFrame
-    inplace : bool
-        passed to DataFrame.rename()
-
-    Returns
-    -------
-    Recolumned DataFrame.
-    """
-    # paste in the header as one long line
-    raw_columns = 'ETR (W/m^2),ETRN (W/m^2),GHI (W/m^2),GHI source,GHI uncert (%),DNI (W/m^2),DNI source,DNI uncert (%),DHI (W/m^2),DHI source,DHI uncert (%),GH illum (lx),GH illum source,Global illum uncert (%),DN illum (lx),DN illum source,DN illum uncert (%),DH illum (lx),DH illum source,DH illum uncert (%),Zenith lum (cd/m^2),Zenith lum source,Zenith lum uncert (%),TotCld (tenths),TotCld source,TotCld uncert (code),OpqCld (tenths),OpqCld source,OpqCld uncert (code),Dry-bulb (C),Dry-bulb source,Dry-bulb uncert (code),Dew-point (C),Dew-point source,Dew-point uncert (code),RHum (%),RHum source,RHum uncert (code),Pressure (mbar),Pressure source,Pressure uncert (code),Wdir (degrees),Wdir source,Wdir uncert (code),Wspd (m/s),Wspd source,Wspd uncert (code),Hvis (m),Hvis source,Hvis uncert (code),CeilHgt (m),CeilHgt source,CeilHgt uncert (code),Pwat (cm),Pwat source,Pwat uncert (code),AOD (unitless),AOD source,AOD uncert (code),Alb (unitless),Alb source,Alb uncert (code),Lprecip depth (mm),Lprecip quantity (hr),Lprecip source,Lprecip uncert (code),PresWth (METAR code),PresWth source,PresWth uncert (code)'  # noqa: E501
-
-    new_columns = [
-        'ETR', 'ETRN', 'GHI', 'GHISource', 'GHIUncertainty',
-        'DNI', 'DNISource', 'DNIUncertainty', 'DHI', 'DHISource',
-        'DHIUncertainty', 'GHillum', 'GHillumSource', 'GHillumUncertainty',
-        'DNillum', 'DNillumSource', 'DNillumUncertainty', 'DHillum',
-        'DHillumSource', 'DHillumUncertainty', 'Zenithlum',
-        'ZenithlumSource', 'ZenithlumUncertainty', 'TotCld', 'TotCldSource',
-        'TotCldUncertainty', 'OpqCld', 'OpqCldSource', 'OpqCldUncertainty',
-        'DryBulb', 'DryBulbSource', 'DryBulbUncertainty', 'DewPoint',
-        'DewPointSource', 'DewPointUncertainty', 'RHum', 'RHumSource',
-        'RHumUncertainty', 'Pressure', 'PressureSource',
-        'PressureUncertainty', 'Wdir', 'WdirSource', 'WdirUncertainty',
-        'Wspd', 'WspdSource', 'WspdUncertainty', 'Hvis', 'HvisSource',
-        'HvisUncertainty', 'CeilHgt', 'CeilHgtSource', 'CeilHgtUncertainty',
-        'Pwat', 'PwatSource', 'PwatUncertainty', 'AOD', 'AODSource',
-        'AODUncertainty', 'Alb', 'AlbSource', 'AlbUncertainty',
-        'Lprecipdepth', 'Lprecipquantity', 'LprecipSource',
-        'LprecipUncertainty', 'PresWth', 'PresWthSource',
-        'PresWthUncertainty']
-
-    mapping = dict(zip(raw_columns.split(','), new_columns))
-
-    return tmy3_dataframe.rename(columns=mapping)
-
-
 def read_tmy2(filename):
     """
     Read a TMY2 file into a DataFrame.