API Documentation

Julia package for finite volume GPU and CPU large eddy simulations (LES) of atmospheric flows. The abstractions, design, and finite volume engine are based on Oceananigans.

CondensedPhase(; ...)
CondensedPhase(FT; reference_latent_heat, heat_capacity)

Returns CondensedPhase with specified parameters converted to FT.

Two examples of CondensedPhase are liquid and ice. When matter is converted from vapor to liquid, water molecules in the gas phase cluster together and slow down to form liquid with heat_capacity, The lost of molecular kinetic energy is called the reference_latent_heat.

Likewise, during deposition, water molecules in the gas phase cluster into ice crystals.

Arguments

• FT: Float type to use (defaults to Oceananigans.defaults.FloatType)
• reference_latent_heat: Difference between the internal energy of the gaseous phase at the energy_reference_temperature.
• heat_capacity: Heat capacity of the phase of matter.

struct IdealGas{FT}

A struct representing an ideal gas with molar mass and specific heat capacity.

Fields

• molar_mass: Molar mass of the gas in kg/mol
• heat_capacity: Specific heat capacity at constant pressure in J/(kg·K)

Examples

dry_air = IdealGas(molar_mass=0.02897, heat_capacity=1005)

# output
IdealGas{Float64}(molar_mass=0.02897, heat_capacity=1005.0)

ThermodynamicConstants(; ...) -> ThermodynamicConstants
ThermodynamicConstants(
    FT;
    molar_gas_constant,
    gravitational_acceleration,
    energy_reference_temperature,
    triple_point_temperature,
    triple_point_pressure,
    dry_air_molar_mass,
    dry_air_heat_capacity,
    vapor_molar_mass,
    vapor_heat_capacity,
    liquid,
    ice
) -> ThermodynamicConstants

Create ThermodynamicConstants with parameters that represent gaseous mixture of dry "air" and vapor, as well as condensed liquid and ice phases. The triple_point_temperature and triple_point_pressure may be combined with internal energy parameters for condensed phases to compute the vapor pressure at the boundary between vapor and a homogeneous sample of the condensed phase. The gravitational_acceleration parameter is included to compute reference_state quantities associated with hydrostatic balance.

The Clausius-Clapeyron relation describes the pressure-temperature relationship during phase transitions from vapor to liquid or vapor to ice,

\[d[\log(pᵛ⁺ᵝ)] / dT = ℒᵝ / (Rᵛ T²)\]

where:

• $pᵛ⁺ᵝ$ is the saturation vapor pressure for a transition between vapor and the $β$-th phase For example $β = l$ for liquid and $β = i$ for ice.
• $T$ is temperature
• $ℒᵝ$ is the latent heat of the transition (the difference between the enthalpy of the vapor and transitioned state at a given temperature)
• $Rᵛ$ is the specific gas constant for vapor

For a thermodynamic model with constant specific heats, the latent heat may be written

\[ℒᵝ(T) = ℒᵝ(T=0) + (cᵖᵛ - cᵝ) T,\]

where $cᵖᵛ$ is the vapor specific heat at constant pressure, $cᵝ$ is the specific heat of phase $β$, which is assumed incompressible, and $ℒᵝ(T=0)$ is the latent heat at $T=0$K. We therefore find that

\[pᵛ⁺ᵝ = pᵗʳ \exp[ ℒᵝ(T=0) (1/Tᵗʳ - 1/T) / Rᵛ ]\]

where

• $pᵗʳ$ is the triple point pressure
• $Tᵗʳ$ is the triple point temperature

See also saturation_vapor_pressure.

Note: any reference values for pressure and temperature can be used in principle. The advantage of using reference values at the triple point is that the same values can then be used for both condensation (vapor → liquid) and deposition (vapor → ice).

mixture_gas_constant(
    q::Breeze.Thermodynamics.MoistureMassFractions,
    thermo::ThermodynamicConstants
) -> Any

Return the gas constant of moist air mixture [in J/(kg K)] given the specific humidity q and thermodynamic parameters thermo.

The mixture gas constant is calculated as a weighted average of the dry air and water vapor gas thermo:

\[Rᵐ = qᵈ Rᵈ + qᵛ Rᵛ\]

where:

• Rᵈ is the dry air gas constant
• Rᵛ is the water vapor gas constant
• qᵈ is the mass fraction of dry air
• qᵛ is the mass fraction of water vapor

Arguments

• q: the moisture mass fractions (vapor, liquid, and ice)
• thermo: ThermodynamicConstants instance containing gas thermo

mixture_heat_capacity(
    q::Breeze.Thermodynamics.MoistureMassFractions,
    thermo::ThermodynamicConstants
) -> Any

Compute the heat capacity of a mixture of dry air, vapor, liquid, and ice, where the mass fractions of vapor, liquid, and ice are given by q. The heat capacity of moist air is the weighted sum of its constituents:

\[cᵖᵐ = qᵈ cᵖᵈ + qᵛ cᵖᵛ + qˡ cˡ + qⁱ cⁱ\]

