Moist Thermodynamics

MoistThermodynamics

Moist thermodynamic functions, e.g., for air pressure (atmosphere equation of state), latent heats of phase transitions, saturation vapor pressures, and saturation specific humidities.

AbstractParameterSet's

Many functions defined in this module rely on CLIMAParameters.jl. CLIMAParameters.jl defines several functions (e.g., many planet parameters). For example, to compute the mole-mass ratio:

using CLIMAParameters.Planet: molmass_ratio
using CLIMAParameters: AbstractEarthParameterSet
struct EarthParameterSet <: AbstractEarthParameterSet end
param_set = EarthParameterSet()
_molmass_ratio = molmass_ratio(param_set)

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

PhasePartition

Represents the mass fractions of the moist air mixture.

Constructors

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

See also PhasePartition_equil

Fields

• tot

  total specific humidity

• liq

  liquid water specific humidity (default: 0)

• ice

  ice specific humidity (default: 0)

PhasePartition_equil(param_set, T, ρ, q_tot)

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

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density
• q_tot total specific humidity

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

ThermodynamicState{FT}

A thermodynamic state, which can be initialized for various thermodynamic formulations (via its sub-types). All ThermodynamicState's have access to functions to compute all other thermodynamic properties.

PhaseDry{FT} <: ThermodynamicState

A dry thermodynamic state (q_tot = 0).

Constructors

PhaseDry(param_set, e_int, ρ)

Fields

• param_set

  parameter set, used to dispatch planet parameter function calls

• e_int

  internal energy

• ρ

  density of dry air

PhaseDry_given_pT(param_set, p, T)

Constructs a PhaseDry thermodynamic state from:

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• p pressure
• T temperature

PhaseDry_given_ρT(param_set, ρ, T)

Constructs a PhaseDry thermodynamic state from:

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• ρ density
• T temperature

PhaseEquil{FT} <: ThermodynamicState

A thermodynamic state assuming thermodynamic equilibrium (therefore, saturation adjustment may be needed).

Constructors

PhaseEquil(param_set, e_int, ρ, q_tot)

Fields

• param_set

  parameter set, used to dispatch planet parameter function calls

• e_int

  internal energy

• ρ

  density of air (potentially moist)

• q_tot

  total specific humidity

• T

  temperature: computed via saturation_adjustment

PhaseNonEquil{FT} <: ThermodynamicState

A thermodynamic state assuming thermodynamic non-equilibrium (therefore, temperature can be computed directly).

Constructors

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

Fields

• param_set

  parameter set, used to dispatch planet parameter function calls

• e_int

  internal energy

• ρ

  density of air (potentially moist)

• q

  phase partition

TemperatureSHumEquil(param_set, T, ρ, q_tot)

Constructs a PhaseEquil thermodynamic state from temperature.

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ density
• q_tot total specific humidity

TemperatureSHumEquil_given_pressure(param_set, T, p, q_tot)

Constructs a PhaseEquil thermodynamic state from temperature.

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• p pressure
• q_tot total specific humidity

LiquidIcePotTempSHumEquil(param_set, θ_liq_ice, ρ, q_tot)

Constructs a PhaseEquil thermodynamic state from:

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• θ_liq_ice liquid-ice potential temperature
• ρ (moist-)air density
• q_tot total specific humidity
• temperature_tol temperature tolerance for saturation adjustment
• maxiter maximum iterations for saturation adjustment

LiquidIcePotTempSHumNonEquil(param_set, θ_liq_ice, ρ, q_pt)

Constructs a PhaseNonEquil thermodynamic state from:

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• θ_liq_ice liquid-ice potential temperature
• ρ (moist-)air density
• q_pt phase partition

and, optionally

• potential_temperature_tol potential temperature for non-linear equation solve
• maxiter maximum iterations for non-linear equation solve

LiquidIcePotTempSHumNonEquil_given_pressure(param_set, θ_liq_ice, p, q_pt)

Constructs a PhaseNonEquil thermodynamic state from:

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• θ_liq_ice liquid-ice potential temperature
• p pressure
• q_pt phase partition

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

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

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T air temperature
• p pressure

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

air_density(ts::ThermodynamicState)

The (moist-)air density, given a thermodynamic state ts.

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

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

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T air temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

air_pressure(ts::ThermodynamicState)

