diff --git a/docs/make.jl b/docs/make.jl index f124ffed1..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 @@ -68,9 +69,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 +``` diff --git a/docs/src/appendix/notation.md b/docs/src/appendix/notation.md index 531a4ba3d..ec89874be 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,16 +89,16 @@ 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), 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) | @@ -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 | +| ``τˡʷ`` | `τˡʷ` | | Atmosphere optical thickness for longwave | +| ``τˢʷ`` | `τˢʷ` | | Atmosphere optical thickness for shortwave | diff --git a/docs/src/breeze.bib b/docs/src/breeze.bib index 2647722ab..0f4ce6c5b 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} +} 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: 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 diff --git a/ext/BreezeCloudMicrophysicsExt.jl b/ext/BreezeCloudMicrophysicsExt.jl index 13617a0e0..924b921e8 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). """ function ZeroMomentCloudMicrophysics(FT::DataType = Oceananigans.defaults.FloatType; nucleation = SaturationAdjustment(FT), diff --git a/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl b/ext/BreezeRRTMGPExt/gray_radiative_transfer_model.jl index aecb4b96e..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, @@ -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) @@ -525,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 13dbb378c..696cbaf94 100644 --- a/src/CelestialMechanics/solar_zenith_angle.jl +++ b/src/CelestialMechanics/solar_zenith_angle.jl @@ -6,24 +6,20 @@ ##### - 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) +$(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. -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 @@ -47,14 +47,18 @@ 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 Spencer (1971) approximation. +Uses the approximation by [spencer1971fourier](@citet); see [`solar_declination`](@ref). + +# 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 @@ -68,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. @@ -101,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. @@ -138,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.