Merge pull request #303 from Deltares/wflow_sbm_figure

Wflow_sbm figure leakage term and `ksathorfrac` documentation

docs/src/changelog.md

@@ -5,9 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-
 ## [unreleased]
 
+### Fixed
+- Documentation: add leakage term to the wflow\_sbm figure, document external input
+  parameter `ksathorfrac` and fix description of adding external `inflow` to the kinematic
+  wave.
+
 ### Changed
 - For cyclic parameters different cyclic time inputs are supported (only one common cyclic
   time (for example daily or monthly) was allowed).

docs/src/model_docs/lateral/kinwave.md

@@ -134,8 +134,8 @@ through a simple explicit scheme. In summary the following limitations apply:
 
 ## External inflows
 External inflows, for example water supply or abstractions, can be added to the kinematic
-wave via the `inflow` variable. For this, the user can supply a 2D map of the inflow which
-can be static or dynamic (changing every timestep or cyclic is possible). These inflow are
+wave via the `inflow` variable. For this, the user can supply a 2D map of the inflow, as a
+cyclic parameter or as part of forcing (see also [Input section](@ref)). These inflows are
 added or abstracted from the upstream inflow `qin` before running the kinematic wave to
 solve the impact on resulting `q`. In case of a negative inflow (abstractions), a minimum of
 zero is applied to the upstream flow `qin`.

docs/src/model_docs/params_lateral.md

@@ -8,11 +8,13 @@ flow, including a description of these parameters, the unit, and default value i
 applicable. The parameters in bold represent model parameters that can be set through static
 input data (netCDF), and can be listed in the TOML configuration file under
 `[input.lateral.river]` to map the internal model parameter to the external netCDF variable.
+The input parameter `slope` (listed under `[input.lateral.river]`) is not equal to the
+internal model parameter `sl`, and is listed in the Table below between parentheses.
 
 |  parameter  | description  	  | unit  | default |
 |:--------------- | ------------------| ----- | -------- |
 | `β`             |  constant in Manning's equation | - | - |
-| **`sl`**        |  slope       | m m``^{-1}``| - |
+| **`sl`** (`slope`) |  slope       | m m``^{-1}``| - |
 | **`n`**         | Manning's roughness | s m``^{-\frac{1}{3}}``| 0.036 |
 | **`dl`**        |  length      | m     |  -      |
 | `q`             | discharge     | m``^3`` s``^{-1}``| - |
@@ -42,12 +44,14 @@ The Table below shows the parameters (fields) of struct `SurfaceFlowLand` used f
 flow, including a description of these parameters, the unit, and default value if
 applicable. The parameters in bold represent model parameters that can be set through static
 input data (netCDF), and can be listed in the TOML configuration file under
-`[input.lateral.land]` to map the internal model parameter to the external netCDF variable. 
+`[input.lateral.land]` to map the internal model parameter to the external netCDF variable.
+The input parameter `slope` (listed under `[input.lateral.land]`) is not equal to the
+internal model parameter `sl`, and is listed in the Table below between parentheses.
 
 |  parameter  | description  	  | unit  | default |
 |:--------------- | ------------------| ----- | -------- |
 | `β`             |  constant in Manning's equation | - | - |
-| **`sl`**        |  slope       | m m``^{-1}``| - |
+| **`sl`** (`slope`) |  slope       | m m``^{-1}``| - |
 | **`n`**         | Manning's roughness | s m``^{-\frac{1}{3}}``| 0.072 |
 | `dl`            |  length      | m     |  -      |
 | `q`             | discharge     | m``^3`` s``^{-1}``| - |
@@ -65,7 +69,7 @@ input data (netCDF), and can be listed in the TOML configuration file under
 | `alpha_term`    | term used in computation of ``\alpha`` | - | - |
 | `α`             | constant in momentum equation ``A = \alpha Q^{\beta}`` | s``^{\frac{3}{5}}`` m``^{\frac{1}{5}}`` | - |
 | `cel`           | celerity of kinematic wave | m s``^{-1}`` | - |
-| `to_river`      | part of overland flow that flows to the river | m s``^3`` | - |
+| `to_river`      | part of overland flow that flows to the river | m``^3`` s``^{-1}`` | - |
 | `kinwave_it`    | boolean for kinematic wave iterations | - | false |
 
 ### [Reservoirs](@id reservoir_params)
