The Model Object • dynatop

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)
#> [1] "hru"         "output_flux" "map"

We consider each of these separately.

map

The map element gives the path to the raster map of HRU locations which can be used in the creation of a new dynatop object to enable plotting of the state variables.

output_flux

The output_flux element contains a data frame which defines the series to be output during a simulation. This is passed to the sim method of the dynatop object. The columns of output_flux are given in Table 1.

A single output value for each series is given for each data time step. If multiple rows of the data frame contain the same name the values of the series are summed. If the simulation is run with substeps then the outputs are averaged over the sub steps. Note that strictly only “q_sf”, “q_sf_in”, “q_sz” and “q_sz_in” are fluxes, the remainder are volumes.

Table 1: Description of `output_flux` data frame columns
Name	Class	Unit	Description
name	character	-	name given to the output series
id	integer	-	id of the HRU from which the output is to be taken
flux	character	-	Flux to be recorded. One of “precip”, “pet”, “aet”, “q_sf”, “q_sf_in”, “q_sz”, “q_sz_in”, “s_sf”, “s_rz”, “s_uz”, “s_sz”, “v_sf_rz”, “v_rz_uz” or “v_uz_sz”.

hru

The hru contains a list, where each list element is the description of a single HRU. Each HRU is described by a list containing the elements outlined in Table 2 and described in more detail in the sections below. In many cases the naming of the variables within the vectors relates to the variables names in the HRU vignette as given in implementation document.

Table 2: Description of top-level model components
Name	Class	Description
id	integer	The unique ID of the HRU
states	numeric	Named numeric vector of states
properties	numeric	Named numeric vector of properties
sf	list	Description of the surface zone solution
rz	list	Description of the surface zone solution
uz	list	Description of the unsaturated zone solution
sz	list	Description of the saturated solution
sf_flow_direction	list	Description of the surface zone outflows to other HRUs
sz_flow_direction	list	Description of the saturated zone outflows to other HRUs
initialisation	numeric	Named numeric vector of initialisation parameters
precip	list	Description of the precipitation input to the HRU
pet	list	Description of the PET input to the HRU
class	list	Classification information from dynatopGIS

states

A numeric vector of states, see Table 3, such as

model$hru[[1]]$states
#> s_sf s_rz s_uz s_sz 
#>   NA   NA   NA   NA

Table 3: Description of numeric state vector
Name	Class	Unit	Description
s_sf	numeric	m	Surface Zone storage volume per unit area
s_rz	numeric	m	Root Zone storage volume per unit area
s_uz	numeric	m	Unsaturated Zone storage volume per unit area
s_sz	numeric	m	Saturated Zone storage deficit per unit area

properties

A numeric vector of properties, see Table 4 such as

model$hru[[1]]$properties
#>         area        width           Dx     gradient 
#> 1.120000e+04 2.000000e+00 1.638000e+03 1.446232e-02

Table 4: Description of numeric state vector
Name	Class	Unit	Description
area	numeric	m\(^2\)	Surface area of the HRU
width	numeric	m	Width of the HRU
Dx	numeric	m	Effective length of the HRU
gradient	numeric	-	Average gradient

sf, rz, uz,& sz

The list variables describe the surface (sf), root zone (rz), unsaturated zone (uz) ans saturated zone (sz) representations. Each list contains a character vector type giving the type of representation and parameters a numeric vector of names parameters. For example

model$hru[[1]]$sz
#> $type
#> [1] "exp"
#> 
#> $parameters
#>   t_0     m 
#> 0.135 0.040

The description of the types and parameters are given in the HRU vignette

sf_flow_direction & sz_flow_direction

Each of these lists contains two vectors as specified in Table 5. In the special case that no outflow goes to another HRU, such as at the outlet of the catchment, the description of the flow direction takes the following form:

model$hru[[1]]$sf_flow_direction
#> $id
#> integer(0)
#> 
#> $fraction
#> numeric(0)

Table 5: Description of flow direction list variables
Name	Class	Unit	Description
id	integer	-	Vector of id values for the HRUs to which the flow is going. Must be lower then the current id
frc	numeric	0-1	Fraction of the flow which goes from the corresponding id. Must sum to 1

initialisation

The named numeric vector contains the values to use in the initialisation of the HRU as given in Table 6 and shown below.

model$hru[[1]]$initialisation
#>    s_rz_0 r_uz_sz_0 
#>   7.5e-01   1.0e-07

Table 6: Description of initialisation values
Name	Class	Unit	Description
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)

precip & pet

These list contain the description of the precipitation (precip) and PET (pet) inputs used by the HRU. Each list takes the form of two vectors as given in Table 7 and shown below. From this the average input value is calculated.

model$hru[[1]]$precip
#> $name
#> [1] "precip"
#> 
#> $fraction
#> [1] 1

Table 7: Description of precip and pet lists
Name	Class	Unit	Description
name	character	-	Character vector containing the names of the input series to use.
frc	numeric	0-1	The fraction of the HRU area for which the input series is valid. Must sum to 1.

class

Class is a list variable. while not used in the simulation code it can be used to store information that might be of use in, for example, determining which parameter values to apply to the HRU (see the “Getting Started” vignette for an example).

Currently if the model is constructed using dynatopGIS class is populated based on the classification and channel data used in the model build process, but the format of this is subject to change.