where qᵛ = q.vapor, qˡ = q.liquid, qⁱ = q.ice are the mass fractions of vapor, liquid, and ice constituents, respectively, and qᵈ = 1 - qᵛ - qˡ - qⁱ is the mass fraction of dry air. The heat capacities cᵖᵈ, cᵖᵛ, cˡ, cⁱ are the heat capacities of dry air, vapor, liquid, and ice at constant pressure, respectively. The liquid and ice phases are assumed to be incompressible.

MoistAirBuoyancy(
    grid;
    base_pressure,
    reference_potential_temperature,
    thermodynamics
) -> MoistAirBuoyancy{RS, AT} where {RS<:(ReferenceState{_A, F} where {_A, F<:(Field{Nothing, Nothing, Center, Nothing, G, I, D, T, B, Nothing} where {G, I, D, T, B})}), AT<:ThermodynamicConstants}

Return a MoistAirBuoyancy formulation that can be provided as input to an Oceananigans.NonhydrostaticModel.

Example

using Breeze, Oceananigans

grid = RectilinearGrid(size=(1, 1, 8), extent=(1, 1, 3e3))
buoyancy = MoistAirBuoyancy(grid)

# output
MoistAirBuoyancy:
├── reference_state: ReferenceState{Float64}(p₀=101325.0, θ₀=288.0)
└── thermodynamics: ThermodynamicConstants{Float64}

To build a model with MoistAirBuoyancy, we include potential temperature and total specific humidity tracers θ and qᵗ to the model.

model = NonhydrostaticModel(; grid, buoyancy, tracers = (:θ, :qᵗ))
                                     
# output
NonhydrostaticModel{CPU, RectilinearGrid}(time = 0 seconds, iteration = 0)
├── grid: 1×1×8 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 1×1×3 halo
├── timestepper: RungeKutta3TimeStepper
├── advection scheme: Centered(order=2)
├── tracers: (θ, qᵗ)
├── closure: Nothing
├── buoyancy: MoistAirBuoyancy with ĝ = NegativeZDirection()
└── coriolis: Nothing

AtmosphereModel(
    grid;
    clock,
    thermodynamics,
    formulation,
    moisture_density,
    tracers,
    coriolis,
    boundary_conditions,
    forcing,
    advection,
    microphysics,
    timestepper
) -> AtmosphereModel{Frm, Arc, Tst, Grd, Oceananigans.TimeSteppers.Clock{Float64, Float64, Int64, Int64}, Thm, Den, Mom, Eng, Moi, Mfr, Tmp, Prs, Ppa, Sol, Vel, Trc, Adv, Nothing, Frc, Nothing, @NamedTuple{}, Nothing, Nothing} where {Frm, Arc, Tst, Grd, Thm, Den, Mom, Eng, Moi, Mfr, Tmp, Prs, Ppa, Sol, Vel, Trc, Adv, Frc}

Return an AtmosphereModel that uses the anelastic approximation following Pauluis (2008).

Example

julia> using Breeze, Breeze.AtmosphereModels, Oceananigans

julia> grid = RectilinearGrid(size=(8, 8, 8), extent=(1, 2, 3));

julia> model = AtmosphereModel(grid)
AtmosphereModel{CPU, RectilinearGrid}(time = 0 seconds, iteration = 0)
├── grid: 8×8×8 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── formulation: AnelasticFormulation(p₀=101325.0, θ₀=288.0)
├── timestepper: RungeKutta3TimeStepper
├── advection scheme: WENO{3, Float64, Float32}(order=5)
├── tracers: ()
├── coriolis: Nothing
└── microphysics: Nothing

References

Pauluis, O. (2008). Thermodynamic consistency of the anelastic approximation for a moist atmosphere. Journal of the Atmospheric Sciences 65, 2719–2729.

WarmPhaseSaturationAdjustment(reference_state, thermodynamics)

Simple warm-phase saturation adjustment microphysics that computes temperature via a saturation adjustment.

struct MoistureMassFractions{FT}

A struct representing the moisture mass fractions of a moist air parcel.

Fields

• vapor: the mass fraction of vapor
• liquid: the mass fraction of liquid
• ice: the mass fraction of ice

adiabatic_hydrostatic_density(z, p₀, θ₀, thermo) -> Any

Compute the reference density at height z that associated with the reference pressure and potential temperature. The reference density is defined as the density of dry air at the reference pressure and temperature.

adiabatic_hydrostatic_pressure(z, p₀, θ₀, thermo) -> Any

Compute the reference pressure at height z that associated with the reference pressure and potential temperature. The reference pressure is defined as the pressure of dry air at the reference pressure and temperature.

saturation_specific_humidity(
    T,
    ρ,
    thermo::ThermodynamicConstants,
    phase::CondensedPhase
) -> Any

Compute the saturation specific humidity for a gas at temperature T, total density ρ, thermodynamics, and phase via:

\[qᵛ⁺ = pᵛ⁺ / (ρ Rᵛ T) ,\]

where $pᵛ⁺$ is the saturation_vapor_pressure, $ρ$ is total density, and $Rᵛ$ is the specific gas constant for water vapor.

