pycontrails 0.58.0__cp314-cp314-macosx_11_0_arm64.whl

pycontrails/physics/static/iata-cargo-load-factors-20250221.csv

@@ -0,0 +1,74 @@
+Date,Global,Africa,Asia Pacific,Europe,Latin America,Middle East,North America
+15/12/2018,0.488,0.381,0.54,0.567,0.291,0.488,0.414
+15/1/2019,0.451,0.354,0.501,0.501,0.299,0.421,0.4
+15/2/2019,0.447,0.363,0.473,0.53,0.297,0.466,0.379
+15/3/2019,0.495,0.384,0.556,0.56,0.323,0.488,0.416
+15/4/2019,0.463,0.374,0.518,0.496,0.325,0.458,0.405
+15/5/2019,0.468,0.386,0.52,0.513,0.353,0.469,0.398
+15/6/2019,0.454,0.324,0.522,0.498,0.337,0.44,0.382
+15/7/2019,0.45,0.323,0.519,0.485,0.354,0.453,0.373
+15/8/2019,0.446,0.302,0.516,0.477,0.372,0.435,0.377
+15/9/2019,0.464,0.329,0.539,0.501,0.379,0.459,0.381
+15/10/2019,0.477,0.361,0.539,0.533,0.364,0.477,0.394
+15/11/2019,0.496,0.404,0.538,0.569,0.403,0.497,0.413
+15/12/2019,0.467,0.368,0.519,0.53,0.3,0.47,0.395
+15/1/2020,0.45,0.356,0.474,0.501,0.311,0.426,0.424
+15/2/2020,0.464,0.368,0.543,0.531,0.342,0.461,0.372
+15/3/2020,0.545,0.425,0.656,0.63,0.411,0.532,0.429
+15/4/2020,0.58,0.486,0.691,0.648,0.554,0.525,0.487
+15/5/2020,0.576,0.612,0.643,0.625,0.561,0.483,0.526
+15/6/2020,0.573,0.547,0.645,0.62,0.512,0.494,0.521
+15/7/2020,0.564,0.489,0.639,0.594,0.464,0.53,0.506
+15/8/2020,0.548,0.502,0.616,0.568,0.478,0.535,0.489
+15/9/2020,0.569,0.507,0.642,0.62,0.456,0.579,0.484
+15/10/2020,0.576,0.502,0.617,0.651,0.443,0.606,0.496
+15/11/2020,0.582,0.496,0.631,0.655,0.436,0.6,0.5
+15/12/2020,0.573,0.51,0.639,0.653,0.367,0.597,0.482
+15/1/2021,0.589,0.48,0.665,0.627,0.39,0.569,0.532
+15/2/2021,0.575,0.476,0.692,0.641,0.429,0.598,0.453
+15/3/2021,0.588,0.499,0.661,0.685,0.453,0.613,0.472
+15/4/2021,0.578,0.504,0.633,0.681,0.457,0.598,0.473
+15/5/2021,0.572,0.502,0.646,0.656,0.423,0.589,0.469
+15/6/2021,0.565,0.48,0.676,0.626,0.381,0.581,0.458
+15/7/2021,0.544,0.455,0.654,0.598,0.387,0.536,0.443
+15/8/2021,0.542,0.43,0.698,0.575,0.404,0.529,0.437
+15/9/2021,0.553,0.428,0.68,0.604,0.37,0.558,0.447
+15/10/2021,0.561,0.45,0.661,0.626,0.421,0.572,0.449
+15/11/2021,0.559,0.434,0.654,0.631,0.446,0.572,0.444
+15/12/2021,0.542,0.502,0.634,0.623,0.413,0.556,0.43
+15/1/2022,0.541,0.492,0.609,0.584,0.417,0.513,0.474
+15/2/2022,0.532,0.502,0.592,0.636,0.476,0.529,0.429
+15/3/2022,0.549,0.494,0.638,0.671,0.448,0.526,0.442
+15/4/2022,0.516,0.49,0.631,0.578,0.419,0.504,0.419
+15/5/2022,0.505,0.495,0.627,0.548,0.387,0.487,0.411
+15/6/2022,0.492,0.447,0.608,0.507,0.383,0.488,0.404
+15/7/2022,0.472,0.452,0.563,0.493,0.374,0.469,0.398
+15/8/2022,0.467,0.418,0.547,0.502,0.374,0.466,0.393
+15/9/2022,0.481,0.451,0.572,0.528,0.381,0.478,0.396
+15/10/2022,0.487,0.437,0.561,0.558,0.384,0.48,0.401
+15/11/2022,0.491,0.458,0.545,0.569,0.382,0.475,0.419
+15/12/2022,0.472,0.432,0.528,0.559,0.322,0.454,0.406
+15/1/2023,0.448,0.439,0.452,0.541,0.325,0.411,0.423
+15/2/2023,0.456,0.468,0.464,0.574,0.361,0.445,0.4
+15/3/2023,0.462,0.489,0.485,0.57,0.366,0.456,0.393
+15/4/2023,0.427,0.482,0.442,0.497,0.364,0.431,0.373
+15/5/2023,0.415,0.448,0.422,0.489,0.333,0.41,0.373
+15/6/2023,0.432,0.446,0.468,0.476,0.337,0.446,0.374
+15/7/2023,0.421,0.417,0.457,0.472,0.322,0.411,0.37
+15/8/2023,0.42,0.388,0.443,0.484,0.326,0.407,0.377
+15/9/2023,0.438,0.436,0.466,0.5,0.319,0.424,0.392
+15/10/2023,0.452,0.416,0.472,0.53,0.354,0.46,0.392
+15/11/2023,0.467,0.421,0.479,0.57,0.363,0.469,0.408
+15/12/2023,0.459,0.41,0.479,0.562,0.316,0.455,0.403
+15/1/2024,0.457,0.431,0.446,0.555,0.344,0.439,0.435
+15/2/2024,0.451,0.451,0.432,0.584,0.376,0.463,0.396
+15/3/2024,0.473,0.473,0.475,0.581,0.402,0.496,0.404
+15/4/2024,0.439,0.429,0.445,0.515,0.387,0.447,0.387
+15/5/2024,0.446,0.438,0.453,0.518,0.362,0.461,0.397
+15/6/2024,0.458,0.385,0.496,0.507,0.336,0.473,0.388
+15/7/2024,0.444,0.4,0.48,0.496,0.338,0.458,0.382
+15/8/2024,0.44,0.378,0.466,0.501,0.359,0.445,0.387
+15/9/2024,0.456,0.392,0.485,0.525,0.368,0.474,0.389
+15/10/2024,0.473,0.401,0.493,0.555,0.411,0.48,0.411
+15/11/2024,0.49,0.425,0.5,0.576,0.396,0.494,0.438
+15/12/2024,0.473,0.415,0.491,0.567,0.335,0.473,0.421

