Thermodynamics

Thermodynamics.Thermodynamics — Module

Thermodynamics

Moist thermodynamic functions for atmospheric modeling, including air pressure, latent heats, saturation vapor pressures, and saturation specific humidities.

Parameter Sets

Many functions defined in this module rely on ClimaParams.jl. ClimaParams.jl defines several functions (e.g., many planet parameters). For example, to compute the mole-mass ratio of dry air and water vapor:

import ClimaParams as CP
import Thermodynamics.Parameters as TP
FT = Float64
param_set = TP.ThermodynamicsParameters(FT)
Rv_over_Rd = TP.Rv_over_Rd(param_set)

Because these parameters are widely used throughout this module, param_set is an argument for many Thermodynamics functions.

Saturation adjustment

One entry point is saturation_adjustment. It accepts:

method: A root-solving method type from RootSolvers.jl (e.g., RS.NewtonsMethod, RS.SecantMethod).
param_set: The thermodynamics parameter set.
formulation: The thermodynamic formulation (e.g., ρe(), ph()).
Thermodynamic state variables appropriate for the formulation.

Supported methods in RootSolvers.jl:

NewtonsMethod: Newton method with analytic gradients (recommended for ρe).
NewtonsMethodAD: Newton method with automatic differentiation.
SecantMethod: Secant method (derivative-free).
BrentsMethod: Brent's method (hybrid root-finding).

Thermodynamic functions

Many thermodynamic functions (e.g., air_temperature, air_pressure) are dispatched over the independent variables used to compute them. The available independent variable types (subtypes of IndepVars) are:

ρe: Density, internal energy, and specific humidities
pe: Pressure, internal energy, and specific humidities
ph: Pressure, enthalpy, and specific humidities
pρ: Pressure, density, and specific humidities
pθ_li: Pressure, liquid-ice potential temperature, and specific humidities
ρθ_li: Density, liquid-ice potential temperature, and specific humidities

Thermodynamics Parameters

Thermodynamics.Parameters — Module

Parameters

Submodule defining thermodynamic parameter types and accessor functions.

Thermodynamics.Parameters.ThermodynamicsParameters — Type

ThermodynamicsParameters

Parameters for Thermodynamics.jl.

Example

import ClimaParams as CP
import Thermodynamics.Parameters as TP

FT = Float64;
param_set = TP.ThermodynamicsParameters(FT)

# Alternatively:

toml_dict = CP.create_toml_dict(FT)
param_set = TP.ThermodynamicsParameters(toml_dict)

Types

Thermodynamics.Phase — Type

Phase

A condensed phase, to dispatch over (e.g., in saturation_vapor_pressure).

Thermodynamics.Liquid — Type

Liquid <: Phase

A liquid phase, to dispatch over (e.g., in saturation_vapor_pressure).

Thermodynamics.Ice — Type

Ice <: Phase

An ice phase, to dispatch over (e.g., in saturation_vapor_pressure).

Thermodynamics.IndepVars — Type

IndepVars

Abstract type to dispatch over the independent variables used to compute a thermodynamic quantity (e.g., in air_temperature).

Thermodynamics.ρe — Type

ρe <: IndepVars

Density, internal energy, and specific humidity

Thermodynamics.pe — Type

pe <: IndepVars

Pressure, internal energy, and specific humidity

Thermodynamics.ph — Type

ph <: IndepVars

Pressure, enthalpy, and specific humidity

Thermodynamics.pρ — Type

pρ <: IndepVars

Pressure, density, and specific humidity

Thermodynamics.pθ_li — Type

pθ_li <: IndepVars

Pressure, liquid-ice potential temperature, and specific humidity

Thermodynamics.ρθ_li — Type

ρθ_li <: IndepVars

Density, liquid-ice potential temperature, and specific humidity

Thermodynamics.DryAdiabaticProcess — Type

DryAdiabaticProcess

A type for dispatching to isentropic (dry adiabatic) formulas.

Thermodynamic Functions

Air Properties

Thermodynamics.gas_constant_air — Function

gas_constant_air(param_set, q_tot=0, q_liq=0, q_ice=0)

The specific gas constant of moist air R_m.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

R_m: specific gas constant of moist air [J/(kg·K)]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression.

gas_constant_air(param_set, ts::ThermodynamicState)

The specific gas constant of moist air.

gas_constant_air(param_set[, q::PhasePartition])

The specific gas constant of moist air.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.cp_m — Function

cp_m(param_set, q_tot=0, q_liq=0, q_ice=0)

The isobaric specific heat capacity of moist air cp_m.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
q_tot: total specific humidity of water [kg/kg]
q_liq: specific humidity of liquid [kg/kg]
q_ice: specific humidity of ice [kg/kg]

Returns

cp_m: isobaric specific heat capacity [J/(kg·K)]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The specific heat capacities are assumed to be constant (calorically perfect air).

cp_m(param_set, ts::ThermodynamicState)

The isobaric specific heat capacity of moist air.

cp_m(param_set[, q::PhasePartition])

The isobaric specific heat capacity of moist air.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.cv_m — Function

cv_m(param_set, q_tot=0, q_liq=0, q_ice=0)

The isochoric specific heat capacity of moist air cv_m.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

cv_m: isochoric specific heat capacity [J/(kg·K)]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The specific heat capacities are assumed to be constant (calorically perfect air).

cv_m(param_set, ts::ThermodynamicState)

The isochoric specific heat capacity of moist air.

cv_m(param_set[, q::PhasePartition])

The isochoric specific heat capacity of moist air.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
q PhasePartition. Without humidity argument, the results are for dry air.

Thermodynamics.soundspeed_air — Function

soundspeed_air(param_set, T, q_tot=0, q_liq=0, q_ice=0)

The speed of sound in unstratified air.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

c: speed of sound [m/s]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The formula is c = √(γ R_m T) where γ = cp_m/cv_m.

soundspeed_air(param_set, ts::ThermodynamicState)

The speed of sound in unstratified air.

soundspeed_air(param_set, T[, q::PhasePartition])

The speed of sound in unstratified air.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Air Humidities

Thermodynamics.vapor_specific_humidity — Function

vapor_specific_humidity(q_tot=0, q_liq=0, q_ice=0)

The vapor specific humidity (clamped to be non-negative).

Arguments

q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

q_vap: vapor specific humidity [kg/kg]

If the specific humidities are not given, the result is zero. The formula is q_vap = q_tot - q_liq - q_ice.

vapor_specific_humidity(param_set, ts::ThermodynamicState)

The vapor specific humidity.

vapor_specific_humidity(q::PhasePartition)

The vapor specific humidity.

q a PhasePartition

Thermodynamics.condensate_specific_humidity — Function

condensate_specific_humidity(q_liq=0, q_ice=0)

The condensate specific humidity.

Arguments

q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

q_cond: condensate specific humidity [kg/kg]

If the specific humidities are not given, the result is zero. The formula is q_cond = q_liq + q_ice.

condensate_specific_humidity(param_set, ts::ThermodynamicState)

The condensate specific humidity (liquid + ice).

condensate_specific_humidity(q::PhasePartition{FT})

The condensate specific humidity (liquid + ice) of the phase partition q.

Thermodynamics.vol_vapor_mixing_ratio — Function

vol_vapor_mixing_ratio(param_set, q_tot=0, q_liq=0, q_ice=0)

The molar (volume) mixing ratio of water vapor.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

r_v: molar mixing ratio of water vapor [mol/mol]

If the specific humidities are not given, the result is zero.

vol_vapor_mixing_ratio(param_set, ts::ThermodynamicState)

The volume mixing ratio of water vapor.

vol_vapor_mixing_ratio(param_set, q::PhasePartition)

The volume mixing ratio of water vapor.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
q PhasePartition

Thermodynamics.partial_pressure_dry — Function

partial_pressure_dry(param_set, p, q_tot=0, q_liq=0, q_ice=0)

The partial pressure of dry air.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: air pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

p_d: partial pressure of dry air [Pa]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this equals the total pressure.

partial_pressure_dry(param_set, ts::ThermodynamicState)

The partial pressure of dry air.

partial_pressure_dry(param_set, p, q::PhasePartition)

The partial pressure of dry air.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p air pressure
q phase partition

Thermodynamics.partial_pressure_vapor — Function

partial_pressure_vapor(param_set, p, q_tot=0, q_liq=0, q_ice=0)

The partial pressure of water vapor.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: air pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

p_v: partial pressure of water vapor [Pa]

If the specific humidities are not given, the partial pressure is zero.

partial_pressure_vapor(param_set, ts::ThermodynamicState)

The partial pressure of water vapor.

partial_pressure_vapor(param_set, p, q::PhasePartition)

The partial pressure of water vapor.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p air pressure
q phase partition

Thermodynamics.vapor_pressure_deficit — Function

vapor_pressure_deficit(param_set, T, p, q_tot, q_liq, q_ice, phase::Phase)

The vapor pressure deficit (saturation vapor pressure minus actual vapor pressure, truncated to be non-negative) over a specific phase (Liquid or Ice).

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: air temperature [K]
p: air pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]
phase: phase to compute saturation over (Liquid() or Ice())

Returns

VPD: vapor pressure deficit [Pa]

vapor_pressure_deficit(param_set, T, p, q_tot=0, q_liq=0, q_ice=0)

