pvlib 0.11.0a1__py3-none-any.whl → 0.11.2__py3-none-any.whl

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

@@ -1,6 +1,7 @@
 """
 The ``atmosphere`` module contains methods to calculate relative and
-absolute airmass and to determine pressure from altitude or vice versa.
+absolute airmass, determine pressure from altitude or vice versa, and wind
+speed at different heights.
 """
 
 import numpy as np
@@ -336,6 +337,85 @@ def gueymard94_pw(temp_air, relative_humidity):
     return pw
 
 
+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
+
+
 first_solar_spectral_correction = deprecated(
     since='0.10.0',
     alternative='pvlib.spectrum.spectral_factor_firstsolar'
@@ -533,3 +613,158 @@ def angstrom_alpha(aod1, lambda1, aod2, lambda2):
     pvlib.atmosphere.angstrom_aod_at_lambda
     """
     return - np.log(aod1 / aod2) / np.log(lambda1 / lambda2)
+
+
+# Values of the Hellmann exponent
+HELLMANN_SURFACE_EXPONENTS = {
+    'unstable_air_above_open_water_surface': 0.06,
+    'neutral_air_above_open_water_surface': 0.10,
+    'stable_air_above_open_water_surface': 0.27,
+    'unstable_air_above_flat_open_coast': 0.11,
+    'neutral_air_above_flat_open_coast': 0.16,
+    'stable_air_above_flat_open_coast': 0.40,
+    'unstable_air_above_human_inhabited_areas': 0.27,
+    'neutral_air_above_human_inhabited_areas': 0.34,
+    'stable_air_above_human_inhabited_areas': 0.60,
+}
+
+
+def windspeed_powerlaw(wind_speed_reference, height_reference,
+                       height_desired, exponent=None,
+                       surface_type=None):
+    r"""
+    Estimate wind speed for different heights.
+
+    The model is based on the power law equation by Hellmann [1]_ [2]_.
+
+    Parameters
+    ----------
+    wind_speed_reference : numeric
+        Measured wind speed. [m/s]
+
+    height_reference : float
+        The height above ground at which the wind speed is measured. [m]
+
+    height_desired : float
+        The height above ground at which the wind speed will be estimated. [m]
+
+    exponent : float, optional
+        Exponent based on the surface type. [unitless]
+
+    surface_type : string, optional
+        If supplied, overrides ``exponent``. Can be one of the following
+        (see [1]_):
+
+        * ``'unstable_air_above_open_water_surface'``
+        * ``'neutral_air_above_open_water_surface'``
+        * ``'stable_air_above_open_water_surface'``
+        * ``'unstable_air_above_flat_open_coast'``
+        * ``'neutral_air_above_flat_open_coast'``
+        * ``'stable_air_above_flat_open_coast'``
+        * ``'unstable_air_above_human_inhabited_areas'``
+        * ``'neutral_air_above_human_inhabited_areas'``
+        * ``'stable_air_above_human_inhabited_areas'``
+
+    Returns
+    -------
+    wind_speed : numeric
+        Adjusted wind speed for the desired height. [m/s]
+
+    Raises
+    ------
+    ValueError
+        If neither of ``exponent`` nor a ``surface_type`` is given.
+        If both ``exponent`` and a ``surface_type`` is given. These parameters
+        are mutually exclusive.
+
+    KeyError
+        If the specified ``surface_type`` is invalid.
+
+    Notes
+    -----
+    Module temperature functions often require wind speeds at a height of 10 m
+    and not the wind speed at the module height.
+
+    For example, the following temperature functions require the input wind
+    speed to be 10 m: :py:func:`~pvlib.temperature.sapm_cell`, and
+    :py:func:`~pvlib.temperature.sapm_module` whereas the
+    :py:func:`~pvlib.temperature.fuentes` model requires wind speed at 9.144 m.
+
+    Additionally, the heat loss coefficients of some models have been developed
+    for wind speed measurements at 10 m (e.g.,
+    :py:func:`~pvlib.temperature.pvsyst_cell`,
+    :py:func:`~pvlib.temperature.faiman`, and
+    :py:func:`~pvlib.temperature.faiman_rad`).
+
+    The equation for calculating the wind speed at a height of :math:`h` is
+    given by the following power law equation [1]_ [2]_:
+
+    .. math::
+       :label: wind speed
+
+        WS_{h} = WS_{ref} \cdot \left( \frac{h}{h_{ref}} \right)^a
+
+    where :math:`h` [m] is the height at which we would like to calculate the
+    wind speed, :math:`h_{ref}` [m] is the reference height at which the wind
+    speed is known, and :math:`WS_{h}` [m/s] and :math:`WS_{ref}`
+    [m/s] are the corresponding wind speeds at these heights. The exponent
+    :math:`a` [unitless] depends on the surface type. Some values found in the
+    literature [1]_ for :math:`a` are:
+
+    .. table:: Values for the Hellmann-exponent
+
+       +-----------+--------------------+------------------+------------------+
+       | Stability | Open water surface | Flat, open coast | Cities, villages |
+       +===========+====================+==================+==================+
+       | Unstable  | 0.06               | 0.10             | 0.27             |
+       +-----------+--------------------+------------------+------------------+
+       | Neutral   | 0.11               | 0.16             | 0.40             |
+       +-----------+--------------------+------------------+------------------+
+       | Stable    | 0.27               | 0.34             | 0.60             |
+       +-----------+--------------------+------------------+------------------+
+
+    In a report by Sandia [3]_, the equation was experimentally tested for a
+    height of 30 ft (:math:`h_{ref} = 9.144` [m]) at their test site in
+    Albuquerque for a period of six weeks where a coefficient of
+    :math:`a = 0.219` was calculated.
+
+    It should be noted that the equation returns a value of NaN if the
+    reference heights or wind speed are negative.
+
+    References
+    ----------
+    .. [1] Kaltschmitt M., Streicher W., Wiese A. (2007). "Renewable Energy:
+       Technology, Economics and Environment." Springer,
+       :doi:`10.1007/3-540-70949-5`.
+
+    .. [2] Hellmann G. (1915). "Über die Bewegung der Luft in den untersten
+       Schichten der Atmosphäre." Meteorologische Zeitschrift, 32
+
+    .. [3] Menicucci D.F., Hall I.J. (1985). "Estimating wind speed as a
+       function of height above ground: An analysis of data obtained at the
+       southwest residential experiment station, Las Cruses, New Mexico."
+       SAND84-2530, Sandia National Laboratories.
+       Accessed at:
+       https://web.archive.org/web/20230418202422/https://www2.jpl.nasa.gov/adv_tech/photovol/2016CTR/SNL%20-%20Est%20Wind%20Speed%20vs%20Height_1985.pdf
+    """  # noqa:E501
+    if surface_type is not None and exponent is None:
+        # use the Hellmann exponent from dictionary
+        exponent = HELLMANN_SURFACE_EXPONENTS[surface_type]
+    elif surface_type is None and exponent is not None:
+        # use the provided exponent
+        pass
+    else:
+        raise ValueError(
+            "Either a 'surface_type' or an 'exponent' parameter must be given")
+
+    wind_speed = wind_speed_reference * (
+        (height_desired / height_reference) ** exponent)
+
+    # if wind speed is negative or complex return NaN
+    wind_speed = np.where(np.iscomplex(wind_speed) | (wind_speed < 0),
+                          np.nan, wind_speed)
+
+    if isinstance(wind_speed_reference, pd.Series):
+        wind_speed = pd.Series(wind_speed, index=wind_speed_reference.index)
+
+    return wind_speed

pvlib/bifacial/__init__.py

@@ -1,10 +1,10 @@
 """
-The ``bifacial`` module contains functions to model irradiance for bifacial
-modules.
-
+The ``bifacial`` submodule contains functions to model bifacial modules.
 """
+
 from pvlib._deprecation import deprecated
-from pvlib.bifacial import pvfactors, infinite_sheds, utils   # noqa: F401
+from pvlib.bifacial import pvfactors, infinite_sheds, utils  # noqa: F401
+from .loss_models import power_mismatch_deline  # noqa: F401
 
 pvfactors_timeseries = deprecated(
     since='0.9.1',

pvlib/bifacial/loss_models.py

@@ -0,0 +1,163 @@
+import numpy as np
+import pandas as pd
+
+
+def power_mismatch_deline(
+    rmad,
+    coefficients=(0, 0.142, 0.032 * 100),
+    fill_factor: float = None,
+    fill_factor_reference: float = 0.79,
+):
+    r"""
+    Estimate DC power loss due to irradiance non-uniformity.
+
+    This model is described for bifacial modules in [1]_, where the backside
+    irradiance is less uniform due to mounting and site conditions.
+
+    The power loss is estimated by a polynomial model of the Relative Mean
+    Absolute Difference (RMAD) of the cell-by-cell total irradiance.
+
+    Use ``fill_factor`` to account for different fill factors between the
+    data used to fit the model and the module of interest. Specify the model's fill factor with
+    ``fill_factor_reference``.
+
+    .. versionadded:: 0.11.1
+
+    Parameters
+    ----------
+    rmad : numeric
+        The Relative Mean Absolute Difference of the cell-by-cell total
+        irradiance. [Unitless]
+
+        See the *Notes* section for the equation to calculate ``rmad`` from the
+        bifaciality and the front and back irradiances.
+
+    coefficients : float collection or numpy.polynomial.polynomial.Polynomial, default ``(0, 0.142, 0.032 * 100)``
+        The polynomial coefficients to use.
+
+        If a :external:class:`numpy.polynomial.polynomial.Polynomial`,
+        it is evaluated as is. If not a ``Polynomial``, it must be the
+        coefficients of a polynomial in ``rmad``, where the first element is
+        the constant term and the last element is the highest order term. A
+        :external:class:`~numpy.polynomial.polynomial.Polynomial`
+        will be created internally.
+
+    fill_factor : float, optional
+        Fill factor at standard test condition (STC) of the module.
+        Accounts for different fill factors between the trained model and the
+        module under non-uniform irradiance.
+        If not provided, the default ``fill_factor_reference`` of 0.79 is used.
+
+    fill_factor_reference : float, default 0.79
+        Fill factor at STC of the module used to train the model.
+
+    Returns
+    -------
+    loss : numeric
+        The fractional power loss. [Unitless]
+
+        Output will be a ``pandas.Series`` if ``rmad`` is a ``pandas.Series``.
+
+    Notes
+    -----
+    The default model implemented is equation (11) [1]_:
+
+    .. math::
+
+       M[\%] &= 0.142 \Delta[\%] + 0.032 \Delta^2[\%] \qquad \text{(11)}
+
+       M[-] &= 0.142 \Delta[-] + 0.032 \times 100 \Delta^2[-]
+
+    where the upper equation is in percentage (same as paper) and the lower
+    one is unitless. The implementation uses the unitless version, where
+    :math:`M[-]` is the mismatch power loss [unitless] and
+    :math:`\Delta[-]` is the Relative Mean Absolute Difference (RMAD) [unitless]
+    of the global irradiance, Eq. (4) of [1]_ and [2]_.
+    Note that the n-th power coefficient is multiplied by :math:`100^{n-1}`
+    to convert the percentage to unitless.
+
+    The losses definition is Eq. (1) of [1]_, and it's defined as a loss of the
+    output power:
+
+    .. math::
+
+       M = 1 - \frac{P_{Array}}{\sum P_{Cells}} \qquad \text{(1)}
+
+    To account for a module with a fill factor distinct from the one used to
+    train the model (``0.79`` by default), the output of the model can be
+    modified with Eq. (7):
+
+    .. math::
+
+       M_{FF_1} = M_{FF_0} \frac{FF_1}{FF_0} \qquad \text{(7)}
+
+    where parameter ``fill_factor`` is :math:`FF_1` and
+    ``fill_factor_reference`` is :math:`FF_0`.
+
+    In the section *See Also*, you will find two packages that can be used to
+    calculate the irradiance at different points of the module.
+
+    .. note::
+       The global irradiance RMAD is different from the backside irradiance
+       RMAD.
+
+    RMAD of a variable :math:`G_{total}` is defined as:
+
+    .. math::
+
+        RMAD \left[ unitless \right] = \Delta \left[ unitless \right] =
+        \frac{1}{n^2 \bar{G}_{total}} \sum_{i=1}^{n} \sum_{j=1}^{n}
+        \lvert G_{total,i} - G_{total,j} \rvert
+
+    In case the RMAD of the backside irradiance is known, the global RMAD can
+    be calculated as follows, assuming the front irradiance RMAD is
+    negligible [2]_:
+
+    .. math::
+
+       RMAD(k \cdot X + c) = RMAD(X) \cdot k \frac{k \bar{X}}{k \bar{X} + c}
+       = RMAD(X) \cdot \frac{k}{1 + \frac{c}{k \bar{X}}}
+
+    by similarity with equation (2) of [1]_:
+
+    .. math::
+
+       G_{total\,i} = G_{front\,i} + \phi_{Bifi} G_{rear\,i} \qquad \text{(2)}
+
+    which yields:
+
+    .. math::
+
+       RMAD_{total} = RMAD_{rear} \frac{\phi_{Bifi}}
+       {1 + \frac{G_{front}}{\phi_{Bifi} \bar{G}_{rear}}}
+
+    See Also
+    --------
+    `solarfactors <https://github.com/pvlib/solarfactors/>`_
+        Calculate the irradiance at different points of the module.
+    `bifacial_radiance <https://github.com/NREL/bifacial_radiance>`_
+        Calculate the irradiance at different points of the module.
+
+    References
+    ----------
+    .. [1] C. Deline, S. Ayala Pelaez, S. MacAlpine, and C. Olalla, 'Estimating
+       and parameterizing mismatch power loss in bifacial photovoltaic
+       systems', Progress in Photovoltaics: Research and Applications, vol. 28,
+       no. 7, pp. 691-703, 2020, :doi:`10.1002/pip.3259`.
+    .. [2] “Mean absolute difference,” Wikipedia, Sep. 05, 2023.
+       https://en.wikipedia.org/wiki/Mean_absolute_difference#Relative_mean_absolute_difference
+       (accessed 2024-04-14).
+    """  # noqa: E501
+    if isinstance(coefficients, np.polynomial.Polynomial):
+        model_polynom = coefficients
+    else:  # expect an iterable
+        model_polynom = np.polynomial.Polynomial(coef=coefficients)
+
+    if fill_factor:  # Eq. (7), [1]
+        # Scale output of trained model to account for different fill factors
+        model_polynom = model_polynom * fill_factor / fill_factor_reference
+
+    mismatch = model_polynom(rmad)
+    if isinstance(rmad, pd.Series):
+        mismatch = pd.Series(mismatch, index=rmad.index)
+    return mismatch