Notation and conventions

This appendix establishes a common notation across the documentation and source code. Each entry lists a mathematical symbol and the Unicode form commonly used in the codebase, along with a common "property name", and a description. The property names may take a verbose "English form" or concise "mathematical form" corresponding to the given Unicode symbol. As properties, mathematical names are usually used mathematical form is invoked for the elements of a NamedTuple. Mathematical symbols are shown with inline math, while the Unicode column shows the exact glyphs used in code.

The table below reserves symbols for the dynamics and thermodynamics — the equations of motion, the thermodynamic state, and the numerics that step them — so that new notation in those can be introduced without colliding with what is already there. A parameterization dense enough to exhaust the alphabet on its own does not belong in it: its notation is scoped to its own pages instead, where reusing a letter reserved here is a local decision rather than a conflict. The P3 notation section does that for the Predicted Particle Properties scheme.

A few notes about the following table:

  • TC stands for ThermodynamicConstants
  • AM stands for AtmosphereModel
  • RS stands for ReferenceState
  • Note that there are independent concepts of "reference". For example, AnelasticDynamics involves a "reference state", which is an adiabatic, hydrostatic solution to the equations of motion. But there is also an "energy reference temperature" and "reference latent heat", which are thermodynamic constants required to define the internal energy of moist atmospheric constituents.
  • Mapping to AM fields: ρs corresponds to static_energy_density(model), and the moisture density is accessed via model.moisture_density.