The vapor pressure deficit (saturation vapor pressure minus actual vapor pressure, truncated to be non-negative) over liquid water for temperatures above freezing and over ice for temperatures below freezing.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: air temperature [K]
p: air pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

VPD: vapor pressure deficit [Pa]

If the specific humidities are not given, the result is the saturation vapor pressure.

vapor_pressure_deficit(param_set, T, p[, q::PhasePartition])

The vapor pressure deficit (saturation vapor pressure minus actual vapor pressure, truncated to be non-negative) over liquid water for temperatures above freezing and over ice for temperatures below freezing.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T air temperature
p air pressure
q PhasePartition

When q is not provided, the vapor pressure deficit is the saturation vapor pressure.

Thermodynamics.relative_humidity — Function

relative_humidity(param_set, T, p, q_tot=0, q_liq=0, q_ice=0)

The relative humidity (clipped between 0 and 1).

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
p: pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

RH: relative humidity [dimensionless], 0 ≤ RH ≤ 1

If q_liq and q_ice are zero (or not given), the relative humidity is computed relative to saturation over ice below freezing and over liquid above freezing. If condensate is present, the relative humidity is computed relative to saturation over a mixture of liquid and ice, with the liquid fraction given by the ratio q_liq / (q_liq + q_ice).

Note: relative_humidity uses saturation_vapor_pressure(param_set, T, q_liq, q_ice). In particular, for q_liq == q_ice == 0 it includes a small smooth transition around freezing (via liquid_fraction(param_set, T, q_liq, q_ice)).

relative_humidity(param_set, ts::ThermodynamicState)

The relative humidity.

relative_humidity(param_set, T, p, phase_type, q::PhasePartition)

The relative humidity (clipped between 0 and 1).

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
p pressure
phase_type a thermodynamic state type
q PhasePartition.

Thermodynamics.condensate_partition — Function

condensate_partition(param_set, T, ρ, q_tot)

Compute the equilibrium liquid and ice specific humidities from the condensate in thermodynamic equilibrium, returning a tuple (q_liq, q_ice).

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]

Returns

(q_liq, q_ice): tuple of liquid and ice specific humidities [kg/kg]

The condensate is partitioned into liquid and ice using the temperature-dependent liquid fraction (see liquid_fraction) and the saturation excess (see saturation_excess).

Thermodynamics.has_condensate — Function

has_condensate(q_c)

Bool indicating if condensate exists, i.e., q_c > eps.

We use a threshold of eps rather than 0 to avoid division by zero in functions such as liquid_fraction and to robustly handle numerical noise.

has_condensate(param_set, ts::ThermodynamicState)

Bool indicating if condensate exists.

has_condensate(q::PhasePartition{FT})

Bool indicating if condensate exists in the phase partition

Thermodynamics.liquid_fraction — Function

liquid_fraction(param_set, T, q_liq, q_ice)

The fraction of condensate that is liquid.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

λ: liquid fraction [dimensionless], 0 ≤ λ ≤ 1

The liquid fraction is computed from q_liq and q_ice. If q_liq + q_ice exceeds a small threshold (see has_condensate), q_liq / (q_liq + q_ice) is returned. If there is effectively no condensate, a smooth temperature-dependent partitioning is used (linear ramp from 0 to 1 over ±0.1 K around freezing).

liquid_fraction(param_set, ts::ThermodynamicState)

The fraction of condensate that is liquid.

Thermodynamics.liquid_fraction_ramp — Function

liquid_fraction_ramp(param_set, T)

The liquid fraction computed from temperature using a power law interpolation between T_icenuc and T_freeze.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

λ: liquid fraction [dimensionless], 0 ≤ λ ≤ 1

Edge cases:

For T > T_freeze, this returns 1; for T ≤ T_icenuc, it returns 0.

Reference

Kaul et al. (2015), "Sensitivities in large-eddy simulations of mixed-phase Arctic stratocumulus clouds using a simple microphysics approach," Monthly Weather Review, 143, 4393-4421, doi:10.1175/MWR-D-14-00319.1.

Thermodynamics.specific_humidity_to_mixing_ratio — Function

specific_humidity_to_mixing_ratio(q, q_tot)

Converts specific humidity to mixing ratio (total basis).

Arguments

q: specific humidity of interest [kg/kg]
q_tot: total specific humidity [kg/kg]

Returns

r: mixing ratio [kg/kg]

Note that this function is singular when q_tot = 1. The formula is r = q / (1 - q_tot).

Air Energies

Thermodynamics.internal_energy — Function

internal_energy(param_set, T, q_tot=0, q_liq=0, q_ice=0)

The internal energy per unit mass.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

e_int: specific internal energy [J/kg]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The internal energy is computed as a mass-weighted sum of the internal energies of each component (dry air, vapor, liquid, ice), referenced to T_0.

internal_energy(param_set, ts::ThermodynamicState)

The internal energy per unit mass.

internal_energy(param_set, T[, q::PhasePartition])

The internal energy per unit mass.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.internal_energy_dry — Function

internal_energy_dry(param_set, T)

The dry air internal energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

e_d: specific internal energy of dry air [J/kg]

internal_energy_dry(param_set, ts::ThermodynamicState)

The dry air internal energy.

Thermodynamics.internal_energy_vapor — Function

internal_energy_vapor(param_set, T)

The water vapor internal energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

e_v: specific internal energy of water vapor [J/kg]

internal_energy_vapor(param_set, ts::ThermodynamicState)

The water vapor internal energy.

Thermodynamics.internal_energy_liquid — Function

internal_energy_liquid(param_set, T)

The liquid water internal energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

e_l: specific internal energy of liquid water [J/kg]

internal_energy_liquid(param_set, ts::ThermodynamicState)

The liquid water internal energy.

Thermodynamics.internal_energy_ice — Function

internal_energy_ice(param_set, T)

The ice internal energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

e_i: specific internal energy of ice [J/kg]

internal_energy_ice(param_set, ts::ThermodynamicState)

The ice internal energy.

Thermodynamics.enthalpy — Function

enthalpy(e_int, R_m, T)

The specific enthalpy.

Arguments

e_int: internal specific energy [J/kg]
R_m: gas constant of moist air [J/(kg·K)], see gas_constant_air
T: air temperature [K]

Returns

h: specific enthalpy [J/kg]

The enthalpy is computed as h = e_int + R_m T, which follows from h = e_int + p v with the ideal gas law p v = R_m T (specific volume v = 1/ρ).

enthalpy(param_set, T, q_tot=0, q_liq=0, q_ice=0)

The specific enthalpy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

h: specific enthalpy [J/kg]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The enthalpy is computed as a mass-weighted sum of the enthalpies of each component (dry air, vapor, liquid, ice).

enthalpy(param_set, ts)

The specific enthalpy.

enthalpy(param_set, T, q::PhasePartition)

The specific enthalpy.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
q PhasePartition.

Thermodynamics.enthalpy_dry — Function

enthalpy_dry(param_set, T)

The specific enthalpy of dry air.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

h_d: specific enthalpy of dry air [J/kg]

Thermodynamics.enthalpy_vapor — Function

enthalpy_vapor(param_set, T)

The specific enthalpy of water vapor.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]

Returns

h_v: specific enthalpy of water vapor [J/kg]

Thermodynamics.enthalpy_liquid — Function

enthalpy_liquid(param_set, T)

The specific enthalpy of liquid.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

h_l: specific enthalpy of liquid [J/kg]

The specific enthalpy of liquid is equal to the internal energy of liquid because the specific volume of condensed water is neglected (i.e., p v_l ≈ 0).

Thermodynamics.enthalpy_ice — Function

enthalpy_ice(param_set, T)

The specific enthalpy of ice.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

h_i: specific enthalpy of ice [J/kg]

The specific enthalpy of ice is equal to the internal energy of ice because the specific volume of condensed water is neglected (i.e., p v_i ≈ 0).

Thermodynamics.total_energy — Function

total_energy(param_set, e_kin, e_pot, T, q_tot=0, q_liq=0, q_ice=0)

The total energy per unit mass.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
e_kin: kinetic energy per unit mass [J/kg]
e_pot: gravitational potential energy (geopotential)per unit mass [J/kg]
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

e_tot: total specific energy [J/kg]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The total energy is e_tot = e_int + e_kin + e_pot.

total_energy(param_set, ts::ThermodynamicState, e_kin, e_pot)

The total energy per unit mass.

total_energy(param_set, e_kin, e_pot, T[, q::PhasePartition])

The total energy per unit mass.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
e_kin kinetic energy per unit mass
e_pot gravitational potential energy per unit mass
T temperature

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.total_enthalpy — Function

total_enthalpy(e_tot, R_m, T)

The total specific enthalpy.

Arguments

e_tot: total specific energy [J/kg]
R_m: gas constant of moist air [J/(kg·K)], see gas_constant_air
T: air temperature [K]

Returns

h_tot: total specific enthalpy [J/kg]

The total enthalpy is computed as h_tot = e_tot + R_m T.

total_enthalpy(param_set, ts, e_tot::Real)

The total specific enthalpy.

total_enthalpy(param_set, e_tot, T[, q::PhasePartition])

