earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/atmosphere/systems/moisture.py

@@ -0,0 +1,162 @@
+"""Moisture: saturation vapour pressure, mixing ratio, specific and relative humidity and virtual temperature.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+from earthsciencekit.constants import EPSILON_WATER, R_VAPOR
+
+__all__ = [
+    "saturation_vapor_pressure",
+    "mixing_ratio",
+    "specific_humidity",
+    "virtual_temperature",
+    "relative_humidity",
+]
+
+
+@model
+def saturation_vapor_pressure(temperature):
+    """Integrated Clausius-Clapeyron approximation.
+
+    Phase equilibrium makes saturation vapor pressure strongly temperature dependent.
+
+    Parameters
+    ----------
+    temperature : float or array_like
+        K; constraint: temperature.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Liquid-water reference with constant latent heat; restricted to 180-330 K, not an ice saturation formula.
+    Equation: ``611.2 * np.exp((2.5e6 / R_VAPOR) * (1 / 273.15 - 1 / temperature))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    temperature = quantity("temperature", temperature, lower=180, upper=330)
+    return 611.2 * np.exp((2.5e6 / R_VAPOR) * (1 / 273.15 - 1 / temperature))
+
+
+@model
+def mixing_ratio(vapor_pressure, total_pressure):
+    """Water-vapor mass mixing ratio.
+
+    Partial pressure determines water mass per unit dry-air mass.
+
+    Parameters
+    ----------
+    vapor_pressure : float or array_like
+        Pa; constraint: nonnegative.
+    total_pressure : float or array_like
+        Pa; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Ideal vapor mixture; vapor pressure must be below total pressure.
+    Equation: ``EPSILON_WATER * vapor_pressure / (total_pressure - vapor_pressure)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    vapor_pressure = quantity("vapor_pressure", vapor_pressure, lower=0)
+    total_pressure = quantity("total_pressure", total_pressure, lower=0, strict_lower=True)
+    require(vapor_pressure < total_pressure, "vapor pressure must be below total pressure")
+    return EPSILON_WATER * vapor_pressure / (total_pressure - vapor_pressure)
+
+
+@model
+def specific_humidity(mixing_ratio):
+    """Specific humidity from mixing ratio.
+
+    Changing the denominator connects two moisture conventions.
+
+    Parameters
+    ----------
+    mixing_ratio : float or array_like
+        kg/kg dry air; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Output is water mass per total moist-air mass.
+    Equation: ``mixing_ratio / (1 + mixing_ratio)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    mixing_ratio = quantity("mixing_ratio", mixing_ratio, lower=0)
+    return mixing_ratio / (1 + mixing_ratio)
+
+
+@model
+def virtual_temperature(temperature, specific_humidity):
+    """Virtual-temperature buoyancy correction.
+
+    Moist air is less dense than dry air at the same pressure and temperature.
+
+    Parameters
+    ----------
+    temperature : float or array_like
+        K; constraint: positive.
+    specific_humidity : float or array_like
+        kg/kg moist air; constraint: fraction.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Ideal vapor mixture without suspended liquid or ice.
+    Equation: ``temperature * (1 + (1 / EPSILON_WATER - 1) * specific_humidity)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    temperature = quantity("temperature", temperature, lower=0, strict_lower=True)
+    specific_humidity = quantity("specific_humidity", specific_humidity, lower=0, upper=1)
+    return temperature * (1 + (1 / EPSILON_WATER - 1) * specific_humidity)
+
+
+@model
+def relative_humidity(vapor_pressure, saturation_pressure):
+    """Relative humidity fraction.
+
+    Humidity compares actual vapor pressure to a saturation reference.
+
+    Parameters
+    ----------
+    vapor_pressure : float or array_like
+        Pa; constraint: nonnegative.
+    saturation_pressure : float or array_like
+        Pa; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Returned fraction may exceed one during supersaturation; no clipping.
+    Equation: ``vapor_pressure / saturation_pressure``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    vapor_pressure = quantity("vapor_pressure", vapor_pressure, lower=0)
+    saturation_pressure = quantity("saturation_pressure", saturation_pressure, lower=0, strict_lower=True)
+    return vapor_pressure / saturation_pressure

earthsciencekit/atmosphere/systems/thermodynamics.py

