================
Catchment Models
================

Catchment models describe how the inputted water leaves the subcatchment.
Currently only one is implemented:

* Comola

Comola Catchment Model
======================
SWIFlow is a two layer streamflow model. There is an upper storage and a lower
storage that interact. The model uses three state variables to model streamflow.
The are storage of a layer, infiltration rate into the layer, and the flowrate
from the layer.

This model was introduced by `Comola et. al 2015`_ and implemented the same in swiflow
as it was originally described.

.. _Comola et. al 2015: https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2014WR016228


Equations
---------

Below are the definitions used in the model equations:

* Q - Flowrate in :math:`\frac{m^3}{s}`
* S - Storage in units of meters of water height over subbasin area.
* I - Infiltration rate in units of :math:`\frac{m}{s}`
* :math:`\bar{\tau}` - Residence time, (calibrated term) in units of seconds
* :math:`R_{max}` - Maximum infiltration rate to the lower layer (calibrated)
* A - Surface area of either the subbasin or the total watershed in :math:`m^2`.

The model is described by the following equations:

.. math::

    I_{res_L} = min(I_{swi}, R_{max})

    I_{res_U} = I_{swi} - I_{res_L}


For change in storage in the upper and lower layer:

.. math::

    \frac{d S_{res_{L,U}}}{dt} = I_{res_{L,U}} - \frac{Q}{A_{subbasin}}



The Residence time for each layer for each subbasin is:

.. math::

    \tau = \left(\frac{A_{subbasin}}{A_{total}}\right) ^ {\frac{1}{3}} \bar{\tau}


The flowrate out of a layer is defined by:

.. math::

    Q_{res_{L,U}} = A_{subbasin} \frac{S_{res_{L,U}}}{\tau_{res_{L,U}}}

    Q_{subbasin} = Q_{res_U} + Q_{res_L}


Discretization
--------------

Spatially the model is split up by subwatersheds or sometimes called HRUs prior
to running SWIFlow. This can be performed by
basin_setup_ . Temporally, the change in storage equation is split up
explicitly which is implemented as follows:

.. math::

    S_{res_{t+1}} = \left(I_{res_t} - \frac{Q_t}{A_{subbasin}}\right) \Delta t + S_{res_t}




.. _basin_setup: https://github.com/USDA-ARS-NWRC/basin_setup

Algorithm
---------
At the beginning of the run, SWIFlow the initial conditions for
:math:`Q_{res_{L,U}}` and :math:`S_{res_{L,U}}`, S are all zero. SWIFlow computes
the state variables in the following order for each timestep.

1. Calculate lower **then** upper infiltration rates (:math:`I_{res_{L,U}}`)
2. Calculate upper and lower flowrates (:math:`Q_{res_{L,U}}`)
3. Calculate future storage using discretized change in storage equation (:math:`S_{res_{t+1}}`)