The total specific enthalpy, defined as e_tot + R_m * T.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
e_tot total specific energy
T temperature

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.dry_static_energy — Function

dry_static_energy(param_set, T, e_pot)

The dry static energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
e_pot: gravitational potential energy per unit mass (geopotential) [J/kg]

Returns

s_d: dry static energy [J/kg]

The dry static energy is the sum of the dry enthalpy and geopotential: s_d = h_d + e_pot.

Thermodynamics.vapor_static_energy — Function

vapor_static_energy(param_set, T, e_pot)

The static energy (sensible heat only) of water vapor.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
e_pot: gravitational potential energy per unit mass (geopotential) [J/kg]

Returns

s_v: vapor static energy [J/kg]

The formula is s_v = cp_v * (T - T_0) + e_pot, where T_0 is the reference temperature.

Thermodynamics.moist_static_energy — Function

moist_static_energy(param_set, T, e_pot, q_tot=0, q_liq=0, q_ice=0)

The moist static energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
e_pot: gravitational potential energy per unit mass (geopotential) [J/kg]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

s_m: moist static energy [J/kg]

If the specific humidities are not given, the result is for dry air. The moist static energy is the sum of the moist enthalpy and geopotential: s_m = h + e_pot, where h is computed from enthalpy.

moist_static_energy(param_set, ts, e_pot)

The moist static energy.

moist_static_energy(param_set, T, e_pot, q::PhasePartition)

The moist static energy.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
e_pot gravitational potential energy per unit mass (geopotential)
q PhasePartition.

Thermodynamics.virtual_dry_static_energy — Function

virtual_dry_static_energy(param_set, T, e_pot, q_tot=0, q_liq=0, q_ice=0)

The virtual dry static energy.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
e_pot: gravitational potential energy per unit mass (geopotential) [J/kg]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

s_vd: virtual dry static energy [J/kg]

If the specific humidities are not given, the result is for dry air. The virtual dry static energy is s_vd = cp_d * (T_virt - T_0) + e_pot, where T_virt is the virtual temperature (see virtual_temperature) and T_0 is the reference temperature.

virtual_dry_static_energy(param_set, ts, e_pot)

The virtual dry static energy.

virtual_dry_static_energy(param_set, T, e_pot, q::PhasePartition)

The virtual dry static energy.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
e_pot gravitational potential energy per unit mass (geopotential)
q PhasePartition.

Thermodynamics.latent_heat_fusion — Function

latent_heat_fusion(param_set, T)

The specific latent heat of fusion L_f.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

L_f: latent heat of fusion [J/kg]

Because the specific heats are assumed constant, the latent heats are linear functions of temperature by Kirchhoff's law.

latent_heat_fusion(param_set, ts::ThermodynamicState)

The specific latent heat of fusion.

Thermodynamics.latent_heat_sublim — Function

latent_heat_sublim(param_set, T)

The specific latent heat of sublimation L_s.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

L_s: latent heat of sublimation [J/kg]

Because the specific heats are assumed constant, the latent heats are linear functions of temperature by Kirchhoff's law.

latent_heat_sublim(param_set, ts::ThermodynamicState)

The specific latent heat of sublimation.

Thermodynamics.latent_heat_vapor — Function

latent_heat_vapor(param_set, T)

The specific latent heat of vaporization L_v.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]

Returns

L_v: latent heat of vaporization [J/kg]

Because the specific heats are assumed constant, the latent heats are linear functions of temperature by Kirchhoff's law.

latent_heat_vapor(param_set, ts::ThermodynamicState)

The specific latent heat of vaporization.

Thermodynamics.latent_heat_mixed — Function

latent_heat_mixed(param_set, T, λ)

The specific latent heat of a mixed phase, weighted by the liquid fraction λ.

param_set thermodynamics parameter set, see the Thermodynamics for more details
T air temperature
λ liquid fraction

Because the specific heats are assumed constant, the latent heats are linear functions of temperature by Kirchhoff's law.

Thermodynamics.humidity_weighted_latent_heat — Function

humidity_weighted_latent_heat(param_set, q_liq=0, q_ice=0)

Specific-humidity weighted sum of latent heats of liquid and ice evaluated at reference temperature T_0.

param_set thermodynamics parameter set, see the Thermodynamics for more details
q_liq liquid specific humidity
q_ice ice specific humidity

If q_liq and q_ice are not provided, humidity_weighted_latent_heat is zero.

humidity_weighted_latent_heat(param_set::APS, ts::ThermodynamicState)

Specific-humidity weighted sum of latent heats of liquid and ice evaluated at reference temperature T_0.

humidity_weighted_latent_heat(param_set[, q::PhasePartition])

Specific-humidity weighted sum of latent heats of liquid and ice evaluated at reference temperature T_0.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
q PhasePartition.

When q is not provided, humidity_weighted_latent_heat is zero.

This is used in the evaluation of the liquid-ice potential temperature.

Air Temperatures

Thermodynamics.air_temperature — Function

air_temperature(param_set, e_int, q_tot=0, q_liq=0, q_ice=0)

The air temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
e_int: specific internal energy of moist air [J/kg]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T: air temperature [K]

If the specific humidities are not given, the result is for dry air. This method inverts internal_energy by solving for T given e_int.

air_temperature(param_set, ::ph, h, q_tot=0, q_liq=0, q_ice=0)

The air temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
h: specific enthalpy of moist air [J/kg]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T: air temperature [K]

If the specific humidities are not given, the result is for dry air. This method inverts enthalpy by solving for T given h.

air_temperature(param_set, ::pρ, p, ρ, q_tot=0, q_liq=0, q_ice=0)

The air temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
p: air pressure [Pa]
ρ: air density [kg/m³]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T: air temperature [K]

If the specific humidities are not given, the result is for dry air. This directly applies the ideal gas law: T = p / (R_m ρ).

air_temperature(
    param_set,
    ::pθ_li,
    p,
    θ_li,
    q_tot=0,
    q_liq=0,
    q_ice=0
)

The air temperature obtained by inverting the liquid-ice potential temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
p: pressure [Pa]
θ_li: liquid-ice potential temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T: air temperature [K]

If the specific humidities are not given, θ_li is assumed to be the dry-air potential temperature. This inverts liquid_ice_pottemp_given_pressure by solving for T.

air_temperature(param_set, ::ρθ_li, ρ, θ_li, q_tot=0, q_liq=0, q_ice=0)

The air temperature obtained by inverting the liquid-ice potential temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
ρ: (moist-)air density [kg/m³]
θ_li: liquid-ice potential temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T: air temperature [K]

If the specific humidities are not given, the results are for dry air.

Method

This function uses a second-order Taylor expansion to avoid an iterative inversion. The unsaturated temperature T_unsat is first computed assuming the ideal gas law with potential temperature, then latent heat corrections are applied.

air_temperature(param_set, ::DryAdiabaticProcess, p, θ)

The air temperature for an isentropic process.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: pressure [Pa]
θ: potential temperature [K]

Returns

T: air temperature [K]

The temperature is computed using the definition of the dry potential temperature: T = θ * (p/p₀)^κ_d, where p₀ is the reference pressure and κ_d = R_d/cp_d.

air_temperature(param_set, ts::ThermodynamicState)

The air temperature.

air_temperature(param_set, e_int[, q::PhasePartition])

The air temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
e_int specific internal energy of moist air

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.potential_temperature — Function

potential_temperature(param_set, T, ρ, q_tot=0, q_liq=0, q_ice=0)

The potential temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

θ: potential temperature [K]

If the specific humidities are not given, the result is for dry air.

Note: if any of q_tot, q_liq, or q_ice are nonzero, the Exner function uses the moist exponent R_m/cp_m (reducing to the dry exponent R_d/cp_d in the dry limit).

potential_temperature(param_set, ts::ThermodynamicState)

The dry potential temperature.

potential_temperature(param_set, T, ρ[, q::PhasePartition])

The dry potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.potential_temperature_given_pressure — Function

potential_temperature_given_pressure(param_set, T, p, q_tot=0, q_liq=0, q_ice=0)

The potential temperature.

param_set thermodynamics parameter set, see the Thermodynamics for more details
T temperature
p pressure
q_tot total specific humidity
q_liq liquid specific humidity
q_ice ice specific humidity

If the specific humidities are not given, the result is for dry air.

Note: if any of q_tot, q_liq, or q_ice are nonzero, the Exner function uses the moist exponent R_m/cp_m (reducing to the dry exponent R_d/cp_d in the dry limit).

potential_temperature_given_pressure(param_set, T, p[, q::PhasePartition])

The dry potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
p pressure

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air, i.e., using the adiabatic exponent for dry air.

Thermodynamics.liquid_ice_pottemp — Function

liquid_ice_pottemp(param_set, T, ρ, q_tot=0, q_liq=0, q_ice=0)

The liquid-ice potential temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

θ_li: liquid-ice potential temperature [K]

If the specific humidities are not given, the result is for dry air.

Reference

Betts (1973), "Non-precipitating cumulus convection and its parameterization," Quarterly Journal of the Royal Meteorological Society, 99, 178-196, doi:10.1002/qj.49709941915.

liquid_ice_pottemp(param_set, ts::ThermodynamicState)

The liquid-ice potential temperature.

liquid_ice_pottemp(param_set, T, ρ[, q::PhasePartition])

