% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reservoir_strategic.R
\name{reservoir_strategic}
\alias{reservoir_strategic}
\title{Assemble of reservoir parameter file for WASA for import into database with \code{\link[lumpR]{db_fill}()}}
\usage{
reservoir_strategic(res_vect = NULL, subbasin = NULL,
  res_file = NULL, dir_out = "./", reservoir_file = "reservoir.txt",
  overwrite = F, silent = F)
}
\arguments{
\item{res_vect}{Name of reservoir vector map in GRASS location. Should be point
instead of polygon feature (i.e. reservoir outlet locations; consider function
\code{\link[lumpR]{reservoir_outlet}})! For mandatory columns in attribute table
see Details. In any case, column \code{subbas_id} containing the subbasin
ID derived from \code{subbasin} will be added to the attribute table.}

\item{subbasin}{Subbasin raster map in GRASS location. Can be created with
\code{\link[lumpR]{calc_subbas}}.}

\item{res_file}{tab-delimited file containing reservoir properties (fields see details) and key \code{res_id}. 
If set to NULL, these attributes must be contained in the attribute table of \code{res_vect}. If they are missing,
they will be set to deafult values (see Details).}

\item{dir_out}{Character string specifying output directory (will be created if it
does not yet exist). The result file can later be imported to the database with \code{\link[lumpR]{db_fill}()}}

\item{reservoir_file}{Output: File of parameters for the strategic reservoirs
assigned to subbasins. To be filled into a database using \code{\link[lumpR]{db_fill}()}.
This file is \bold{NOT} directly compatible with WASA-SED!}

\item{overwrite}{\code{logical}. Shall output of previous calls of this function be
deleted? If \code{FALSE} the function returns an error if output already exists.
Default: \code{FALSE}.}

\item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings
of internally used GRASS functions)? Default: \code{FALSE}.}
}
\description{
Function generates the reservoir parameter file from a pre-processed
reservoir vector map and optional supplemental parameter file.
}
\details{
For each reservoir that should be modelled explicitly within WASA the
     following information need to be collected and written into the vector file's
     attribute table or \code{res_file}. Column order is not important. Additional
     columns can be given but will be ignored:
     
     \emph{res_id}\cr
     Unique numeric reservoir identifier (if \code{res_file} is given, it also needs to be
     defined in the vector file's attribute table!).
     
     \emph{name}\cr
     OPTIONAL: name of the reservoir. Will be filled with \code{<NA>} if not given.

     \emph{minlevel}\cr
     Initial minimum level in the reservoir [m]. Value varies because of sediment
     accumulation. Default: 0.
     
     \emph{maxlevel}\cr
     Maximum water level in the reservoir [m]. Default: Estimated using Molle's equation (alpha = 2.7, k = 1500).
     
     \emph{vol0}\cr
     Initial volume of the reservoir [10^3 m^3]. Value varies because of sediment
     accumulation. Set to '-999' if information is not available. Default: Estimated using Molle's equation (alpha = 2.7, k = 1500).
     
     \emph{storecap}\cr
     Initial storage capacity of the reservoir [10^3 m^3]. Value varies because of
     sediment accumulation. DEfault: \code{vol0}
     
     \emph{damflow}\cr
     Target outflow discharge of the reservoir (90 \% reliability) [m^3/s]. Default: 9.99
     
     \emph{damq_frac}\cr
     Fraction of Q90 released from the reservoir in regular years [-]. Default: 1 
     
     \emph{withdrawal}\cr
     Water withdrawal discharge from the reservoir to supply the water use sectors 
     [m^3/s]. Outflow discharge through the dam is not considered. Default: 0
     
     \emph{damyear}\cr
     Year of construction of the dam (YYYY). Default: 1900
     
     \emph{maxdamarea}\cr
     Initial maximum area of the reservoir [ha]. Value varies because of sediment
     accumulation. Default from GIS
     
     \emph{damdead}\cr
     Initial dead volume of the reservoir [10^3 m^3]. Value varies because of
     sediment accumulation. Default: 0.01 * storecap
     
     \emph{damalert}\cr
     Initial alert volume of the reservoir [10^3 m^3]. Value varies because of
     sediment accumulation. Default: 0.01 * storecap
     
     \emph{dama, damb}\cr
     Parameters of the area-volume relationship in the reservoir:
     area = dama * Vol^damb [-]. Values of reservoir area and volume are
     expressed in m^2 and m^3, respectively. Attention: These are not the Molle parameters! The correct values can be derived from them as shown in the default.
     Default: dama = (1/k * (alpha * k)^(alpha/(alpha-1)))^((alpha-1)/alpha), 
     damb = (alpha-1)/alpha
     
     \emph{q_outlet}\cr
     Maximum outflow discharge released through the bottom outlets of the
     reservoir [m^3/s]. Default: 0.999
     
     \emph{fvol_botm}\cr
     Fraction of storage capacity that indicates the minimum storage volume for
     sediment release through the bottom outlets of the reservoir [-]. Default: 0.01
     
     \emph{fvol_over}\cr
     Fraction of storage capacity that indicates the minimum storage volume for
     water release through the spillway of the reservoir [-]. Default: 1
     
     \emph{damc, damd}\cr
     Parameters of the spillway rating curve of the reservoir: Qout = damc * Hv^damd
     [-]. Values of water height over the spillway and overflow discharges are
     expressed in m and m^3/s, respectively. 
     Default: 1.6 * 30, 1.5
     
     \emph{elevbottom}\cr
     Bottom outlet elevation of the reservoir [m]. Currently ignored in WASA. Default: 99
     
     The output file \code{reservoir_file} contains the additional column \emph{pid}
     which is the corresponding subbasin ID determined from input \code{subbasin}.
}
\note{
If you applied \code{\link[lumpR]{reservoir_outlet}} using the outlet locations
     of strategic reservoirs as drainage points, it might be necessary to use
     locations of the function's output \code{points_processed} instead of the
     true reservoir outlet locations as otherwise the reservoirs might get assigned to
     the wrong subbasins!
}
\references{
lumpR package introduction with literature study and sensitivity analysis:\cr
     Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating
     landscape discretisation for hillslope-based hydrological models.
     \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017

     WASA model in general:\cr
     Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 
     North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate
     Impact Research, Potsdam, Germany.
     
     Reservoir module of the WASA model:\cr
     Mamede, G. L. (2008):  Reservoir sedimentation in dryland catchments: Modeling
     and management. PhD Thesis, University of Potsdam, Germany.
}
\author{
Tobias Pilz \email{tpilz@uni-potsdam.de}
}