saturation_vapor_pressure(
    T,
    thermo,
    phase::CondensedPhase
) -> Any

Compute the saturation vapor pressure $pᵛ⁺$ over a planar surface composed of the "$β$-phase" (liquid, or ice) using the Clausius-Clapeyron relation,

\[dpᵛ⁺ / dT = pᵛ⁺ ℒᵝ(T) / (Rᵛ T^2) ,\]

where the latent heat is $ℒᵝ(T) = ℒᵝ(T=0) + Δcᵝ T$, with $Δcᵝ ≡ (cᵖᵛ - cᵝ)$ .

The saturation vapor pressure $pᵛ⁺$ is obtained after integrating the above from the triple point, i.e., $p(Tᵗʳ) = pᵗʳ$ to get

\[pᵛ⁺(T) = pᵗʳ \left ( \frac{T}{Tᵗʳ} \right )^{Δcᵝ / Rᵛ} \exp \left [ (1/Tᵗʳ - 1/T) ℒᵝ(T=0) / Rᵛ \right ] .\]

Note that latent heat $ℒᵝ(T=0)$ is the difference between the enthalpy of water vapor and the phase $β$ when the temperature is $T = 0$K, or absolute zero.

We define the latent heat using its value $ℒᵝᵣ = ℒᵝ(T=Tᵣ)$ at the "energy reference temperature" $T = Tᵣ$ (usually $Tᵣ ≡ 273.15$K $= 0^∘$C), such that

\[ℒᵝ(T) = ℒᵝᵣ + Δcᵝ (T - Tᵣ), \quad \text{and} \quad ℒᵝ(T=0) = ℒᵝᵣ - Δcᵝ Tᵣ``.\]

compute_boussinesq_adjustment_temperature(
    𝒰₀::Breeze.Thermodynamics.PotentialTemperatureState{FT},
    thermo
) -> Any

Return the temperature $T$ corresponding to thermodynamic equilibrium between the specific humidity and liquid mass fractions of the input thermodynamic state 𝒰₀, wherein the specific humidity is equal to or less than the saturation specific humidity at the given conditions and affiliated with theromdynamic constants thermo.

The saturation equilibrium temperature satisfies the nonlinear relation

\[θ = [1 - ℒˡᵣ qˡ / (cᵖᵐ T)] T / Π ,\]

with $ℒˡᵣ$ the latent heat at the reference temperature $Tᵣ$, $cᵖᵐ$ the mixture specific heat, $Π$ the Exner function, $qˡ = \max(0, qᵗ - qᵛ⁺)$ the condensate specific humidity, $qᵗ$ is the total specific humidity, $qᵛ⁺$ is the saturation specific humidity.

The saturation equilibrium temperature is thus obtained by solving $r(T)$, where

\[r(T) ≡ T - θ Π - ℒˡᵣ qˡ / cᵖᵐ .\]

Solution of $r(T) = 0$ is found via the secant method.

PotentialTemperatureKernel(temperature)

A callable object for diagnosing the potential temperature field, given a temperature field, designed for use as a KernelFunctionOperation in Oceananigans. Follows the pattern used for saturation diagnostics.

SaturationSpecificHumidityField(
    model
) -> Field{LX, LY, LZ, O, G, I, D, T, B, Oceananigans.Fields.FieldStatus{Float64}} where {LX, LY, LZ, O, G, I, D, T, B}

Return a field for the saturation specific humidity.

SaturationSpecificHumidityKernel(temperature)

A callable object for diagnosing the saturation specific humidity field, given a temperature field, designed for use as a KernelFunctionOperation in Oceananigans. Parameters are captured within the kernel struct for GPU friendliness.

compute_temperature(state, microphysics, thermo) -> Any

Return the temperature associated with the thermodynamic state, microphysics scheme, and thermodynamic constants.

compute_thermodynamic_state(
    state::Breeze.Thermodynamics.AbstractThermodynamicState,
    _::Nothing,
    thermo
) -> Breeze.Thermodynamics.AbstractThermodynamicState

Return a possibly adjusted thermodynamic state associated with the microphysics scheme and thermodynamic constants.

moisture_mass_fractions(
    i,
    j,
    k,
    grid,
    _::Nothing,
    microphysical_fields,
    moisture_mass_fraction
) -> Breeze.Thermodynamics.MoistureMassFractions

Build and return MoistureMassFractions at (i, j, k) for the given grid, microphysics, microphysical_fields, and total moisture mass fraction qᵗ.

Dispatch is provided for ::Nothing microphysics here. Specific microphysics schemes may extend this method to provide tailored behavior.

compute_flux_bc_tendencies!(model::AtmosphereModel)

Apply boundary conditions by adding flux divergences to the right-hand-side.

make_pressure_correction!(
    model::AtmosphereModel{<:AnelasticFormulation},
    Δt
)

Update the predictor momentum $(ρu, ρv, ρw)$ with the non-hydrostatic pressure via

\[(\rho\boldsymbol{u})^{n+1} = (\rho\boldsymbol{u})^n - \Delta t \rho_r \boldsymbol{\nabla} \left( \alpha_r p_{nh} \right)\]