The air pressure from the equation of state (ideal gas law), given a thermodynamic state ts.

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

The air pressure for an isentropic process, where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• T∞ ambient temperature
• p∞ ambient pressure

air_temperature(param_set, e_int, q::PhasePartition)

The air temperature, where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• e_int internal energy per unit mass

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

air_temperature(ts::ThermodynamicState)

The air temperature, given a thermodynamic state ts.

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

The air temperature for an isentropic process, where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• p pressure
• θ potential temperature

air_temperature_from_liquid_ice_pottemp(param_set, θ_liq_ice, ρ, q::PhasePartition)

The temperature given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• θ_liq_ice liquid-ice potential temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

cp_m(param_set, [q::PhasePartition])

The isobaric specific heat capacity of moist air given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details

and, optionally

• q PhasePartition. Without this argument, the results are for dry air.

cp_m(ts::ThermodynamicState)

The isobaric specific heat capacity of moist air, given a thermodynamic state ts.

cv_m(param_set, [q::PhasePartition])

The isochoric specific heat capacity of moist air given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details

and, optionally

• q PhasePartition. Without this argument, the results are for dry air.

cv_m(ts::ThermodynamicState)

The isochoric specific heat capacity of moist air, given a thermodynamic state ts.

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

The dry potential temperature where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

dry_pottemp(ts::ThermodynamicState)

The dry potential temperature, given a thermodynamic state ts.

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

The Exner function where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

exner(ts::ThermodynamicState)

The Exner function, given a thermodynamic state ts.

gas_constant_air(param_set, [q::PhasePartition])

The specific gas constant of moist air given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• q PhasePartition. Without this argument, the results are for dry air.

gas_constant_air(ts::ThermodynamicState)

The specific gas constant of moist air given a thermodynamic state ts.

Ice <: Phase

An ice phase, to dispatch over saturation_vapor_pressure and q_vap_saturation_generic.

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

The internal energy per unit mass, given a thermodynamic state ts or

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

internal_energy(ts::ThermodynamicState)

The internal energy per unit mass, given a thermodynamic state ts.

internal_energy(ρ::FT, ρe::FT, ρu::AbstractVector{FT}, e_pot::FT)

The internal energy per unit mass, given

• ρ (moist-)air density
• ρe total energy per unit volume
• ρu momentum vector
• e_pot potential energy (e.g., gravitational) per unit mass

internal_energy_sat(param_set, T, ρ, q_tot)

The internal energy per unit mass in thermodynamic equilibrium at saturation where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density
• q_tot total specific humidity

internal_energy_sat(ts::ThermodynamicState)

The internal energy per unit mass in thermodynamic equilibrium at saturation, given a thermodynamic state ts.

latent_heat_fusion(param_set, T::FT) where {FT<:Real}

The specific latent heat of fusion where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature

latent_heat_fusion(ts::ThermodynamicState)

The specific latent heat of fusion given a thermodynamic state ts.

latent_heat_sublim(param_set, T::FT) where {FT<:Real}

The specific latent heat of sublimation where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature

latent_heat_sublim(ts::ThermodynamicState)

The specific latent heat of sublimation given a thermodynamic state ts.

latent_heat_vapor(param_set, T::FT) where {FT<:Real}

The specific latent heat of vaporization where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature

latent_heat_vapor(ts::ThermodynamicState)

The specific latent heat of vaporization given a thermodynamic state ts.

Liquid <: Phase

A liquid phase, to dispatch over saturation_vapor_pressure and q_vap_saturation_generic.

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

The fraction of condensate that is liquid where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• q PhasePartition

If q.liq or q.ice are nonzero, the liquid fraction is computed from them.

Otherwise, phase equilibrium is assumed so that the fraction of liquid is a function that is 1 above T_freeze and goes to zero below T_freeze.

liquid_fraction(ts::ThermodynamicState)

The fraction of condensate that is liquid given a thermodynamic state ts.

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

The liquid-ice potential temperature where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

liquid_ice_pottemp(ts::ThermodynamicState)

The liquid-ice potential temperature, given a thermodynamic state ts.

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

The saturated liquid ice potential temperature where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

liquid_ice_pottemp_sat(param_set, T, ρ, q_tot)

The saturated liquid ice potential temperature where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density
• q_tot total specific humidity

