From 7496e9466d126c2877389663ca35c7b342554a7f Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 09:31:49 +1100 Subject: [PATCH 01/13] add ext docstrings in API list --- docs/make.jl | 12 +++++++++++- docs/src/api.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index f124ffed1..38153be18 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -68,9 +68,19 @@ semaphore = Base.Semaphore(Threads.nthreads(:interactive)) end end +modules = Module[] +BreezeRRTMGPExt = isdefined(Base, :get_extension) ? Base.get_extension(Breeze, :BreezeRRTMGPExt) : Breeze.BreezeRRTMGPExt +BreezeCloudMicrophysicsExt = isdefined(Base, :get_extension) ? Base.get_extension(Breeze, :BreezeCloudMicrophysicsExt) : Breeze.BreezeCloudMicrophysicsExt + +for m in [Breeze, BreezeRRTMGPExt, BreezeCloudMicrophysicsExt] + if !isnothing(m) + push!(modules, m) + end +end + makedocs( ; - modules = [Breeze], + modules, sitename = "Breeze", plugins = [bib], format = Documenter.HTML( diff --git a/docs/src/api.md b/docs/src/api.md index 2edaa4675..1f19fca6c 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -70,6 +70,20 @@ Modules = [Breeze.CelestialMechanics] Private = false ``` +### BreezeRRTMGPExt + +```@autodocs +Modules = [BreezeRRTMGPExt] +Private = false +``` + +### BreezeCloudMicrophysicsExt + +```@autodocs +Modules = [BreezeCloudMicrophysicsExt] +Private = false +``` + ## Private API ```@autodocs @@ -125,3 +139,17 @@ Public = false Modules = [Breeze.CelestialMechanics] Public = false ``` + +### BreezeRRTMGPExt + +```@autodocs +Modules = [BreezeRRTMGPExt] +Public = false +``` + +### BreezeCloudMicrophysicsExt + +```@autodocs +Modules = [BreezeCloudMicrophysicsExt] +Public = false +``` From cb2681306b2f8205632f9afb701eec293da9836f Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 09:40:49 +1100 Subject: [PATCH 02/13] add proper bibtex citation --- docs/src/breeze.bib | 10 ++++++++++ .../gray_radiative_transfer_model.jl | 5 ++++- src/CelestialMechanics/solar_zenith_angle.jl | 16 ++++++++++------ 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/src/breeze.bib b/docs/src/breeze.bib index 2647722ab..f2aa9d8f6 100644 --- a/docs/src/breeze.bib +++ b/docs/src/breeze.bib @@ -185,3 +185,13 @@ @article{vanZanten2011 year = {2011}, doi = {10.1029/2011MS000056} } + +@article{spencer1971fourier, + title={Fourier series representation of the position of the sun}, + author={Spencer, J. W.}, + journal={Search}, + volume={2}, + number={5}, + pages={162-172}, + year={1971} +} \ No newline at end of file diff --git a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl index aecb4b96e..38150e27b 100644 --- a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl +++ b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl @@ -485,7 +485,10 @@ $(TYPEDSIGNATURES) Copy RRTMGP flux arrays to Oceananigans ZFaceFields. -Applies sign convention: positive = upward, negative = downward. +Applies sign convention: +* positive = upward +* negative = downward. + For the non-scattering shortwave solver, only the direct beam flux is computed. """ function copy_fluxes_to_fields!(rtm::GrayRadiativeTransferModel, grid) diff --git a/src/CelestialMechanics/solar_zenith_angle.jl b/src/CelestialMechanics/solar_zenith_angle.jl index 13dbb378c..7277eab2c 100644 --- a/src/CelestialMechanics/solar_zenith_angle.jl +++ b/src/CelestialMechanics/solar_zenith_angle.jl @@ -6,10 +6,6 @@ ##### - Latitude (in degrees) ##### - Longitude (in degrees) ##### -##### Reference: -##### Spencer, J. W. (1971). Fourier series representation of the position of the sun. -##### Search, 2(5), 172. -##### """ day_of_year(dt::DateTime) @@ -23,7 +19,7 @@ day_of_year(dt::DateTime) = Dates.dayofyear(dt) Compute the solar declination angle (in radians) for a given day of year. -Uses the approximation from Spencer (1971): +Uses the approximation by [spencer1971fourier](@citet): ```math δ = 0.006918 - 0.399912 \\cos(γ) + 0.070257 \\sin(γ) @@ -33,6 +29,10 @@ Uses the approximation from Spencer (1971): where ``γ = 2π (d - 1) / 365`` is the fractional year in radians and ``d`` is the day of year. + +# References + +* Spencer, J. W. (1971) Fourier series representation of the position of the sun. Search, 2, 162-172. """ function solar_declination(day_of_year) # Fractional year in radians @@ -54,7 +54,11 @@ Compute the equation of time (in minutes) for a given day of year. This accounts for the difference between mean solar time and apparent solar time due to the eccentricity of Earth's orbit and the obliquity of the ecliptic. -Uses the Spencer (1971) approximation. +Uses the approximation by [spencer1971fourier](@citet). + +# References + +* Spencer, J. W. (1971) Fourier series representation of the position of the sun. Search, 2, 162-172. """ function equation_of_time(day_of_year) # Fractional year in radians From 807a49c7292fabcb85a14c6d50b7784165b0642f Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 10:09:30 +1100 Subject: [PATCH 03/13] updates --- docs/make.jl | 1 + .../gray_radiative_transfer_model.jl | 2 +- src/CelestialMechanics/CelestialMechanics.jl | 3 +-- src/CelestialMechanics/solar_zenith_angle.jl | 14 +++++++------- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 38153be18..d49546c8f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,4 +1,5 @@ using Breeze +using RRTMGP, CloudMicrophysics # to load Breeze extensions using Documenter using DocumenterCitations using Literate diff --git a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl index 38150e27b..a744efedf 100644 --- a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl +++ b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl @@ -528,4 +528,4 @@ end end # Default no-op for models without radiation -update_radiation!(::Nothing, model) = nothing \ No newline at end of file +update_radiation!(::Nothing, model) = nothing diff --git a/src/CelestialMechanics/CelestialMechanics.jl b/src/CelestialMechanics/CelestialMechanics.jl index 3ae837d05..47ca2471d 100644 --- a/src/CelestialMechanics/CelestialMechanics.jl +++ b/src/CelestialMechanics/CelestialMechanics.jl @@ -7,10 +7,9 @@ export cos_solar_zenith_angle, day_of_year using Dates: DateTime, Dates - +using DocStringExtensions: TYPEDSIGNATURES using Oceananigans.Grids: RectilinearGrid, Flat, Bounded, Center, xnode, ynode include("solar_zenith_angle.jl") end # module - diff --git a/src/CelestialMechanics/solar_zenith_angle.jl b/src/CelestialMechanics/solar_zenith_angle.jl index 7277eab2c..696cbaf94 100644 --- a/src/CelestialMechanics/solar_zenith_angle.jl +++ b/src/CelestialMechanics/solar_zenith_angle.jl @@ -8,14 +8,14 @@ ##### """ - day_of_year(dt::DateTime) +$(TYPEDSIGNATURES) Return the day of year (1-365/366) for a given DateTime. """ day_of_year(dt::DateTime) = Dates.dayofyear(dt) """ - solar_declination(day_of_year) +$(TYPEDSIGNATURES) Compute the solar declination angle (in radians) for a given day of year. @@ -47,14 +47,14 @@ function solar_declination(day_of_year) end """ - equation_of_time(day_of_year) +$(TYPEDSIGNATURES) Compute the equation of time (in minutes) for a given day of year. This accounts for the difference between mean solar time and apparent solar time due to the eccentricity of Earth's orbit and the obliquity of the ecliptic. -Uses the approximation by [spencer1971fourier](@citet). +Uses the approximation by [spencer1971fourier](@citet); see [`solar_declination`](@ref). # References @@ -72,7 +72,7 @@ function equation_of_time(day_of_year) end """ - hour_angle(datetime::DateTime, longitude) +$(TYPEDSIGNATURES) Compute the hour angle (in radians) for a given datetime and longitude. @@ -105,7 +105,7 @@ function hour_angle(datetime::DateTime, longitude) end """ - cos_solar_zenith_angle(datetime::DateTime, latitude, longitude) +$(TYPEDSIGNATURES) Compute the cosine of the solar zenith angle for a given datetime and location. @@ -142,7 +142,7 @@ end const SingleColumnGrid = RectilinearGrid{<:Any, <:Flat, <:Flat, <:Bounded} """ - cos_solar_zenith_angle(grid::AbstractGrid, datetime::DateTime) +$(TYPEDSIGNATURES) Compute the cosine of the solar zenith angle for the grid's location. From 388e55e3e02398fcdc996a476918c930925f5fef Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 10:18:10 +1100 Subject: [PATCH 04/13] add empty line --- docs/src/breeze.bib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/breeze.bib b/docs/src/breeze.bib index f2aa9d8f6..0f4ce6c5b 100644 --- a/docs/src/breeze.bib +++ b/docs/src/breeze.bib @@ -194,4 +194,4 @@ @article{spencer1971fourier number={5}, pages={162-172}, year={1971} -} \ No newline at end of file +} From 3ed8127d5d7317cb118b5e412df75939974bcf5c Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 10:18:10 +1100 Subject: [PATCH 05/13] rewrite expressions --- docs/src/radiative_transfer.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/src/radiative_transfer.md b/docs/src/radiative_transfer.md index 284fe9ced..c147dffd0 100644 --- a/docs/src/radiative_transfer.md +++ b/docs/src/radiative_transfer.md @@ -54,21 +54,23 @@ The [`RadiativeTransferModel`](@ref) model computes: - **Longwave radiation**: Both upwelling and downwelling thermal radiation using RRTMGP's two-stream solver - **Shortwave radiation**: Direct beam solar radiation -The gray atmosphere optical thickness follows the parameterization by [OGormanSchneider2008](@citet): +The gray atmosphere optical thickness for longwave follows the parameterization by [OGormanSchneider2008](@citet)š ```math -τ_{lw} = α \frac{Δp}{p} \left[ f_l \frac{p}{p_0} + 4 (1 - f_l) \left(\frac{p}{p_0}\right)^4 \right] \left[ τ_e + (τ_p - τ_e) \sin^2 φ \right] +τ_{lw} = α \frac{Δp}{p_0} \left[ f_l + 4 (1 - f_l) \left(\frac{p}{p_0}\right)^3 \right] \left[ τ_e + (τ_p - τ_e) \sin^2 φ \right] ``` where ``φ`` is latitude and ``α``, ``f_l``, ``τ_e``, ``τ_p`` are empirical parameters. For shortwave: ```math -τ_{sw} = 2 τ_0 \frac{p}{p_0} \frac{Δp}{p_0} +τ_{sw} = 2 τ_0 \frac{Δp}{p_0} \frac{p}{p_0} ``` where ``τ_0 = 0.22`` is the shortwave optical depth parameter. +The above two expressions are identical to those in the [RRTMGP documentation](https://clima.github.io/RRTMGP.jl/latest/Optics/#Gray-atmosphere-optics). + ### Radiative Fluxes After running [`set!`](@ref), the radiative fluxes are available from the radiation model: From b2df5563f841c6748f6da740fa13def670aea152 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 11:05:19 +1100 Subject: [PATCH 06/13] fix url --- ext/BreezeCloudMicrophysicsExt.jl | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ext/BreezeCloudMicrophysicsExt.jl b/ext/BreezeCloudMicrophysicsExt.jl index 13617a0e0..9611f3058 100644 --- a/ext/BreezeCloudMicrophysicsExt.jl +++ b/ext/BreezeCloudMicrophysicsExt.jl @@ -113,8 +113,7 @@ and _either_ - `S_0`: supersaturation threshold (default: 0) - `qc_0`: cloud liquid water threshold for precipitation (default: 5×10⁻⁴ kg/kg) -For more information see the -[`CloudMicrophysics.jl` documentation](https://clima.github.io/CloudMicrophysicsDocumentation.jl/dev/parameters/parameters0m/). +For more information see the [CloudMicrophysics.jl documentation](https://clima.github.io/CloudMicrophysics.jl/stable/Microphysics0M/s). """ function ZeroMomentCloudMicrophysics(FT::DataType = Oceananigans.defaults.FloatType; nucleation = SaturationAdjustment(FT), From 031a44715afd147c6e8fc2ba98f8a1c273b432be Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 12:23:59 +1100 Subject: [PATCH 07/13] fix url --- ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl index a744efedf..e2c5b48a7 100644 --- a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl +++ b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl @@ -167,10 +167,10 @@ function RadiativeTransferModel(grid, constants, grid_parameters = RRTMGPGridParams(FT; context, nlay=Nz, ncol=Nc) - longwave_solver = NoScatLWRTE(grid_parameters; - params = radiative_transfer_parameters, - sfc_emis = rrtmgp_ε₀, - inc_flux = nothing) + longwave_solver = NoScatLWRTE(grid_parameters; + params = radiative_transfer_parameters, + sfc_emis = rrtmgp_ε₀, + inc_flux = nothing) shortwave_solver = NoScatSWRTE(grid_parameters; cos_zenith = cos_zenith, From 843c2c46eec0945dca72491fbd0868920946a061 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 13:38:14 +1100 Subject: [PATCH 08/13] fix url --- ext/BreezeCloudMicrophysicsExt.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ext/BreezeCloudMicrophysicsExt.jl b/ext/BreezeCloudMicrophysicsExt.jl index 9611f3058..924b921e8 100644 --- a/ext/BreezeCloudMicrophysicsExt.jl +++ b/ext/BreezeCloudMicrophysicsExt.jl @@ -113,7 +113,7 @@ and _either_ - `S_0`: supersaturation threshold (default: 0) - `qc_0`: cloud liquid water threshold for precipitation (default: 5×10⁻⁴ kg/kg) -For more information see the [CloudMicrophysics.jl documentation](https://clima.github.io/CloudMicrophysics.jl/stable/Microphysics0M/s). +For more information see the [CloudMicrophysics.jl documentation](https://clima.github.io/CloudMicrophysics.jl/stable/Microphysics0M). """ function ZeroMomentCloudMicrophysics(FT::DataType = Oceananigans.defaults.FloatType; nucleation = SaturationAdjustment(FT), From d163d7e72244c2990b996b275e3ae5db1b755f43 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 14:16:54 +1100 Subject: [PATCH 09/13] add LW/SW optical depths --- docs/src/appendix/notation.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index 531a4ba3d..fcc4ebfba 100644 --- a/docs/src/appendix/notation.md +++ b/docs/src/appendix/notation.md @@ -79,7 +79,7 @@ The following table also uses a few conventions that suffuse the source code and | ``\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.surface_pressure` | Base (surface) reference pressure | +| ``p₀`` | `p₀` | `RS.surface_pressure` | Base (surface) reference pressure | | ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | | ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | | ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure of a dry adiabatic reference pressure for the anelastic formulation | @@ -89,15 +89,15 @@ The following table also uses a few conventions that suffuse the source code and | ``θˡⁱ`` | `θˡⁱ` | | Liquid-ice potential temperature | | ``θᵇ`` | `θᵇ` | | Stability-equivalent potential temperature (for moist Brunt-Väisälä) | | ``θ`` | `θ` | | Shorthand for liquid-ice potential temperature (used in [`set!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | -| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time step | +| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic diffusive flux for scalars | -| ``τˣ`` | `τˣ` | | Surface momentum flux (x-component), ``τˣ = -ρ₀ Cᴰ U ρu / |U|`` | -| ``τʸ`` | `τʸ` | | Surface momentum flux (y-component), ``τʸ = -ρ₀ Cᴰ U ρv / |U|`` | +| ``τˣ`` | `τˣ` | | Surface momentum flux (``x``-component), ``τˣ = -ρ₀ Cᴰ U ρu / |U|`` | +| ``τʸ`` | `τʸ` | | Surface momentum flux (``y``-component), ``τʸ = -ρ₀ Cᴰ U ρv / |U|`` | | ``\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, ``Jᵀ = -ρ₀ Cᵀ U (θ - θ_0)`` | +| ``Jᵀ`` | `Jᵀ` | | Surface temperature flux, ``Jᵀ = -ρ₀ Cᵀ U (θ - θ_0)`` | | ``Jᵛ`` | `Jᵛ` | | Surface moisture flux, ``Jᵛ = -ρ₀ Cᵛ U (q - q_0^{v+})`` | | ``Cᴰ`` | `Cᴰ` | | Surface drag coefficient | | ``Cᵀ`` | `Cᵀ` | | Surface sensible heat transfer coefficient (Stanton number) | @@ -106,3 +106,5 @@ The following table also uses a few conventions that suffuse the source code and | ``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 | +| ``τˡʷ`` | `τˡʷ` | | Atmospheric atmosphere optical thickness for longwave | +| ``τˢʷ`` | `τˢʷ` | | Atmospheric atmosphere optical thickness for shortwave | From 75cba2f093639994db8fc2e4e63e781bf8b30a0e Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 15:40:14 +1100 Subject: [PATCH 10/13] drop duplicate --- docs/src/appendix/notation.md | 4 ++-- examples/single_column_radiation.jl | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index fcc4ebfba..75172f47d 100644 --- a/docs/src/appendix/notation.md +++ b/docs/src/appendix/notation.md @@ -106,5 +106,5 @@ The following table also uses a few conventions that suffuse the source code and | ``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 | -| ``τˡʷ`` | `τˡʷ` | | Atmospheric atmosphere optical thickness for longwave | -| ``τˢʷ`` | `τˢʷ` | | Atmospheric atmosphere optical thickness for shortwave | +| ``τˡʷ`` | `τˡʷ` | | Atmosphere optical thickness for longwave | +| ``τˢʷ`` | `τˢʷ` | | Atmosphere optical thickness for shortwave | diff --git a/examples/single_column_radiation.jl b/examples/single_column_radiation.jl index cac748a34..642121d91 100644 --- a/examples/single_column_radiation.jl +++ b/examples/single_column_radiation.jl @@ -121,5 +121,4 @@ Legend(fig[1, 6], ax_I, orientation=:horizontal, nbanks=2, framevisible=false) title = "Single Column Gray Radiation with O'Gorman & Schneider (2008) optical thickness" fig[1, :] = Label(fig, title, fontsize=18, tellwidth=false) -save("single_column_radiation.png", fig) fig From 65509ee5d78febf62cfb672af82f992651b30757 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 15:43:54 +1100 Subject: [PATCH 11/13] drop the bulk formula defs --- docs/src/appendix/notation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index 75172f47d..ec89874be 100644 --- a/docs/src/appendix/notation.md +++ b/docs/src/appendix/notation.md @@ -93,12 +93,12 @@ The following table also uses a few conventions that suffuse the source code and | ``\boldsymbol{\tau}`` | `τ` | | Kinematic subgrid/viscous stress tensor (per unit mass) | | ``\boldsymbol{\mathcal{T}}`` | `𝒯` | | Dynamic stress tensor used in anelastic momentum, ``\mathcal{T} = ρᵣ τ`` | | ``\boldsymbol{J}`` | `J` | | Dynamic diffusive flux for scalars | -| ``τˣ`` | `τˣ` | | Surface momentum flux (``x``-component), ``τˣ = -ρ₀ Cᴰ U ρu / |U|`` | -| ``τʸ`` | `τʸ` | | Surface momentum flux (``y``-component), ``τʸ = -ρ₀ Cᴰ U ρv / |U|`` | +| ``τˣ`` | `τˣ` | | 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, ``Jᵀ = -ρ₀ Cᵀ U (θ - θ_0)`` | -| ``Jᵛ`` | `Jᵛ` | | Surface moisture flux, ``Jᵛ = -ρ₀ Cᵛ U (q - q_0^{v+})`` | +| ``Jᵀ`` | `Jᵀ` | | Surface temperature flux, 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) | From 86a919524c83d33c6d7ecb1fa74ca1f87c35dcdc Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 15:44:33 +1100 Subject: [PATCH 12/13] fix notation --- docs/src/appendix/notation.md | 330 ++++++++++++++++++++++++++++++++++ 1 file changed, 330 insertions(+) diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index ec89874be..cc597ee3a 100644 --- a/docs/src/appendix/notation.md +++ b/docs/src/appendix/notation.md @@ -108,3 +108,333 @@ The following table also uses a few conventions that suffuse the source code and | ``F_{\mathscr{I}}`` | `Fℐ` | | Radiative flux divergence (heating rate), K/s | | ``τˡʷ`` | `τˡʷ` | | Atmosphere optical thickness for longwave | | ``τˢʷ`` | `τˢʷ` | | Atmosphere optical thickness for shortwave | +# 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. + +A few notes about the following table: + +* `TC` stands for [`ThermodynamicConstants`](@ref) +* `AM` stands for [`AtmosphereModel`](@ref) +* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) +* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. + +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`](@ref Breeze.Thermodynamics.MoistureMassFractions) +* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). +* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). +* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). + +| math symbol | code | property name | description | +| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | +| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | +| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | +| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | +| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | +| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | +| ``T`` | `T` | `AM.temperature` | Temperature | +| ``p`` | `p` | `AM.pressure` | Pressure | +| ``b`` | `b` | | Buoyancy | +| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | +| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | +| ``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 | +| ``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ᵛ⁺`` | +| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | +| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | +| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | +| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | +| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | +| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | +| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | +| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | +| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | +| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | +| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | +| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | +| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | +| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | +| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | +| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | +| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | +| ``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 | +# 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. + +A few notes about the following table: + +* `TC` stands for [`ThermodynamicConstants`](@ref) +* `AM` stands for [`AtmosphereModel`](@ref) +* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) +* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. + +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`](@ref Breeze.Thermodynamics.MoistureMassFractions) +* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). +* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). +* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). + +| math symbol | code | property name | description | +| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | +| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | +| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | +| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | +| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | +| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | +| ``T`` | `T` | `AM.temperature` | Temperature | +| ``p`` | `p` | `AM.pressure` | Pressure | +| ``b`` | `b` | | Buoyancy | +| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | +| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | +| ``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 | +| ``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ᵛ⁺`` | +| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | +| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | +| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | +| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | +| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | +| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | +| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | +| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | +| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | +| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | +| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | +| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | +| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | +| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | +| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | +| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | +| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | +| ``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 | +# 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. + +A few notes about the following table: + +* `TC` stands for [`ThermodynamicConstants`](@ref) +* `AM` stands for [`AtmosphereModel`](@ref) +* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) +* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. + +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`](@ref Breeze.Thermodynamics.MoistureMassFractions) +* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). +* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). +* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). + +| math symbol | code | property name | description | +| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | +| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | +| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | +| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | +| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | +| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | +| ``T`` | `T` | `AM.temperature` | Temperature | +| ``p`` | `p` | `AM.pressure` | Pressure | +| ``b`` | `b` | | Buoyancy | +| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | +| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | +| ``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 | +| ``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ᵛ⁺`` | +| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | +| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | +| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | +| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | +| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | +| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | +| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | +| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | +| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | +| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | +| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | +| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | +| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | +| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | +| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | +| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | +| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | +| ``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 | From 261bf1ade5a096e927914ed815a1f6f325a1ee4e Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Tue, 16 Dec 2025 15:45:12 +1100 Subject: [PATCH 13/13] fix notation --- docs/src/appendix/notation.md | 330 ---------------------------------- 1 file changed, 330 deletions(-) diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index cc597ee3a..ec89874be 100644 --- a/docs/src/appendix/notation.md +++ b/docs/src/appendix/notation.md @@ -108,333 +108,3 @@ The following table also uses a few conventions that suffuse the source code and | ``F_{\mathscr{I}}`` | `Fℐ` | | Radiative flux divergence (heating rate), K/s | | ``τˡʷ`` | `τˡʷ` | | Atmosphere optical thickness for longwave | | ``τˢʷ`` | `τˢʷ` | | Atmosphere optical thickness for shortwave | -# 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. - -A few notes about the following table: - -* `TC` stands for [`ThermodynamicConstants`](@ref) -* `AM` stands for [`AtmosphereModel`](@ref) -* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) -* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. - -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`](@ref Breeze.Thermodynamics.MoistureMassFractions) -* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). -* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). -* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). - -| math symbol | code | property name | description | -| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | -| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | -| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | -| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | -| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | -| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | -| ``T`` | `T` | `AM.temperature` | Temperature | -| ``p`` | `p` | `AM.pressure` | Pressure | -| ``b`` | `b` | | Buoyancy | -| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | -| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | -| ``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 | -| ``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ᵛ⁺`` | -| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | -| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | -| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | -| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | -| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | -| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | -| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | -| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | -| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | -| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | -| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | -| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | -| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | -| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | -| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | -| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | -| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | -| ``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 | -# 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. - -A few notes about the following table: - -* `TC` stands for [`ThermodynamicConstants`](@ref) -* `AM` stands for [`AtmosphereModel`](@ref) -* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) -* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. - -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`](@ref Breeze.Thermodynamics.MoistureMassFractions) -* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). -* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). -* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). - -| math symbol | code | property name | description | -| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | -| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | -| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | -| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | -| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | -| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | -| ``T`` | `T` | `AM.temperature` | Temperature | -| ``p`` | `p` | `AM.pressure` | Pressure | -| ``b`` | `b` | | Buoyancy | -| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | -| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | -| ``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 | -| ``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ᵛ⁺`` | -| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | -| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | -| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | -| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | -| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | -| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | -| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | -| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | -| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | -| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | -| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | -| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | -| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | -| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | -| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | -| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | -| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | -| ``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 | -# 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. - -A few notes about the following table: - -* `TC` stands for [`ThermodynamicConstants`](@ref) -* `AM` stands for [`AtmosphereModel`](@ref) -* `RS` stands for [`ReferenceState`](@ref Breeze.AtmosphereModels.ReferenceState) -* Note that there are independent concepts of "reference". For example, [`AnelasticFormulation`](@ref) 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: `ρe` corresponds to `energy_density(model)`, `ρqᵗ` to `model.moisture_density`, and `qᵗ` to `model.specific_moisture`. - -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`](@ref Breeze.Thermodynamics.MoistureMassFractions) -* "Reference" quantities use a subscript ``r`` (e.g., ``p_r``, ``\rho_r``). -* Phase or mixture identifiers (``d``, ``v``, ``m``) appear as superscripts (e.g., ``Rᵈ``, ``cᵖᵐ``), matching usage in the codebase (e.g., `Rᵈ`, `cᵖᵐ`). -* Conservative variables are stored in ρᵣ-weighted form in the code (e.g., `ρu`, `ρv`, `ρw`, `ρe`, `ρqᵗ`). - -| math symbol | code | property name | description | -| ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------ | -| ``\rho`` | `ρ` | `AM.density` | Density, ``ρ = pᵣ / Rᵐ T`` for anelastic | -| ``\alpha`` | `α` | | Specific volume, ``α = 1/ρ`` | -| ``\boldsymbol{u} = (u,v,w)`` | `u, v, w` | `AM.velocities` | Velocity components in (x, y, z) or (east, north, up) | -| ``\boldsymbol{ρu} = (ρu, ρv, ρw)`` | `ρu, ρv, ρw` | `AM.momentum` | Momentum components | -| ``ρ e`` | `ρe` | `AM.energy_density` | Energy density | -| ``T`` | `T` | `AM.temperature` | Temperature | -| ``p`` | `p` | `AM.pressure` | Pressure | -| ``b`` | `b` | | Buoyancy | -| ``ρ qᵗ`` | `ρqᵗ` | `AM.moisture_density` | Total moisture density | -| ``qᵗ`` | `qᵗ` | `AM.specific_moisture` | Total specific moisture (the sum of vapor, liquid, and ice mass fractions) | -| ``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 | -| ``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ᵛ⁺`` | -| ``g`` | `g` | `TC.gravitational_acceleration` | Gravitational acceleration | -| ``\mathcal{R}`` | `ℛ` | `TC.molar_gas_constant` | Universal (molar) gas constant | -| ``Tᵗʳ`` | `Tᵗʳ` | `TC.triple_point_temperature` | Temperature at the vapor-liquid-ice triple point | -| ``pᵗʳ`` | `pᵗʳ` | `TC.triple_point_pressure` | Pressure at the vapor-liquid-ice triple point | -| ``mᵈ`` | `mᵈ` | `TC.dry_air.molar_mass` | Molar mass of dry air | -| ``mᵛ`` | `mᵛ` | `TC.vapor.molar_mass` | Molar 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_capacity` | Heat capacity of dry air at constant pressure | -| ``cᵖᵛ`` | `cᵖᵛ` | `TC.vapor.heat_capacity` | Heat capacity of vapor at constant pressure | -| ``cˡ`` | `cˡ` | `TC.liquid.heat_capacity` | Heat capacity of the liquid phase (incompressible) | -| ``cⁱ`` | `cⁱ` | `TC.ice.heat_capacity` | Heat capacity of the ice phase (incompressible) | -| ``cᵖᵐ`` | `cᵖᵐ` | `mixture_heat_capacity(q, constants)` | Mixture heat capacity at constant pressure | -| ``Tᵣ`` | `Tᵣ` | `TC.energy_reference_temperature` | Reference temperature for internal energy relations and latent heat | -| ``\mathcal{L}^l_r`` | `ℒˡᵣ` | `TC.liquid.reference_latent_heat` | Latent heat of condensation at the energy reference temperature | -| ``\mathcal{L}^i_r`` | `ℒⁱᵣ` | `TC.ice.reference_latent_heat` | Latent 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.surface_pressure` | Base (surface) reference pressure | -| ``ρᵣ`` | `ρᵣ` | `RS.density` | Density of a dry reference state for the anelastic formulation | -| ``αᵣ`` | `αᵣ` | | Specific volume of a dry reference state, ``αᵣ = Rᵈ θ₀ / pᵣ`` | -| ``pᵣ`` | `pᵣ` | `RS.pressure` | Pressure 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!`](https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.set!)) | -| ``\Delta t`` | `Δt` | `Simulation.Δt` | Time 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}`` | `J` | | Dynamic 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 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) | -| ``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 |