@@ -120,6 +124,10 @@ areas = "wflow_lakeareas"
 locs = "wflow_lakelocs"
 ```
 
+The input parameter `linkedlakelocs` (listed under `[input.lateral.river.lake]`) is not
+equal to the internal model parameter `lowerlake_ind`, and is listed in the Table below
+between parentheses.
+
 |  parameter | description  	        | unit | default |
 |:---------------| --------------- | ---------------------- | ----- |
 | **`area`**         | area| m``^2`` | - |
@@ -141,19 +149,44 @@ locs = "wflow_lakelocs"
 | `precipitation` | average precipitation for lake area | mm Δt⁻¹  | - |
 | `evaporation` | average precipitation for lake area | mm Δt⁻¹  | - |
 
-### Lateral subsurface flow
+### [Lateral subsurface flow](@id params_ssf)
 The Table below shows the parameters (fields) of struct `LateralSSF`, including a
-description of these parameters, the unit, and default value if applicable.
+description of these parameters, the unit, and default value if applicable. The parameters
+in bold represent model parameters that can be set through static input data (netCDF). The
+soil related parameters `f`, `soilthickness`, `θₛ` and `θᵣ` are derived from the vertical
+`SBM` concept (including unit conversion for `f` and `soilthickness`), and can be listed in
+the TOML configuration file under `[input.vertical]`, to map the internal model parameter to
+the external netCDF variable. The internal slope model parameter `βₗ` is set through the
+TOML file as follows:
+
+```toml
+[input.lateral.land]
+slope = "Slope"
+```
+
+The parameter `kh₀` is computed by multiplying the vertical hydraulic conductivity at the
+soil surface `kv₀` (including unit conversion) of the vertical `SBM` concept with the
+external parameter `ksathorfrac` \[-\] (default value of 1.0). The external parameter
+`ksathorfrac` can be set as follows through the TOML file:
+
+```toml
+[input.lateral.subsurface]
+ksathorfrac = "KsatHorFrac"
+```
+
+The `ksathorfrac` parameter compensates for anisotropy, small scale `kv₀` measurements (soil
+core) that do not represent larger scale hydraulic conductivity, and smaller flow length
+scales (hillslope) in reality, not represented by the model resolution.
 
 | parameter | description  	        | unit | default |
 |:---------------| --------------- | ---------------------- | ----- |
-| `kh₀`          | horizontal hydraulic conductivity at soil surface  | m d``^{-1}`` |  - |
-| `f` | a scaling parameter (controls exponential decline of kh₀) | m``^{-1}``  | - |
-| `soilthickness` | soil thickness | m  | - |
-| `θₛ` | saturated water content (porosity) | -  | - |
-| `θᵣ` | residual water content  | -  | - |
+| `kh₀`          | horizontal hydraulic conductivity at soil surface  | m d``^{-1}`` |  3.0 |
+| **`f`** | a scaling parameter (controls exponential decline of kh₀) | m``^{-1}``  | 1.0 |
+| **`soilthickness`** | soil thickness | m  | 2.0 |
+| **`θₛ`** | saturated water content (porosity) | -  | 0.6 |
+| **`θᵣ`** | residual water content  | -  | 0.01 |
 | `Δt` | model time step | d  | - |
-| `βₗ` | slope | -  | - |
+| **`βₗ`** (`slope`) | slope | m m``^{-1}``  | - |
 | `dl` | drain length | m | - |
 | `dw` | drain width | m | - |
 | `zi` | pseudo-water table depth (top of the saturated zone) | m | - |
@@ -187,6 +220,9 @@ floodplain routing, and parameter `q_channel_av` represents average river channe
 Otherwise parameters `q_av` and `q_channel_av` represent both average river channel
 discharge (are equal).
 
+The input parameter `n` (listed under `[input.lateral.river]`) is not equal to the internal
+model parameter `mannings_n`, and is listed in the Table below between parentheses.
+
 |  parameter  | description  	  | unit  | default |
 |:--------------- | ------------------| ------- | ------ |
 | **`mannings_n`** (`n`) |  Manning's roughness | s m``^{-\frac{1}{3}}`` | 0.036 |
@@ -239,7 +275,9 @@ The Table below shows the parameters (fields) of struct `FloodPlain` (part of st
 value if applicable. The parameters in bold represent model parameters that can be set
 through static input data (netCDF), and can be listed in the TOML configuration file under
 `[input.lateral.river.floodplain]`, to map the internal model parameter to the external
-netCDF variable.
+netCDF variable. The input parameter `n` (listed under `[input.lateral.river.floodplain]`)
+is not equal to the internal model parameter `mannings_n`, and is listed in the Table below
+between parentheses.
 
 |  parameter  | description  	  | unit  | default |
 |:--------------- | ------------------| ----- | -------- |
@@ -269,14 +307,17 @@ The floodplain profile `FloodPlainProfile` contains the following parameters:
 |  `a`   |  cumulative floodplain flow area (per flood depth) | m``^2`` | - |
 |  `p`   |  cumulative floodplain wetted perimeter (per flood depth) | m | - |
 
-The floodplain volumes (per flood depth interval) can be set as follows through the TOML
+The floodplain volumes (per flood `depth` interval) can be set as follows through the TOML
 file:
 
 ```toml
 [input.lateral.river.floodplain]
 volume = "floodplain_volume"
 ```
 
+The input parameter `flood_depth` (dimension of floodplain `volume`) is not equal to the
+internal model parameter `depth`, and is listed in the Table below between parentheses.
+
 ### [Overland flow](@id local-inertial_land_params)
 The Table below shows the parameters (fields) of struct `ShallowWaterLand`, including a
 description of these parameters, the unit, and default value if applicable. The parameters
@@ -291,6 +332,8 @@ follows in the TOML file:
 [input.lateral.land]
 n = "n_land" # mannings roughness
 ```