The liquid-ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density

and, optionally,

q PhasePartition.

When q is not provided, the result is the dry-air potential temperature.

Thermodynamics.liquid_ice_pottemp_given_pressure — Function

liquid_ice_pottemp_given_pressure(param_set, T, p, q_tot=0, q_liq=0, q_ice=0)

The liquid-ice potential temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
p: pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

θ_li: liquid-ice potential temperature [K]

If the specific humidities are not given, the result is for dry air. The latent heats of phase transitions are approximated as constants.

Reference

Betts (1973), "Non-precipitating cumulus convection and its parameterization," Quarterly Journal of the Royal Meteorological Society, 99, 178-196, doi:10.1002/qj.49709941915.

liquid_ice_pottemp_given_pressure(param_set, T, p[, q::PhasePartition])

The liquid-ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
p pressure

and, optionally,

q PhasePartition.

When q is not provided, the result is the dry-air potential temperature.

Thermodynamics.virtual_pottemp — Function

virtual_pottemp(param_set, T, ρ, q_tot=0, q_liq=0, q_ice=0)

The virtual potential temperature.

param_set thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density
q_tot total specific humidity
q_liq liquid specific humidity
q_ice ice specific humidity

If the specific humidities are not given, the result is for dry air.

virtual_pottemp(param_set, ts::ThermodynamicState)

The virtual potential temperature.

virtual_pottemp(param_set, T, ρ[, q::PhasePartition])

The virtual potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density

and, optionally,

q PhasePartition.

The virtual potential temperature is defined as θ_v = (R_m/R_d) * θ, where θ is the potential temperature. It is the potential temperature a dry air parcel would need to have to have the same density as the moist air parcel at the same pressure.

Thermodynamics.virtual_temperature — Function

virtual_temperature(param_set, T, q_tot=0, q_liq=0, q_ice=0)

The virtual temperature.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

T_v: virtual temperature [K]

If the specific humidities are not given, the result is for dry air. The virtual temperature is defined such that dry air at T_v has the same density as moist air at T, i.e., T_v = T (R_m / R_d).

virtual_temperature(param_set, ts::ThermodynamicState)

The virtual temperature.

virtual_temperature(param_set, T, q::PhasePartition)

The virtual temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
q PhasePartition.

The virtual temperature is defined as T_v = (R_m/R_d) * T. It is the temperature a dry air parcel would need to have to have the same density as the moist air parcel at the same pressure.

Air Pressure and Density

Thermodynamics.air_pressure — Function

air_pressure(param_set, T, ρ, q_tot=0, q_liq=0, q_ice=0)

The air pressure from the equation of state (ideal gas law).

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: air temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

p: air pressure [Pa]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The formula is p = ρ R_m T where R_m is the gas constant of moist air (see gas_constant_air).

air_pressure(param_set, ::DryAdiabaticProcess, T, T∞, p∞)

The air pressure for an isentropic process.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: current temperature [K]
T∞: reference temperature [K]
p∞: reference pressure [Pa]

Returns

p: air pressure [Pa]

The pressure is computed using the isentropic relation: p = p∞ * (T/T∞)^(1/κ_d), where κ_d = R_d/cp_d is the ratio of the gas constant to the isobaric specific heat constant of dry air.

air_pressure(param_set, ts::ThermodynamicState)

The air pressure from the equation of state (ideal gas law).

air_pressure(param_set, T, ρ[, q::PhasePartition])

The air pressure from the equation of state (ideal gas law).

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T air temperature
ρ (moist-)air density

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.air_density — Function

air_density(param_set, T, p, q_tot=0, q_liq=0, q_ice=0)

The (moist-)air density from the equation of state (ideal gas law).

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: air temperature [K]
p: pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

ρ: (moist-)air density [kg/m³]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The formula is ρ = p / (R_m T) where R_m is the gas constant of moist air (see gas_constant_air).

air_density(param_set, ts::ThermodynamicState)

The (moist-)air density.

air_density(param_set, T, p[, q::PhasePartition])

The (moist-)air density from the equation of state (ideal gas law).

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T air temperature
p pressure

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.exner — Function

exner(param_set, T, ρ, q_tot=0, q_liq=0, q_ice=0)

The Exner function Π = (p/p₀)^(R_m/cp_m).

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
T: temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

Π: Exner function [dimensionless]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The pressure is computed internally from the equation of state (see air_pressure).

exner(param_set, ts::ThermodynamicState)

The Exner function.

exner(param_set, T, ρ[, q::PhasePartition)])

The Exner function.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.exner_given_pressure — Function

exner_given_pressure(param_set, p, q_tot=0, q_liq=0, q_ice=0)

The Exner function Π = (p/p₀)^(R_m/cp_m), where p₀ is the reference pressure.

Arguments

param_set: thermodynamics parameter set, see the Thermodynamics for more details
p: pressure [Pa]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

Π: Exner function [dimensionless]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The reference pressure p₀ is p_ref_theta from the parameter set.

exner_given_pressure(param_set, p[, q::PhasePartition, cpm])

The Exner function.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.air_pressure_given_θ — Function

air_pressure_given_θ(param_set, ::DryAdiabaticProcess, θ, Φ)

The air pressure for an isentropic process.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
θ: potential temperature [K]
Φ: gravitational potential [J/kg]

Returns

p: air pressure [Pa]

The pressure is computed using the hydrostatic balance and the definition of potential temperature for an isentropic process: p = p₀ * (1 - Φ/(θ * cp_d))^(1/κ_d), where p₀ is the reference pressure, cp_d is the isobaric specific heat capacity of dry air, and κ_d = R_d/cp_d.

Air Saturation Functions

Thermodynamics.saturation_vapor_pressure — Function

saturation_vapor_pressure(param_set, T, ::Liquid)
saturation_vapor_pressure(param_set, T, ::Ice)

The saturation vapor pressure over a plane surface of condensate.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
Liquid() or Ice() to dispatch over the condensate type

Returns

p_v^*: saturation vapor pressure [Pa]

The saturation vapor pressure is computed by integration of the Clausius-Clapeyron relation, assuming constant specific heat capacities in the so-called Rankine-Kirchhoff approximation.

saturation_vapor_pressure(param_set, T)
saturation_vapor_pressure(param_set, T, q_liq, q_ice)

The saturation vapor pressure over liquid, ice, or a mixture of liquid and ice.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
q_liq: (optional) liquid specific humidity [kg/kg]
q_ice: (optional) ice specific humidity [kg/kg]

Returns

p_v^*: saturation vapor pressure [Pa]

If q_liq and q_ice are provided, the saturation vapor pressure is computed from a weighted mean of the latent heats of vaporization and sublimation, with the weights given by the liquid fraction (see liquid_fraction). If q_liq and q_ice are 0, the saturation vapor pressure is that over liquid above freezing and over ice below freezing.

Otherwise, the liquid fraction below freezing is computed from a temperature dependent parameterization liquid_fraction_ramp(param_set, T).

Edge case: the saturation_vapor_pressure(param_set, T, q_liq, q_ice) form includes a small smooth transition around freezing when q_liq == q_ice == 0 (via liquid_fraction(param_set, T, q_liq, q_ice)).

saturation_vapor_pressure(param_set, ts::ThermodynamicState, ::Liquid)

The saturation vapor pressure over a plane surface of condensate.

saturation_vapor_pressure(param_set, ts::ThermodynamicState, ::Ice)

The saturation vapor pressure over a plane surface of condensate.

saturation_vapor_pressure(param_set, T, q::PhasePartition)

The saturation vapor pressure.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
q PhasePartition.

Thermodynamics.q_vap_saturation — Function

q_vap_saturation(param_set, T, ρ)
q_vap_saturation(param_set, T, ρ, q_liq, q_ice)

The saturation specific humidity.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
ρ: air density [kg/m³]
(optional) q_liq: liquid specific humidity [kg/kg]
(optional) q_ice: ice specific humidity [kg/kg]

Returns

q_v^*: saturation specific humidity [kg/kg]

If q_liq and q_ice are provided, the saturation specific humidity is that over a mixture of liquid and ice, computed in a thermodynamically consistent way from the weighted sum of the latent heats of the respective phase transitions. That is, the saturation vapor pressure and from it the saturation specific humidity are computed from a weighted mean of the latent heats of vaporization and sublimation, with the weights given by the liquid fraction (see liquid_fraction). If q_liq and q_ice are 0, the saturation specific humidity is that over liquid above freezing and over ice below freezing.

Otherwise, the fraction of liquid is given by the temperature dependent liquid_fraction_ramp(param_set, T).

Reference

Pressel et al. (2015), "Numerics and subgrid-scale modeling in large eddy simulations of stratocumulus clouds," Journal of Advances in Modeling Earth Systems, 7(3), 1199-1220, doi:10.1002/2014MS000376.

q_vap_saturation(param_set, T, ρ, phase::Phase)

The saturation specific humidity.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
ρ: (moist-)air density [kg/m³]
phase: the phase to compute saturation over (either Liquid() or Ice())

Returns

q_v^*: saturation specific humidity [kg/kg]

q_vap_saturation(param_set, ts::ThermodynamicState)

The saturation specific humidity.

q_vap_saturation(param_set, T, ρ, q::PhasePartition)