@@ -0,0 +1,222 @@
+"""Dry thermodynamics: potential temperature, the dry adiabat, static stability, the Richardson number and parcel ascent.
+
+SI units unless stated otherwise.
+"""
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+from earthsciencekit.constants import CP_DRY_AIR, R_DRY_AIR
+
+__all__ = [
+    "potential_temperature",
+    "temperature_from_potential",
+    "dry_adiabatic_lapse_rate",
+    "brunt_vaisala_squared",
+    "richardson_number",
+    "simulate_dry_ascent",
+]
+
+
+@model
+def potential_temperature(temperature, pressure, reference_pressure):
+    """Poisson potential temperature.
+
+    Adiabatic temperature adjustment permits comparisons across pressure levels.
+
+    Parameters
+    ----------
+    temperature : float or array_like
+        K; constraint: positive.
+    pressure : float or array_like
+        Pa; constraint: positive.
+    reference_pressure : float or array_like
+        Pa; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Dry ideal gas with constant heat capacity; not equivalent potential temperature.
+    Equation: ``temperature * (reference_pressure / pressure)**(R_DRY_AIR / CP_DRY_AIR)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    temperature = quantity("temperature", temperature, lower=0, strict_lower=True)
+    pressure = quantity("pressure", pressure, lower=0, strict_lower=True)
+    reference_pressure = quantity("reference_pressure", reference_pressure, lower=0, strict_lower=True)
+    return temperature * (reference_pressure / pressure) ** (R_DRY_AIR / CP_DRY_AIR)
+
+
+@model
+def temperature_from_potential(potential_temperature, pressure, reference_pressure):
+    """Inverse potential temperature.
+
+    Potential-temperature inversion recovers the local dry-air temperature.
+
+    Parameters
+    ----------
+    potential_temperature : float or array_like
+        K; constraint: positive.
+    pressure : float or array_like
+        Pa; constraint: positive.
+    reference_pressure : float or array_like
+        Pa; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Uses the same dry-air heat capacity and reference pressure convention.
+    Equation: ``potential_temperature * (pressure / reference_pressure)**(R_DRY_AIR / CP_DRY_AIR)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    potential_temperature = quantity("potential_temperature", potential_temperature, lower=0, strict_lower=True)
+    pressure = quantity("pressure", pressure, lower=0, strict_lower=True)
+    reference_pressure = quantity("reference_pressure", reference_pressure, lower=0, strict_lower=True)
+    return potential_temperature * (pressure / reference_pressure) ** (R_DRY_AIR / CP_DRY_AIR)
+
+
+@model
+def dry_adiabatic_lapse_rate(gravity, heat_capacity):
+    """Dry adiabatic lapse rate.
+
+    Rising dry parcels cool as they perform expansion work.
+
+    Parameters
+    ----------
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+    heat_capacity : float or array_like
+        J/(kg K); constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Returned positive lapse magnitude in K per metre; temperature decreases upward.
+    Equation: ``gravity / heat_capacity``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    heat_capacity = quantity("heat_capacity", heat_capacity, lower=0, strict_lower=True)
+    return gravity / heat_capacity
+
+
+@model
+def brunt_vaisala_squared(potential_temperature, vertical_gradient, gravity):
+    """Dry static stability.
+
+    A potential-temperature gradient determines dry stratification stability.
+
+    Parameters
+    ----------
+    potential_temperature : float or array_like
+        K; constraint: positive.
+    vertical_gradient : float or array_like
+        K/m; constraint: real.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Returns signed N squared; negative values represent instability rather than an imaginary frequency.
+    Equation: ``gravity * vertical_gradient / potential_temperature``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    potential_temperature = quantity("potential_temperature", potential_temperature, lower=0, strict_lower=True)
+    vertical_gradient = quantity("vertical_gradient", vertical_gradient)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return gravity * vertical_gradient / potential_temperature
+
+
+@model
+def richardson_number(brunt_vaisala_squared, shear):
+    """Gradient Richardson number.
+
+    Stratification suppresses the turbulence that vertical wind shear generates.
+
+    Parameters
+    ----------
+    brunt_vaisala_squared : float or array_like
+        1/s^2; constraint: real.
+    shear : float or array_like
+        1/s; constraint: nonzero.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Signed; stratified shear flow can become unstable only where it falls below 1/4 (Miles-Howard).
+    Equation: ``brunt_vaisala_squared / shear**2``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    brunt_vaisala_squared = quantity("brunt_vaisala_squared", brunt_vaisala_squared)
+    shear = quantity("shear", shear)
+    require(shear != 0, "shear must be nonzero")
+    return brunt_vaisala_squared / shear**2
+
+
+@safe_arithmetic
+def simulate_dry_ascent(initial_temperature, initial_pressure, vertical_speed, time):
+    """Follow an ideal dry parcel along a hydrostatic constant-speed ascent.
+
+    Parameters
+    ----------
+    initial_temperature : float
+        Positive scalar initial temperature [K].
+    initial_pressure : float
+        Positive scalar initial pressure [Pa].
+    vertical_speed : float
+        Finite scalar vertical velocity [m/s], positive upward.
+    time : array_like
+        Nonnegative strictly increasing sampled times [s].
+
+    Returns
+    -------
+    TimeSeries
+        Parcel temperature [K] and pressure [Pa].
+
+    Notes
+    -----
+    Dry lapse and hydrostatic pressure equations use constant standard gravity
+    and dry-air heat capacity. Potential temperature should remain constant.
+    The parcel is unsaturated; condensation and environmental entrainment are
+    excluded. Reject trajectories whose predicted temperature reaches zero.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.constants import GRAVITY
+    from earthsciencekit.integrators import integrate_ode
+
+    temperature = quantity("initial_temperature", initial_temperature, lower=0, strict_lower=True)
+    pressure = quantity("initial_pressure", initial_pressure, lower=0, strict_lower=True)
+    speed = quantity("vertical_speed", vertical_speed)
+    require(temperature.ndim == pressure.ndim == speed.ndim == 0, "parcel parameters must be scalars")
+    time = time_grid(time)
+    require(temperature - GRAVITY / CP_DRY_AIR * speed * (time[-1] - time[0]) > 0, "trajectory reaches nonpositive temperature")
+    return integrate_ode(
+        lambda t, y: [-GRAVITY / CP_DRY_AIR * speed, -GRAVITY * y[1] * speed / (R_DRY_AIR * y[0])],
+        [temperature, pressure],
+        time,
+        names=("temperature", "pressure"),
+        units=("K", "Pa"),
+    )