Function to estimate wind speed at different heights

docs/sphinx/source/reference/airmass_atmospheric.rst

@@ -17,3 +17,4 @@ Airmass and atmospheric models
  atmosphere.kasten96_lt
  atmosphere.angstrom_aod_at_lambda
  atmosphere.angstrom_alpha
+ atmosphere.windspeed_hellmann

docs/sphinx/source/whatsnew/v0.11.1.rst

@@ -17,6 +17,9 @@ Enhancements
  :py:func:`pvlib.spectrum.spectral_factor_firstsolar`.
  (:issue:`2086`, :pull:`2100`)
 
+* Added function for calculating wind speed at different heights,
+ :py:func:`pvlib.atmosphere.windspeed_hellmann`.
+ (:issue:`2118`, :pull:`2124`)
 
 Bug fixes
 ~~~~~~~~~
@@ -45,4 +48,3 @@ Contributors
 * Leonardo Micheli (:ghuser:`lmicheli`)
 * Echedey Luis (:ghuser:`echedey-ls`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
-

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,165 @@
  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_hellmann(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 at which the wind speed is measured. [m]
+
+ height_desired : float
+ The height at which the wind speed will be estimated. [m]
+
+ exponent : float, optional
+ Exponent based on the surface type. [-]
+
+ 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
+ -----
+ 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
+
+ U_{w,h} = U_{w,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:`U_{w,h}` [m/s] and :math:`U_{w,ref}`
+ [m/s] are the corresponding wind speeds at these heights. :math:`a` is a
+ value that depends on the surface type. Some values found in the literature
+ [1]_ for :math:`a` are the following:
+
+ .. 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]_, this equation was experimentally tested for a
+ height of 30 ft (9.144 m) and the following coefficients were recommended:
+ :math:`h_{ref} = 9.144` [m], :math:`a = 0.219` [-], and
+ :math:`windspeed_{href}` is the wind speed at a height of 9.144 [m].
+
+ It should be noted that the equation returns a value of NaN if the
+ calculated wind speed is negative or a complex number.
+
+ Warning
+ -------
+ 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`,
+ :py:func:`~pvlib.temperature.sapm_module`, and
+ :py:func:`~pvlib.temperature.generic_linear`, 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`).
+
+ 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 the provided height is negative the calculated wind speed is complex
+ # so a NaN value is returned
+ if isinstance(wind_speed, complex):
+ wind_speed = np.nan
+
+ # if wind speed is negative return NaN
+ wind_speed = np.where(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/tests/test_atmosphere.py

@@ -131,3 +131,74 @@ def test_bird_hulstrom80_aod_bb():
  aod380, aod500 = 0.22072480948195175, 0.1614279181106312
  bird_hulstrom = atmosphere.bird_hulstrom80_aod_bb(aod380, aod500)
  assert np.isclose(0.11738229553812768, bird_hulstrom)
+
+
+@pytest.fixture
+def windspeeds_data_hellman():
+ data = pd.DataFrame(
+ index=pd.date_range(start="2015-01-01 00:00", end="2015-01-01 05:00",
+ freq="1h"),
+ columns=["wind_ref", "height_ref", "height_desired", "wind_calc"],
+ data=[
+ (10, -2, 5, np.nan),
+ (-10, 2, 5, np.nan),
+ (5, 4, 5, 5.067393209486324),
+ (7, 6, 10, 7.2178684911195905),
+ (10, 8, 20, 10.565167835216586),
+ (12, 10, 30, 12.817653329393977)
+ ]
+ )
+ return data
+
+
+def test_windspeed_hellmann_ndarray(windspeeds_data_hellman):
+ # test wind speed estimation by passing in surface_type
+ result_surface = atmosphere.windspeed_hellmann(
+ windspeeds_data_hellman["wind_ref"].to_numpy(),
+ windspeeds_data_hellman["height_ref"],
+ windspeeds_data_hellman["height_desired"],
+ surface_type='unstable_air_above_open_water_surface')
+ assert_allclose(windspeeds_data_hellman["wind_calc"].to_numpy(),
+ result_surface)
+ # test wind speed estimation by passing in the exponent corresponding
+ # to the surface_type above
+ result_exponent = atmosphere.windspeed_hellmann(
+ windspeeds_data_hellman["wind_ref"].to_numpy(),
+ windspeeds_data_hellman["height_ref"],
+ windspeeds_data_hellman["height_desired"],
+ exponent=0.06)
+ assert_allclose(windspeeds_data_hellman["wind_calc"].to_numpy(),
+ result_exponent)
+
+
+def test_windspeed_hellmann_series(windspeeds_data_hellman):
+ result = atmosphere.windspeed_hellmann(
+ windspeeds_data_hellman["wind_ref"],
+ windspeeds_data_hellman["height_ref"],
+ windspeeds_data_hellman["height_desired"],
+ surface_type='unstable_air_above_open_water_surface')
+ assert_series_equal(windspeeds_data_hellman["wind_calc"],
+ result, check_names=False)
+
+
+def test_windspeed_hellmann_invalid():
+ with pytest.raises(ValueError, match="Either a 'surface_type' or an "
+ "'exponent' parameter must be given"):
+ # no exponent or surface_type given
+ atmosphere.windspeed_hellmann(wind_speed_reference=10,
+ height_reference=5,
+ height_desired=10)
+ with pytest.raises(ValueError, match="Either a 'surface_type' or an "
+ "'exponent' parameter must be given"):
+ # no exponent or surface_type given
+ atmosphere.windspeed_hellmann(wind_speed_reference=10,
+ height_reference=5,
+ height_desired=10,
+ exponent=1.2,
+ surface_type="surf")
+ with pytest.raises(KeyError, match='not_an_exponent'):
+ # invalid surface_type
+ atmosphere.windspeed_hellmann(wind_speed_reference=10,
+ height_reference=5,
+ height_desired=10,
+ surface_type='not_an_exponent')