The saturation specific humidity.

param_set: an thermodynamics parameter set, see the Thermodynamics for more details
T: temperature
ρ: air density
q: PhasePartition

If the PhasePartition q is given, the saturation specific humidity is that over a mixture of liquid and ice, computed in a thermodynamically consistent way from the weighted sum of the latent heats of the respective phase transitions (Pressel et al., JAMES, 2015).

Thermodynamics.supersaturation — Function

supersaturation(param_set, q_vap, ρ, T[, phase::Phase = Liquid()])

The supersaturation over water or ice.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
q_vap: vapor specific humidity [kg/kg]
ρ: air density [kg/m³]
T: air temperature [K]
phase: (optional) liquid or ice phase to dispatch over (default: Liquid())

Returns

S: supersaturation [dimensionless], defined as p_v/p_v^* - 1

supersaturation(param_set, q_vap, ρ, T, p_v_sat)

The supersaturation given the saturation vapor pressure.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
q_vap: vapor specific humidity [kg/kg]
ρ: air density [kg/m³]
T: temperature [K]
p_v_sat: saturation vapor pressure [Pa]

Returns

S: supersaturation [dimensionless], defined as p_v/p_v_sat - 1

supersaturation(param_set::APS, ts::ThermodynamicState, phase::Phase)

The supersaturation (pv/pv_sat -1) over water or ice.

supersaturation(param_set, q, ρ, T, Liquid())
supersaturation(param_set, q, ρ, T, Ice())

The supersaturation (pv/pv_sat -1) over water or ice.

param_set - abstract set with earth parameters
q - phase partition
ρ - air density,
T - air temperature
Liquid(), Ice() - liquid or ice phase to dispatch over.

supersaturation(param_set, q::PhasePartition, ρ, T, p_v_sat)

The supersaturation (pv/pvsat - 1) given the saturation vapor pressure `pv_sat`:

param_set: Thermodynamic parameter set
q: Phase partition
ρ: Air density
T: Temperature
p_v_sat: Saturation vapor pressure

Thermodynamics.saturation_excess — Function

saturation_excess(param_set, T, ρ, q_tot)
saturation_excess(param_set, T, ρ, q_tot, q_liq, q_ice)

The saturation excess in equilibrium.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
ρ: (moist-)air density [kg/m³]
q_tot: total specific humidity [kg/kg]
(optional) q_liq: liquid specific humidity [kg/kg]
(optional) q_ice: ice specific humidity [kg/kg]

Returns

q_ex: saturation excess [kg/kg]

The saturation excess is the difference between the total specific humidity q_tot and the saturation specific humidity in equilibrium, and it is defined to be nonzero only if this difference is positive: q_ex = max(0, q_tot - q_v^*).

saturation_excess(param_set, T, ρ, q_tot, p_vap_sat)

The saturation excess given the saturation vapor pressure.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: temperature [K]
ρ: air density [kg/m³]
q_tot: total specific humidity [kg/kg]
p_vap_sat: saturation vapor pressure [Pa]

Returns

q_ex: saturation excess [kg/kg]

The saturation excess is the difference between the total specific humidity q_tot and the saturation specific humidity, and it is defined to be nonzero only if this difference is positive: q_ex = max(0, q_tot - q_v^*).

saturation_excess(param_set, ts::ThermodynamicState)

The saturation excess in equilibrium.

saturation_excess(param_set, T, ρ, phase_type, q::PhasePartition)

The saturation excess in equilibrium.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density
phase_type a thermodynamic state type
q PhasePartition

The saturation excess is the difference between the total specific humidity q.tot and the saturation specific humidity in equilibrium, and it is defined to be nonzero only if this difference is positive.

saturation_excess(param_set, T, ρ, p_vap_sat, q::PhasePartition)

The saturation excess given the saturation vapor pressure p_vap_sat:

param_set: Thermodynamic parameter set
T: Temperature
ρ: Air density
p_vap_sat: Saturation vapor pressure
q: Phase partition

The saturation excess is the difference between the total specific humidity q.tot and the saturation specific humidity, and it is defined to be nonzero only if this difference is positive.

Thermodynamics.q_vap_from_RH — Function

q_vap_from_RH(param_set, p, T, RH, phase)

Compute the vapor specific humidity from the relative humidity.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: pressure [Pa]
T: temperature [K]
RH: relative humidity [dimensionless], 0 ≤ RH ≤ 1
phase: the phase to compute saturation over (either Liquid() or Ice())

Returns

q_vap: vapor specific humidity [kg/kg]

Thermodynamics.q_vap_from_p_vap — Function

q_vap_from_p_vap(param_set, T, ρ, p_v)

Compute the vapor specific humidity from the vapor partial pressure.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
T: air temperature [K]
ρ: (moist-)air density [kg/m³]
p_v: partial pressure of water vapor [Pa]

Returns

q_vap: vapor specific humidity [kg/kg]

Thermodynamics.q_vap_saturation_from_pressure — Function

q_vap_saturation_from_pressure(param_set, q_tot, p, T)
q_vap_saturation_from_pressure(param_set, q_tot, p, T, q_liq, q_ice)

The saturation specific humidity.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
q_tot: total water specific humidity [kg/kg]
p: air pressure [Pa]
T: air temperature [K]
(optional) q_liq: liquid specific humidity [kg/kg]
(optional) q_ice: ice specific humidity [kg/kg]

Returns

q_v^*: saturation specific humidity [kg/kg]

If q_liq and q_ice are provided, the saturation vapor pressure is computed from a weighted mean of the latent heats of vaporization and sublimation, with the weights given by the liquid fraction (see liquid_fraction). If q_liq and q_ice are 0, the saturation vapor pressure is that over liquid above freezing and over ice below freezing.

Otherwise, the liquid fraction is computed from a temperature dependent parameterization liquid_fraction_ramp(param_set, T).

The saturation specific humidity is computed as: $q_v^* = (R_d / R_v) * (1 - q_{tot}) * p_v^* / (p - p_v^*)$ where p_v^* is the saturation vapor pressure.

Edge case: this expression assumes p > p_v^*(T); if p ≤ p_v^*(T) the denominator changes sign.

Saturation Adjustment

Thermodynamics.saturation_adjustment — Function

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::ρe,
    ρ::Real,
    e_int::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real} = nothing],
    [forced_fixed_iters::Bool = false]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given density ρ, internal energy e_int, and total specific humidity q_tot.

Arguments

M: Root-solving method type from RS.jl. Use RS.NewtonsMethod, RS.SecantMethod, RS.BrentsMethod, or RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
ρ: Density of moist air [kg/m³].
e_int: Specific internal energy [J/kg].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K]. Defaults to nothing.
forced_fixed_iters: Optional boolean to force a fixed number of iterations (maxiter) without checking for convergence. Useful for GPU optimization to avoid branch divergence. When true, T_guess and tol are ignored. Defaults to false.

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

Notes

This function solves for T such that e_int = internal_energy_sat(param_set, T, ρ, q_tot) using root-finding, then computes (q_liq, q_ice) from condensate_partition.
For ρe formulation, NewtonsMethod is recommended (fast + analytic derivative available).
For other formulations, SecantMethod or BrentsMethod are recommended.
GPU broadcasting: Pass forced_fixed_iters as a positional Bool.

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::pe,
    p::Real,
    e_int::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real}]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given pressure p, specific internal energy e_int, and total specific humidity q_tot.

Arguments

M: Root-solving method type from RootSolvers.jl. Supported types: RS.SecantMethod, RS.BrentsMethod, RS.NewtonsMethod, RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
p: Pressure of moist air [Pa].
e_int: Specific internal energy [J/kg].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K].

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::ph,
    p::Real,
    h::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real}]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given pressure p, specific enthalpy h, and total specific humidity q_tot.

Returns a NamedTuple (; T, q_liq, q_ice, converged).

Arguments

M: Root-solving method type from RootSolvers.jl. Supported types: RS.SecantMethod, RS.BrentsMethod, RS.NewtonsMethod, RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
p: Pressure of moist air [Pa].
h: Specific enthalpy [J/kg].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K].

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::pθ_li,
    p::Real,
    θ_li::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real}]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given pressure p, liquid-ice potential temperature θ_li, and total specific humidity q_tot.

Arguments

M: Root-solving method type from RootSolvers.jl. Supported types: RS.SecantMethod, RS.BrentsMethod, RS.NewtonsMethod, RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
p: Pressure of moist air [Pa].
θ_li: Liquid-ice potential temperature [K].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K].

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::ρθ_li,
    ρ::Real,
    θ_li::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real}]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given density ρ, liquid-ice potential temperature θ_li, and total specific humidity q_tot.

Arguments

M: Root-solving method type from RootSolvers.jl. Supported types: RS.SecantMethod, RS.BrentsMethod, RS.NewtonsMethod, RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
ρ: Density of moist air [kg/m³].
θ_li: Liquid-ice potential temperature [K].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K].

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

saturation_adjustment(
    ::Type{M},  # RS.RootSolvingMethod type
    param_set,
    ::pρ,
    p::Real,
    ρ::Real,
    q_tot::Real,
    maxiter::Int,
    tol,
    [T_guess::Union{Nothing, Real}]
)