pycontrails/physics/static/iata-passenger-load-factors-20250221.csv

@@ -0,0 +1,74 @@
+Date,Global,Africa,Asia Pacific,Europe,Latin America,Middle East,North America
+15/12/2018,0.804,0.724,0.81,0.81,0.818,0.736,0.825
+15/1/2019,0.796,0.709,0.81,0.796,0.825,0.76,0.795
+15/2/2019,0.806,0.704,0.826,0.815,0.813,0.726,0.808
+15/3/2019,0.817,0.72,0.812,0.837,0.815,0.739,0.85
+15/4/2019,0.828,0.733,0.817,0.851,0.822,0.803,0.839
+15/5/2019,0.815,0.676,0.802,0.837,0.832,0.732,0.851
+15/6/2019,0.844,0.706,0.821,0.875,0.832,0.767,0.887
+15/7/2019,0.857,0.735,0.831,0.89,0.853,0.812,0.888
+15/8/2019,0.857,0.755,0.839,0.889,0.833,0.821,0.875
+15/9/2019,0.819,0.721,0.801,0.866,0.819,0.75,0.828
+15/10/2019,0.82,0.697,0.815,0.855,0.819,0.734,0.841
+15/11/2019,0.818,0.708,0.813,0.833,0.822,0.732,0.828
+15/12/2019,0.823,0.724,0.816,0.828,0.825,0.78,0.859
+15/1/2020,0.803,0.702,0.799,0.816,0.826,0.785,0.812
+15/2/2020,0.759,0.668,0.678,0.813,0.812,0.725,0.811
+15/3/2020,0.606,0.609,0.589,0.67,0.681,0.599,0.557
+15/4/2020,0.366,0.111,0.538,0.32,0.55,0.284,0.15
+15/5/2020,0.507,0.071,0.62,0.427,0.623,0.255,0.381
+15/6/2020,0.576,0.162,0.638,0.555,0.666,0.357,0.524
+15/7/2020,0.579,0.296,0.657,0.609,0.631,0.396,0.476
+15/8/2020,0.585,0.39,0.65,0.635,0.639,0.372,0.477
+15/9/2020,0.601,0.378,0.692,0.586,0.706,0.365,0.525
+15/10/2020,0.602,0.482,0.687,0.552,0.721,0.387,0.558
+15/11/2020,0.58,0.474,0.664,0.523,0.74,0.372,0.518
+15/12/2020,0.575,0.549,0.616,0.578,0.73,0.44,0.516
+15/1/2021,0.541,0.544,0.566,0.576,0.685,0.422,0.484
+15/2/2021,0.554,0.516,0.591,0.563,0.683,0.398,0.527
+15/3/2021,0.623,0.53,0.669,0.593,0.708,0.422,0.624
+15/4/2021,0.633,0.476,0.678,0.563,0.723,0.404,0.668
+15/5/2021,0.658,0.53,0.678,0.593,0.768,0.389,0.728
+15/6/2021,0.696,0.587,0.657,0.658,0.784,0.459,0.806
+15/7/2021,0.731,0.614,0.675,0.725,0.793,0.513,0.841
+15/8/2021,0.7,0.64,0.545,0.746,0.774,0.56,0.786
+15/9/2021,0.676,0.56,0.605,0.719,0.773,0.524,0.727
+15/10/2021,0.706,0.558,0.629,0.741,0.809,0.577,0.769
+15/11/2021,0.713,0.616,0.597,0.752,0.822,0.616,0.786
+15/12/2021,0.723,0.647,0.625,0.745,0.816,0.663,0.793
+15/1/2022,0.645,0.623,0.576,0.682,0.782,0.591,0.663
+15/2/2022,0.698,0.648,0.629,0.721,0.795,0.648,0.745
+15/3/2022,0.747,0.657,0.642,0.739,0.808,0.718,0.839
+15/4/2022,0.778,0.68,0.67,0.795,0.809,0.713,0.858
+15/5/2022,0.794,0.696,0.696,0.807,0.807,0.762,0.86
+15/6/2022,0.824,0.743,0.729,0.86,0.817,0.772,0.891
+15/7/2022,0.835,0.753,0.764,0.87,0.831,0.812,0.882
+15/8/2022,0.818,0.757,0.74,0.862,0.824,0.796,0.856
+15/9/2022,0.816,0.743,0.747,0.847,0.823,0.795,0.855
+15/10/2022,0.82,0.726,0.755,0.848,0.833,0.791,0.864
+15/11/2022,0.808,0.748,0.77,0.838,0.82,0.775,0.832
+15/12/2022,0.811,0.769,0.772,0.836,0.785,0.8,0.842
+15/1/2023,0.777,0.742,0.774,0.762,0.813,0.791,0.784
+15/2/2023,0.778,0.756,0.792,0.752,0.811,0.798,0.771
+15/3/2023,0.807,0.739,0.792,0.805,0.812,0.794,0.837
+15/4/2023,0.813,0.708,0.784,0.838,0.814,0.76,0.856
+15/5/2023,0.818,0.699,0.773,0.848,0.811,0.799,0.863
+15/6/2023,0.842,0.689,0.804,0.877,0.825,0.794,0.887
+15/7/2023,0.852,0.746,0.816,0.877,0.867,0.821,0.897
+15/8/2023,0.846,0.764,0.822,0.876,0.851,0.83,0.858
+15/9/2023,0.826,0.731,0.8,0.86,0.839,0.816,0.83
+15/10/2023,0.831,0.707,0.821,0.856,0.848,0.806,0.836
+15/11/2023,0.818,0.704,0.814,0.837,0.844,0.777,0.827
+15/12/2023,0.821,0.732,0.812,0.851,0.827,0.782,0.829
+15/1/2024,0.799,0.731,0.808,0.782,0.85,0.799,0.799
+15/2/2024,0.806,0.744,0.844,0.761,0.827,0.808,0.795
+15/3/2024,0.82,0.721,0.835,0.809,0.831,0.775,0.837
+15/4/2024,0.824,0.734,0.824,0.838,0.822,0.792,0.83
+15/5/2024,0.834,0.729,0.818,0.852,0.834,0.808,0.858
+15/6/2024,0.85,0.771,0.829,0.877,0.842,0.795,0.876
+15/7/2024,0.86,0.75,0.834,0.882,0.862,0.84,0.889
+15/8/2024,0.862,0.779,0.86,0.879,0.84,0.823,0.871
+15/9/2024,0.836,0.765,0.831,0.865,0.834,0.814,0.824
+15/10/2024,0.839,0.738,0.841,0.862,0.845,0.803,0.832
+15/11/2024,0.834,0.733,0.849,0.853,0.845,0.812,0.81
+15/12/2024,0.84,0.76,0.833,0.865,0.83,0.805,0.85