liquid_ice_pottemp_sat(ts::ThermodynamicState)

The liquid potential temperature given a thermodynamic state ts.

(R_m, cp_m, cv_m, γ_m) = gas_constants(param_set, [q::PhasePartition])

Wrapper to compute all gas constants at once, where optionally,

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• q PhasePartition. Without this argument, the results are for dry air.

The function returns a tuple of

• R_m gas_constant_air
• cp_m cp_m
• cv_m cv_m
• γ_m = cp_m/cv_m

(R_m, cp_m, cv_m, γ_m) = gas_constants(ts::ThermodynamicState)

Wrapper to compute all gas constants at once, given a thermodynamic state ts.

The function returns a tuple of

• R_m gas_constant_air
• cp_m cp_m
• cv_m cv_m
• γ_m = cp_m/cv_m

saturation_adjustment(param_set, e_int, ρ, q_tot)

Compute the temperature that is consistent with

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• e_int internal energy
• ρ (moist-)air density
• q_tot total specific humidity
• tol absolute tolerance for saturation adjustment iterations. Can be one of:
  • SolutionTolerance() to stop when |x_2 - x_1| < tol
  • ResidualTolerance() to stop when |f(x)| < tol
• maxiter maximum iterations for non-linear equation solve

by finding the root of

$e_int - internal_energy_sat(param_set, T, ρ, q_tot) = 0$

using Newtons method with analytic gradients.

See also saturation_adjustment.

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

The saturation excess in equilibrium where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density
• 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(ts::ThermodynamicState)

Compute the saturation excess in equilibrium, given a thermodynamic state ts.

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

Compute the saturation specific humidity, given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition

If the PhasePartition q is given, the saturation specific humidity is that of 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). 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 fractions of condensates q.liq/(q.liq + q.ice) and q.ice/(q.liq + q.ice) that are liquid and ice, respectively.

If the PhasePartition q is not given, or has zero liquid and ice specific humidities, the saturation specific humidity is that over a mixture of liquid and ice, with the fraction of liquid given by temperature dependent liquid_fraction(T) and the fraction of ice by the complement 1 - liquid_fraction(T).

q_vap_saturation(ts::ThermodynamicState)

Compute the saturation specific humidity, given a thermodynamic state ts.

q_vap_saturation_generic(param_set, T, ρ[; phase=Liquid()])

Compute the saturation specific humidity over a plane surface of condensate, given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• Liquid() indicating condensate is liquid
• Ice() indicating condensate is ice

saturation_vapor_pressure(param_set, T, Liquid())

Return the saturation vapor pressure over a plane liquid surface given

• T temperature

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details

  saturationvaporpressure(param_set, T, Ice())

Return the saturation vapor pressure over a plane ice surface given

• T temperature

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details

  saturationvaporpressure(paramset, T, LH0, Δcp)

Compute the saturation vapor pressure over a plane surface by integration of the Clausius-Clapeyron relation.

The Clausius-Clapeyron relation

dlog(p_v_sat)/dT = [LH_0 + Δcp * (T-T_0)]/(R_v*T^2)

is integrated from the triple point temperature T_triple, using Kirchhoff's relation

L = LH_0 + Δcp * (T - T_0)

for the specific latent heat L with constant isobaric specific heats of the phases. The linear dependence of the specific latent heat on temperature T allows analytic integration of the Clausius-Clapeyron relation to obtain the saturation vapor pressure p_v_sat as a function of the triple point pressure press_triple.

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

The speed of sound in unstratified air, where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

soundspeed_air(ts::ThermodynamicState)

The speed of sound in unstratified air given a thermodynamic state ts.

specific_volume(ts::ThermodynamicState)

The (moist-)air specific volume, given a thermodynamic state ts.

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

The total energy per unit mass, given

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• e_kin kinetic energy per unit mass
• e_pot potential energy per unit mass
• T temperature

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

total_energy(e_kin, e_pot, ts::ThermodynamicState)

The total energy per unit mass given a thermodynamic state ts.

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

The virtual temperature where

• param_set an AbstractParameterSet, see the MoistThermodynamics for more details
• T temperature
• ρ (moist-)air density

and, optionally,

• q PhasePartition. Without this argument, the results are for dry air.

virtual_pottemp(ts::ThermodynamicState)

The virtual potential temperature, given a thermodynamic state ts.