Compute the saturation equilibrium temperature T and phase partition (q_liq, q_ice) given pressure p, density ρ, and total specific humidity q_tot.

Arguments

M: Root-solving method type from RootSolvers.jl. Supported types: RS.SecantMethod, RS.BrentsMethod, RS.NewtonsMethod, RS.NewtonsMethodAD.
param_set: Thermodynamics parameter set, see Thermodynamics.
p: Pressure of moist air [Pa].
ρ: Density of moist air [kg/m³].
q_tot: Total specific humidity [kg/kg].
maxiter: Maximum iterations for the solver [dimensionless integer].
tol: Relative tolerance for the temperature solution (or a RS.RelativeSolutionTolerance).
T_guess: Optional initial guess for the temperature [K].

Returns

NamedTuple (; T, q_liq, q_ice, converged):
- T: Temperature [K]
- q_liq: Liquid specific humidity [kg/kg]
- q_ice: Ice specific humidity [kg/kg]
- converged: Boolean flag indicating if the solver converged

saturation_adjustment(args...)

Legacy wrapper for saturation_adjustment with phase_type argument. Forwards to saturation_adjustment(..., ::ρeq, ...) with arguments (ρ, e_int) swapped.

Air Entropies

Thermodynamics.entropy — Function

entropy(param_set, p, T, q_tot=0, q_liq=0, q_ice=0)

The specific entropy in thermodynamic equilibrium.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: pressure [Pa]
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

s: specific entropy [J/(kg·K)]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), this reduces to the dry-air expression. The entropy is computed as a mass-weighted sum of the entropies of each component (dry air, vapor, liquid, ice).

Reference

Pressel et al. (2015), "Numerics and subgrid-scale modeling in large eddy simulations of stratocumulus clouds," Journal of Advances in Modeling Earth Systems, 7(3), 1199-1220, doi:10.1002/2015MS000496. (Their Eqs. (29)-(33))

entropy(param_set, ts)

The specific entropy.

entropy(param_set, p, T, q::PhasePartition)

The specific entropy.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T temperature
q PhasePartition.

The specific entropy is computed from equations (29)-(33) of [7].

Thermodynamics.entropy_dry — Function

entropy_dry(param_set, p, T, q_tot=0, q_liq=0, q_ice=0)

The specific entropy of dry air at its partial pressure.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: total air pressure [Pa]
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

s_d: specific entropy of dry air [J/(kg·K)]

In the dry limit (q_tot = q_liq = q_ice = 0, the default), the dry-air partial pressure equals the total pressure.

entropy_dry(param_set, p, T, q::PhasePartition)

The dry air specific entropy.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T temperature
q PhasePartition.

Thermodynamics.entropy_vapor — Function

entropy_vapor(param_set, p, T, q_tot=0, q_liq=0, q_ice=0)

The specific entropy of water vapor at its partial pressure.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: total air pressure [Pa]
T: temperature [K]
q_tot: total specific humidity [kg/kg]
q_liq: liquid specific humidity [kg/kg]
q_ice: ice specific humidity [kg/kg]

Returns

s_v: specific entropy of water vapor [J/(kg·K)]

Note: the entropy of water vapor diverges logarithmically as q_tot → 0 (since p_v → 0).

entropy_vapor(param_set, p, T, q::PhasePartition)

The specific entropy of water vapor.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T temperature
q PhasePartition.

Temperature Profiles

Thermodynamics.TemperatureProfiles.TemperatureProfile — Type

TemperatureProfile

Abstract type for temperature or virtual temperature reference profiles that can be used in atmosphere models.

Instances of this type are required to be callable objects with the following signature

T,p = (::TemperatureProfile)(param_set::APS, z::FT) where {FT}

where T is the temperature or virtual temperature (K), and p is the pressure (Pa).

Thermodynamics.TemperatureProfiles.DecayingTemperatureProfile — Type

DecayingTemperatureProfile{FT} <: TemperatureProfile{FT}

Virtual temperature profile that decays smoothly with height z from T_virt_surf to T_min_ref over height scale H_t (default: density scale height with T_virt_surf).

\[T_{\text{v}}(z) = \max(T_{\text{v, sfc}} − (T_{\text{v, sfc}} - T_{\text{v, min}}) \tanh(z/H_{\text{t}}), T_{\text{v, min}})\]

Fields

T_virt_surf: Virtual temperature at surface (K)
T_min_ref: Minimum virtual temperature at the top of the atmosphere (K)
H_t: Height scale over which virtual temperature drops (m)

Thermodynamics.TemperatureProfiles.IsothermalProfile — Function

IsothermalProfile(param_set, T_virt)
IsothermalProfile(param_set, ::Type{FT<:Real})

Uniform virtual temperature profile implemented as a special case of DecayingTemperatureProfile.

Thermodynamics.TemperatureProfiles.DryAdiabaticProfile — Type

DryAdiabaticProfile{FT} <: TemperatureProfile{FT}

Temperature profile with uniform potential temperature θ up to the height where a minimum temperature is reached.

Fields

T_surface: Surface temperature (K)
T_min_ref: Minimum temperature (K)

Data Collection

Thermodynamics.DataCollection — Module

DataCollection

This module is designed to help judge the accuracy and performance for a particular formulation, tolerance, and or solver configuration, by providing tools to collect various statistics when saturation_adjustment is called.

Example:

import Thermodynamics as TD
import RootSolvers as RS

function do_work()
    # Calls TD.saturation_adjustment()..., possibly many times
end

TD.solution_type() = RS.VerboseSolution()
do_work()
TD.DataCollection.print_summary()

Warn

This data collection was designed for unthreaded single processor runs, and may not work correctly for threaded / multi-processor runs.

Deprecated Functions

These functions are deprecated and will be removed in a future release.

Backward Compatibility Wrappers

These wrappers exist for backward compatibility with older versions of the package.

Thermodynamics.specific_enthalpy — Function

specific_enthalpy(args...)

Deprecated: Use enthalpy instead.

Thermodynamics.specific_enthalpy_dry — Function

specific_enthalpy_dry(args...)

Deprecated: Use enthalpy_dry instead.

Thermodynamics.specific_enthalpy_vapor — Function

specific_enthalpy_vapor(args...)

Deprecated: Use enthalpy_vapor instead.

Thermodynamics.specific_enthalpy_liquid — Function

specific_enthalpy_liquid(args...)

Deprecated: Use enthalpy_liquid instead.

Thermodynamics.specific_enthalpy_ice — Function

specific_enthalpy_ice(args...)

Deprecated: Use enthalpy_ice instead.

Thermodynamics.dry_pottemp — Function

dry_pottemp(args...)

Deprecated: Use potential_temperature instead.

Thermodynamics.total_specific_enthalpy — Function

total_specific_enthalpy(args...)

Deprecated: Use total_enthalpy instead.

Thermodynamics.q_vap_saturation_generic — Function

q_vap_saturation_generic(args...)

Deprecated: Use q_vap_saturation instead.

Thermodynamics.latent_heat_liq_ice — Function

latent_heat_liq_ice(args...)

Deprecated: Use humidity_weighted_latent_heat instead.

Other Deprecated Functions

Thermodynamics.air_temperature_given_hq — Function

air_temperature_given_hq(param_set, h, q_tot=0, q_liq=0, q_ice=0)

Deprecated

This function is deprecated and will be removed in a future release. Please use air_temperature with the ph type instead.

air_temperature_given_hq(param_set, h[, q::PhasePartition]s)

The air temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
h specific enthalpy of moist air

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.air_temperature_given_pρq — Function

air_temperature_given_pρq(param_set, p, ρ, q_tot=0, q_liq=0, q_ice=0)

Deprecated

This function is deprecated and will be removed in a future release. Please use air_temperature with the pρ type instead.

air_temperature_given_pρq(param_set, p, ρ[, q::PhasePartition])

The air temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p air pressure
ρ air density

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.air_temperature_given_pθq — Function

air_temperature_given_pθq(param_set, p, θ_li, q_tot=0, q_liq=0, q_ice=0)

Deprecated

This function is deprecated and will be removed in a future release. Please use air_temperature with the pθ_li type instead.

air_temperature_given_pθq(
    param_set,
    p,
    θ_li,
    [q::PhasePartition]
)

The air temperature obtained by inverting the liquid-ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
θ_li liquid-ice potential temperature

and, optionally,

q PhasePartition.

When q is not provided, the θ_li is assumed to be the dry-air potential temperature.

Thermodynamics.air_temperature_given_ρθq — Function

air_temperature_given_ρθq(param_set, ρ, θ_li, q_tot=0, q_liq=0, q_ice=0)

Deprecated

This function is deprecated and will be removed in a future release. Please use air_temperature with the ρθ_li type instead.

air_temperature_given_ρθq(param_set, ρ, θ_li[, q::PhasePartition])

The air temperature obtained by inverting the liquid-ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ (moist-)air density
θ_li liquid-ice potential temperature

and, optionally,

q PhasePartition.

When q is not provided, the results are for dry air.

Thermodynamics.air_temperature_given_ρθq_nonlinear — Function

air_temperature_given_ρθq_nonlinear(param_set, ρ, θ_li, maxiter, tol, q::PhasePartition)

Computes temperature T.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ (moist-)air density
θ_li liquid-ice potential temperature

and, optionally,