+The input parameter `elevation` (listed under `[input.lateral.land]`) is not equal to the
+internal model parameter `z`, and is listed in the Table below between parentheses.
 
 |  parameter  | description  	  | unit  | default |
 |:--------------- | ------------------| ----- | -------- |
@@ -331,7 +374,7 @@ description of these parameters, the unit, and default value if applicable. Stru
 |:--------------- | ------------------| ----- | -------|
 | `k` | horizontal conductivity  | m d``^{-1}``s | - |
 | `storativity`     | storativity  | m m``^{-1}`` | - |
-| `specific_storage` | specific storage | m``^{-1}`` | - }
+| `specific_storage` | specific storage | m``^{-1}`` | - |
 | `top`     | top groundwater layers  | m | - |
 | `bottom`     | bottom groundwater layers  | m | - |
 | `area`          | cell area    | m``^2`` | - |
@@ -342,19 +385,22 @@ description of these parameters, the unit, and default value if applicable. Stru
 The Table below shows the parameters (fields) of struct `UnconfinedAquifer`, including a
 description of these parameters, the unit, and default value if applicable. The parameters
 in bold represent model parameters that can be set through static input data (netCDF), and
-can be listed in the TOML configuration file under `[lateral.subsurface]`, to map the
+can be listed in the TOML configuration file under `[input.lateral.subsurface]`, to map the
 internal model parameter to the external netCDF variable. For some input parameters the
-parameter listed under `[lateral.subsurface]` is not equal to the internal model parameter,
-these are listed in the Table below between parentheses after the internal model parameter.
-The `top` parameter is provided by the external parameter `altitude` as part of the static
-input data and set as follows through the TOML file:
+parameter listed under `[input.lateral.subsurface]` is not equal to the internal model
+parameter, these are listed in the Table below between parentheses after the internal model
+parameter. The `top` parameter is provided by the external parameter `altitude` as part of
+the static input data and set as follows through the TOML file:
 
 ```toml
 [input]
 # these are not directly part of the model
 altitude = "wflow_dem"
 ```
 
+The input parameter `conductivity` (listed under `[input.lateral.subsurface]`) is not equal
+to the internal model parameter `kh₀`, and is listed in the Table below between parentheses.
+
 |  parameter  | description  	        | unit  | default |
 |:--------------- | ------------------| ----- | -------|
 | **`kh₀`** (`conductivity`) | horizontal conductivity  | m d``^{-1}``s | - |
@@ -370,10 +416,10 @@ altitude = "wflow_dem"
 The Table below shows the parameters (fields) of struct `ConstantHead`, including a
 description of these parameters, the unit, and default value if applicable. The parameters
 in bold represent model parameters that can be set through static input data (netCDF), and
-can be listed in the TOML configuration file under `[lateral.subsurface]`, to map the
-internal model parameter to the external netCDF variable. For some input parameters the
-parameter listed under `[lateral.subsurface]` is not equal to the internal model parameter,
-these are listed in the Table below between parentheses after the internal model parameter.
+can be listed in the TOML configuration file under `[input.lateral.subsurface]`, to map the
+internal model parameter to the external netCDF variable. The input parameter
+`constant_head` (listed under `[input.lateral.subsurface]`) is not equal to the internal
+model parameter `head`, and is listed in the Table below between parentheses.
 
 |  parameter  | description  	       | unit  | default |
 |:--------------- | ------------------| ----- | --------- |
