Calculate Relative Humidity via Magnus Tetens Equation

pvlib/atmosphere.py

@@ -337,6 +337,82 @@
     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/spectrum/magnus_tetens.py

@@ -0,0 +1,108 @@
+import numpy as np
+
+
+def magnus_tetens_aekr(temperature, dewpoint, A=6.112, B=17.62, C=243.12):
+    """
+    Calculate relative humidity using Magnus equation with AEKR coefficients.
+    This function was used by First Solar in creating their spectral model
+    and is therefore relevant to the first solar spectral model in pvlib.
+    Default magnus equation coefficients are from [2].
+
+    Parameters
+    ----------
+    temperature : pd.Series
+        Air temperature in degrees Celsius
+    dewpoint : pd.Series
+        Dewpoint temperature in degrees Celsius
+    A: float
+        Magnus equation coefficient A
+    B: float
+        Magnus equation coefficient B
+    C: float
+        Magnus equation coefficient C
+
+    Returns
+    -------
+    pd.Series
+        Relative humidity as percentage (0-100)
+
+    Notes
+    -----
+    Uses the AEKR coefficients which minimize errors between -40 and
+    50 degrees C according to reference [1].
+
+    References
+    ----------
+    .. [1] https://www.osti.gov/servlets/purl/548871-PjpxAP/webviewable/
+    .. [2] https://www.schweizerbart.de//papers/metz/detail/3/89544/Advancements_in_the_field_of_hygrometry?af=crossref
+    """
+
+    # Calculate vapor pressure (e) and saturation vapor pressure (es)
+    e = A * np.exp((B * temperature) / (C + temperature))
+    es = A * np.exp((B * dewpoint) / (C + dewpoint))
+
+    # Calculate relative humidity as percentage
+    relative_humidity = 100 * (es / e)
+
+    return relative_humidity
+
+
+def reverse_magnus_tetens_aekr(
+    temperature, relative_humidity, B=17.62, C=243.12
+):
+    """
+    Calculate dewpoint temperature using Magnus equation with
+    AEKR coefficients.  This is just a reversal of the calculation
+    in calculate_relative_humidity.
+
+    Parameters
+    ----------
+    temperature : pd.Series
+        Air temperature in degrees Celsius
+    relative_humidity : pd.Series
+        Relative humidity as percentage (0-100)
+
+    Returns
+    -------
+    pd.Series
+        Dewpoint temperature in degrees Celsius
+
+    Notes
+    -----
+    Derived by solving the Magnus equation for dewpoint given
+    relative humidity.
+    Valid for temperatures between -40 and 50 degrees C.
+
+    References
+    ----------
+    .. [1] https://www.osti.gov/servlets/purl/548871-PjpxAP/webviewable/
+    """
+    # 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 = (
+        (B * temperature) / (C + temperature)
+        + np.log(relative_humidity/100)
+    )
+
+    # Then solve for dewpoint
+    dewpoint = C * ln_term / (B - ln_term)
+
+    return dewpoint
+
+
+if __name__ == "__main__":
+    import pandas as pd
+    rh = magnus_tetens_aekr(
+        temperature=pd.Series([20.0, 25.0, 30.0, 15.0, 10.0]),
+        dewpoint=pd.Series([15.0, 20.0, 25.0, 12.0, 8.0])
+    )
+
+    dewpoint = reverse_magnus_tetens_aekr(
+        temperature=pd.Series([20.0, 25.0, 30.0, 15.0, 10.0]),
+        relative_humidity=rh
+    )
+    print(rh)
+    print(dewpoint)

pvlib/tests/conftest.py

@@ -474,3 +474,39 @@
                   'IXXO': 3.18803,
                   'FD': 1}
     return parameters
+
+
+@pytest.fixture(scope='function')
+def tdew_from_rh_tamb():
+    temperature = pd.Series([20.0, 25.0, 30.0, 15.0, 10.0])
+    return temperature
+
+
+@pytest.fixture(scope='function')
+def tdew_from_rh_tdew():
+    dewpoint = pd.Series([15.0, 20.0, 25.0, 12.0, 8.0])
+    return dewpoint
+
+@pytest.fixture(scope='function')
+def tdew_from_rh_tdew_aekr():
+    dewpoint = pd.Series([
+        15.002788636614607, 20.00273293813965, 25.002679259728964,
+        12.001714029144065, 8.0011690397714
+    ])
+    return dewpoint
+
+@pytest.fixture(scope='function')
+def tdew_from_rh_rh():
+    relative_humidity = pd.Series([
+        72.95185312581116, 73.81500029087906, 74.6401272083123,
+        82.27063889868842, 87.39018119185337
+    ])
+    return relative_humidity
+
+@pytest.fixture(scope='function')
+def tdew_from_rh_rh_aekr():
+   relative_humidity = pd.Series([
+       72.93876680928582, 73.8025121880607, 74.62820502423823,
+        82.26135295757305, 87.38323744820416
+   ])
+   return relative_humidity