maxiter maximum iterations for non-linear equation solve
tol absolute tolerance for non-linear equation iterations. Can be one of:
- RelativeSolutionTolerance() to stop when |x_2 - x_1|/x_1 < tol
- ResidualTolerance() to stop when |f(x)| < tol
q PhasePartition.When q is not provided, the results are for dry air,

The temperature T is found by finding the root of T - air_temperature_given_pθq(param_set, air_pressure(param_set, T, ρ, q), θ_li, q) = 0

Thermodynamics.saturated — Function

saturated(param_set, ts::ThermodynamicState)

Checks if the thermodynamic state ts is saturated or supersaturated.

Thermodynamics.total_specific_humidity — Function

total_specific_humidity(param_set, ts::ThermodynamicState)

The total specific humidity.

Thermodynamics.liquid_specific_humidity — Function

liquid_specific_humidity(param_set, ts::ThermodynamicState)

The liquid specific humidity.

liquid_specific_humidity(q::PhasePartition)

The liquid specific humidity.

q a PhasePartition

Thermodynamics.ice_specific_humidity — Function

ice_specific_humidity(param_set, ts::ThermodynamicState)

The ice specific humidity.

ice_specific_humidity(q::PhasePartition)

The ice specific humidity.

q a PhasePartition

Thermodynamics.mixing_ratios — Function

mixing_ratios(param_set, ts::ThermodynamicState)

The mixing ratios, stored in a PhasePartition.

mixing_ratios(q::PhasePartition)

The mixing ratios returned in a PhasePartition with the fields

r.tot total mixing ratio
r.liq liquid mixing ratio
r.ice ice mixing ratio

Thermodynamics.specific_volume — Function

specific_volume(param_set, ts::ThermodynamicState)

The (moist-)air specific volume.

Thermodynamics.q_vap_from_RH_liquid — Function

q_vap_from_RH_liquid(param_set, p, T, RH)

Compute the vapor specific humidity from the relative humidity over liquid.

Arguments

param_set: thermodynamics parameter set, see Thermodynamics
p: pressure [Pa]
T: temperature [K]
RH: relative humidity [dimensionless], 0 ≤ RH ≤ 1

Returns

q_vap: vapor specific humidity [kg/kg]

This function is deprecated. Use q_vap_from_RH with Liquid() instead.

Thermodynamics.temperature_and_humidity_given_TᵥρRH — Function

temperature_and_humidity_given_TᵥρRH(param_set, T_virt, ρ, RH, phase_type, maxiter, tol)

Compute temperature and total specific humidity given virtual temperature, density, and relative humidity.

Thermodynamics.liquid_ice_pottemp_sat — Function

liquid_ice_pottemp_sat(param_set, ts::ThermodynamicState)

The liquid potential temperature.

liquid_ice_pottemp_sat(param_set, T, ρ, phase_type[, q::PhasePartition, cpm])

The saturated liquid ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density
phase_type a thermodynamic state type

and, optionally,

q PhasePartition.

When q is not provided, the air assumed to be dry.

liquid_ice_pottemp_sat(param_set, T, ρ, phase_type, q_tot)

The saturated liquid ice potential temperature.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density
phase_type a thermodynamic state type
q_tot total specific humidity

Thermodynamics.PhasePartition_equil — Function

PhasePartition_equil(param_set, ts::ThermodynamicState)

Partition the phases in equilibrium, returning a PhasePartition object.

PhasePartition_equil(param_set, T, ρ, q_tot, phase_type)
PhasePartition_equil(param_set, T, ρ, q_tot, p_vap_sat, λ)

Partition the phases in equilibrium, returning a PhasePartition object.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ (moist-)air density
q_tot total specific humidity
phase_type a thermodynamic state type
p_vap_sat saturation vapor pressure
λ liquid fraction

The residual q.tot - q.liq - q.ice is the vapor specific humidity.

PhasePartition_equil(param_set, T, ρ, q_tot, phase_type)

Partition the phases in equilibrium, returning a PhasePartition object.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
ρ air density
q_tot total specific humidity
phase_type a thermodynamic state type

If the specific humidity q_tot exceeds the saturation specific humidity q_vap_sat (computed using ρ, T and the saturation vapor pressure), the condensate is partitioned into liquid and ice. The fraction of liquid is given by the temperature dependent liquid_fraction_ramp(param_set, T).

Thermodynamics.PhasePartition_equil_given_p — Function

PhasePartition_equil_given_p(param_set, T, p, q_tot, phase_type)

Partition the phases in equilibrium, returning a PhasePartition object using the liquid_fraction function.

param_set a thermodynamics parameter set, see the Thermodynamics for more details
T temperature
p air pressure
q_tot total specific humidity
phase_type a thermodynamic state type

The residual q.tot - q.liq - q.ice is the vapor specific humidity.

Thermodynamic State Constructors (Deprecated)

Thermodynamics.ThermodynamicState — Type

ThermodynamicState{FT}

A thermodynamic state representing the complete thermodynamic properties of a moist air parcel. All ThermodynamicState subtypes provide access to functions to compute all other thermodynamic properties through the equation of state and thermodynamic relations.

The state can be initialized using various thermodynamic formulations (via its subtypes), each representing different assumptions about phase equilibrium and the specific variables used to define the state.

Thermodynamics.PhasePartition — Type

PhasePartition

Represents the mass fractions of the moist air mixture (the partitioning of water substance between vapor, liquid, and ice phases).

The total specific humidity q_tot represents the total water content, while q_liq and q_ice represent the liquid and ice specific humidities, respectively. The vapor specific humidity is computed as q_vap = q_tot - q_liq - q_ice.

Constructors

PhasePartition(q_tot::Real[, q_liq::Real[, q_ice::Real]])
PhasePartition(param_set::APS, ts::ThermodynamicState)

See also PhasePartition_equil

Fields

tot: total specific humidity
liq: liquid water specific humidity (default: 0)
ice: ice specific humidity (default: 0)

Thermodynamics.PhaseDry — Type

PhaseDry{FT} <: AbstractPhaseDry

A dry thermodynamic state representing air with no water vapor (q_tot = 0). This state assumes the air parcel contains only dry air components.

Constructors

PhaseDry(param_set, e_int, ρ)

Fields

e_int: internal energy
ρ: density of dry air

Thermodynamics.PhaseDry_ρe — Function

PhaseDry_ρe(param_set, ρ, e_int)

Constructs a PhaseDry thermodynamic state from density and internal energy, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ air density
e_int specific internal energy

This constructor directly stores the provided density and internal energy without any additional computations, assuming the air is completely dry.

Thermodynamics.PhaseDry_pT — Function

PhaseDry_pT(param_set, p, T)

Constructs a PhaseDry thermodynamic state from pressure and temperature, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T temperature

The internal energy is computed from the temperature using the dry air equation of state, and the density is computed from the ideal gas law using the pressure and temperature.

Thermodynamics.PhaseDry_pθ — Function

PhaseDry_pθ(param_set, p, θ_dry)

Constructs a PhaseDry thermodynamic state from pressure and dry potential temperature, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
θ_dry dry potential temperature

The temperature is computed from the pressure and potential temperature using the Exner function, and the density is computed from the ideal gas law using the pressure and temperature.

Thermodynamics.PhaseDry_pe — Function

PhaseDry_pe(param_set, p, e_int)

Constructs a PhaseDry thermodynamic state from pressure and internal energy, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
e_int specific internal energy

The temperature is computed from the internal energy using the dry air equation of state, and the density is computed from the ideal gas law using the pressure and temperature.

Thermodynamics.PhaseDry_ph — Function

 PhaseDry_ph(param_set, p, h)

Constructs a PhaseDry thermodynamic state from pressure and specific enthalpy, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
h specific enthalpy

The temperature is computed from the specific enthalpy using the dry air equation of state, and the density is computed from the ideal gas law using the pressure and temperature.

Thermodynamics.PhaseDry_ρθ — Function

PhaseDry_ρθ(param_set, ρ, θ_dry)

Constructs a PhaseDry thermodynamic state from density and dry potential temperature, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
θ_dry dry potential temperature

The temperature is computed from the density and potential temperature using the dry air equation of state, and the internal energy is computed from the temperature.

Thermodynamics.PhaseDry_ρT — Function

PhaseDry_ρT(param_set, ρ, T)

Constructs a PhaseDry thermodynamic state from density and temperature, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
T temperature

The internal energy is computed directly from the temperature using the dry air equation of state.

Thermodynamics.PhaseDry_ρp — Function

PhaseDry_ρp(param_set, ρ, p)

Constructs a PhaseDry thermodynamic state from density and pressure, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
p pressure

The temperature is computed from the ideal gas law using the pressure and density, and the internal energy is computed from the temperature.

Thermodynamics.PhaseEquil — Type

PhaseEquil{FT} <: AbstractPhaseEquil

A thermodynamic state assuming thermodynamic equilibrium between water phases. This state assumes that the water vapor is in equilibrium with liquid and/or ice, requiring saturation adjustment to compute the temperature and phase partitioning.

The state stores the density, pressure, internal energy, total specific humidity, and the computed temperature from saturation adjustment.

Constructors

PhaseEquil(param_set, ρ, e_int, q_tot)

Fields

