Skip to content

Conversation

@xtian15
Copy link

@xtian15 xtian15 commented Dec 26, 2025

Summary

Adds a method parameter to dewpoint() allowing users to choose between:

  • 'bolton' (default): Original analytical formula - preserves backward compatibility
  • 'ambaum': Numerical inversion of Ambaum (2020), consistent with saturation_vapor_pressure()

Problem

As reported in #3976, saturation_vapor_pressure() uses Ambaum (2020) but dewpoint() inverts Bolton (1980). This causes round-trip inconsistency:

dewpoint(saturation_vapor_pressure(T)) != T  # ~0.01-0.1°C error

Solution

Add optional method='ambaum' that numerically inverts the Ambaum formula:

# Default - unchanged behavior
dewpoint(22 * units.hPa)  # → 19.029°C (Bolton)

# New option - thermodynamically consistent
dewpoint(22 * units.hPa, method='ambaum')  # → 19.043°C

# Perfect round-trip with ambaum method
dewpoint(saturation_vapor_pressure(T), method='ambaum') == T  # < 1e-12°C error

Changes

  • dewpoint(): Add method parameter with 'bolton' (default) and 'ambaum' options
  • _dewpoint_ambaum(): New helper function using scipy.optimize.brentq
  • Tests: Add test_dewpoint_ambaum_roundtrip() verifying consistency
  • Docstring: Document both methods with examples

Benefits

  • ✅ Non-breaking: Default behavior unchanged, all existing tests pass
  • ✅ User choice: Those needing consistency can opt-in to method='ambaum'
  • ✅ Future-proof: Maintainers can flip the default when ready

Testing

All 228 tests pass (227 existing + 1 new round-trip test).

Addresses #3976

@xtian15 xtian15 requested a review from a team as a code owner December 26, 2025 12:55
@xtian15 xtian15 requested review from dopplershift and removed request for a team December 26, 2025 12:55
@CLAassistant
Copy link

CLAassistant commented Dec 26, 2025

CLA assistant check
All committers have signed the CLA.

Add 'method' parameter to dewpoint() with options:
- 'bolton' (default): Original analytical formula, preserves backward compatibility
- 'ambaum': Numerical inversion of Ambaum (2020), consistent with saturation_vapor_pressure()

This allows users who need thermodynamic consistency to use:
  dewpoint(e, method='ambaum')

which satisfies: dewpoint(saturation_vapor_pressure(T), method='ambaum') == T

- Add _dewpoint_ambaum() helper using scipy.optimize.brentq
- Add test_dewpoint_ambaum_roundtrip() verifying consistency
- Document both methods in docstring with examples

Addresses Unidata#3976
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants