Add doc strings for routing

Deltares · Nov 27, 2024 · b9abcb5 · b9abcb5
1 parent 023940f
commit b9abcb5
Show file tree

Hide file tree

Showing 6 changed files with 152 additions and 43 deletions.
diff --git a/src/routing/lake.jl b/src/routing/lake.jl
@@ -1,3 +1,4 @@
+"Struct for storing lake model parameters"
 @get_units @grid_loc @with_kw struct LakeParameters{T}
     dt::T                                           # Model time step [s]
     lowerlake_ind::Vector{Int} | "-"                # Index of lower lake (linked lakes)
@@ -12,6 +13,7 @@
     hq::Vector{Union{HQ, Missing}}                  # data for rating curve    
 end
 
+"Initialize lake model parameters"
 function LakeParameters(config, dataset, inds_riv, nriv, pits, dt)
     # read only lake data if lakes true
     # allow lakes only in river cells
@@ -200,6 +202,7 @@ function LakeParameters(config, dataset, inds_riv, nriv, pits, dt)
     return parameters, lake_network, inds_lake_map2river, lake_waterlevel, pits
 end
 
+"Struct for storing Lake model parameters"
 @get_units @grid_loc @with_kw struct LakeVariables{T}
     waterlevel::Vector{T} | "m"                 # waterlevel H [m] of lake
     storage::Vector{T} | "m3"                   # storage lake [m³]
@@ -208,6 +211,7 @@ end
     actevap::Vector{T}                          # average actual evapotranspiration for lake area [mm Δt⁻¹] 
 end
 