ρ: density of air (potentially moist)
p: air pressure
e_int: internal energy
q_tot: total specific humidity
T: temperature: computed via saturation_adjustment

Thermodynamics.PhaseEquil_ρeq — Function

PhaseEquil_ρeq(param_set, ρ, e_int, q_tot[, maxiter, relative_temperature_tol, sat_adjust_method, T_guess])

Constructs a PhaseEquil thermodynamic state from density, internal energy, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
e_int specific internal energy
q_tot total specific humidity

and, optionally

maxiter maximum iterations for saturation adjustment (default: 8)
relative_temperature_tol relative temperature tolerance for saturation adjustment (default: 1e-4)
sat_adjust_method the numerical method to use for saturation adjustment (default: NewtonsMethod) See the Thermodynamics for options.
T_guess initial guess for temperature in saturation adjustment

The temperature is computed using saturation adjustment to ensure thermodynamic equilibrium, and the pressure is computed from the equation of state using the temperature and density.

Thermodynamics.PhaseEquil_ρTq — Function

PhaseEquil_ρTq(param_set, ρ, T, q_tot)

Constructs a PhaseEquil thermodynamic state from density, temperature, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
T temperature
q_tot total specific humidity

The phase partitioning is computed assuming thermodynamic equilibrium at the given temperature, and the pressure and internal energy are computed from the equation of state.

Thermodynamics.PhaseEquil_pTq — Function

PhaseEquil_pTq(param_set, p, T, q_tot)

Constructs a PhaseEquil thermodynamic state from pressure, temperature, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T temperature
q_tot total specific humidity

The phase partitioning is computed assuming thermodynamic equilibrium at the given temperature, and the density and internal energy are computed from the equation of state.

Thermodynamics.PhaseEquil_pθq — Function

PhaseEquil_pθq(param_set, p, θ_li, q_tot[, maxiter, relative_temperature_tol, sat_adjust_method, T_guess])

Constructs a PhaseEquil thermodynamic state from pressure, liquid-ice potential temperature, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p air pressure
θ_li liquid-ice potential temperature
q_tot total specific humidity

and, optionally

maxiter maximum iterations for saturation adjustment (default: 50)
relative_temperature_tol relative temperature tolerance for saturation adjustment (default: 1e-4)
sat_adjust_method the numerical method to use for saturation adjustment (default: SecantMethod) See the Thermodynamics for options.
T_guess initial guess for temperature in saturation adjustment

The temperature is computed using saturation adjustment with respect to the liquid-ice potential temperature, and the density and internal energy are computed from the equation of state.

Thermodynamics.PhaseEquil_peq — Function

PhaseEquil_peq(param_set, p, e_int, q_tot[, maxiter, relative_temperature_tol, sat_adjust_method, T_guess])

Constructs a PhaseEquil thermodynamic state from pressure, internal energy, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
e_int specific internal energy
q_tot total specific humidity

and, optionally

maxiter maximum iterations for saturation adjustment (default: 40)
relative_temperature_tol relative temperature tolerance for saturation adjustment (default: 1e-4)
sat_adjust_method the numerical method to use for saturation adjustment (default: SecantMethod) See the Thermodynamics for options.
T_guess initial guess for temperature in saturation adjustment

The temperature is computed using saturation adjustment given pressure and internal energy, and the density is computed from the equation of state using the pressure and temperature.

Thermodynamics.PhaseEquil_phq — Function

PhaseEquil_phq(param_set, p, h, q_tot[, maxiter, relative_temperature_tol, sat_adjust_method, T_guess])

Constructs a PhaseEquil thermodynamic state from pressure, specific enthalpy, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
h specific enthalpy
q_tot total specific humidity

and, optionally

maxiter maximum iterations for saturation adjustment (default: 40)
relative_temperature_tol relative temperature tolerance for saturation adjustment (default: 1e-4)
sat_adjust_method the numerical method to use for saturation adjustment (default: SecantMethod) See the Thermodynamics for options.
T_guess initial guess for temperature in saturation adjustment

The temperature is computed using saturation adjustment given pressure and specific enthalpy, and the density and internal energy are computed from the equation of state.

Thermodynamics.PhaseEquil_ρθq — Function

PhaseEquil_ρθq(param_set, ρ, θ_li, q_tot[, maxiter, relative_temperature_tol, T_guess])

Constructs a PhaseEquil thermodynamic state from density, liquid-ice potential temperature, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ (moist-)air density
θ_li liquid-ice potential temperature
q_tot total specific humidity

and, optionally

maxiter maximum iterations for saturation adjustment (default: 36)
relative_temperature_tol relative temperature tolerance for saturation adjustment (default: 1e-4)
T_guess initial guess for temperature in saturation adjustment

The temperature is computed using saturation adjustment with respect to the liquid-ice potential temperature, and the pressure and internal energy are computed from the equation of state.

Thermodynamics.PhaseEquil_ρpq — Function

PhaseEquil_ρpq(param_set, ρ, p, q_tot[, perform_sat_adjust=true, maxiter, sat_adjust_method, T_guess])

Constructs a PhaseEquil thermodynamic state from density, pressure, and total specific humidity, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
p pressure
q_tot total specific humidity

and, optionally

perform_sat_adjust Boolean indicating whether to perform saturation adjustment (default: false)
maxiter maximum number of iterations to perform in saturation adjustment (default: 5)
sat_adjust_method the numerical method to use for saturation adjustment (default: NewtonsMethodAD) See the Thermodynamics for options.
T_guess initial guess for temperature in saturation adjustment

If perform_sat_adjust is true, the temperature is computed using saturation adjustment. Otherwise, the temperature is computed directly from the ideal gas law. The internal energy is computed from the temperature and phase partitioning.

TODO: change input argument order: performsatadjust is unique to this constructor, so it should be last. (breaking change)

Thermodynamics.PhaseNonEquil — Type

 PhaseNonEquil{FT} <: ThermodynamicState

A thermodynamic state assuming thermodynamic non-equilibrium between water phases. This state allows for arbitrary phase partitioning without requiring saturation adjustment, enabling direct computation of temperature from the given thermodynamic variables.

The state stores the internal energy, density, and a complete phase partition specifying the distribution of water substance between vapor, liquid, and ice phases.

Constructors

PhaseNonEquil(param_set, e_int, q::PhasePartition, ρ)

Fields

e_int: internal energy
ρ: density of air (potentially moist)
q: phase partition

Thermodynamics.PhaseNonEquil_ρTq — Function

PhaseNonEquil_ρTq(param_set, ρ, T, q_pt)

Constructs a PhaseNonEquil thermodynamic state from density, temperature, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ (moist-)air density
T temperature
q_pt phase partition

The internal energy is computed from the temperature and phase partition using the equation of state.

Thermodynamics.PhaseNonEquil_pTq — Function

PhaseNonEquil_pTq(param_set, p, T, q_pt)

Constructs a PhaseNonEquil thermodynamic state from pressure, temperature, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
T air temperature
q_pt phase partition

The density is computed from the ideal gas law using the pressure and temperature, and the internal energy is computed from the temperature and phase partition.

Thermodynamics.PhaseNonEquil_ρθq — Function

PhaseNonEquil_ρθq(param_set, ρ, θ_li, q_pt)

Constructs a PhaseNonEquil thermodynamic state from density, liquid-ice potential temperature, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ (moist-)air density
θ_li liquid-ice potential temperature
q_pt phase partition

and, optionally

maxiter maximum iterations for non-linear equation solve (default: 10)
relative_temperature_tol relative temperature tolerance for non-linear equation solve (default: 1e-2)

The temperature is computed from the density and liquid-ice potential temperature using a non-linear solver, and the internal energy is computed from the temperature and phase partition.

Thermodynamics.PhaseNonEquil_pθq — Function

PhaseNonEquil_pθq(param_set, p, θ_li, q_pt)

Constructs a PhaseNonEquil thermodynamic state from pressure, liquid-ice potential temperature, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
θ_li liquid-ice potential temperature
q_pt phase partition

The temperature is computed from the pressure and liquid-ice potential temperature, and the density and internal energy are computed from the equation of state.

Thermodynamics.PhaseNonEquil_peq — Function

PhaseNonEquil_peq(param_set, p, e_int, q_pt)

Constructs a PhaseNonEquil thermodynamic state from pressure, internal energy, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
e_int specific internal energy
q_pt phase partition

The temperature is computed from the internal energy and phase partition using the equation of state, and the density is computed from the ideal gas law using the pressure and temperature.

Thermodynamics.PhaseNonEquil_phq — Function

PhaseNonEquil_phq(param_set, p, h, q_pt)

Constructs a PhaseNonEquil thermodynamic state from pressure, specific enthalpy, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
p pressure
h specific enthalpy
q_pt phase partition

The temperature is computed from the specific enthalpy and phase partition using the equation of state, and the density and internal energy are computed from the equation of state.

Thermodynamics.PhaseNonEquil_ρpq — Function

PhaseNonEquil_ρpq(param_set, ρ, p, q_pt)

Constructs a PhaseNonEquil thermodynamic state from density, pressure, and phase partition, given

param_set a thermodynamics parameter set, see the Thermodynamics for more details
ρ density
p pressure
q_pt phase partition

The temperature is computed from the ideal gas law using the pressure and density, and the internal energy is computed from the temperature and phase partition.