Thermodynamics

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

Saturation adjustment functions accept:

• sat_adjust_method: numerical method type (from RootSolvers.jl)
• A function returning the numerical method instance (e.g., sa_numerical_method_ρpq returns an instance of the numerical method for the ρ-p-q_tot formulation)

Supported methods in RootSolvers.jl:

• NewtonsMethod: Newton method with analytic gradients
• NewtonsMethodAD: Newton method with autodiff
• SecantMethod: Secant method
• RegulaFalsiMethod: Regula-Falsi method

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)

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)

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.

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

PhaseDry_ρe(param_set, ρ, e_int)

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

• param_set an AbstractParameterSet, 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.

PhaseDry_pT(param_set, p, T)

Constructs a PhaseDry thermodynamic state from pressure and temperature, given

• param_set an AbstractParameterSet, 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.

PhaseDry_pθ(param_set, p, θ_dry)

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

• param_set an AbstractParameterSet, 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.

PhaseDry_pe(param_set, p, e_int)

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

• param_set an AbstractParameterSet, 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.

 PhaseDry_ph(param_set, p, h)

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

• param_set an AbstractParameterSet, 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.

PhaseDry_ρθ(param_set, ρ, θ_dry)

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

• param_set an AbstractParameterSet, 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.

PhaseDry_ρT(param_set, ρ, T)

Constructs a PhaseDry thermodynamic state from density and temperature, given

• param_set an AbstractParameterSet, 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.

PhaseDry_ρp(param_set, ρ, p)

Constructs a PhaseDry thermodynamic state from density and pressure, given

• param_set an AbstractParameterSet, 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.

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

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 an AbstractParameterSet, 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.

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

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

• param_set an AbstractParameterSet, 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.

PhaseEquil_pTq(param_set, p, T, q_tot)

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

• param_set an AbstractParameterSet, 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.