The following table also uses a few conventions that suffuse the source code and which are internalized by wise developers:

  • constants refers to an instance of ThermodynamicConstants()
  • q refers to an instance of MoistureMassFractions
  • "Reference" quantities use a subscript $r$ (e.g., $p_r$, $\rho_r$).
  • Phase or mixture identifiers ($d$, $v$, $m$, and $t$ for total) appear as superscripts (e.g., $Rᵈ$, $cᵖᵐ$, $qᵗ$, $ρᵗ$), matching usage in the codebase (e.g., Rᵈ, cᵖᵐ).
  • The superscript $s$ is reserved for surface (e.g. $pˢ$, $θˢ$, $ρˢ$: values at a column's bottom face). Snow therefore takes $sn$ (e.g. $qˢⁿ$, $ρqˢⁿ$, $𝕎ˢⁿ$). Other multi-letter superscripts keep their own spellings: $st$ for standard ($pˢᵗ$) and $sw$ for shortwave ($τˢʷ$).
  • Momentum and the thermodynamic variable are stored coupling-density-weighted ($ρu = ρᵈ u$, and the thermodynamic density $ρᵡ = ρᵈ χ$ — i.e. $ρθ = ρᵈ θ$ or $ρs$). The coupling density is dynamics_density(dynamics): the reference density $ρᵣ$ for AnelasticDynamics, and the prognostic dry-air density $ρᵈ$ for CompressibleDynamics. Velocity and $θ$ are recovered by dividing by the coupling density.
  • Water/moisture is stored as partial densities (ρqᵛ, ρqˡ, ρqⁱ, …; mass per volume) and recovered as mass fractions by dividing by the total air density $ρ = ρᵈ + ρᵗ$ ($qˣ = ρˣ/ρ$), where $ρᵗ = ρqᵛᵉ + Σ ρqᶜ$ is the total condensate density (all phases of the condensable species). The thermodynamics works in mass fractions throughout. The total density (total_density(dynamics)) — diagnosed on the compressible core, the reference density on the anelastic core — is also the carrier for scalar/water advection, the equation of state, and buoyancy.
math symbolcodeproperty namedescription
$\rho$ρAM.densityTotal air density, $ρ = ρᵈ + ρᵗ$ (diagnosed on the compressible core); the reference density $ρ = pᵣ / Rᵐ T$ on the anelastic core
$ρᵈ$ρᵈAM.dynamics.dry_densityDry-air density; the prognostic coupling density of CompressibleDynamics (total $ρ = ρᵈ + ρᵗ$)
$ρᵗ$ρᵗTotal condensate density, $ρᵗ = ρqᵛᵉ + Σ ρqᶜ$ (vapor/equilibrium moisture plus all condensed species); diagnosed via total_condensate_density, summed over condensate_field_names
$\alpha$αSpecific volume, $α = 1/ρ$
$\boldsymbol{u} = (u,v,w)$u, v, wAM.velocitiesVelocity components in (x, y, z) or (east, north, up)
$\boldsymbol{ρu} = (ρu, ρv, ρw)$ρu, ρv, ρwAM.momentumMomentum components
$\tilde{w}$w̃AM.dynamics.contravariant_vertical_velocityContravariant vertical velocity (grid-relative, normal to $r$-surfaces)
$\rho \tilde{w}$ρw̃AM.dynamics.contravariant_vertical_momentumContravariant vertical momentum
$r$rrnode(i, j, k, grid, ℓz)Reference (computational) vertical coordinate of a terrain-following grid; the physical height is $z(x, y, r)$ (znode), matching Oceananigans' r/z convention
$s$sstatic_energy(model)(Liquid-ice) moist static energy, $s = cᵖᵐ T + g z - ℒˡᵣ qˡ - ℒⁱᵣ qⁱ$; $e$ is reserved for turbulent kinetic energy
$ρ s$ρsstatic_energy_density(model)Static energy density, the prognostic thermodynamic variable of StaticEnergyFormulation
$E$Etotal_energy(model)Total energy, $E = s + (u^2 + v^2 + w^2)/2$. E is also the formulation-agnostic energy key: a flux or forcing supplied under E (or ρE) is applied to whichever thermodynamic variable the formulation evolves
$ρ E$ρETotal energy density; the boundary_conditions and forcing key for an energy input, routed onto $ρᵡ$
$ρᵡ$ρᵡthermodynamic_density(formulation)Thermodynamic density: the generic coupling-weighted prognostic thermodynamic variable, $ρᵡ = ρᵈ χ$ — concretely $ρθ$ for the potential-temperature formulation or $ρs$ for static energy. The intensive variable is recovered as $χ = ρᵡ / ρᵈ$
$T$TAM.temperatureTemperature
$T⁺$T⁺DewpointTemperature(model)Dewpoint temperature
$p$pAM.pressurePressure
$b$bBuoyancy
$q^{ve}$qᵛᵉScheme-dependent specific moisture: vapor (non-equilibrium) or equilibrium moisture (saturation adjustment)
$ρ q^{ve}$ρqᵛᵉAM.moisture_densityScheme-dependent moisture density: $ρqᵛ$ or $ρqᵉ$
$ρ qᵉ$ρqᵉAM.moisture_densityEquilibrium moisture density (saturation adjustment schemes)
$ρ qᵛ$ρqᵛAM.moisture_densityVapor density (non-equilibrium schemes)
$ρ qᵗ$ρqᵗTotal moisture density; the boundary_conditions and forcing key for a water input (specific alias qᵗ for forcings), routed onto $ρqᵛᵉ$ whatever the microphysics calls it
$qᵛ$qᵛAM.microphysical_fields.qᵛVapor mass fraction, a.k.a "specific humidity"
$qˡ$qˡAM.microphysical_fields.qˡLiquid mass fraction
$qⁱ$qⁱAM.microphysical_fields.qⁱIce mass fraction
$qᶜˡ$qᶜˡAM.microphysical_fields.qᶜˡCloud liquid mass fraction
$qᶜⁱ$qᶜⁱAM.microphysical_fields.qᶜⁱCloud ice mass fraction
$qʳ$qʳRain mass fraction
$qˢⁿ$qˢⁿSnow mass fraction
$ρqᵛ$ρqᵛVapor density
$ρqˡ$ρqˡLiquid density
$ρqⁱ$ρqⁱIce density
$ρqᶜˡ$ρqᶜˡCloud liquid density
$ρqᶜⁱ$ρqᶜⁱCloud ice density
$ρqʳ$ρqʳAM.microphysical_fields.ρqʳRain density
$ρqˢⁿ$ρqˢⁿAM.microphysical_fields.ρqˢⁿSnow density
$n^{cl}$nᶜˡAM.microphysical_fields.nᶜˡCloud droplet number per unit mass (1/kg)
$n^r$nʳAM.microphysical_fields.nʳRain drop number per unit mass (1/kg)
$n^a$nᵃAM.microphysical_fields.nᵃAerosol number per unit mass (1/kg)
$\rho n^{cl}$ρnᶜˡAM.microphysical_fields.ρnᶜˡCloud droplet number density (1/m³)
$\rho n^r$ρnʳAM.microphysical_fields.ρnʳRain drop number density (1/m³)
$\rho n^a$ρnᵃAM.microphysical_fields.ρnᵃAerosol number density (1/m³)
$N^{cl}$NᶜˡVolumetric cloud droplet number density, $Nᶜˡ = ρ nᶜˡ$ (1/m³)
$N^r$NʳVolumetric rain drop number density, $Nʳ = ρ nʳ$ (1/m³)
$N^a$NᵃVolumetric aerosol number density, $Nᵃ = ρ nᵃ$ (1/m³)
$n^{ccn}$nᶜᶜⁿCloud condensation nuclei activated per unit mass (1/kg); the activation rate $∂nᶜᶜⁿ/∂t$ is a source of $nᶜˡ$
$N^{ccn}$NᶜᶜⁿVolumetric CCN number density, $Nᶜᶜⁿ = ρ nᶜᶜⁿ$ (1/m³)
$q^{ccn}$qᶜᶜⁿMass fraction condensed onto newly activated CCN (kg/kg)
$\mathbb{W}^{cl}$𝕎ᶜˡTerminal velocity of cloud liquid (scalar, positive downward)
$\mathbb{W}^{ci}$𝕎ᶜⁱTerminal velocity of cloud ice (scalar, positive downward)
$\mathbb{W}^r$𝕎ʳTerminal velocity of rain (scalar, positive downward)
$\mathbb{W}^{sn}$𝕎ˢⁿTerminal velocity of snow (scalar, positive downward)
$\mathbb{W}^i$𝕎ⁱTerminal velocity of ice (scalar, positive downward); $i$ is dry ice, distinct from cloud ice $ci$
$\mathbb{W}^{nx}$𝕎ⁿˣNumber-weighted terminal velocity of species $x$ (𝕎ⁿᶜˡ, 𝕎ⁿʳ, 𝕎ⁿⁱ); a bare species label is the mass-weighted mean, and the weighting marker is a superscript preceding the species
$w^x$wˣSigned vertical advection velocity of species $x$, $wˣ = -𝕎ˣ$ (wᶜˡ, wⁿᶜˡ, wʳ, wⁿʳ, wⁱ, wⁿⁱ)
$qᵛ⁺$qᵛ⁺Saturation specific humidity over a surface
$qᵛ⁺ˡ$qᵛ⁺ˡSaturation specific humidity over a planar liquid surface
$qᵛ⁺ⁱ$qᵛ⁺ⁱSaturation specific humidity over a planar ice surface
$pᵛ$pᵛVapor pressure (partial pressure of water vapor), $pᵛ = ρ qᵛ Rᵛ T$
$pᵛ⁺$pᵛ⁺Saturation vapor pressure
$\mathscr{H}$ℋRelativeHumidity(model)Relative humidity, $ℋ = pᵛ / pᵛ⁺$
$\mathscr{S}$𝒮supersaturation(T, ρ, q, c, surf)Supersaturation, $𝒮 = pᵛ / pᵛ⁺ - 1$
$ξ$ξpsychrometric_correctionPsychrometric correction, $ξ = 1 + ℒ² qᵛ⁺ / (cᵖ Rᵛ T²)$; $ξˡ$ and $ξⁱ$ name the liquid and ice phase
$δqˡ$, $δqⁱ$δqˡ, δqⁱSaturation-adjustment increments, $δq = (qᵛ - qᵛ⁺) / ξ$ for the liquid and ice phase
$g$gTC.gravitational_accelerationGravitational acceleration
$c^{ac}$cᵃᶜAcoustic sound speed, $cᵃᶜ = \sqrt{γ Rᵈ T}$
$\mathbb{C}_{X,i}$ℂˣᵢdescriptive parameter propertyThe $i$-th calibratable empirical coefficient in relation $X$; source uses modifier letters because Unicode lacks general subscript letters; state, physical constants, case inputs, switches, and numerical safeguards do not receive $\mathbb{C}$
$\mathcal{R}$ℛTC.molar_gas_constantUniversal (molar) gas constant
$Tᵗʳ$TᵗʳTC.triple_point_temperatureTemperature at the vapor-liquid-ice triple point
$pᵗʳ$pᵗʳTC.triple_point_pressurePressure at the vapor-liquid-ice triple point
$mᵈ$mᵈTC.dry_air.molar_massMolar mass of dry air
$mᵛ$mᵛTC.vapor.molar_massMolar mass of vapor
$Rᵈ$Rᵈdry_air_gas_constant(constants)Dry air gas constant ($Rᵈ = \mathcal{R} / mᵈ$)
$Rᵛ$Rᵛvapor_gas_constant(constants)Water vapor gas constant ($Rᵛ = \mathcal{R} / mᵛ$)
$Rᵐ$Rᵐmixture_gas_constant(q, constants)Mixture gas constant, function of $q$
$cᵖᵈ$cᵖᵈTC.dry_air.heat_capacityHeat capacity of dry air at constant pressure
$cᵖᵛ$cᵖᵛTC.vapor.heat_capacityHeat capacity of vapor at constant pressure
$cˡ$cˡTC.liquid.heat_capacityHeat capacity of the liquid phase (incompressible)
$cⁱ$cⁱTC.ice.heat_capacityHeat capacity of the ice phase (incompressible)
$\rho^L$ρᴸTC.liquid.densityIntrinsic density of liquid water
$\rho^I$ρᴵTC.ice.densityIntrinsic density of ice
$cᵖᵐ$cᵖᵐmixture_heat_capacity(q, constants)Mixture heat capacity at constant pressure
$Tᵣ$TᵣTC.energy_reference_temperatureReference temperature for internal energy relations and latent heat
$\mathcal{L}^l_r$ℒˡᵣTC.liquid.reference_latent_heatLatent heat of condensation at the energy reference temperature
$\mathcal{L}^i_r$ℒⁱᵣTC.ice.reference_latent_heatLatent heat of deposition at the energy reference temperature
$\mathcal{L}^l(T)$ℒˡliquid_latent_heat(T, constants)Temperature-dependent latent heat of condensation
$\mathcal{L}^i(T)$ℒⁱice_latent_heat(T, constants)Temperature-dependent latent heat of deposition
$θ₀$θ₀RS.potential_temperature(Constant) reference potential temperature for the anelastic formulation
$p₀$p₀RS.base_pressureReference pressure at $z = 0$: the datum the reference profiles are anchored to
$pˢ$pˢRS.surface_pressureReference pressure at a column's bottom face (the terrain surface over terrain), $p₀$ reduced to that height
$p^{st}$pˢᵗRS.standard_pressureStandard pressure for potential temperature (default 10⁵ Pa)
$ρᵣ$ρᵣRS.densityDensity of a dry reference state for the anelastic formulation
$αᵣ$αᵣSpecific volume of a dry reference state, $αᵣ = Rᵈ θ₀ / pᵣ$
$pᵣ$pᵣRS.pressurePressure of a dry adiabatic reference pressure for the anelastic formulation
$\Pi$ΠExner function, $Π = (pᵣ / pˢᵗ)^{Rᵐ / cᵖᵐ}$
$θᵛ$θᵛVirtual potential temperature
$θᵉ$θᵉEquivalent potential temperature
$θˡⁱ$θˡⁱLiquid-ice potential temperature
$θᵇ$θᵇStability-equivalent potential temperature (for moist Brunt-Väisälä)
$θ$θShorthand for liquid-ice potential temperature (used in set!)
$\Delta t$ΔtSimulation.ΔtTime step.
$\boldsymbol{\tau}$τKinematic subgrid/viscous stress tensor (per unit mass)
$\boldsymbol{\mathcal{T}}$𝒯Dynamic stress tensor used in anelastic momentum, $\mathcal{T} = ρᵣ τ$
$\boldsymbol{J}$JDynamic diffusive flux for scalars
$τˣ$τˣSurface momentum flux ($x$-component), N/m²
$τʸ$τʸSurface momentum flux ($y$-component), N/m²
$\mathcal{Q}^T$𝒬ᵀSurface sensible heat flux, $\mathcal{Q}^T = cᵖᵐ Jᵀ$
$\mathcal{Q}^v$𝒬ᵛSurface latent heat flux, $\mathcal{Q}^v = \mathcal{L}^l Jᵛ$
$Jᵀ$JᵀSurface temperature flux, kg K/m²s
$Jᶿ$JᶿSurface potential-temperature flux, $Jᶿ = Jᵀ / Π$, kg K/m²s
$Jᵛ$JᵛSurface moisture flux, kg/m²s
$Cᴰ$CᴰSurface drag coefficient
$Cᵀ$CᵀSurface sensible heat transfer coefficient (Stanton number)
$Cᵛ$CᵛSurface vapor transfer coefficient (Dalton number)
$\ell$ℓA length scale, m; the superscript says which one. Bare $ℓ$ is used locally where only one length scale is in play (the primary mixing length in TKEBasedTurbulenceClosure, the divergence-damping scale in CompressibleEquations)
$\ell^N$ℓᴺStratification length of the mixing length, $ℓᴺ = Cᴺ \sqrt{e} / N$; the primary length is $ℓ = \min(z, ℓᴺ)$
$\ell^u, \ell^c, \ell^e, \ell^D$ℓᵘ, ℓᶜ, ℓᵉ, ℓᴰMixing lengths for momentum, scalars, TKE and dissipation: $ℓᵘ = Sᵘ ℓ$, $ℓᶜ = Sᶜ ℓ$, $ℓᵉ = Sᵉ ℓ$, $ℓᴰ = ℓ / Sᴰ$
$S^u, S^c, S^e, S^D$Sᵘ, Sᶜ, Sᵉ, SᴰStability functions of TKEBasedTurbulenceClosure; constants $Cᵘ, Cᶜ, Cᵉ, Cᴰ$ in ConstantStabilityFunctions
$\ell^r$ℓʳroughness_lengthSurface roughness length for momentum, m. Superscript $r$ elsewhere denotes rain ($qʳ$); the two never appear together
$\ell^{rh}$ℓʳʰscalar_roughness_lengthSurface roughness length for heat and moisture; defaults to $ℓʳ/7.3$
$\kappa$κvon Kármán constant. Never used for a diffusivity in Breeze's own code — the Oceananigans accessors literally named κᶠᶜᶜ, κᶜᶠᶜ, κᶜᶜᶠ are the one exception, and they are thin one-liners
$K^u$KᵘEddy diffusivity for momentum, $K^u = ℓ^u \sqrt{e}$, m² s⁻¹. Oceananigans' scalar-diffusivity closures spell their own field νₑ, which Breeze reads but does not define
$K^c$KᶜEddy diffusivity for scalars, $K^c = ℓ^c \sqrt{e}$, m² s⁻¹
$K^e$KᵉEddy diffusivity for TKE, $K^e = ℓ^e \sqrt{e}$, m² s⁻¹
$e$eSubgrid turbulent kinetic energy, m² s⁻²
$\rho e$ρePrognostic TKE density, the tracer TKEBasedTurbulenceClosure adds to the model
$\mathrm{Pr}$PrTurbulent Prandtl number, $\mathrm{Pr} = K^u/K^c = S^u/S^c$
$Ri$RiGradient Richardson number, $Ri = N²/S²$
$S$SVertical shear magnitude, $S² = (∂_z u)² + (∂_z v)²$, s⁻¹
$N^2$N²Squared Brunt–Väisälä frequency, s⁻². (Bare $N$ is the acoustic substep count, below)
$h^{bl}$hᵇˡBoundary-layer depth, m; a diagnostic (the height of the capping inversion in convective conditions)
$T_0$T₀Sea surface temperature
$qᵛ₀$qᵛ₀Saturation specific humidity at sea surface
$\mathscr{I}$ℐRadiative flux (intensity), W/m²
$F_{\mathscr{I}}$FℐRadiative flux divergence (heating rate), K/s
$τˡʷ$τˡʷAtmosphere optical thickness for longwave
$τˢʷ$τˢʷAtmosphere optical thickness for shortwave
$N_A$ℕᴬAvogadro's number, molecules per mole
$\mathcal{U}$𝒰Thermodynamic state struct (e.g., StaticEnergyState)
$\mathcal{M}$ℳMicrophysical state struct (e.g., WarmPhaseOneMomentState)
$Π^L$ΠᴸAcousticSubstepper.linearization_exnerStage-entry Exner function, $Π^L = (p^L / p^{st})^κ$
$θ^L$θᴸAcousticSubstepper.linearization_potential_temperatureStage-entry potential temperature, $θ^L = (ρθ)^L / ρ^L$
$γ^m R^m\vert_L$γRᵐᴸAcousticSubstepper.linearization_gamma_R_mixtureStage-entry equation-of-state coefficient in $p' = γ^m R^m\vert_L Π^L (ρθ)'$
$C^L$CᴸLinearized pressure coefficient, $C^L = γ^m R^m\vert_L Π^L$
$G^n$GⁿTendency fields at time step $n$
$G^s$GˢSlow tendencies (excludes fast pressure gradient and buoyancy)
$N$NAcousticSubstepper.substepsAcoustic substeps per outer time step, or adaptive substep count before stage partitioning
$N_τ$NτAcoustic substeps in one Runge-Kutta stage
$\Delta \tau$ΔτAcoustic substep size, $Δτ = Δt / N$ for proportional substep distribution
$ρ'$ρ′AcousticSubstepper.density_perturbationDensity perturbation about the stage-entry state
$(ρθ)'$ρθ′AcousticSubstepper.density_potential_temperature_perturbationThermodynamic-density perturbation about the stage-entry state
$(ρu)', (ρv)', (ρw)'$ρu′, ρv′, ρw′AcousticSubstepper.momentum_perturbationMomentum perturbations about the stage-entry state
$D_τ$DτKlemp-Skamarock-Ha divergence-damping proxy, $D_τ = ((ρθ)'_τ - (ρθ)'_{τ-\Delta τ}) / θ^L$
$\bar{u}, \bar{v}, \bar{w}$ū, v̄, w̄AcousticSubstepper.time_averaged_velocitiesTime-averaged velocities for non-acoustic scalar advection