% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reservoir_lumped.R
\name{reservoir_lumped}
\alias{reservoir_lumped}
\title{Generation of WASA parameter files for simulation of lumped reservoirs ("small reservoirs")}
\usage{
reservoir_lumped(res_vect = NULL, subbas = NULL,
  res_vect_classified = NULL, dir_out = "./",
  reservoirs_small_classes_file = "reservoirs_small_classes.dat",
  r_subbas_contains_reservoirs_small_file = "r_subbas_contains_reservoirs_small.dat",
  res_param = data.frame(class = 1:5, f_vol_init = 0.2, class_change = 0,
  alpha_Molle = 2.7, damk_Molle = 1500, damc_hrr = c(7, 14, 21, 28, 35),
  damd_hrr = 1.5), keep_temp = F, overwrite = F, silent = F)
}
\arguments{
\item{res_vect}{Name of reservoir vector map in GRASS location. Can be point
or polygon feature (e.g. reservoir centroids).
If it has the columns 'volume' with information on volume in [m^3] or column 'area'
with information on lake area in [m^2], these will be used for computation. 
If none is encountered, 'area' can be generated from the area of the polygons, if present.}

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

\item{res_vect_classified}{Output: Name for the vector reservoir map to be created in GRASS
location. This is a point map based on \code{res_vect} with information of area or volume (whichever is missing),
ID of the subbasin in which the reservoir is located, and the classified size class
appended to the attribute table. If \code{NULL} (default) it will not be created.}

\item{dir_out}{Character string specifying output directory (will be created if
not available and files will be overwritten if \code{overwrite = TRUE}.}

\item{reservoirs_small_classes_file}{Parameters for the reservoir size classes.
See \code{\link{db_fill}}.}

\item{r_subbas_contains_reservoirs_small_file}{Distribution of small reservoirs in subbasins.
See \code{\link{db_fill}}.}

\item{res_param}{A \code{data.frame} object containing parameters for the reservoir
size classes. The default parameter set is adjusted to semi-arid Brazil.
See \code{Details}.}

\item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept
in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.}

\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}.}
}
\value{
The two output files specified in \code{reservoirs_small_classes_file} and \code{r_subbas_contains_reservoirs_small_file}; and
     the vector map \code{res_vect_class} in GRASS
}
\description{
Function generates the WASA parameter files lake.dat and lake_number.dat from
a pre-processed reservoir vector and a subbasin raster file stored in a GRASS
location.
}
\details{
This function creates WASA input files which are needed to run the model
     with option \code{doacudes=.T.} (simulate small unlocated reservoirs).
     
     The default values for \code{res_param} set were estimated by Molle (1989) for the 
     \bold{semi-arid NE of Brazil} and need to be adjusted if applied to some other region!
     
     \bold{lake_file} / \bold{res_param}\cr
     Specification of parameters for the reservoir size classes. Note that \code{lake_file} and \code{res_param} have the same order, but different header names! If information
     on 'maxlake0' / 'vol_max' is not available, you can specify 'area_max' in \code{res_param},
     i.e. the maximum area of reservoir size classes in \emph{m^2}. This is internally converted to volume
     by relationship of Molle (1989) using parameters 'alpha_Molle' and 'damk_Molle'.
     If neither is given (default), the values will be estimated from the 20 % and 100 %
     percentiles of the value distribution of area or volume in \code{res_vect} by interpolation
     between both values using a logarithmic relationship.
     
     \emph{Reservoir_class-ID / class}\cr
     ID of reservoir size class.
     
     \emph{maxlake0 / vol_max}\cr
     Upper limit of reservoir size class in terms of volume in \emph{m^3}.
     
     \emph{lake_vol0_factor / f_vol_init}\cr
     Fraction of storage capacity that indicates the initial water volume in the
     reservoir size classes (\emph{dimensionless}).
     
     \emph{lake_change / class_change}\cr
     Factor that indicates yearly variation in the number of reservoirs of the size
     classes (\emph{dimensionless}).
     
     \emph{alpha_Molle, damk_Molle}\cr
     Parameters of the area-volume relationship in the reservoir size classes:
     Area = alpha_Molle * damk_Molle * (Volume / damk_Molle)^( (alpha_Molle - 1) / alpha_Molle).
     Unit of Area: \emph{m^2}, unit of Volume: \emph{m^3}.
     
     \emph{damc_hrr, damd_hrr}\cr
     Parameters of the spillway rating curve in the reservoir size classes:
     Overflow = damc_hrr * Height^(damd_hrr). 
     Unit of Overflow: \emph{m^3/s}, unit of Height (over spillway): \emph{m}.
}
\note{
Prepare GRASS location and necessary spatial objects in advance and start
     GRASS session in R using \code{\link[rgrass7]{initGRASS}}.
     
     Use \code{\link{reservoir_strategic}} to prepare the input for large / strategic reservoirs. 
     
     Points in \code{res_vect} not overlapping with any \code{subbas} will be
     silently removed during processing!
     
     Polygons overlapping over various subbasins will be classified to the subbasin
     containing the polygon's centroid. If that occurs frequently, you should
     consider running \code{\link[lumpR]{reservoir_outlet}} in advance where
     reservoir outlet locations are estimated instead of using the centroid.
}
\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.
     
     Reservoir parameter set herein given as standard values:\cr
     Molle, F. (1989): Evaporation and infiltration losses in small reservoirs.
     \emph{Serie Hydrologia}, 25, SUDENE / ORSTOM, Recife, Brazil, in Portuguese.
}
\author{
Tobias Pilz \email{tpilz@uni-potsdam.de}, Till Francke \email{francke@uni-potsdam.de}
}