PhaseEquil_pθq(param_set, p, θ_liq_ice, 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 an AbstractParameterSet, see the Thermodynamics for more details
• p air pressure
• θ_liq_ice 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.

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 an AbstractParameterSet, 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.

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 an AbstractParameterSet, 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.

PhaseEquil_ρθq(param_set, ρ, θ_liq_ice, 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 an AbstractParameterSet, see the Thermodynamics for more details
• ρ (moist-)air density
• θ_liq_ice 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.

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 an AbstractParameterSet, 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)

 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

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

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

• param_set an AbstractParameterSet, 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.

PhaseNonEquil_pTq(param_set, p, T, q_pt)

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

• param_set an AbstractParameterSet, 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.

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

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

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• ρ (moist-)air density
• θ_liq_ice 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.

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

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

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p pressure
• θ_liq_ice 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.

PhaseNonEquil_peq(param_set, p, e_int, q_pt)

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

• param_set an AbstractParameterSet, 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.

PhaseNonEquil_phq(param_set, p, h, q_pt)

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

• param_set an AbstractParameterSet, 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.

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

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

• param_set an AbstractParameterSet, 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.

Ice <: Phase

An ice phase, to dispatch over saturation_vapor_pressure and q_vap_saturation_generic.

Liquid <: Phase

A liquid phase, to dispatch over saturation_vapor_pressure and q_vap_saturation_generic.

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

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

• param_set an AbstractParameterSet, 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.

air_density(param_set, 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), given

• param_set an AbstractParameterSet, 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.

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

The air pressure for an isentropic process, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• T current temperature
• T∞ reference temperature
• p∞ reference pressure

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

air_pressure(param_set, ts::ThermodynamicState)

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

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

The air temperature, given

• param_set an AbstractParameterSet, 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.

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

The air temperature, given

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

The temperature is computed using the definition of the dry potential temperature: T = θ * (p/p₀)^(R/cₚ), where p₀ is the reference pressure, R is the gas constant of dry air, and cₚ is the isobaric specific heat capacity of dry air.

air_temperature(param_set, ts::ThermodynamicState)

The air temperature, given a thermodynamic state ts.

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

The air pressure for an isentropic process, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• θ potential temperature
• Φ gravitational potential

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

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

The air temperature, where

• param_set an AbstractParameterSet, 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.

condensate(q::PhasePartition{FT})

This is identical to condensate_specific_humidity and will be removed in a future release.

condensate_specific_humidity(q::PhasePartition{FT})

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

condensate_specific_humidity(param_set, ts::ThermodynamicState)

The condensate specific humidity (liquid + ice) given a thermodynamic state ts.

cp_m(param_set, q_tot, q_liq, q_ice)

The isobaric specific heat capacity of moist air, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q_tot total specific humidity of water
• q_liq specific humidity of liquid
• q_ice specific humidity of ice

cp_m(param_set[, q::PhasePartition])

The isobaric specific heat capacity of moist air given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q PhasePartition.

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

cp_m(param_set, 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 Thermodynamics for more details
• q PhasePartition. Without humidity argument, the results are for dry air.

cv_m(param_set, 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, given

• param_set an AbstractParameterSet, 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.

dry_pottemp(param_set, ts::ThermodynamicState)

The dry potential temperature, given a thermodynamic state ts.

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

The Exner function, given

• param_set an AbstractParameterSet, 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.

exner(param_set, ts::ThermodynamicState)

The Exner function, given a thermodynamic state ts.

gas_constant_air(param_set, q_tot, q_liq, q_ice)

The specific gas constant of moist air, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q_tot, q_liq, q_ice - specific humidities for total water, liquid water, and ice

gas_constant_air(param_set[, q::PhasePartition])

The specific gas constant of moist air, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q PhasePartition.

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

gas_constant_air(param_set, ts::ThermodynamicState)

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

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

Wrapper to compute the gas constant, specific heat capacities, and their ratio at once, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q PhasePartition

The function returns a tuple of

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

This function is deprecated and will be removed in a future release.

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

Wrapper to compute the gas constant, specific heat capacities, and their ratio at once, given a thermodynamic state ts.

has_condensate(q::PhasePartition{FT})

Bool indicating if condensate exists in the phase partition

has_condensate(param_set, ts::ThermodynamicState)

Bool indicating if condensate exists given a thermodynamic state ts.

ice_specific_humidity(q::PhasePartition)

The ice specific humidity, given

• q a PhasePartition

ice_specific_humidity(param_set, ts::ThermodynamicState)

The ice specific humidity, given a thermodynamic state ts.

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

The internal energy per unit mass, given

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

and, optionally,

• q PhasePartition.

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

internal_energy(param_set, ts::ThermodynamicState)

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

internal_energy_dry(param_set, T)

The dry air internal energy, given

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

internal_energy_dry(param_set, ts::ThermodynamicState)

The dry air internal energy, given a thermodynamic state ts.

internal_energy_vapor(param_set, T)

The water vapor internal energy, given

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

internal_energy_vapor(param_set, ts::ThermodynamicState)

The water vapor internal energy, given a thermodynamic state ts.

internal_energy_liquid(param_set, T)

The liquid water internal energy, given

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

internal_energy_liquid(param_set, ts::ThermodynamicState)

The liquid water internal energy, given a thermodynamic state ts.

internal_energy_ice(param_set, T)

The ice internal energy, given

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

internal_energy_ice(param_set, ts::ThermodynamicState)

The ice internal energy, given a thermodynamic state ts.

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

The internal energy per unit mass in thermodynamic equilibrium at saturation with a fixed temperature and total specific humidity, given

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

internal_energy_sat(param_set, ts::ThermodynamicState)

The internal energy per unit mass in thermodynamic equilibrium at saturation with a fixed temperature and total specific humidity, given a thermodynamic state ts.

latent_heat_fusion(param_set, T)

The specific latent heat of fusion, given

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

latent_heat_fusion(param_set, ts::ThermodynamicState)

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

latent_heat_liq_ice(param_set[, q::PhasePartition])

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

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q PhasePartition.

When q is not provided, latent_heat_liq_ice is zero.

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

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

Specific-humidity weighted sum of latent heats of liquid and ice evaluated at reference temperature T_0, given a thermodynamic state ts.

latent_heat_sublim(param_set, T)

The specific latent heat of sublimation, given

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

latent_heat_sublim(param_set, ts::ThermodynamicState)

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

latent_heat_vapor(param_set, T)

The specific latent heat of vaporization, given

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

latent_heat_vapor(param_set, ts::ThermodynamicState)

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

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

The fraction of condensate that is liquid, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• T temperature
• phase_type a thermodynamic state type

PhaseNonEquil behavior

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

PhaseEquil, PhaseDry behavior

Otherwise, the liquid fraction goes from 0 below T_icenuc to 1 above T_freeze, with a power law interpolation between the two temperatures based on Kaul et al., Monthly Weather Rev., 2015, https://doi.org/10.1029/2009JD012384

liquid_fraction(param_set, 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, given

• param_set an AbstractParameterSet, 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.

liquid_ice_pottemp(param_set, ts::ThermodynamicState)

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

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

The saturated liquid ice potential temperature, given

• param_set an AbstractParameterSet, 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, given

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

liquid_ice_pottemp_sat(param_set, ts::ThermodynamicState)

The liquid potential temperature, given a thermodynamic state ts.

liquid_specific_humidity(q::PhasePartition)

The liquid specific humidity, given

• q a PhasePartition

liquid_specific_humidity(param_set, ts::ThermodynamicState)

The liquid specific humidity, given a thermodynamic state ts.

mixing_ratios(q::PhasePartition)

The mixing ratios, given a specific humidity phase partition, q, returned in a PhasePartition with the fields

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

mixing_ratios(param_set, ts::ThermodynamicState)

The mixing ratios, stored in a PhasePartition, given a thermodynamic state ts.

moist_static_energy(param_set, ts, e_pot)

The moist static energy, given a thermodynamic state ts.

virtual_dry_static_energy(param_set, ts, e_pot)

The virtual dry static energy, given a thermodynamic state ts.

q_vap_from_RH_liquid(param_set, p, T, RH)

The water vapor specific humidity, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p pressure
• T temperature
• RH relative humidity with respect to liquid water

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

The saturation specific humidity, given

• param_set: an AbstractParameterSet, see the Thermodynamics for more details
• T: temperature
• ρ: air density
• phase_type: a thermodynamic state type
• (optional) 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). 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.

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 the temperature dependent liquid_fraction(param_set, T, phase_type) and the fraction of ice by the complement 1 - liquid_fraction(param_set, T, phase_type).

q_vap_saturation(param_set, ts::ThermodynamicState)

The saturation specific humidity, given a thermodynamic state ts.

q_vap_saturation_liquid(param_set, ts::ThermodynamicState)

The saturation specific humidity over liquid, given a thermodynamic state ts.

q_vap_saturation_ice(param_set, ts::ThermodynamicState)

The saturation specific humidity over ice, given a thermodynamic state ts.

q_vap_from_p_vap(param_set, T, ρ, p_v)

The vapor specific humidity, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• T temperature,
• ρ (moist-)air density
• p_v partial pressure of vapor

q_vap_saturation_from_density(param_set, T, ρ, p_v)

This function is identical to q_vap_from_p_vap and is provided for backward compatibility. It will be removed in a future release.

partial_pressure_vapor(param_set, p[, q::PhasePartition])

The partial pressure of water vapor, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p air pressure
• q phase partition

When q is not provided, the partial pressure is zero.

partial_pressure_vapor(param_set, ts::ThermodynamicState)

The partial pressure of water vapor, given a thermodynamic state ts.

partial_pressure_dry(param_set, p[, q::PhasePartition])

The partial pressure of dry air, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p air pressure
• q phase partition

When q is not provided, the partial pressure is the total pressure.

partial_pressure_dry(param_set, ts::ThermodynamicState)

The partial pressure of dry air, given a thermodynamic state ts.

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

The relative humidity (clipped between 0 and 1), given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p pressure
• phase_type a thermodynamic state type

and, optionally,

• q PhasePartition.

When q is not provided, the relative humidity is 0.

relative_humidity(param_set, ts::ThermodynamicState)

The relative humidity, given a thermodynamic state ts.

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

Boolean indicating if thermodynamic state is saturated.

saturation_adjustment(
    sat_adjust_method,
    param_set,
    e_int,
    ρ,
    q_tot,
    phase_type,
    maxiter,
    relative_temperature_tol,
    T_guess,
)

Computes the saturation equilibrium temperature given internal energy e_int, density ρ, and total specific humidity q_tot.

This function finds the temperature T that satisfies the root equation: e_int - internal_energy_sat(T, ρ, q_tot) = 0. It is the most common entry point for saturation adjustment.

Arguments

• sat_adjust_method: The numerical method for root-finding (e.g., NewtonsMethod, SecantMethod).
• param_set: An AbstractParameterSet containing thermodynamic parameters.
• e_int: Specific internal energy.
• ρ: Density of moist air.
• q_tot: Total specific humidity (vapor + condensate).
• phase_type: A thermodynamic phase type (PhaseEquil, etc.).
• maxiter: Maximum iterations for the solver.
• relative_temperature_tol: Relative tolerance for the temperature solution.
• T_guess: An initial guess for the temperature.

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

The saturation excess in equilibrium, given

• param_set an AbstractParameterSet, 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.

saturation_excess(param_set, ts::ThermodynamicState)

The saturation excess in equilibrium, given a thermodynamic state ts.

saturation_vapor_pressure(param_set, T, ::Phase)
saturation_vapor_pressure(param_set, T, LH_0, Δcp)

The saturation vapor pressure over a plane surface of condensate, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• T temperature or ts a thermodynamic state
• Phase either Liquid() or Ice() to dispatch over the condensate type

or, given

• param_set an AbstractParameterSet
• T temperature
• LH_0 latent heat at reference temperature T_0
• Δcp difference in isobaric specific heat capacity between the two phases

The saturation vapor pressure is computed by integration of the Clausius-Clapeyron relation, assuming constant specific heat capacities. The closed-form solution is: p_v^*(T) = p_tr * (T/T_tr)^(Δc_p/R_v) * exp((L_0 - Δc_p*T_0)/R_v * (1/T_tr - 1/T)), where p_tr is the triple point pressure, T_tr is the triple point temperature, L_0 is the latent heat at the reference temperature T_0, and Δc_p is the difference in isobaric specific heat capacities between the phases.

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

The saturation vapor pressure over a plane surface of condensate, given a thermodynamic state ts and phase Liquid.

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

The saturation vapor pressure over a plane surface of condensate, given a thermodynamic state ts and phase Ice.

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

The speed of sound in unstratified air, given

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

and, optionally,

• q PhasePartition.

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

soundspeed_air(param_set, ts::ThermodynamicState)

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

specific_enthalpy(e_int, R_m, T)

The specific enthalpy, given

• e_int internal specific energy
• R_m gas_constant_air
• T air temperature

This method is deprecated and will be removed in a future release.

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

The specific enthalpy, given

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

and, optionally,

• q PhasePartition.

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

specific_enthalpy(param_set, ts)

The specific enthalpy, given a thermodynamic state ts.

specific_volume(param_set, ts::ThermodynamicState)

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

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

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

• 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

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

The supersaturation (pv/pv_sat -1) over water or ice, 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 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.

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

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

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

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

• param_set an AbstractParameterSet, 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.

total_specific_enthalpy(e_tot, R_m, T)

The total specific enthalpy, given

• e_tot total specific energy
• R_m gas_constant_air
• T air temperature

total_specific_enthalpy(param_set, ts, e_tot::Real)

The total specific enthalpy, given a thermodynamic state ts.

total_specific_humidity(param_set, ts::ThermodynamicState)

The total specific humidity, given a thermodynamic state ts.

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, given

• param_set an AbstractParameterSet, 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.

vapor_pressure_deficit(param_set, T, p, q_vap)

The vapor pressure deficit over liquid water (saturation vapor pressure minus actual vapor pressure, truncated to be non-negative), given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• T air temperature
• p air pressure
• q_vap vapor specific humidity

vapor_specific_humidity(q::PhasePartition)

The vapor specific humidity, given a

• q a PhasePartition

vapor_specific_humidity(param_set, ts::ThermodynamicState)

The vapor specific humidity, given a thermodynamic state ts.

vol_vapor_mixing_ratio(param_set, q::PhasePartition)

The volume mixing ratio of water vapor, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q PhasePartition

vol_vapor_mixing_ratio(param_set, ts::ThermodynamicState)

The volume mixing ratio of water vapor, given a thermodynamic state ts.

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

The virtual potential temperature, given

• param_set an AbstractParameterSet, 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.

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.

virtual_pottemp(param_set, ts::ThermodynamicState)

The virtual potential temperature, given a thermodynamic state ts.

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

The virtual temperature, given

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

and, optionally,

• q PhasePartition.

When q is not provided, the result is the regular temperature.

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.

virtual_temperature(param_set, ts::ThermodynamicState)

The virtual temperature, given a thermodynamic state ts.

specific_entropy(param_set, p, T, q)
specific_entropy(param_set, ts)

The specific entropy, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• p pressure
• T temperature
• q phase partition

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

specific_entropy(param_set, ts)

The specific entropy, given a thermodynamic state ts.

shum_to_mixing_ratio(q, q_tot)

The mixing ratio, given

• q specific humidity
• q_tot total specific humidity

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

The saturation specific humidity over a plane surface of condensate, given - param_set: an AbstractParameterSet, see the Thermodynamics for more details - T: temperature - ρ: air density - (optional) Liquid(): indicating condensate is liquid (default) - (optional) Ice(): indicating condensate is ice

The saturation specific humidity is computed as q_v^* = p_v^*(T) / (ρ * R_v * T), where p_v^* is the saturation vapor pressure.

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

The saturation specific humidity, given

• param_set an AbstractParameterSet, see the Thermodynamics for more details
• q_tot total water specific humidity,
• p air pressure,
• T air tempearture
• phase_type a thermodynamic state type

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, given

• param_set an AbstractParameterSet, 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, ts::ThermodynamicState)

Partition the phases in equilibrium, returning a PhasePartition object, given a thermodynamic state ts.

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, given

• param_set an AbstractParameterSet, 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.

DryAdiabaticProcess

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

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

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

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).

DryAdiabaticProfile{FT} <: TemperatureProfile{FT}

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

Fields

• T_surface: Surface temperature (K)

• T_min_ref: Minimum temperature (K)

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}})\]

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)

TestedProfiles

This module contains functions to compute all of the thermodynamic states that Thermodynamics is tested with in runtests.jl

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 Thermodynamic saturation_adjustment is called.

Example:

import Thermodynamics as TD
import RootSolvers as RS

function do_work()
    # Calls TD.PhaseEquil_ρeq()..., possibly many times
end

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