Skip to content

Commit

Permalink
document flextopo
Browse files Browse the repository at this point in the history
  • Loading branch information
@laurenebouaziz @visr
laurenebouaziz authored and visr committed Apr 8, 2022
1 parent 98b76ea commit 5934394
Show file tree
Hide file tree
Showing 9 changed files with 562 additions and 3 deletions.
1 change: 1 addition & 0 deletions docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ pages = [
"Vertical concepts" => [
"model_docs/vertical/sbm.md",
"model_docs/vertical/hbv.md",
"model_docs/vertical/flextopo.md",
"model_docs/vertical/sediment.md",
"model_docs/shared_concepts.md",
],
Expand Down
Binary file added docs/src/images/flextopo_julia_1class.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/src/images/flextopo_julia_3class.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
83 changes: 83 additions & 0 deletions docs/src/model_docs/model_configurations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,86 @@ lateral.river.lake => struct NaturalLake{T} # optional
lateral.river.reservoir => struct SimpleReservoir{T} # optional
```

## [wflow\_flextopo](@id config_flextopo)
The FLEXTopo model is a process-based model, which consists of different parallel classes
connected through their groundwater storage. These classes are usually delineated from
topographical data to represent the variability in hydrological processes across
user-defined Hydrological Response Units (HRU). The main assumption underlying the concept,
which was first introduced by Savenije (2010), is that different parts of the landscape
fulfill different tasks in runoff generation and, hence, can be represented by different
model structures. The strength of the concept is that the definition of classes and
associated model structures is modular and flexible and not fixed to a predefined model
structure. The flexible approach allows to develop process-based models for different
topographic, climatic, geologic and land use conditions, making use of the available data
and expert knowledge.

The kinematic wave function is used to route the water downstream. In a similar way as for
HBV, all runoff that is generated in a cell in one of the FLEXTopo storages is added to the
kinematic wave reservoir at the end of a timestep. There is no connection between the
different vertical FLEXTopo cells within the model. The FLEXTopo model is implemented in a
fully distributed way in the Wflow Julia framework.

In wflow\_flextopo, the user is free to determine the number of classes and which model
components to include or exclude for each class, this is done in the TOML file. Currently,
for each storage, it is possible to bypass the storage and pass on the fluxes to the next
model component. Interested users can contribute to the code by adding other
conceptualizations for each storage components.

```julia
[model]
type = "flextopo"
classes = ["h", "p", "w"] #user can set the number and name of each class.

# for each component which is class specific, the user can select which conceptualization
# to apply for each class as defined above in classes = ["h", "p", "w"]
select_snow = ["common_snow_hbv"]
# available options are ["common_snow_hbv", "common_snow_no_storage"]
select_interception = ["interception_overflow", "interception_overflow", "interception_overflow"]
# available options are ["interception_overflow", "interception_no_storage"]
select_hortonponding = ["hortonponding_no_storage", "hortonponding_no_storage", "hortonponding_no_storage"]
# available options are ["hortonponding", "hortonponding_no_storage"]
select_hortonrunoff = ["hortonrunoff_no_storage", "hortonrunoff_no_storage", "hortonrunoff_no_storage"]
# available options are ["hortonrunoff", "hortonrunoff_no_storage"]
select_rootzone = ["rootzone_storage", "rootzone_storage", "rootzone_storage"]
# available options are ["rootzone_storage", "rootzone_no_storage"]
select_fast = ["fast_storage", "fast_storage", "fast_storage"]
# available options are ["fast_storage", "fast_no_storage"]
select_slow = ["common_slow_storage"]
# available options are ["common_slow_storage", "slow_no_storage"]
```

A schematic representation of the most complete model structure including all storage
components, as currently implemented in the code, is shown in the Figure below. When setting
up the model with multiple classes, model structures can be adapted by bypassing storages or
turning parameter values on or off (e.g.: percolation or capillary rise, non-linear versus
linear outflow of the fast runoff etc.), an example of a three class model is shown in
[FLEXTopo vertical concept](@ref vert_flextopo).

![flextopo_julia_1class.png](../images/flextopo_julia_1class.png)
*Schematic representation of the FLEXTopo model for a single class model including all
storages and fluxes. Main parameters are denoted in red.*

In the staticmaps, the user needs to provide maps of the fraction of each class within each
cell, as shown below with `hrufrac`. For each model parameter which is class specific, an
extra dimension `classes` is required in the staticmaps netcdf. For an example model, see
[FLEXTopo example model](@ref wflow_flextopo_data).

```julia
[input.vertical]
hrufrac = "hrufrac_lu"
```

Parameter multiplication of model parameters which are defined for several classes is
possible through the TOML file:

```julia
[input.vertical.kf]
netcdf.variable.name = "kf"
scale = [1.0, 3.0, 4.0]
offset = [0.0, 0.0, 0.0]
class = ["h", "p", "w"]
```

## wflow\_sediment
The processes and fate of many particles and pollutants impacting water quality at the
catchment level are intricately linked to the processes governing sediment dynamics. Both
Expand Down Expand Up @@ -228,3 +308,6 @@ Bedconc = "Bedconc"
+ Köhler, L., Mulligan, M., Schellekens, J., Schmid, S., Tobón, C., 2006, Hydrological
impacts of converting tropical montane cloud forest to pasture, with initial reference to
northern Costa Rica. Final Technical Report DFID‐FRP Project No. R799.

+ Savenije, H. H. G. (2010). HESS opinions “topography driven conceptual modelling (FLEX-Topo).”
Hydrology and Earth System Sciences, 14(12), 2681–2692. https://doi.org/10.5194/hess-14-2681-2010
95 changes: 94 additions & 1 deletion docs/src/model_docs/params_vertical.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ The Table below shows the parameters (fields) of struct `HBV`, including a descr
these parameters, the unit, and default value if applicable. The parameters in bold
represent model parameters that can be set through static and forcing input data (netCDF),
and can be listed in the TOML configuration file under `[input.vertical]`, to map the
internal model parameter to the external netCDF variable.
internal model parameter to the external netCDF variable.

| parameter | description | unit | default |
|:---------------| --------------- | ---------------------- | ----- |
Expand Down Expand Up @@ -182,6 +182,99 @@ internal model parameter to the external netCDF variable.
| `runoff` | total specific runoff per cell | mm Δt``^-1`` | - |


## [FLEXtopo](@id params_flextopo)
The Table below shows the parameters (fields) of struct `FLEXTOPO`, 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 and forcing input data (netCDF),
and can be listed in the TOML configuration file under `[input.vertical]`, to map the
internal model parameter to the external netCDF variable.

| parameter | description | unit | default |
|:---------------| --------------- | ---------------------- | ----- |
| **`cfmax`** | degree-day factor | mm ᵒC``^{-1}`` Δt``^{-1}`` | 3.75653 mm ᵒC``^{-1}`` day``^{-1}`` |
| **`tt`** | threshold temperature for snowfall| ᵒC | -1.41934 |
| **`tti`** | threshold temperature interval length | ᵒC | 1.0 |
| **`ttm`** | threshold temperature for snowmelt | ᵒC | -1.41934 |
| **`whc`** | water holding capacity as fraction of current snow pack | - | 0.1 |
| **`cfr`** | refreezing efficiency constant in refreezing of freewater in snow | - | 0.05 |
| **`g_tt`** | threshold temperature for snowfall above glacier | ᵒC| 0.0 |
| **`g_cfmax`** | Degree-day factor for glacier | mm ᵒC``^{-1}`` Δt``^{-1}``| 3.0 mm ᵒC``^{-1}`` day``^{-1}`` |
| **`g_sifrac`** | fraction of the snowpack on top of the glacier converted into ice | - | 0.001 |
| **`glacierfrac`** | fraction covered by a glacier | - | 0.0 |
| **`glacierstore`** | water within the glacier | mm | 5500.0 |
| **`ecorr`** | evaporation correction | - | 1.0 |
| **`pcorr`** | correction factor for precipitation | - | 1.0 |
| **`rfcf`** | correction factor for rainfall | - | 1.0 |
| **`sfcf`** | correction factor for snowfall | - | 1.0 |
| **`imax`** | maximum interception storage (``I_\mathrm{max}``) | mm | 3.0 |
| **`shmax`** | maximum horton ponding storage capacity (``S_\mathrm{Hmax}``) | mm | 30.0 |
| **`srmax`** | maximum root zone storage capacity (``S_\mathrm{Rmax}``) | mm | 260.0 |
| **`beta`** | exponent in soil runoff generation equation | - | 0.3 |
| **`lp`** | fraction of root zone capacity below which actual evaporation=potential evaporation (``L_\mathrm{P}``) | - | 0.3 |
| **`ks`** | recession constant slow groundwater storage (``K_\mathrm{S}``) | Δt``^-1`` | 0.006 day``^{-1}`` |
| **`kf`** | recession constant fast storage (``K_\mathrm{F}``) | Δt``^-1`` | 0.1 day``^{-1}`` |
| **`khf`** | recession constant horton runoff storage (``K_\mathrm{Hf}``) | Δt``^-1`` | 0.5 day``^{-1}`` |
| **`alfa`** | measure of non-linearity of upper reservoir (``\alpha``) | - | 1.0 |
| **`perc`** | maximum percolation flux from root zone to slow storage (``Q_\mathrm{perc,max}``) | mm Δt``^-1``| 0.30 mm day``^{-1}`` |
| **`cap`** | maximum capillary rise from slow storage to root zone (``Q_\mathrm{cap,max}``)| mm Δt``^-1`` | 0.20 mm day``^{-1}`` |
| **`ds`** | splitter parameter determining fraction of root zone outflow to slow storage (``d_\mathrm{s}``) | - | 0.2 |
| **`shmin`** | minimum storage capacity in horton ponding (relative to ``S_\mathrm{Hmax}``) (``S_\mathrm{Hmin}``) | [-] | 0.2 |
| **`facc0`** | maximum modelled accumulated frost resulting in `shmin` (``F_\mathrm{acc,fr0}``) | [ᵒC Δt] | -3.0 |
| **`facc1`** | minimum modelled accumulated frost resulting in `shmin` (``F_\mathrm{acc,fr1}``) | [ᵒC Δt] | 0.0 |
| **`fdec`** | exponent for the decline of infiltration capacity (``F_\mathrm{dec}``) | [-] | 0.2 |
| **`fmax`** | maximum infiltration capacity from horton ponding (``F_\mathrm{max}``) | [mm Δt``^-1``] | 2.0 |
| **`kmf`** | melt coefficient of frozen topsoil (``K_\mathrm{mf}``) | [-] | 1.0 |
| **`hrufrac`** | fraction of class within cell (``F_\mathrm{hrufrac}``)| - | 1/length(classes) |
| **`precipitation`** | precipitation | mm Δt``^-1`` | - |
| **`temperature`** | temperature | ᵒC | - |
| **`potential_evaporation`** | potential evapotranspiration | mm Δt``^-1`` | - |
| `precipcorr` | corrected precipitation | mm Δt``^-1`` | - |
| `epotcorr` | corrected potential evaporation | mm Δt``^-1`` | - |
| `snow` | snow water (``S_\mathrm{W}``) | mm | - |
| `snowwater` | available free water in snow | mm | - |
| `interceptionstorage` | interception storage (``S_\mathrm{I}``) | mm | - |
| `interceptionstorage_m` | average interception storage over classes (``S_\mathrm{I}``) | mm | - |
| `hortonpondingstorage` | horton ponding storage (``S_\mathrm{Hp}``) | mm | - |
| `hortonpondingstorage_m` | average horton ponding storage over classes (``S_\mathrm{Hp}``) | mm | - |
| `hortonrunoffstorage` | horton runoff storage (``S_\mathrm{Hf}``) | mm | - |
| `hortonrunoffstorage_m` | average horton runoff storage over classes (``S_\mathrm{Hf}``) | mm | - |
| `rootzonestorage` | root zone storage (``S_\mathrm{R}``) | mm | - |
| `rootzonestorage_m` | average root zone storage over classes (``S_\mathrm{R}``) | mm | - |
| `faststorage` | fast storage (``S_\mathrm{F}``) | mm | - |
| `faststorage_m` | average fast storage over classes (``S_\mathrm{F}``) | mm | - |
| `slowstorage` | slow storage (``S_\mathrm{S}``) | mm | - |
| `potsoilevap` | potential soil evaporation (``E_\mathrm{P}``) | mm Δt``^-1`` | - |
| `soilevap` | soil evaporation | mm Δt``^-1`` | - |
| `intevap` | evaporation from interception storage (``E_\mathrm{I}``) | mm Δt``^-1`` | - |
| `intevap_m` | average evaporation from interception storage over classes (``E_\mathrm{I}``) | mm Δt``^-1`` | - |
| `hortonevap` | evaporation from horton ponding storage (``E_\mathrm{H}``) | mm Δt``^-1`` | - |
| `hortonevap_m` | average evaporation from horton ponding storage over classes (``E_\mathrm{H}``) | mm Δt``^-1`` | - |
| `rootevap` | evaporation from root zone storage (``E_\mathrm{R}``) | mm Δt``^-1`` | - |
| `rootevap_m` | average evaporation from root zone storage over classes (``E_\mathrm{R}``) | mm Δt``^-1`` | - |
| `actevap` | actual evapotranspiration (intevap + hortonevap + rootevap) (``E_\mathrm{A}``) | mm Δt``^-1`` | - |
| `actevap_m` | average actual evapotranspiration (intevap + hortonevap + rootevap) over classes (``E_\mathrm{A}``) | mm Δt``^-1`` | - |
| `precipeffective` | Effective precipitation (``P_\mathrm{E}``) | mm Δt``^-1`` | - |
| `rainfallplusmelt` | snow melt + precipitation as rainfall (``P_\mathrm{M} + P_\mathrm{R}``) | mm Δt``^-1`` | - |
| `snowmelt` | snowfall | mm Δt``^-1`` | - |
| `snowfall` | snowfall | mm Δt``^-1`` | - |
| `facc` | modeled accumulated frost | ᵒC Δt | - |
| `qhortonpond` | Flux from the hortonian ponding storage to the hortonian runoff storage (``Q_\mathrm{H}``) | mm Δt``^-1`` | - |
| `qhortonrootzone` | Flux from the hortonian ponding storage to the root zone storage (``Q_\mathrm{HR}``) | mm Δt``^-1`` | - |
| `qhortonrun` | Flux from the hortonian runoff storage (``Q_\mathrm{Hf}``) | mm Δt``^-1`` | - |
| `qrootzone` | Flux from the root zone storage (``Q_\mathrm{R}``) | mm Δt``^-1`` | - |
| `qrootzonefast` | Pref. recharge to fast storage (``Q_\mathrm{RF}``) | mm Δt``^-1`` | - |
| `qrootzoneslow_m` | Pref. recharge to slow storage sum classes (``Q_\mathrm{RS}``) | mm Δt``^-1`` | - |
| `qcapillary` | Capillary flux from the slow to the root-zone storage (``Q_\mathrm{cap}``) | mm Δt``^-1`` | - |
| `qcapillary_m` | Capillary flux from the slow to the root-zone storage sum classes (``Q_\mathrm{cap}``) | mm Δt``^-1`` | - |
| `qpercolation` | Percolation flux from the root-zone to the slow storage (``Q_\mathrm{perc}``) | mm Δt``^-1`` | - |
| `qpercolation_m` | Percolation flux from the root-zone to the slow storage sum classes (``Q_\mathrm{perc}``) | mm Δt``^-1`` | - |
| `qfast` | runoff from fast storage (``Q_\mathrm{F}``) | mm Δt``^-1`` | - |
| `qfast_tot` | sum of fast runoff (from fast and horton runoff storages) over classes | mm Δt``^-1`` | - |
| `qslow` | runoff from slow storage (``Q_\mathrm{S}``) | mm Δt``^-1`` | - |
| `runoff` | total specific runoff per cell (qslow + qfast_tot) (``Q``) | mm Δt``^-1`` | - |
| `wb_tot` | total water balance | mm Δt``^-1`` | - |


## [Sediment](@id params_sediment)

The Table below shows external parameters that can be set through static input data
Expand Down
Loading

0 comments on commit 5934394

Please sign in to comment.