Merge pull request #580 from SpeedyWeather/mg/set-docs-kwargs

Set! documentation / keywords

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 - Extend `set!` with `orography` keyword argument to set the orography with `set!` [#578](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/578)
 - Added a new benchmark suite for the dynamics functions [#577](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/577)
-- Introduced a new `set!` function that allows to set `PrognosticVariables` to new values with keyword arguments
+- Introduced a new `set!` function that allows to set `PrognosticVariables` to new values with keyword arguments [#563](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/563)
 - Restructured dynamical core with prognostic/diagnostic variables array-agnostic and 3-dimensional [#525](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/525)
 - Modularised NetCDF output [#573](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/573)
 - Fixed a bug in RingGrids, now broadcasts are defined even when the dimensions mismatch in some cases [#568](https://github.com/SpeedyWeather/SpeedyWeather.jl/pull/568)

src/dynamics/orography.jl

@@ -47,6 +47,12 @@ function set!(
 end
 
 # convenient function barrier to use geometry, spectral_transform and gravity from model
+"""
+$(TYPEDSIGNATURES)
+Sets a new `orography` for the `model`. The input can be a function, `RingGrid`, `LowerTriangularMatrix`, 
+or scalar as for other `set!` functions. If the keyword `add==true` the input is added to the exisiting 
+orography instead.  
+"""
 function set!(model::AbstractModel; orography, kwargs...)
     set!(model.orography, orography, model.geometry, model.spectral_transform;
         gravity=model.planet.gravity, kwargs...)

src/dynamics/prognostic_variables.jl

@@ -238,28 +238,28 @@ function set!(
     soil_moisture_layer2 = nothing,
     lf::Integer = 1,
     add::Bool = false,
-    S::Union{Nothing, SpectralTransform} = nothing,
+    spectral_transform::Union{Nothing, SpectralTransform} = nothing,
     coslat_scaling_included::Bool = false,
 )
     # ATMOSPHERE
-    isnothing(vor)   || set!(progn.vor[lf],     vor, geometry, S; add)
-    isnothing(div)   || set!(progn.div[lf],     div, geometry, S; add)
-    isnothing(temp)  || set!(progn.temp[lf],   temp, geometry, S; add)
-    isnothing(humid) || set!(progn.humid[lf], humid, geometry, S; add)
-    isnothing(pres)  || set!(progn.pres[lf],   pres, geometry, S; add)
+    isnothing(vor)   || set!(progn.vor[lf],     vor, geometry, spectral_transform; add)
+    isnothing(div)   || set!(progn.div[lf],     div, geometry, spectral_transform; add)
+    isnothing(temp)  || set!(progn.temp[lf],   temp, geometry, spectral_transform; add)
+    isnothing(humid) || set!(progn.humid[lf], humid, geometry, spectral_transform; add)
+    isnothing(pres)  || set!(progn.pres[lf],   pres, geometry, spectral_transform; add)
 
     # or provide u, v instead of vor, div
-    isnothing(u) | isnothing(v) || set_vordiv!(progn.vor[lf], progn.div[lf], u, v, geometry, S; add, coslat_scaling_included)
+    isnothing(u) | isnothing(v) || set_vordiv!(progn.vor[lf], progn.div[lf], u, v, geometry, spectral_transform; add, coslat_scaling_included)
 
     # OCEAN
-    isnothing(sea_surface_temperature)  || set!(progn.ocean.sea_surface_temperature, sea_surface_temperature, geometry, S; add)
-    isnothing(sea_ice_concentration)    || set!(progn.ocean.sea_ice_concentration, sea_ice_concentration, geometry, S; add)
+    isnothing(sea_surface_temperature)  || set!(progn.ocean.sea_surface_temperature, sea_surface_temperature, geometry, spectral_transform; add)
+    isnothing(sea_ice_concentration)    || set!(progn.ocean.sea_ice_concentration, sea_ice_concentration, geometry, spectral_transform; add)
 
     # LAND
-    isnothing(land_surface_temperature) || set!(progn.land.land_surface_temperature, land_surface_temperature, geometry, S; add)
-    isnothing(snow_depth)               || set!(progn.land.snow_depth, snow_depth, geometry, S; add)
-    isnothing(soil_moisture_layer1)     || set!(progn.land.soil_moisture_layer1, soil_moisture_layer1, geometry, S; add)
-    isnothing(soil_moisture_layer2)     || set!(progn.land.soil_moisture_layer2, soil_moisture_layer2, geometry, S; add)
+    isnothing(land_surface_temperature) || set!(progn.land.land_surface_temperature, land_surface_temperature, geometry, spectral_transform; add)
+    isnothing(snow_depth)               || set!(progn.land.snow_depth, snow_depth, geometry, spectral_transform; add)
+    isnothing(soil_moisture_layer1)     || set!(progn.land.soil_moisture_layer1, soil_moisture_layer1, geometry, spectral_transform; add)
+    isnothing(soil_moisture_layer2)     || set!(progn.land.soil_moisture_layer2, soil_moisture_layer2, geometry, spectral_transform; add)
     return nothing
 end
 
@@ -439,11 +439,18 @@ function set_vordiv!(
     end
 end 
 
+"""
+$(TYPEDSIGNATURES)
+
+Sets properties of the simuluation `S`. Convenience wrapper to call the other concrete 
+`set!` methods. All `kwargs` are forwarded to these methods, which are documented 
+seperately. See their documentation for possible `kwargs`. 
+"""
 function set!(S::AbstractSimulation; kwargs...)
-    set!(S.prognostic_variables, S.model.geometry; S=S.model.spectral_transform, kwargs...)
+    set!(S.prognostic_variables, S.model.geometry; spectral_transform=S.model.spectral_transform, kwargs...)
 end
 
 function set!(progn::PrognosticVariables, model::AbstractModel; kwargs...)
     progn.scale[] != 1 && @warn "Prognostic variables are scaled with $(progn.scale[]), but `set!` assumes unscaled variables."
-    set!(progn, model.geometry; S=model.spectral_transform, kwargs...)
+    set!(progn, model.geometry; spectral_transform=model.spectral_transform, kwargs...)
 end