---
title: "The Model Object"
output:
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
    number_sections: false
    toc: true
    toc_depth: 2
pkgdown:
  as_is: true
vignette: >
  %\VignetteIndexEntry{The Model Object}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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](https://waternumbers.github.io/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"](dynatop.html) 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

```{r, setup}
library(dynatop)
data("Swindale")
model <- Swindale$model
```

The top level of the model contains the following elements:

```{r model_parts}
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](Hillslope_HRU.html)
and
[channel](Channel_HRU.html)
vignettes for further details.

## Hillslope HRU table

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

```{r hillslope_parts}
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:
```{r channel_parts}
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:

```{r gauge}
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:

```{r point_inflow}
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:

```{r diffuse_inflow}
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:

```{r flow_direction}
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:

```{r precip_input}
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:

```{r pet_input}
head(model$pet_input)
```