@@ -383,13 +429,13 @@ these are listed in the Table below between parentheses after the internal model
 ### Boundary conditions
 
 #### [River](@id gwf_river_params)
-The Table below shows the parameters (fields) of struct `River`, including a
-description of these parameters, the unit, and default value if applicable. The parameters
-in bold represent model parameters that can be set through static input data (netCDF), and
-can be listed in the TOML configuration file under `[lateral.subsurface]`, to map the
-internal model parameter to the external netCDF variable. For some input parameters the
-parameter listed under `[lateral.subsurface]` is not equal to the internal model parameter,
-these are listed in the Table below between parentheses after the internal model parameter.
+The Table below shows the parameters (fields) of struct `River`, including a description of
+these parameters, the unit, and default value if applicable. The parameters in bold
+represent model parameters that can be set through static input data (netCDF), and can be
+listed in the TOML configuration file under `[input.lateral.subsurface]`, to map the
+internal model parameter to the external netCDF variable. The input parameter `river_bottom`
+(listed under `[input.lateral.subsurface]`) is not equal to the internal model parameter
+`bottom`, and is listed in the Table below between parentheses.
 
 |  parameter  | description  	        | unit  | default |
 |:--------------- | ------------------| ----- | -------|
@@ -401,13 +447,14 @@ these are listed in the Table below between parentheses after the internal model
 | `flux`          | exchange flux (river to aquifer)  | m``^3`` d``^{-1}`` | - |
 
 #### [Drainage](@id gwf_drainage_params)
-The Table below shows the parameters (fields) of struct `Drainage`, including a
-description of these parameters, the unit, and default value if applicable. The parameters
-in bold represent model parameters that can be set through static input data (netCDF), and
-can be listed in the TOML configuration file under `[lateral.subsurface]`, to map the
+The Table below shows the parameters (fields) of struct `Drainage`, including a description
+of these parameters, the unit, and default value if applicable. The parameters in bold
+represent model parameters that can be set through static input data (netCDF), and can be
+listed in the TOML configuration file under `[input.lateral.subsurface]`, to map the
 internal model parameter to the external netCDF variable. For some input parameters the
-parameter listed under `[lateral.subsurface]` is not equal to the internal model parameter,
-these are listed in the Table below between parentheses after the internal model parameter.
+parameter listed under `[input.lateral.subsurface]` is not equal to the internal model
+parameter, these are listed in the Table below between parentheses after the internal model
+parameter.
 
 |  parameter  | description  	        | unit  | default |
 |:--------------- | ------------------| ----- | -------|
@@ -417,8 +464,8 @@ these are listed in the Table below between parentheses after the internal model
 | `flux`          | exchange flux (drains to aquifer)  | m``^3`` day``^{-1}`` | - |
 
 #### [Recharge](@id gwf_recharge_params)
-The Table below shows the parameters (fields) of struct `Recharge`, including a
-description of these parameters, the unit, and default value if applicable.
+The Table below shows the parameters (fields) of struct `Recharge`, including a description
+of these parameters, the unit, and default value if applicable.
 
 |  parameter  | description  	        | unit  | default |
 |:--------------- | ------------------| ----- | ---- |

docs/src/user_guide/model-setup.md

@@ -56,8 +56,8 @@ the SBM + Kinematic wave model includes the lateral component [Subsurface flow
 routing](@ref) and parameters that are part of this component are described in the [Lateral
 subsurface flow](@ref) section of Model parameters. Input parameters for this component of
 the SBM + Kinematic wave model are derived from the SBM vertical concept and the land slope.
-One external parameter `ksathorfrac` is used to calculate the horizontal hydraulic
-conductivity at the soil surface `kh₀`.
+One external parameter [`ksathorfrac`](@ref params_ssf) is used to calculate the horizontal
+hydraulic conductivity at the soil surface `kh₀`.
 
 There is also the option to use the local inertial model as part of the `sbm` model type:
 + for river flow, see also  [SBM + Local inertial river](@ref) model.

src/io.jl

@@ -980,7 +980,7 @@ function prepare_writer(
     # data, but only if config.netcdf.variable has been set.
     if haskey(config, "netcdf") && haskey(config.netcdf, "variable")
         nc_scalar_path = output_path(config, config.netcdf.path)
-        @info "Create an output NetCDF file `$nc_state_path` for scalar data."
+        @info "Create an output NetCDF file `$nc_scalar_path` for scalar data."
         # get NetCDF info for scalar data (variable name, locationset (dim) and
         # location ids)
         ncvars_dims = nc_variables_dims(config.netcdf.variable, nc_static, config)