The Model Object

In dynatop: An Implementation of Dynamic TOPMODEL Hydrological Model in R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The purpose of this vignette is to document the structure of a Dynamic TOPMODEL model 'object'; that is the structure of the model that can be generated in the dynatopGIS package and is used in calls to the dynatop function in the current package. Currently the model is stored as an R variable of the list class.

This should be read alongside the "Getting Started" vignette which demonstrates the manipulation and use of a model object.

The model structure will be documented with reference to the model in the test catchment data supplied with the package. This can be loaded with

library(dynatop)
data("Swindale")
model <- Swindale$model

The top level of the model contains the following elements:

names(model)

These are outlined in Table \@ref(tab:model-table) and described in more detail in the sections below.

| Name | Class | Description | | --- | --- | ------ | | options | character vector | Options defining the model | | hillslope | data.frame | Description of the hill slope HRU units | | channel | data.frame | Description of the channel HRU units | | gauge | data.frame | Description of the gauge locations on the channel network | | point_inflow | data.frame | Description of the point inflows to the channel network | | diffuse_inflow | data.frame | Description of the diffuse inflows to the channel network | | flow_direction | data.frame | Description of the flow linkages between HRUs | | precip_input | data.frame | Description of the precipitation input to the HRUs | | pet_input | data.frame | Description of the PET input to the HRUs | | map | list | Location of files for creating plots of the HRUs |

Table: (#tab:model-table) Description of top-level model components

Options

The options vector is a named character vector. Two named variables are used:

• transmissivity_profile which defines the transmissivity function used for the hillslope HRUs
• channel_solver which defines the channel solution to be used

The columns present in the hillslope and channel data.frames will depend upon the value taken by these options. See the hillslope and channel vignettes for further details.

Hillslope HRU table

Each row of the hillslope table describes a single hillslope HRU. In this example it looks like:

head(model$hillslope)

The individual columns are documented in Table \@ref(tab:hillslope-table). Not all the parameters are relevant for each option. See the Hillslope HRU vignette for details.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | id | integer | - | Unique identifying number of the HRU. These combined with the HRU numbers in the channel table should be unique and take values 1,2,3... | | area | numeric | m$^2$ | Surface area of the HRU | | atb_bar | numeric | ?? | Topographic index, log if the upslope area divided by tangent of gradient | | s_bar | numeric | - | Average gradient | | min_dst | numeric | -[m] | Minimum distance from HRU to a channel from the distance metric used in the model generation | | width | numeric | m | Contour length of downslope end of HRU | | s_sf | numeric | m | Surface Zone storage volume per unit area (state) | | s_rz | numeric | m | Root Zone storage volume per unit area (state) | | s_uz | numeric | m | Unsaturated Zone storage volume per unit area (state) | | s_sz | numeric | m | Saturated Zone storage deficit per unit area (state) | | cls_* | integer | - | Classification of HRU in each of the classes used in its definition. The extra part of the name matches the class name given in dynatopGIS | | opt | character | - | Option controlling the type of Hillslope HRU. Currently defines the transmissivity profile. | | r_sfmax | numeric | m/s | Maximum flow rate from surface to root zone (parameter) | | c_sf | numeric | m/s | Celerity of the surface excess storage (parameter) | | s_rzmax | numeric | m | Maximum root zone depth (parameter) | | t_d | numeric | s/m | Unsaturated zone time constant given per $m$ of saturated storage deficit (parameter) | | ln_t0 | numeric | m/s | Log of the soil saturated conductivity (parameter) | | m | numeric | - | Exponential transmissivity decay parameter (parameter) | | m_2 | numeric | - | Second Exponential transmissivity decay parameter (parameter) | | omega | numeric | 0-1 | Weighting between the two transmissivity parameters (parameter) | | c_sz | numeric | m/s | Constant saturated zone celerity (parameter) | | s_rz0 | numeric | 0-1 | Initial root zone depth expressed as fraction of maximum depth (parameter) | | r_uz_sz0 | numeric | m/s | Initial recharge to the saturated zone per unit area (parameter) |

Table: (#tab:hillslope-table) Description of hillslope data frame columns

Channel HRU table

Each row of the channel HRU table describes a single channel HRU. In this example it looks like:

head(model$channel)

Many of the columns are not needed and are passed through from the original data. The columns required are documented in Table \@ref(tab:channel-table).

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | id | integer | - | Unique identifying number of the channel HRU. These, combined with the id from the hillslope table should for consecutive integers increasing from 1. | | area | numeric | m$^2$ | Surface area of the HRU in m$^2$ | | length | numeric | m | Length of the channel in metres | | v_ch | numeric | m/s | Channel velocity parameter |

Table: (#tab:channel-table) Description of channel data frame columns

Gauge locations

Gauge locations can be specified on the channel HRUs as outlined in Table \@ref(tab:gauge-table). Gauges are taken to be at the outlet of the channel length.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | name | character | - | Unique name to identify the gauge. Used to name the output series | | id | integer | - | The id of the channel HRU on which the gauge is sited |

Table: (#tab:gauge-table) Description of gauge data frame columns

In this case there is a single gauge at the outlet:

model$gauge

Point Inflows

The point_inflow data frame allows the specification for point inflow which are added to the inflow at the head of the channel length.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | name | character | - | Name of the input series to use. | | id | integer | - | The id of the channel HRU to which the inflow is added |

Table: (#tab:point-inflow-table) Description of point_inflow data frame columns

In the current catchment there are no inflows so the table is left blank:

model$point_inflow

Diffuse Inflows

The diffuse_inflow data frame allows the specification of diffuse inputs to the channel. These are presumed to occur uniformly along the channel length.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | name | character | - | Name of the input series to use. | | id | integer | - | The id of the channel HRU to which the inflow is added |

Table: (#tab:diffuse-inflow-table) Description of diffuse_inflow data frame columns

In the current catchment there are no inflows so the table is left blank:

model$diffuse_inflow

Flow direction

The flow_direction data frame describes the connections between the HRUs.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | from | integer | - | id of the HRU which the flow comes from | | to | integer | - | id of the HRU to which the flow is going | | frc | numeric | 0-1 | Fraction of the flow which goes from the from id to the to id |

Table: (#tab:flow-direction-table) Description of flow_direction data frame columns

The start of the data frame in the current example is:

head(model$flow_direction)

Precipitation input

The precip_input data frame describes the precipitation series to use for each HRU. Each row contains a HRU id, the series to use and the fraction of the HRU to which this series should be applied. From this an average precipitation for each HRU is derived.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | id | integer | - | The id of the channel HRU to which the input is applied | | name | character | - | Name of the input series to use. | | frc | numeric | 0-1 | The fraction of the HRU area for which the input series is valid |

Table: (#tab:precip-input-table) Description of precip_input data frame columns

In the current example there is a single precipitation series being used:

head(model$precip_input)

PET input

The pet_input data frame describes the potential evapotranspiration series to use for each HRU. Each row contains a HRU id, the series to use and the fraction of the HRU to which this series should be applied. From this an average PET value for each HRU is derived.

| Name | Class | Unit | Description | | --- | --- | --- | ----- | | id | integer | - | The id of the channel HRU to which the input is applied | | name | character | - | Name of the input series to use. | | frc | numeric | 0-1 | The fraction of the HRU area for which the input series is valid |

Table: (#tab:pet-input-table) Description of pet_input data frame columns

In the current example there is a single PET series being used:

head(model$pet_input)

dynatop documentation built on Oct. 11, 2022, 1:06 a.m.