Merge pull request #365 from SpeedyWeather/mk/docs

Primitive equation documentation

docs/make.jl

@@ -9,7 +9,7 @@ makedocs(
     pages=["Home"=>"index.md",
             "Installation"=>"installation.md",
             "How to run SpeedyWeather.jl"=>"how_to_run_speedy.md",
-            "Spherical harmonic transform"=>"spectral_transform.md",
+            "Spherical Harmonic Transform"=>"spectral_transform.md",
             "Grids"=>"grids.md",
             "Barotropic model"=>"barotropic.md",
             "Shallow water model"=>"shallowwater.md",

docs/src/index.md

@@ -55,6 +55,7 @@ The development of  SpeedyWeather.jl is lead by [Milan Klöwer](https://github.c
 - [David Meyer](https://github.com/dmey)
 - [Daisuke Hotta](https://github.com/hottad)
 - [Navid Constantinou](https://github.com/navidcy)
+- [Simone Silvestri](https://github.com/simone-silvestri)
 
 Any contributions are always welcome!
 

docs/src/output.md

@@ -135,6 +135,40 @@ Note that some fields are actual options, but others are derived from the option
 arrays/objects the output writer needs, but shouldn't be passed on by the user.
 The actual options are declared as `[OPTION]` in the following
 
-```@docs
-OutputWriter
+```julia
+help?> OutputWriter
+search: OutputWriter
+
+  NetCDF output writer. Contains all output options and auxiliary fields for
+  output interpolation. To be initialised with
+  OutputWriter(::SpectralGrid,::Type{<:ModelSetup},kwargs...) to pass on the
+  resolution information and the model type which chooses which variables to
+  output. Options include
+
+    •  spectral_grid::SpectralGrid
+
+    •  output::Bool
+
+    •  path::String: [OPTION] path to output folder, run_???? will be
+       created within
+
+    •  id::String: [OPTION] run identification number/string
+
+    •  run_path::String
+
+    •  filename::String: [OPTION] name of the output netcdf file
+
+    •  write_restart::Bool: [OPTION] also write restart file if
+       output==true?
+
+    •  pkg_version::VersionNumber
+
+    •  startdate::Dates.DateTime
+
+    •  output_dt::Float64: [OPTION] output frequency, time step [hrs]
+
+    •  output_dt_sec::Int64: actual output time step [sec]
+
+    •  output_vars::Vector{Symbol}: [OPTION] which variables to output,
+       u, v, vor, div, pres, temp, humid
 ```

docs/src/shallowwater.md

@@ -128,7 +128,9 @@ is then
 with the right-hand side operator ``N`` evaluated at the current time step ``i``. Now the
 idea is to split the terms in ``N`` into non-linear terms that are evaluated explicitly
 in ``N_E`` and into the linear terms ``N_I``, solved implicitly, that are responsible for
-the gravity waves. We could already assume to evaluate ``N_I`` at ``i+1``, but in fact,
+the gravity waves. Linearization happens around a state of rest without orography.
+
+We could already assume to evaluate ``N_I`` at ``i+1``, but in fact,
 we can introduce ``\alpha \in [0,1]`` so that for ``\alpha=0`` we use ``i-1`` (i.e. explicit),
 for ``\alpha=1/2`` it is centred implicit ``\tfrac{1}{2}N_I(V_{i-1}) + \tfrac{1}{2}N_I(V_{i+1})``,
 and for ``\alpha=1`` a fully backwards scheme ``N_I(V_{i+1})`` evaluated at ``i+1``.

src/dynamics/constants.jl

@@ -38,10 +38,10 @@ Base.@kwdef struct DynamicsConstants{NF<:AbstractFloat} <: AbstractDynamicsConst
     f_coriolis::Vector{NF}
 
     # ADIABATIC TERM
-    "σ-related factor A needed for adiabatic terms"
+    "σ-related factor A needed for adiabatic conversion term"
     σ_lnp_A::Vector{NF}
 
-    "σ-related factor B needed for adiabatic terms"
+    "σ-related factor B needed for adiabatic conversion term"
     σ_lnp_B::Vector{NF}
 
     # GEOPOTENTIAL INTEGRATION (on half/full levels)

src/dynamics/tendencies.jl

@@ -56,7 +56,7 @@ function dynamics_tendencies!(  diagn::DiagnosticVariables,
 
         # calculate Tᵥ = T + Tₖμq in spectral as a approxmation to Tᵥ = T(1+μq) used for geopotential
         linear_virtual_temperature!(diagn_layer,progn_layer,model,lf_implicit)
-        temperature_anomaly!(diagn_layer,I)           # temperature relative to profile
+        temperature_anomaly!(diagn_layer,I)         # temperature relative to profile
     end
 
     geopotential!(diagn,O,C)                        # from ∂Φ/∂ln(pₛ) = -RTᵥ, used in bernoulli_potential!

src/dynamics/tendencies_dynamics.jl

@@ -283,7 +283,7 @@ function temperature_tendency!(
     # implicit_correction! then calculated the implicit terms from Vi-1 minus Vi
     # to move the implicit terms to i-1 which is cheaper then the alternative below
 
-    # Adiabatic term following Simmons and Burridge 1981 but for σ coordinates 
+    # Diabatic term following Simmons and Burridge 1981 but for σ coordinates 
     # += as tend already contains parameterizations + vertical advection
     @. temp_tend_grid += temp_grid*div_grid +       # +T'D term of hori advection
         κ*(Tᵥ+Tₖ)*(                                 # +κTᵥ*Dlnp/Dt, adiabatic term
@@ -534,9 +534,9 @@ function linear_pressure_gradient!(
     C::DynamicsConstants,
     I::ImplicitPrimitiveEq,
 )                          
-    (; R_dry ) = C
+    (;R_dry) = C                            # dry gas constant 
     Tₖ = I.temp_profile[diagn.k]            # reference profile at layer k      
-    (;pres) = surface.timesteps[lf]
+    (;pres) = surface.timesteps[lf]         # logarithm of surface pressure
     (;geopot) = diagn.dynamics_variables
 
     # -R_dry*Tₖ*∇²lnpₛ, linear part of the ∇⋅RTᵥ∇lnpₛ pressure gradient term

src/dynamics/vertical_coordinates.jl

@@ -13,6 +13,18 @@ end
 # obtain nlev from length of predefined σ_half levels
 SigmaCoordinates(σ_half::AbstractVector) = SigmaCoordinates(nlev=length(σ_half)-1;σ_half) 
 
+function Base.show(io::IO,σ::SigmaCoordinates)
+    println("$(σ.nlev)-level SigmaCoordinates:")
+    nchars = length(string(σ.nlev))
+    format = Printf.Format("%$(nchars)d")
+    for k=1:σ.nlev
+        println(" k=",Printf.format(format,k-1),".5  -- ",@sprintf("%1.4f",σ.σ_half[k]))
+        σk = (σ.σ_half[k] + σ.σ_half[k+1])/2
+        println(" k=",Printf.format(format,k),"    ×  ",@sprintf("%1.4f",σk))
+    end
+    print(" k=",Printf.format(format,σ.nlev),".5  -- ",@sprintf("%1.4f",σ.σ_half[end]))
+end
+
 """Coefficients of the generalised logistic function to describe the vertical coordinate.
 Default coefficients A,K,C,Q,B,M,ν are fitted to the old L31 configuration at ECMWF.