pycontrails/physics/thermo.py

@@ -0,0 +1,551 @@
+"""Thermodynamic relationships."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from pycontrails.physics import constants
+from pycontrails.utils.types import ArrayScalarLike, support_arraylike
+
+# -------------------
+# Material Properties
+# -------------------
+
+
+def rho_d(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate air density for (T, p) assuming dry air.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Air density of dry air, [:math:`kg \ m^{-3}`]
+    """
+    return p / (constants.R_d * T)
+
+
+def rho_v(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate the air density for (T, p) assuming all water vapor.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Air density of water vapor, [:math:`kg \ m^{-3}`]
+    """
+    return p / (constants.R_v * T)
+
+
+def c_pm(q: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate isobaric heat capacity of moist air.
+
+    Parameters
+    ----------
+    q : ArrayScalarLike
+        Specific humidity, [:math:`kg \ kg^{-1}`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Isobaric heat capacity of moist air, [:math:`J \ kg^{-1} \ K^{-1}`]
+
+    Notes
+    -----
+    Some models (including CoCiP) use a constant value here (1004 :math:`J \ kg^{-1} \ K^{-1}`)
+
+    """
+    return constants.c_pd * (1.0 - q) + constants.c_pv * q
+
+
+def p_vapor(q: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate the vapor pressure.
+
+    Parameters
+    ----------
+    q : ArrayScalarTypeVar
+        Specific humidity, [:math:`kg \ kg^{-1}`]
+    p : ArrayScalarTypeVar
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarTypeVar
+        Vapor pressure, [:math:`Pa`]
+    """
+    return q * p * (constants.R_v / constants.R_d)
+
+
+def water_vapor_partial_pressure_along_mixing_line(
+    specific_humidity: ArrayScalarLike,
+    air_pressure: ArrayScalarLike,
+    T_plume: ArrayScalarLike,
+    T_ambient: ArrayScalarLike,
+    G: ArrayScalarLike,
+) -> ArrayScalarLike:
+    """
+    Calculate water vapor partial pressure along mixing line.
+
+    Parameters
+    ----------
+    specific_humidity : ArrayScalarLike
+        Specific humidity at each waypoint, [:math:`kg_{H_{2}O} / kg_{air}`]
+    air_pressure : ArrayScalarLike
+        Pressure altitude at each waypoint, [:math:`Pa`]
+    T_plume : ArrayScalarLike
+        Plume temperature evolution along mixing line, [:math:`K`]
+    T_ambient : ArrayScalarLike
+        Ambient temperature for each waypoint, [:math:`K`]
+    G : ArrayScalarLike
+        Slope of the mixing line in a temperature-humidity diagram.
+
+    Returns
+    -------
+    ArrayScalarLike
+        Water vapor partial pressure along mixing line (p_mw), [:math:`Pa`]
+
+    References
+    ----------
+    Eq. (2) of Karcher et al. (2015).
+    """
+    p_wa = p_vapor(specific_humidity, air_pressure)
+    return p_wa + G * (T_plume - T_ambient)
+
+
+# -------------------
+# Saturation Pressure
+# -------------------
+
+
+def e_sat_ice(T: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate saturation pressure of water vapor over ice.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation pressure of water vapor over ice, [:math:`Pa`]
+
+    References
+    ----------
+    - :cite:`sonntag1994`
+
+    """
+    # Goff Gratch equation (Smithsonian Tables, 1984)
+    # return np.log10(-9.09718 * (273.16/T - 1) - 3.56654 * np.log10(273.16/T) + \
+    #                  0.87679 * (1 - T/273.16) + np.log10(6.1071))
+
+    # Magnus Teten (Murray, 1967)
+    # return 6.1078 * np.exp(21.8745 * (T - 273.16) / (T - 7.66))
+
+    # Zhang 2017 - incorrect implementation of Magnus Teten
+    # return 6.1808 * np.exp(21.875 * (T - 276.16) / (T - 7.66))
+
+    # Guide to Meteorological Instruments and Methods of Observation (CIMO Guide) (WMO, 2008)
+    # return 6.112 * np.exp(22.46 * (T - 273.16) / (272.62 + T - 273.16))
+
+    # Sonntag (1994) is used in CoCiP
+
+    # FIXME: Presently, mypy is not aware that numpy ufuncs will return `xr.DataArray``
+    # when xr.DataArray is passed in. This will get fixed at some point in the future
+    # as `numpy` their typing patterns, after which the "type: ignore" comment can
+    # get ripped out.
+    # We could explicitly check for `xr.DataArray` then use `xr.apply_ufunc`, but
+    # this only renders our code more boilerplate and less performant.
+    # This comment is pasted several places in `pycontrails` -- they should all be
+    # addressed at the same time.
+    return 100.0 * np.exp(  # type: ignore[return-value]
+        (-6024.5282 / T)
+        + 24.7219
+        + (0.010613868 * T)
+        - (1.3198825e-5 * (T**2))
+        - 0.49382577 * np.log(T)
+    )
+
+
+def sonntag_e_sat_liquid(T: ArrayScalarLike) -> ArrayScalarLike:
+    """Calculate saturation pressure of water vapor over liquid water using Sonntag (1994).
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation pressure of water vapor over liquid water, [:math:`Pa`]
+    """
+    return 100.0 * np.exp(  # type: ignore[return-value]
+        -6096.9385 / T + 16.635794 - 0.02711193 * T + 1.673952 * 1e-5 * T**2 + 2.433502 * np.log(T)
+    )
+
+
+def mk05_e_sat_liquid(T: ArrayScalarLike) -> ArrayScalarLike:
+    """Calculate saturation pressure of water vapor over liquid water using Murphy and Koop (2005).
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation pressure of water vapor over liquid water, [:math:`Pa`]
+
+    Notes
+    -----
+    Several formulations exist for the saturation vapor pressure over liquid water.
+
+    Buck (Buck Research Manual 1996)..
+
+        6.1121 * np.exp((18.678 * (T - 273.15) / 234.5) * (T - 273.15) / (257.14 + (T - 273.15)))
+
+    Magnus Tetens (Murray, 1967)..
+
+        6.1078 * np.exp(17.269388 * (T - 273.16) / (T - 35.86))
+
+    Guide to Meteorological Instruments and Methods of Observation (CIMO Guide) (WMO, 2008)..
+
+        6.112 * np.exp(17.62 * (T - 273.15) / (243.12 + T - 273.15))
+
+    Sonntag (1994) (see :func:`sonntag_e_sat_liquid`) is used in older versions of CoCiP.
+    """
+
+    return np.exp(  # type: ignore[return-value]
+        54.842763
+        - 6763.22 / T
+        - 4.21 * np.log(T)
+        + 0.000367 * T
+        + np.tanh(0.0415 * (T - 218.8))
+        * (53.878 - 1331.22 / T - 9.44523 * np.log(T) + 0.014025 * T)
+    )
+
+
+def sonntag_e_sat_liquid_prime(T: ArrayScalarLike) -> ArrayScalarLike:
+    """Calculate the derivative of :func:`sonntag_e_sat_liquid`.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`].
+
+    Returns
+    -------
+    ArrayScalarLike
+        Derivative of :func:`sonntag_e_sat_liquid`
+    """
+    d_inside = 6096.9385 / (T**2) - 0.02711193 + 1.673952 * 1e-5 * 2 * T + 2.433502 / T
+    return sonntag_e_sat_liquid(T) * d_inside
+
+
+def mk05_e_sat_liquid_prime(T: ArrayScalarLike) -> ArrayScalarLike:
+    """Calculate the derivative of :func:`mk05_e_sat_liquid`.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`].
+
+    Returns
+    -------
+    ArrayScalarLike
+        Derivative of :func:`mk05_e_sat_liquid`
+    """
+    tanh_term = np.tanh(0.0415 * (T - 218.8))
+    return mk05_e_sat_liquid(T) * (
+        6763.22 / T**2
+        - 4.21 / T
+        + 0.000367
+        + 0.0415 * (1 - tanh_term**2) * (53.878 - 1331.22 / T - 9.44523 * np.log(T) + 0.014025 * T)
+        + tanh_term * (1331.22 / T**2 - 9.44523 / T + 0.014025)
+    )
+
+
+# Set aliases. These could be swapped out or made configurable.
+e_sat_liquid = mk05_e_sat_liquid
+e_sat_liquid_prime = mk05_e_sat_liquid_prime
+
+
+@support_arraylike
+def _e_sat_piecewise(T: np.ndarray) -> np.ndarray:
+    """Calculate `e_sat_liquid` when T is above freezing otherwise `e_sat_ice`.
+
+    Parameters
+    ----------
+    T : np.ndarray
+        Temperature, [:math:`K`]
+
+    Returns
+    -------
+    np.ndarray
+        Piecewise array of e_sat_liquid and e_sat_ice values.
+    """
+    condlist = [T >= -constants.absolute_zero, T < constants.absolute_zero]  # noqa: SIM300
+    funclist = [e_sat_liquid, e_sat_ice, np.nan]  # nan passed through
+    return np.piecewise(T, condlist, funclist)
+
+
+# ----------------------------
+# Saturation Specific Humidity
+# ----------------------------
+
+
+def q_sat(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate saturation specific humidity over liquid or ice.
+
+    When T is above 0 C, liquid saturation is computed. Otherwise, ice saturation
+    is computed.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation specific humidity, [:math:`kg \ kg^{-1}`]
+
+    Notes
+    -----
+    Smith et al. (1999)
+    """
+    e_sat = _e_sat_piecewise(T)
+    return constants.epsilon * e_sat / p
+
+
+def q_sat_ice(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate saturation specific humidity over ice.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation specific humidity, [:math:`kg \ kg^{-1}`]
+
+    Notes
+    -----
+    Smith et al. (1999)
+    """
+    return constants.epsilon * e_sat_ice(T) / p
+
+
+def q_sat_liquid(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate saturation specific humidity over liquid.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Saturation specific humidity, [:math:`kg \ kg^{-1}`]
+
+    Notes
+    -----
+    Smith et al. (1999)
+    """
+    return constants.epsilon * e_sat_liquid(T) / p
+
+
+# -----------------
+# Relative Humidity
+# -----------------
+
+
+def rh(q: ArrayScalarLike, T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate the relative humidity with respect to to liquid water.
+
+    Parameters
+    ----------
+    q : ArrayScalarLike
+        Specific humidity, [:math:`kg \ kg^{-1}`]
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Relative Humidity, :math:`[0 - 1]`
+    """
+    return (q * p * (constants.R_v / constants.R_d)) / e_sat_liquid(T)
+
+
+def rhi(q: ArrayScalarLike, T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate the relative humidity with respect to ice (RHi).
+
+    Parameters
+    ----------
+    q : ArrayScalarLike
+        Specific humidity, [:math:`kg \ kg^{-1}`]
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Relative Humidity over ice, :math:`[0 - 1]`
+    """
+    return (q * p * (constants.R_v / constants.R_d)) / e_sat_ice(T)
+
+
+# --------------
+# Met Properties
+# --------------
+
+
+def pressure_dz(T: ArrayScalarLike, p: ArrayScalarLike, dz: float) -> ArrayScalarLike:
+    r"""Calculate the pressure altitude ``dz`` meters below input pressure.
+
+    Returns surface pressure if the calculated pressure altitude is greater
+    than :const:`constants.p_surface`.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature, [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+    dz : float
+        Difference in altitude between measurements, [:math:`m`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Pressure at altitude, [:math:`Pa`]
+
+    Notes
+    -----
+    This is used to calculate the temperature gradient and wind shear.
+    """
+    dp = rho_d(T, p) * constants.g * dz
+
+    # FIXME: Presently, mypy is not aware that numpy ufuncs will return `xr.DataArray``
+    # when xr.DataArray is passed in. This will get fixed at some point in the future
+    # as `numpy` their typing patterns, after which the "type: ignore" comment can
+    # get ripped out.
+    # We could explicitly check for `xr.DataArray` then use `xr.apply_ufunc`, but
+    # this only renders our code more boilerplate and less performant.
+    # This comment is pasted several places in `pycontrails` -- they should all be
+    # addressed at the same time.
+    return np.minimum(p + dp, constants.p_surface)  # type: ignore[return-value]
+
+
+def T_potential_gradient(
+    T_top: ArrayScalarLike,
+    p_top: ArrayScalarLike,
+    T_btm: ArrayScalarLike,
+    p_btm: ArrayScalarLike,
+    dz: float,
+) -> ArrayScalarLike:
+    r"""Calculate the potential temperature gradient between two altitudes.
+
+    Parameters
+    ----------
+    T_top : ArrayScalarLike
+        Temperature at original altitude, [:math:`K`]
+    p_top : ArrayScalarLike
+        Pressure at original altitude, [:math:`Pa`]
+    T_btm : ArrayScalarLike
+        Temperature at lower altitude, [:math:`K`]
+    p_btm : ArrayScalarLike
+        Pressure at lower altitude, [:math:`Pa`]
+    dz : float
+        Difference in altitude between measurements, [:math:`m`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Potential Temperature gradient, [:math:`K \ m^{-1}`]
+    """
+    T_potential_top = T_potential(T_top, p_top)
+    T_potential_btm = T_potential(T_btm, p_btm)
+    return (T_potential_top - T_potential_btm) / dz
+
+
+def T_potential(T: ArrayScalarLike, p: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate potential temperature.
+
+    The potential temperature is the temperature that
+    an air parcel would attain if adiabatically
+    brought to a standard reference pressure, :const:`constants.p_surface`.
+
+    Parameters
+    ----------
+    T : ArrayScalarLike
+        Temperature , [:math:`K`]
+    p : ArrayScalarLike
+        Pressure, [:math:`Pa`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Potential Temperature, [:math:`K`]
+
+    References
+    ----------
+    - https://en.wikipedia.org/wiki/Potential_temperature
+    """
+    return T * (constants.p_surface / p) ** (constants.R_d / constants.c_pd)
+
+
+def brunt_vaisala_frequency(p: np.ndarray, T: np.ndarray, T_grad: np.ndarray) -> np.ndarray:
+    r"""Calculate the Brunt-Vaisaila frequency.
+
+    The Brunt-Vaisaila frequency is the frequency at which a vertically
+    displaced parcel will oscillate within a statically stable environment.
+
+    Parameters
+    ----------
+    p : np.ndarray
+        Pressure, [:math:`Pa`]
+    T : np.ndarray
+        Temperature , [:math:`K`]
+    T_grad : np.ndarray
+        Potential Temperature gradient (see :func:`T_potential_gradient`), [:math:`K \ m^{-1}`]
+
+    Returns
+    -------
+    np.ndarray
+        Brunt-Vaisaila frequency, [:math:`s^{-1}`]
+
+    References
+    ----------
+    - https://en.wikipedia.org/wiki/Brunt%E2%80%93V%C3%A4is%C3%A4l%C3%A4_frequency
+    """
+    theta = T_potential(T, p)
+    T_grad.clip(min=1e-6, out=T_grad)
+    return (T_grad * constants.g / theta) ** 0.5