+"Initialize lake model variables"
 function LakeVariables(n, lake_waterlevel)
     variables = LakeVariables{Float}(;
         waterlevel = lake_waterlevel,
@@ -220,12 +224,14 @@ function LakeVariables(n, lake_waterlevel)
     return variables
 end
 
+"Struct for storing lake model boundary conditions"
 @get_units @grid_loc @with_kw struct LakeBC{T}
     inflow::Vector{T} | "m3"                    # inflow to the lake [m³]
     precipitation::Vector{T}                    # average precipitation for lake area [mm Δt⁻¹]
     evaporation::Vector{T}                      # average potential evaporation for lake area [mm Δt⁻¹]
 end
 
+"Initialize lake model boundary conditions"
 function LakeBC(n)
     bc = LakeBC{Float}(;
         inflow = fill(mv, n),
@@ -235,12 +241,14 @@ function LakeBC(n)
     return bc
 end
 
+"Lake model"
 @with_kw struct Lake{T}
     boundary_conditions::LakeBC{T}
     parameters::LakeParameters{T}
     variables::LakeVariables{T}
 end
 
+"Initialize lake model"
 function Lake(dataset, config, indices_river, n_river_cells, pits, dt)
     parameters, lake_network, inds_lake_map2river, lake_waterlevel, pits =
         LakeParameters(dataset, config, indices_river, n_river_cells, pits, dt)

diff --git a/src/routing/reservoir.jl b/src/routing/reservoir.jl
@@ -1,3 +1,4 @@
+"Struct for storing reservoir model parameters"
 @get_units @grid_loc @with_kw struct ReservoirParameters{T}
     dt::T                                   # Model time step [s]
     maxvolume::Vector{T} | "m3"             # maximum storage (above which water is spilled) [m³]
@@ -8,6 +9,7 @@
     targetfullfrac::Vector{T} | "-"         # target fraction full (of max storage
 end
 
+"Initialize reservoir model parameters"
 function ReservoirParameters(dataset, config, indices_river, n_river_cells, pits, dt)
     # read only reservoir data if reservoirs true
     # allow reservoirs only in river cells
@@ -135,6 +137,7 @@ function ReservoirParameters(dataset, config, indices_river, n_river_cells, pits
     return parameters, reservoir_network, inds_reservoir_map2river, pits
 end
 
+"Struct for storing reservoir model variables"
 @get_units @grid_loc @with_kw struct ReservoirVariables{T}
     volume::Vector{T} | "m3"                # reservoir volume [m³]
     outflow::Vector{T} | "m3 s-1"           # outflow from reservoir [m³ s⁻¹]
@@ -144,6 +147,7 @@ end
     actevap::Vector{T}                      # average actual evaporation for reservoir area [mm Δt⁻¹]
 end
 
+"Initialize reservoir model variables"
 function ReservoirVariables(n, parameters)
     (; targetfullfrac, maxvolume) = parameters
     variables = ReservoirVariables{Float}(;
@@ -157,12 +161,14 @@ function ReservoirVariables(n, parameters)
     return variables
 end
 
+"Struct for storing reservoir model boundary conditions"
 @get_units @grid_loc @with_kw struct ReservoirBC{T}
     inflow::Vector{T} | "m3"        # total inflow into reservoir [m³]
     precipitation::Vector{T}        # average precipitation for reservoir area [mm Δt⁻¹]
     evaporation::Vector{T}          # average potential evaporation for reservoir area [mm Δt⁻¹]
 end
 
+"Initialize reservoir model boundary conditions"
 function ReservoirBC(n)
     bc = ReservoirBC{Float}(;
         inflow = fill(mv, n),
@@ -172,12 +178,14 @@ function ReservoirBC(n)
     return bc
 end
 
+"Reservoir model `SimpleReservoir`"
 @with_kw struct SimpleReservoir{T}
     boundary_conditions::ReservoirBC{T}
     parameters::ReservoirParameters{T}
     variables::ReservoirVariables{T}
 end
 
+"Initialize reservoir model `SimpleReservoir`"
 function SimpleReservoir(dataset, config, indices_river, n_river_cells, pits, dt)
     parameters, reservoir_network, inds_reservoir_map2river, pits =
         ReservoirParameters(dataset, config, indices_river, n_river_cells, pits, dt)

diff --git a/src/routing/subsurface.jl b/src/routing/subsurface.jl
@@ -1,24 +1,28 @@
+abstract type SubsurfaceFlow end
+
+"Exponential depth profile of horizontal hydraulic conductivity at the soil surface"
 @get_units @grid_loc struct KhExponential{T}
     # Horizontal hydraulic conductivity at soil surface [m d⁻¹]
     kh_0::Vector{T} | "m d-1"
     # A scaling parameter [m⁻¹] (controls exponential decline of kh_0)
     f::Vector{T} | "m-1"
 end
 
+"Exponential constant depth profile of horizontal hydraulic conductivity"
 @get_units @grid_loc struct KhExponentialConstant{T}
     # Exponential horizontal hydraulic conductivity profile type
     exponential::KhExponential
     # Depth [m] from soil surface for which exponential decline of kv_0 is valid
     z_exp::Vector{T} | "m"
 end
 
+"Layered depth profile of horizontal hydraulic conductivity"
 @get_units @grid_loc struct KhLayered{T}
     # Horizontal hydraulic conductivity [m d⁻¹]
     kh::Vector{T} | "m d-1"
 end
 
-abstract type SubsurfaceFlow end
-
+"Struct for storing lateral subsurface flow model parameters"
 @get_units @grid_loc @with_kw struct LateralSsfParameters{T, Kh}
     kh_profile::Kh                         # Horizontal hydraulic conductivity profile type [-]  
     khfrac::Vector{T} | "-"                # A muliplication factor applied to vertical hydraulic conductivity `kv` [-]
@@ -31,6 +35,7 @@ abstract type SubsurfaceFlow end
     flow_width::Vector{T} | "m"            # Flow width [m]
 end
 
+"Initialize lateral subsurface flow model parameters"
 function LateralSsfParameters(
     dataset,
     config,
@@ -82,6 +87,7 @@ function LateralSsfParameters(
     return parameters
 end
 
+"Struct for storing lateral subsurface flow model variables"
 @get_units @grid_loc @with_kw struct LateralSsfVariables{T}
     zi::Vector{T} | "m"                    # Pseudo-water table depth [m] (top of the saturated zone)
     exfiltwater::Vector{T} | "m dt-1"      # Exfiltration [m Δt⁻¹] (groundwater above surface level, saturated excess conditions)
@@ -93,6 +99,7 @@ end
     volume::Vector{T} | "m3"               # Subsurface volume [m³]
 end
 
+"Initialize lateral subsurface flow model variables"
 function LateralSsfVariables(ssf, zi, xl, yl)
     n = length(zi)
     volume = @. (ssf.theta_s - ssf.theta_r) * (ssf.soilthickness - zi) * (xl * yl)
@@ -109,16 +116,19 @@ function LateralSsfVariables(ssf, zi, xl, yl)
     return variables
 end
 
+"Struct for storing lateral subsurface flow model boundary conditions"
 @get_units @grid_loc @with_kw struct LateralSsfBC{T}
     recharge::Vector{T} | "m2 dt-1"        # Net recharge to saturated store [m² Δt⁻¹]
 end
 
+"Lateral subsurface flow model"
 @with_kw struct LateralSSF{T, Kh} <: SubsurfaceFlow
     boundary_conditions::LateralSsfBC{T}
     parameters::LateralSsfParameters{T, Kh}
     variables::LateralSsfVariables{T}
 end
 
+"Initialize lateral subsurface flow model"
 function LateralSSF(
     dataset,
     config,
@@ -148,6 +158,7 @@ function LateralSSF(
     return ssf
 end
 
+"Update lateral subsurface model for a single timestep"
 function update!(model::LateralSSF, network)
     (;
         order_of_subdomains,
@@ -204,13 +215,18 @@ function update!(model::LateralSSF, network)
     return nothing
 end
 
+"""
+Struct for storing groundwater exchange variables for coupling with an external groundwater
+model.
+"""
 @get_units@grid_loc @with_kw struct GroundwaterExchangeVariables{T}
     exfiltwater::Vector{T} | "m dt-1"   # Exfiltration [m Δt⁻¹]  (groundwater above surface level, saturated excess conditions)
     zi::Vector{T} | "m"                 # Pseudo-water table depth [m] (top of the saturated zone)
     to_river::Vector{T} | "m3 d-1"      # Part of subsurface flow [m³ d⁻¹] that flows to the river
     ssf::Vector{T} | "m3 d-1"           # Subsurface flow [m³ d⁻¹]
 end
 
+"Initialize groundwater exchange variables"
 function GroundwaterExchangeVariables(n)
     variables = GroundwaterExchangeVariables{Float}(;
         exfiltwater = fill(mv, n),
@@ -221,22 +237,27 @@ function GroundwaterExchangeVariables(n)
     return variables
 end
 
+"Struct for storing groundwater exchange parameters for coupling with an external groundwater
+model."
 @with_kw struct GroundwaterExchangeParameters{T}
     dt::T       # model time step [d]
 end
 
+"Groundwater exchange"
 @with_kw struct GroundwaterExchange{T} <: SubsurfaceFlow
     parameters::GroundwaterExchangeParameters{T}
     variables::GroundwaterExchangeVariables{T}
 end
 
+"Initialize groundwater exchange"
 function GroundwaterExchange(n, dt)
     parameters = GroundwaterExchangeParameters{Float}(; dt = dt / basetimestep)
     variables = GroundwaterExchangeVariables(n)
     ssf = GroundwaterExchange{Float}(; parameters, variables)
     return ssf
 end
 
+# wrapper methods
 get_water_depth(subsurface::SubsurfaceFlow) = subsurface.variables.zi
 get_exfiltwater(subsurface::SubsurfaceFlow) = subsurface.variables.exfiltwater