pvlib/tests/test_atmosphere.py

@@ -33,7 +33,7 @@
                          [['simple', [nan, 572.958,   5.759,   1.000]],
                           ['kasten1966', [nan, 35.365,  5.580,  0.999]],
                           ['youngirvine1967', [
-                                 nan, -2.251358367165932e+05, 5.5365, 1.0000]],
+                            nan, -2.251358367165932e+05, 5.5365, 1.0000]],
                           ['kastenyoung1989', [nan, 36.467,  5.586,  1.000]],
                           ['gueymard1993', [nan, 36.431,  5.581,  1.000]],
                           ['young1994', [nan, 30.733,  5.541,  1.000]],
@@ -88,6 +88,118 @@
     assert_allclose(pws, expected, atol=0.01)
 
 
+# Unit tests
+def test_rh_from_tdew(
+    tdew_from_rh_tamb, tdew_from_rh_tdew,
+    tdew_from_rh_tdew_aekr, tdew_from_rh_rh,
+    tdew_from_rh_rh_aekr
+):
+
+    # Calculate relative humidity using pandas series as input
+    rh_series = atmosphere.rh_from_tdew(
+        temperature=tdew_from_rh_tamb,
+        dewpoint=tdew_from_rh_tdew
+    )
+
+    # Calulate relative humidity using pandas series as input
+    # with AEKR coefficients
+    rh_series_aekr = atmosphere.rh_from_tdew(
+        temperature=tdew_from_rh_tamb,
+        dewpoint=tdew_from_rh_tdew,
+        coeff=(6.1094, 17.625, 243.04)
+    )
+
+    # Calculate relative humidity using array as input
+    rh_array = atmosphere.rh_from_tdew(
+        temperature=tdew_from_rh_tamb.to_numpy(),
+        dewpoint=tdew_from_rh_tdew.to_numpy()
+    )
+
+    # Calculate relative humidity using float as input
+    rh_float = atmosphere.rh_from_tdew(
+        temperature=tdew_from_rh_tamb.iloc[0],
+        dewpoint=tdew_from_rh_tdew.iloc[0]
+    )
+
+    # test
+    pd.testing.assert_series_equal(
+        rh_series,
+        tdew_from_rh_rh,
+        check_names=False
+    )
+
+    pd.testing.assert_series_equal(
+        rh_series_aekr,
+        tdew_from_rh_rh_aekr,
+        check_names=False
+    )
+
+    np.testing.assert_allclose(
+        rh_array,
+        tdew_from_rh_rh.to_numpy(),
+        atol=0.001
+    )
+
+    assert np.isclose(
+        rh_float,
+        tdew_from_rh_rh.iloc[0]
+    )
+
+
+# Unit tests
+def test_tdew_from_rh(
+    tdew_from_rh_tamb, tdew_from_rh_tdew,
+    tdew_from_rh_rh, tdew_from_rh_rh_aekr,
+    tdew_from_rh_tdew_aekr
+):
+
+    # test as series
+    dewpoint_series = atmosphere.tdew_from_rh(
+        temperature=tdew_from_rh_tamb,
+        relative_humidity=tdew_from_rh_rh
+    )
+
+    # test as series with AEKR coefficients
+    dewpoint_series_aekr = atmosphere.tdew_from_rh(
+        temperature=tdew_from_rh_tamb,
+        relative_humidity=tdew_from_rh_rh,
+        coeff=(6.1094, 17.625, 243.04)
+    )
+
+    # test as numpy array
+    dewpoint_array = atmosphere.tdew_from_rh(
+        temperature=tdew_from_rh_tamb.to_numpy(),
+        relative_humidity=tdew_from_rh_rh.to_numpy()
+    )
+
+    # test as float
+    dewpoint_float = atmosphere.tdew_from_rh(
+        temperature=tdew_from_rh_tamb.iloc[0],
+        relative_humidity=tdew_from_rh_rh.iloc[0]
+    )
+
+    # test
+    pd.testing.assert_series_equal(
+        dewpoint_series, tdew_from_rh_tdew, check_names=False
+    )
+
+    pd.testing.assert_series_equal(
+        dewpoint_series_aekr, tdew_from_rh_tdew_aekr,
+        check_names=False
+    )
+
+    np.testing.assert_allclose(
+        dewpoint_array,
+        tdew_from_rh_tdew.to_numpy(),
+        atol=0.001
+    )
+
+    assert np.isclose(
+        dewpoint_float,
+        tdew_from_rh_tdew.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',