Repository navigation
argument "phase" in specific_humidity_from_dewpoint #3950
Description
What went wrong?
Hi, thanks you so much for implementing the keyword argument "phase" in functions involving relative humidity - we are finding this super useful!
The function specific_humidity_from_dewpoint also has phase as a keyword argument (which I guess effectively turns it into specific humidity from frostpoint when phase=solid?). I find it confusing that dewpoint_from_specific_humidity does not have the argument phase, i.e. the functions specific_humidity_from_dewpoint and dewpoint_from_specific_humidity are not inverses of eachother.
My suggestion would be to remove the keyword "phase" from specific_humidity_from_dewpoint.
Operating System
Linux
Version
1.7
Python Version
3.10.16
Code to Reproduce
temperature = -10 * metpy.units.units.degC
pressure = 500 * metpy.units.units.hPa
specific_humidity = 1.5E-3
dewpoint_from_sh = metpy.calc.dewpoint_from_specific_humidity(
pressure, temperature, specific_humidity
) # no kwarg phase
sh = metpy.calc.specific_humidity_from_dewpoint(
pressure, dewpoint_from_sh, phase='solid'
)
# sh and specific_humidity are not the same
Activity
dcamron commentedon Dec 2, 2025
Hi, thanks for the issue! I understand the confusion, though this is not a bug. Check out #3726 and related issues/PRs for scattered details. Here's the
shortversion:dewpointandsaturation_vapor_pressurewere the inverse of each other, based on Bolton 1980. This is a simplified empirical fit of the Clausius-Clapeyron relationship for equilibrium of water vapor and liquid water based on past experiments and measurements. This loses validity and accuracy near and outside warm, Earth-atmospheric conditions.We updated Saturation Vapor Pressure to a newer calculation, based on Ambaum 2020. Using some clever assumptions, they justified the value in using a physically-based direct calculation for saturation vapor pressure. We made this update to be internally consistent with #3728, a fast, direct LCL calculation based on the same assumptions. By tweaking these assumptions, we can make our formulation valid across phases and equilibrium regimes, eg calculating the saturation pressure of water vapor over ice below 0 degrees C. Neat! This is also required for that new LCL calculation. Romps 2021a is a great overview of this change.
MetPy's functions to calculate dewpoint still depend on that Bolton 1980 formulation, and so (a) does not round-trip with the new saturation vapor pressure formula and (b) does not support wide temperature ranges and multiple phase regimes. However, we can (and will!) update these functions to use these new assumptions, as seen in Romps 2021b. We just haven't gotten there yet, because it's going to break our tests and we haven't prioritized the work. Updating dewpoint was not required to get this fast LCL implemented.
When we make that update, these two will have the same interface and be able to round-trip. We aren't planning on removing any of this functionality for our users in the mean time.
How can we remove some of the confusion? We've considered creating some tutorials to overview these changes and the new LCL functionality, or adding examples to the MetPy Cookbook. Or would a bit of extra function documentation help? Let us know what you think.
kwilliams-mo commentedon Dec 8, 2025
Thanks for this explanation! The update that you're planning sounds like it'll completely remove this confusion for me. In the meantime, might be worth considering a note in the reference guide entries for these functions but that's just the icing on the cake :) (and I would find the tutorials you're suggesting very interesting too)
dopplershift commentedon Dec 16, 2025
Closing this and tracking the updates for dewpoint in #3976.