Calculate Relative Humidity via Magnus Tetens Equation

docs/sphinx/source/reference/airmass_atmospheric.rst

@@ -11,6 +11,8 @@ Airmass and atmospheric models
    atmosphere.get_relative_airmass
    atmosphere.pres2alt
    atmosphere.alt2pres
+   atmosphere.tdew_from_rh
+   atmosphere.rh_from_tdew
    atmosphere.gueymard94_pw
    atmosphere.first_solar_spectral_correction
    atmosphere.bird_hulstrom80_aod_bb

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

@@ -10,7 +10,8 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* :py:func: `~pvlib.atmosphere.rh_from_tdew` and `~pvlib.atmosphere.tdew_from_rh`
+  added. (:issue:`1744`, :pull:`2286`)
 
 Bug fixes
 ~~~~~~~~~

pvlib/atmosphere.py

@@ -337,6 +337,82 @@ def gueymard94_pw(temp_air, relative_humidity):
     return pw
 
 
+def rh_from_tdew(temperature, dewpoint, coeff=(6.112, 17.62, 243.12)):
+    """
+    Calculate relative humidity from dewpoint temperature using the Magnus equation.
+
+    Parameters
+    ----------
+    temperature : numeric
+        Air temperature (dry-bulb temperature) in degrees Celsius
+    dewpoint : numeric
+        Dewpoint temperature in degrees Celsius
+    coeff: tuple
+        Magnus equation coefficient (A, B, C)
+
+    Returns
+    -------
+    numeric
+        Relative humidity as percentage (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] * temperature) / (coeff[2] + temperature))
+    es = coeff[0] * np.exp((coeff[1] * dewpoint) / (coeff[2] + dewpoint))
+
+    # Calculate relative humidity as percentage
+    relative_humidity = 100 * (es / e)
+
+    return relative_humidity
+
+
+def tdew_from_rh(
+    temperature, relative_humidity, coeff=(6.112, 17.62, 243.12)
+):
+    """
+    Calculate dewpoint temperature using Magnus equation.
+    This is a reversal of the calculation in :py:func:`rh_from_tdew`.
+
+    Parameters
+    ----------
+    temperature : numeric
+        Air temperature (dry-bulb temperature) in degrees Celsius
+    relative_humidity : numeric
+        Relative humidity as percentage (0-100)
+
+    Returns
+    -------
+    numeric
+        Dewpoint temperature in degrees Celsius
+
+    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] * temperature) / (coeff[2] + temperature)
+        + 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'

pvlib/tests/test_atmosphere.py

@@ -88,6 +88,143 @@ def test_gueymard94_pw():
     assert_allclose(pws, expected, atol=0.01)
 
 
+# Unit tests
+def test_rh_from_tdew():
+
+    # dewpoint temp calculated with who and aekr coefficients
+    dewpoint = pd.Series([
+        15.0, 20.0, 25.0, 12.0, 8.0
+    ])
+
+    # relative humidity calculated with who and aekr coefficients
+    relative_humidity_who = pd.Series([
+        72.95185312581116, 73.81500029087906, 74.6401272083123,
+        82.27063889868842, 87.39018119185337
+    ])
+    relative_humidity_aekr = pd.Series([
+        72.93876680928582, 73.8025121880607, 74.62820502423823,
+        82.26135295757305, 87.38323744820416
+    ])
+
+    temperature_ambient = pd.Series([20.0, 25.0, 30.0, 15.0, 10.0])
+
+    # Calculate relative humidity using pandas series as input
+    rh_series = atmosphere.rh_from_tdew(
+        temperature=temperature_ambient,
+        dewpoint=dewpoint
+    )
+
+    # Calulate relative humidity using pandas series as input
+    # with AEKR coefficients
+    rh_series_aekr = atmosphere.rh_from_tdew(
+        temperature=temperature_ambient,
+        dewpoint=dewpoint,
+        coeff=(6.1094, 17.625, 243.04)
+    )
+
+    # Calculate relative humidity using array as input
+    rh_array = atmosphere.rh_from_tdew(
+        temperature=temperature_ambient.to_numpy(),
+        dewpoint=dewpoint.to_numpy()
+    )
+
+    # Calculate relative humidity using float as input
+    rh_float = atmosphere.rh_from_tdew(
+        temperature=temperature_ambient.iloc[0],
+        dewpoint=dewpoint.iloc[0]
+    )
+
+    # test
+    pd.testing.assert_series_equal(
+        rh_series,
+        relative_humidity_who,
+        check_names=False
+    )
+
+    pd.testing.assert_series_equal(
+        rh_series_aekr,
+        relative_humidity_aekr,
+        check_names=False
+    )
+
+    np.testing.assert_allclose(
+        rh_array,
+        relative_humidity_who.to_numpy(),
+        atol=0.001
+    )
+
+    assert np.isclose(
+        rh_float,
+        relative_humidity_who.iloc[0]
+    )
+
+
+# Unit tests
+def test_tdew_from_rh():
+
+    # dewpoint temp calculated with who and aekr coefficients
+    dewpoint = pd.Series([
+        15.0, 20.0, 25.0, 12.0, 8.0
+    ])
+
+    # relative humidity calculated with who and aekr coefficients
+    relative_humidity_who = pd.Series([
+        72.95185312581116, 73.81500029087906, 74.6401272083123,
+        82.27063889868842, 87.39018119185337
+    ])
+    relative_humidity_aekr = pd.Series([
+        72.93876680928582, 73.8025121880607, 74.62820502423823,
+        82.26135295757305, 87.38323744820416
+    ])
+
+    temperature_ambient = pd.Series([20.0, 25.0, 30.0, 15.0, 10.0])
+
+    # test as series
+    dewpoint_series = atmosphere.tdew_from_rh(
+        temperature=temperature_ambient,
+        relative_humidity=relative_humidity_who
+    )
+
+    # test as series with AEKR coefficients
+    dewpoint_series_aekr = atmosphere.tdew_from_rh(
+        temperature=temperature_ambient,
+        relative_humidity=relative_humidity_aekr,
+        coeff=(6.1094, 17.625, 243.04)
+    )
+
+    # test as numpy array
+    dewpoint_array = atmosphere.tdew_from_rh(
+        temperature=temperature_ambient.to_numpy(),
+        relative_humidity=relative_humidity_who.to_numpy()
+    )
+
+    # test as float
+    dewpoint_float = atmosphere.tdew_from_rh(
+        temperature=temperature_ambient.iloc[0],
+        relative_humidity=relative_humidity_who.iloc[0]
+    )
+
+    # test
+    pd.testing.assert_series_equal(
+        dewpoint_series, dewpoint, check_names=False
+    )
+
+    pd.testing.assert_series_equal(
+        dewpoint_series_aekr, dewpoint,
+        check_names=False
+    )
+
+    np.testing.assert_allclose(
+        dewpoint_array,
+        dewpoint.to_numpy(),
+    )
+
+    assert np.isclose(
+        dewpoint_float,
+        dewpoint.iloc[0]
+    )
+
+
 def test_first_solar_spectral_correction_deprecated():
     with pytest.warns(pvlibDeprecationWarning,
                       match='Use pvlib.spectrum.spectral_factor_firstsolar'):

pyproject.toml

@@ -56,7 +56,7 @@ optional = [
 ]
 doc = [
     'ipython',
-    'pickleshare',  # required by ipython
+    'pickleshare',                   # required by ipython
     'matplotlib',
     'sphinx == 7.3.7',
     'pydata-sphinx-theme == 0.15.4',