# The Model Object

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] "options"        "map"            "channel"        "hillslope"
    #>  [5] "flow_direction" "gauge"          "point_inflow"   "diffuse_inflow"
    #>  [9] "precip_input"   "pet_input"

These are outlined in Table 1 and described in more detail in the sections below.

Table 1: Description of top-level model components
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

## 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)
    #>   id      area   atb_bar      s_bar min_dst width s_sf s_rz s_uz s_sz
    #> 1 20  1451.820  9.121463 0.28916356       1    40   NA   NA   NA   NA
    #> 2 21  5911.932  9.598746 0.36701868       1   160   NA   NA   NA   NA
    #> 3 22 16356.278 10.264301 0.26385821       1   440   NA   NA   NA   NA
    #> 4 23 23625.880 10.824251 0.18010123       1   640   NA   NA   NA   NA
    #> 5 24 48632.930 11.497418 0.15906415       1  1320   NA   NA   NA   NA
    #> 6 25 75373.071 12.106720 0.09886103       1  2040   NA   NA   NA   NA
    #>   cls_atb_20_band cls_atb_20 cls_band opt r_sfmax c_sf s_rzmax  t_d ln_t0 c_sz
    #> 1               1          1        1 exp     Inf  0.1    0.05 7200    -2   NA
    #> 2               2          2        1 exp     Inf  0.1    0.05 7200    -2   NA
    #> 3               3          3        1 exp     Inf  0.1    0.05 7200    -2   NA
    #> 4               4          4        1 exp     Inf  0.1    0.05 7200    -2   NA
    #> 5               5          5        1 exp     Inf  0.1    0.05 7200    -2   NA
    #> 6               8          6        1 exp     Inf  0.1    0.05 7200    -2   NA
    #>      m  D m_2 omega s_rz0 r_uz_sz0 s_raf t_raf
    #> 1 0.04 NA  NA    NA  0.75    1e-06     0   Inf
    #> 2 0.04 NA  NA    NA  0.75    1e-06     0   Inf
    #> 3 0.04 NA  NA    NA  0.75    1e-06     0   Inf
    #> 4 0.04 NA  NA    NA  0.75    1e-06     0   Inf
    #> 5 0.04 NA  NA    NA  0.75    1e-06     0   Inf
    #> 6 0.04 NA  NA    NA  0.75    1e-06     0   Inf

The individual columns are documented in Table 2. Not all the parameters are relevant for each option. See the Hillslope HRU vignette for details.

Table 2: Description of hillslope data frame columns
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)

## Channel HRU table

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

    head(model$channel)
    #>                  name1                           identifier
    #> 0        Hawthorn Gill 16D0AC09-E0B6-4727-83B8-567E8DE9C533
    #> 1 Little Mosedale Beck 643017BB-01BC-4738-898F-1C62B84164BF
    #> 2        Mosedale Beck D2C2703E-A32F-4D88-A022-4E27EA52FC5C
    #> 3                 <NA> 991D9896-CA0C-492F-A6EE-8BA3972DDA3C
    #> 4                 <NA> CC8639D7-00D2-4C26-9252-350E5A748D51
    #> 5                 <NA> ED03FEDD-0F4B-40C7-86E8-6F0EA8BAC182
    #>                              startNode                              endNode
    #> 0 730F01D2-0F4F-4E27-AF55-B1782F0F844B 72B1A40B-E106-42A9-A261-4B7720037ADB
    #> 1 9B06188C-F4C7-436C-8108-3956D5FFD5CD A19E0D3A-2FA1-4E6D-AEA4-472F91ABC2AC
    #> 2 B03DB3BD-0E33-4E10-A935-997832752609 D649B60C-E631-47FA-971E-CA388DBDDE63
    #> 3 D968F174-FB80-404A-A4A7-2862CC722482 1FDBFCFF-799C-41CF-A2CB-8A56368BD438
    #> 4 1FDBFCFF-799C-41CF-A2CB-8A56368BD438 7C251581-3764-4DEE-8031-EC98FABC1F87
    #> 5 D3A1AEA9-93A6-4ACF-9A11-363F9517723F 673269DF-9E48-4EA0-B439-3D565A023DD2
    #>          form         flow fictitious length name2 sinkdepth Shape_Leng width
    #> 0 inlandRiver in direction      false    431  <NA>        -1  431.30438     2
    #> 1 inlandRiver in direction      false    513  <NA>        -1  513.12806     2
    #> 2 inlandRiver in direction      false    740  <NA>        -1  739.76378     2
    #> 3 inlandRiver in direction      false    573  <NA>        -1  573.48312     2
    #> 4 inlandRiver in direction      false     29  <NA>        -1   29.18951     2
    #> 5 inlandRiver in direction      false    413  <NA>        -1  413.14877     2
    #>                             channel_id id area v_ch
    #> 0 16D0AC09-E0B6-4727-83B8-567E8DE9C533  2   24    1
    #> 1 643017BB-01BC-4738-898F-1C62B84164BF 17  255    1
    #> 2 D2C2703E-A32F-4D88-A022-4E27EA52FC5C 11  242    1
    #> 3 991D9896-CA0C-492F-A6EE-8BA3972DDA3C  7  126    1
    #> 4 CC8639D7-00D2-4C26-9252-350E5A748D51  6    6    1
    #> 5 ED03FEDD-0F4B-40C7-86E8-6F0EA8BAC182 12  168    1

Many of the columns are not needed and are passed through from the original data. The columns required are documented in Table 3.

Table 3: Description of channel data frame columns
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

## Gauge locations

Gauge locations can be specified on the channel HRUs as outlined in Table 4. Gauges are taken to be at the outlet of the channel length.

Table 4: Description of gauge data frame columns
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

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

    model$gauge
    #>        name id
    #> 1 channel_1  1

## 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.

Table 5: Description of point_inflow data frame columns
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

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

    model$point_inflow
    #> [1] name id
    #> <0 rows> (or 0-length row.names)

## 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.

Table 6: Description of diffuse_inflow data frame columns
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

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

    model$diffuse_inflow
    #> [1] name id
    #> <0 rows> (or 0-length row.names)

## Flow direction

The flow_direction data frame describes the connections between the HRUs.

Table 7: Description of flow_direction data frame columns
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

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

    head(model$flow_direction)
    #>        from   to       frc
    #> 18502  1853 1850 0.3033095
    #> 185110 1853 1851 0.4704486
    #> 1852   1853 1852 0.2262419
    #> 18492  1852 1849 0.3781666
    #> 18501  1852 1850 0.4736997
    #> 1851   1852 1851 0.1481338

## 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.

Table 8: Description of precip_input data frame columns
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

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

    head(model$precip_input)
    #>       name id frc
    #> 1 Rainfall  2   1
    #> 2 Rainfall 17   1
    #> 3 Rainfall 11   1
    #> 4 Rainfall  7   1
    #> 5 Rainfall  6   1
    #> 6 Rainfall 12   1

## 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.

Table 9: Description of pet_input data frame columns
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

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

    head(model$pet_input)
    #>   name id frc
    #> 1  PET  2   1
    #> 2  PET 17   1
    #> 3  PET 11   1
    #> 4  PET  7   1
    #> 5  PET  6   1
    #> 6  PET 12   1