pycontrails 0.58.0__cp314-cp314-macosx_10_13_x86_64.whl

pycontrails/physics/units.py

@@ -0,0 +1,472 @@
+"""Unit conversion support."""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+from pycontrails.physics import constants
+from pycontrails.utils.types import ArrayScalarLike, support_arraylike
+
+
+def pl_to_ft(pl: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert from pressure level (hPa) to altitude (ft).
+
+    Assumes the ICAO standard atmosphere.
+
+    Parameters
+    ----------
+    pl : ArrayScalarLike
+        pressure level, [:math:`hPa`], [:math:`mbar`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        altitude, [:math:`ft`]
+
+    See Also
+    --------
+    pl_to_m
+    ft_to_pl
+    m_to_T_isa
+    """
+    return m_to_ft(pl_to_m(pl))
+
+
+def ft_to_pl(h: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert from altitude (ft) to pressure level (hPa).
+
+    Assumes the ICAO standard atmosphere.
+
+    Parameters
+    ----------
+    h : ArrayScalarLike
+        altitude, [:math:`ft`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        pressure level, [:math:`hPa`], [:math:`mbar`]
+
+    See Also
+    --------
+    m_to_pl
+    pl_to_ft
+    m_to_T_isa
+    """
+    return m_to_pl(ft_to_m(h))
+
+
+def kelvin_to_celsius(kelvin: ArrayScalarLike) -> ArrayScalarLike:
+    """Convert temperature from Kelvin to Celsius.
+
+    Parameters
+    ----------
+    kelvin : ArrayScalarLike
+        temperature [:math:`K`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        temperature [:math:`C`]
+    """
+    return kelvin + constants.absolute_zero
+
+
+def m_to_T_isa(h: ArrayScalarLike) -> ArrayScalarLike:
+    """Calculate the ambient temperature (K) for a given altitude (m).
+
+    Assumes the ICAO standard atmosphere.
+
+    Parameters
+    ----------
+    h : ArrayScalarLike
+        altitude, [:math:`m`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        ICAO standard atmosphere ambient temperature, [:math:`K`]
+
+
+    References
+    ----------
+    - :cite:`wikipediacontributorsInternationalStandardAtmosphere2023`
+
+    Notes
+    -----
+    See https://en.wikipedia.org/wiki/International_Standard_Atmosphere
+
+    See Also
+    --------
+    m_to_pl
+    ft_to_pl
+    """
+    h_min = np.minimum(h, constants.h_tropopause)
+    return constants.T_msl + h_min * constants.T_lapse_rate  # type: ignore[return-value]
+
+
+def _low_altitude_m_to_pl(h: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    T_isa = m_to_T_isa(h)
+    power_term = -constants.g / (constants.T_lapse_rate * constants.R_d)
+    return (constants.p_surface * (T_isa / constants.T_msl) ** power_term) / 100.0
+
+
+def _high_altitude_m_to_pl(h: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    T_tropopause_isa = m_to_T_isa(np.asarray(constants.h_tropopause))
+    power_term = -constants.g / (constants.T_lapse_rate * constants.R_d)
+    p_tropopause_isa = constants.p_surface * (T_tropopause_isa / constants.T_msl) ** power_term
+    inside_exp = (-constants.g / (constants.R_d * T_tropopause_isa)) * (h - constants.h_tropopause)
+    return p_tropopause_isa * np.exp(inside_exp) / 100.0
+
+
+@support_arraylike
+def m_to_pl(h: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    r"""Convert from altitude (m) to pressure level (hPa).
+
+    Parameters
+    ----------
+    h : npt.NDArray[np.floating]
+        altitude, [:math:`m`]
+
+    Returns
+    -------
+    npt.NDArray[np.floating]
+        pressure level, [:math:`hPa`], [:math:`mbar`]
+
+    References
+    ----------
+    - :cite:`wikipediacontributorsBarometricFormula2023`
+
+    Notes
+    -----
+    See https://en.wikipedia.org/wiki/Barometric_formula
+
+    See Also
+    --------
+    m_to_T_isa
+    ft_to_pl
+    """
+    condlist = [h < constants.h_tropopause, h >= constants.h_tropopause]
+    funclist = [_low_altitude_m_to_pl, _high_altitude_m_to_pl, np.nan]  # nan passed through
+    return np.piecewise(h, condlist, funclist)
+
+
+def _low_altitude_pl_to_m(pl: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    base = 100.0 * pl / constants.p_surface
+    exponent = -constants.T_lapse_rate * constants.R_d / constants.g
+    T_isa = constants.T_msl * base**exponent
+    return (T_isa - constants.T_msl) / constants.T_lapse_rate
+
+
+def _high_altitude_pl_to_m(pl: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    T_tropopause_isa = m_to_T_isa(np.asarray(constants.h_tropopause))
+    power_term = -constants.g / (constants.T_lapse_rate * constants.R_d)
+    p_tropopause_isa = constants.p_surface * (T_tropopause_isa / constants.T_msl) ** power_term
+    inside_exp = np.log(pl * 100.0 / p_tropopause_isa)
+    return inside_exp / (-constants.g / (constants.R_d * T_tropopause_isa)) + constants.h_tropopause
+
+
+@support_arraylike
+def pl_to_m(pl: npt.NDArray[np.floating]) -> npt.NDArray[np.floating]:
+    r"""Convert from pressure level (hPa) to altitude (m).
+
+    Function is slightly different from the classical formula:
+    ``constants.T_msl / 0.0065) * (1 - (pl_pa / constants.p_surface) ** (1 / 5.255)``
+    in order to provide a mathematical inverse to :func:`m_to_pl`.
+
+    For low altitudes (below the tropopause), this implementation closely agrees to classical
+    formula.
+
+    Parameters
+    ----------
+    pl : ArrayLike
+        pressure level, [:math:`hPa`], [:math:`mbar`]
+
+    Returns
+    -------
+    ArrayLike
+        altitude, [:math:`m`]
+
+    References
+    ----------
+    - :cite:`wikipediacontributorsBarometricFormula2023`
+
+    Notes
+    -----
+    See https://en.wikipedia.org/wiki/Barometric_formula
+
+    See Also
+    --------
+    pl_to_ft
+    m_to_pl
+    m_to_T_isa
+    """
+    pl_tropopause = m_to_pl(constants.h_tropopause)
+    condlist = [pl < pl_tropopause, pl >= pl_tropopause]
+    funclist = [_high_altitude_pl_to_m, _low_altitude_pl_to_m, np.nan]  # nan passed through
+    return np.piecewise(pl, condlist, funclist)
+
+
+def degrees_to_radians(degrees: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert from degrees to radians.
+
+    Parameters
+    ----------
+    degrees : ArrayScalarLike
+        Degrees values, [:math:`\deg`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Radians values
+    """
+    return degrees * (np.pi / 180.0)
+
+
+def radians_to_degrees(radians: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert from radians to degrees.
+
+    Parameters
+    ----------
+    radians : ArrayScalarLike
+        degrees values, [:math:`\rad`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Radian values
+    """
+    return radians * (180.0 / np.pi)
+
+
+def ft_to_m(ft: ArrayScalarLike) -> ArrayScalarLike:
+    """Convert length from feet to meter.
+
+    Parameters
+    ----------
+    ft : ArrayScalarLike
+        length, [:math:`ft`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        length, [:math:`m`]
+    """
+    return ft * 0.3048
+
+
+def m_to_ft(m: ArrayScalarLike) -> ArrayScalarLike:
+    """Convert length from meters to feet.
+
+    Parameters
+    ----------
+    m : ArrayScalarLike
+        length, [:math:`m`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        length, [:math:`ft`]
+    """
+    return m / 0.3048
+
+
+def m_per_s_to_knots(m_per_s: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert speed from meters per second (m/s) to knots.
+
+    Parameters
+    ----------
+    m_per_s : ArrayScalarLike
+        Speed, [:math:`m \ s^{-1}`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Speed, [:math:`knots`]
+    """
+    return m_per_s / 0.514444
+
+
+def knots_to_m_per_s(knots: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert speed from knots to meters per second (m/s).
+
+    Parameters
+    ----------
+    knots : ArrayScalarLike
+        Speed, [:math:`knots`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Speed, [:math:`m \ s^{-1}`]
+    """
+    return knots * 0.514444
+
+
+def longitude_distance_to_m(
+    distance_degrees: ArrayScalarLike, latitude_mean: ArrayScalarLike
+) -> ArrayScalarLike:
+    r"""
+    Convert longitude degrees distance between two points to cartesian distances in meters.
+
+    Parameters
+    ----------
+    distance_degrees : ArrayScalarLike
+        longitude distance, [:math:`\deg`]
+    latitude_mean : ArrayScalarLike, optional
+        mean latitude between ``longitude_1`` and ``longitude_2``, [:math:`\deg`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        cartesian distance along the longitude axis, [:math:`m`]
+    """
+    latitude_mean_rad = degrees_to_radians(latitude_mean)
+    return (distance_degrees / 180.0) * np.pi * constants.radius_earth * np.cos(latitude_mean_rad)
+
+
+def latitude_distance_to_m(distance_degrees: ArrayScalarLike) -> ArrayScalarLike:
+    r"""
+    Convert latitude degrees distance between two points to cartesian distances in meters.
+
+    Parameters
+    ----------
+    distance_degrees : ArrayScalarLike
+        latitude distance, [:math:`\deg`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Cartesian distance along the latitude axis, [:math:`m`]
+    """
+    return (distance_degrees / 180.0) * np.pi * constants.radius_earth
+
+
+def m_to_longitude_distance(
+    distance_m: ArrayScalarLike, latitude_mean: ArrayScalarLike
+) -> ArrayScalarLike:
+    r"""
+    Convert cartesian distance (meters) to differences in longitude degrees.
+
+    Small angle approximation for ``distance_m`` << :attr:`constants.radius_earth`
+
+    Parameters
+    ----------
+    distance_m : ArrayScalarLike
+        cartesian distance along longitude axis, [:math:`m`]
+    latitude_mean : ArrayScalarLike
+        mean latitude between ``longitude_1`` and ``longitude_2``, [:math:`\deg`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        longitude distance, [:math:`\deg`]
+    """
+    return radians_to_degrees(
+        distance_m / (constants.radius_earth * np.cos(degrees_to_radians(latitude_mean)))
+    )
+
+
+def m_to_latitude_distance(distance_m: ArrayScalarLike) -> ArrayScalarLike:
+    r"""
+    Convert cartesian distance (meters) to differences in latitude degrees.
+
+    Small angle approximation for ``distance_m`` << :attr:`constants.radius_earth`
+
+    Parameters
+    ----------
+    distance_m : ArrayScalarLike
+        cartesian distance along latitude axis, [:math:`m`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        latitude distance, [:math:`\deg`]
+    """
+    return radians_to_degrees(distance_m / constants.radius_earth)
+
+
+def tas_to_mach_number(true_airspeed: ArrayScalarLike, T: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Calculate Mach number from true airspeed at a specified ambient temperature.
+
+    Parameters
+    ----------
+    true_airspeed : ArrayScalarLike
+        True airspeed, [:math:`m \ s^{-1}`]
+    T : ArrayScalarLike
+        Ambient temperature, [:math:`K`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        Mach number, [:math: `Ma`]
+
+    References
+    ----------
+    - :cite:`cumpstyJetPropulsion2015`
+    """
+    return true_airspeed / np.sqrt((constants.kappa * constants.R_d) * T)
+
+
+def mach_number_to_tas(
+    mach_number: float | npt.NDArray[np.floating], T: float | npt.NDArray[np.floating]
+) -> float | npt.NDArray[np.floating]:
+    r"""Calculate true airspeed from the Mach number at a specified ambient temperature.
+
+    Parameters
+    ----------
+    mach_number : float | npt.NDArray[np.floating]
+        Mach number, [:math: `Ma`]
+    T : npt.NDArray[np.floating]
+        Ambient temperature, [:math:`K`]
+
+    Returns
+    -------
+    npt.NDArray[np.floating]
+        True airspeed, [:math:`m \ s^{-1}`]
+
+    References
+    ----------
+    - :cite:`cumpstyJetPropulsion2015`
+    """
+    return mach_number * np.sqrt((constants.kappa * constants.R_d) * T)
+
+
+def lbs_to_kg(lbs: ArrayScalarLike) -> ArrayScalarLike:
+    r"""Convert mass from pounds (lbs) to kilograms (kg).
+
+    Parameters
+    ----------
+    lbs : ArrayScalarLike
+        mass, pounds [:math:`lbs`]
+
+    Returns
+    -------
+    ArrayScalarLike
+        mass, kilograms [:math:`kg`]
+    """
+    return lbs * 0.45359
+
+
+def dt_to_seconds(
+    dt: npt.NDArray[np.timedelta64] | np.timedelta64,
+    dtype: npt.DTypeLike = np.float64,
+) -> npt.NDArray[np.floating]:
+    """Convert a time delta to seconds as a float with specified ``dtype`` precision.
+
+    Parameters
+    ----------
+    dt : np.ndarray
+        Time delta for each waypoint
+    dtype : np.dtype
+        Data type of the output array
+
+    Returns
+    -------
+    np.ndarray
+        Time delta in seconds as a float
+    """
+    out = np.empty(dt.shape, dtype=dtype)
+    np.divide(dt, np.timedelta64(1, "s"), out=out)
+    return out

pycontrails/utils/__init__.py

@@ -0,0 +1 @@
+"""Misc re-usable utilities."""

pycontrails/utils/dependencies.py

@@ -0,0 +1,66 @@
+"""Raise ``ImportError`` when dependencies are not met."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+
+def raise_module_not_found_error(
+    name: str,
+    package_name: str,
+    module_not_found_error: ImportError,
+    pycontrails_optional_package: str | None = None,
+    extra: str | None = None,
+) -> NoReturn:
+    """Raise ``ImportError`` with a helpful message.
+
+    Parameters
+    ----------
+    name : str
+        The name describing the context of the ``ImportError``. For example,
+        if the module is required for a specific function, the name could be
+        "my_function function". If the module is required for a specific method,
+        the name could be "MyClass.my_method method". If the module is required
+        for an entire ``pycontrails`` module, the name could be "my_module module".
+    package_name : str
+        The name of the package that is required. This should be the full name of
+        the python package, which may be different from the name of the module
+        that is actually imported. For example, if ``import sklearn`` triggers
+        the ``ImportError``, the ``package_name`` should be "scikit-learn".
+    module_not_found_error : ImportError
+        The ``ImportError`` that was raised. This is passed to the
+        ``from`` clause of the ``raise`` statement below. The subclass of the
+        ``ImportError`` is preserved (e.g., ``ModuleNotFoundError`` or
+        ``ImportError``).
+    pycontrails_optional_package : str, optional
+        The name of the optional ``pycontrails`` package that can be used to
+        install the required package. See the ``pyproject.toml`` file.
+    extra : str, optional
+        Any extra information that should be included in the error message.
+        This is appended to the end of the error message.
+    """
+    # Put the function or method or module name in quotes if the full name
+    # contains a space.
+    try:
+        n1, n2 = name.split(" ")
+    except ValueError:
+        if "'" not in name:
+            name = f"'{name}'"
+    else:
+        if "'" not in n1:
+            n1 = f"'{n1}'"
+        name = f"{n1} {n2}"
+
+    msg = (
+        f"The {name} requires the '{package_name}' package. "
+        f"This can be installed with 'pip install {package_name}'"
+    )
+    if pycontrails_optional_package:
+        msg = f"{msg} or 'pip install pycontrails[{pycontrails_optional_package}]'."
+    else:
+        msg = f"{msg}."
+
+    if extra:
+        msg = f"{msg} {extra}"
+
+    raise type(module_not_found_error)(msg) from module_not_found_error

pycontrails/utils/iteration.py

@@ -0,0 +1,13 @@
+"""Utilites for iterating of sequences."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+def chunk_list(lst: list[Any], n: int) -> Iterator[list[Any]]:
+    """Yield successive n-sized chunks from list."""
+
+    for i in range(0, len(lst), n):
+        yield lst[i : i + n]