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

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
@@ -533,3 +534,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

pvlib/clearsky.py

@@ -9,7 +9,6 @@ import calendar
 
 import numpy as np
 import pandas as pd
-from scipy.optimize import minimize_scalar
 from scipy.linalg import hankel
 import h5py
 
@@ -169,6 +168,13 @@ def lookup_linke_turbidity(time, latitude, longitude, filepath=None,
     Returns
     -------
     turbidity : Series
+
+    Notes
+    -----
+    Linke turbidity is obtained from a file of historical monthly averages.
+    The returned value for each time is either the monthly value or an
+    interpolated value to smooth the transition between months.
+    Interpolation is done on the day of year as determined by UTC.
     """
 
     # The .h5 file 'LinkeTurbidities.h5' contains a single 2160 x 4320 x 12
@@ -201,7 +207,7 @@ def lookup_linke_turbidity(time, latitude, longitude, filepath=None,
     if interp_turbidity:
         linke_turbidity = _interpolate_turbidity(lts, time)
     else:
-        months = time.month - 1
+        months = tools._pandas_to_utc(time).month - 1
         linke_turbidity = pd.Series(lts[months], index=time)
 
     linke_turbidity /= 20.
@@ -247,14 +253,11 @@ def _interpolate_turbidity(lts, time):
     # Jan 1 - Jan 15 and Dec 16 - Dec 31.
     lts_concat = np.concatenate([[lts[-1]], lts, [lts[0]]])
 
-    # handle leap years
-    try:
-        isleap = time.is_leap_year
-    except AttributeError:
-        year = time.year
-        isleap = _is_leap_year(year)
+    time_utc = tools._pandas_to_utc(time)
+
+    isleap = time_utc.is_leap_year
 
-    dayofyear = time.dayofyear
+    dayofyear = time_utc.dayofyear
     days_leap = _calendar_month_middles(2016)
     days_no_leap = _calendar_month_middles(2015)
 
@@ -874,25 +877,11 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         clear_meas = meas[clear_samples]
         clear_clear = clear[clear_samples]
 
-        def rmse(alpha):
-            return np.sqrt(np.mean((clear_meas - alpha*clear_clear)**2))
-
-        optimize_result = minimize_scalar(rmse)
-        if not optimize_result.success:
-            try:
-                message = "Optimizer exited unsuccessfully: " \
-                           + optimize_result.message
-            except AttributeError:
-                message = "Optimizer exited unsuccessfully: \
-                           No message explaining the failure was returned. \
-                           If you would like to see this message, please \
-                           update your scipy version (try version 1.8.0 \
-                           or beyond)."
-            raise RuntimeError(message)
-
-        else:
-            alpha = optimize_result.x
-
+        # Compute arg min of MSE between model and observations
+        C = (clear_clear**2).sum()
+        if not (pd.isna(C) or C == 0):  # safety check
+            # only update alpha if C is strictly positive
+            alpha = (clear_meas * clear_clear).sum() / C
         if round(alpha*10000) == round(previous_alpha*10000):
             break
     else:
@@ -941,7 +930,7 @@ def bird(zenith, airmass_relative, aod380, aod500, precipitable_water,
     zenith is never explicitly defined in the report, since the purpose
     was to compare existing clear sky models with "rigorous radiative
     transfer models" (RTM) it is possible that apparent zenith was
-    obtained as output from the RTM. However, the implentation presented
+    obtained as output from the RTM. However, the implementation presented
     in PVLIB is tested against the NREL Excel implementation by Daryl
     Myers which uses an analytical expression for solar zenith instead
     of apparent zenith.

pvlib/data/pvgis_tmy_meta.json

@@ -1,93 +1,32 @@
-{
-  "inputs": {
-    "location": {
-      "description": "Selected location",
-      "variables": {
-        "latitude": {
-          "description": "Latitude",
-          "units": "decimal degree"
-        },
-        "longitude": {
-          "description": "Longitude",
-          "units": "decimal degree"
-        },
-        "elevation": {
-          "description": "Elevation",
-          "units": "m"
-        }
-      }
-    },
-    "meteo_data": {
-      "description": "Sources of meteorological data",
-      "variables": {
-        "radiation_db": {
-          "description": "Solar radiation database"
-        },
-        "meteo_db": {
-          "description": "Database used for meteorological variables other than solar radiation"
-        },
-        "year_min": {
-          "description": "First year of the calculations"
-        },
-        "year_max": {
-          "description": "Last year of the calculations"
-        },
-        "use_horizon": {
-          "description": "Include horizon shadows"
-        },
-        "horizon_db": {
-          "description": "Source of horizon data"
-        }
-      }
-    }
-  },
-  "outputs": {
-    "months_selected": {
-      "type": "time series",
-      "timestamp": "monthly",
-      "description": "months selected for the TMY"
-    },
-    "tmy_hourly": {
-      "type": "time series",
-      "timestamp": "hourly",
-      "variables": {
-        "T2m": {
-          "description": "2-m air temperature",
-          "units": "degree Celsius"
-        },
-        "RH": {
-          "description": "relative humidity",
-          "units": "%"
-        },
-        "G(h)": {
-          "description": "Global irradiance on the horizontal plane",
-          "units": "W/m2"
-        },
-        "Gb(n)": {
-          "description": "Beam/direct irradiance on a plane always normal to sun rays",
-          "units": "W/m2"
-        },
-        "Gd(h)": {
-          "description": "Diffuse irradiance on the horizontal plane",
-          "units": "W/m2"
-        },
-        "IR(h)": {
-          "description": "Surface infrared (thermal) irradiance on a horizontal plane",
-          "units": "W/m2"
-        },
-        "WS10m": {
-          "description": "10-m total wind speed",
-          "units": "m/s"
-        },
-        "WD10m": {
-          "description": "10-m wind direction (0 = N, 90 = E)",
-          "units": "degree"
-        },
-        "SP": {
-          "description": "Surface (air) pressure",
-          "units": "Pa"
-        }
-      }
-    }
-  }
-}
+{"inputs": {"location": {"description": "Selected location",
+   "variables": {"latitude": {"description": "Latitude",
+     "units": "decimal degree"},
+    "longitude": {"description": "Longitude", "units": "decimal degree"},
+    "elevation": {"description": "Elevation", "units": "m"}}},
+  "meteo_data": {"description": "Sources of meteorological data",
+   "variables": {"radiation_db": {"description": "Solar radiation database"},
+    "meteo_db": {"description": "Database used for meteorological variables other than solar radiation"},
+    "year_min": {"description": "First year of the calculations"},
+    "year_max": {"description": "Last year of the calculations"},
+    "use_horizon": {"description": "Include horizon shadows"},
+    "horizon_db": {"description": "Source of horizon data"}}}},
+ "outputs": {"months_selected": {"type": "time series",
+   "timestamp": "monthly",
+   "description": "months selected for the TMY"},
+  "tmy_hourly": {"type": "time series",
+   "timestamp": "hourly",
+   "variables": {"T2m": {"description": "2-m air temperature",
+     "units": "degree Celsius"},
+    "RH": {"description": "relative humidity", "units": "%"},
+    "G(h)": {"description": "Global irradiance on the horizontal plane",
+     "units": "W/m2"},
+    "Gb(n)": {"description": "Beam/direct irradiance on a plane always normal to sun rays",
+     "units": "W/m2"},
+    "Gd(h)": {"description": "Diffuse irradiance on the horizontal plane",
+     "units": "W/m2"},
+    "IR(h)": {"description": "Surface infrared (thermal) irradiance on a horizontal plane",
+     "units": "W/m2"},
+    "WS10m": {"description": "10-m total wind speed", "units": "m/s"},
+    "WD10m": {"description": "10-m wind direction (0 = N, 90 = E)",
+     "units": "degree"},
+    "SP": {"description": "Surface (air) pressure", "units": "Pa"}}}}}