From 3ddf1e34c95dff29d4bf01693aac0e37db953bf5 Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@inrae.fr>
Date: Wed, 31 Mar 2021 14:37:43 +0200
Subject: [PATCH] refactor: add NAMESPACE and documentation in the repository
---
.gitignore | 3 -
NAMESPACE | 24 ++++++++
README.md | 28 ++-------
man/get_objectives.Rd | 40 +++++++++++++
man/get_vobj_ts.Rd | 43 ++++++++++++++
man/plot_isofrequency.Rd | 21 +++++++
man/plot_isofrequency_lake.Rd | 23 ++++++++
man/vgest_cost.Rd | 52 +++++++++++++++++
man/vgest_cost_lakes.Rd | 19 +++++++
man/vgest_read.Rd | 24 ++++++++
man/vgest_read_all.Rd | 24 ++++++++
man/vgest_read_chrono.Rd | 77 +++++++++++++++++++++++++
man/vgest_read_one.Rd | 26 +++++++++
man/vgest_read_qnat.Rd | 21 +++++++
man/vgest_run.Rd | 26 +++++++++
man/vgest_run_store.Rd | 102 +++++++++++++++++++++++++++++++++
man/vgest_write_batch.Rd | 104 ++++++++++++++++++++++++++++++++++
17 files changed, 631 insertions(+), 26 deletions(-)
create mode 100644 NAMESPACE
create mode 100644 man/get_objectives.Rd
create mode 100644 man/get_vobj_ts.Rd
create mode 100644 man/plot_isofrequency.Rd
create mode 100644 man/plot_isofrequency_lake.Rd
create mode 100644 man/vgest_cost.Rd
create mode 100644 man/vgest_cost_lakes.Rd
create mode 100644 man/vgest_read.Rd
create mode 100644 man/vgest_read_all.Rd
create mode 100644 man/vgest_read_chrono.Rd
create mode 100644 man/vgest_read_one.Rd
create mode 100644 man/vgest_read_qnat.Rd
create mode 100644 man/vgest_run.Rd
create mode 100644 man/vgest_run_store.Rd
create mode 100644 man/vgest_write_batch.Rd
diff --git a/.gitignore b/.gitignore
index 65db2f0..b9fab0b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,10 +2,7 @@
# Project-specific
-# Man pages generated by Roxygen
-man/*.Rd
/.vscode/
-/NAMESPACE
/database
/output
diff --git a/NAMESPACE b/NAMESPACE
new file mode 100644
index 0000000..2936386
--- /dev/null
+++ b/NAMESPACE
@@ -0,0 +1,24 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(get_vobj_ts,ListVobj)
+S3method(get_vobj_ts,Vobj)
+S3method(vgest_cost,Chrono)
+S3method(vgest_cost,ListChrono)
+S3method(vgest_cost,ListVobj)
+S3method(vgest_read_chrono,Objectives)
+S3method(vgest_read_chrono,default)
+S3method(vgest_run_store,Objectives)
+S3method(vgest_run_store,character)
+export(get_objectives)
+export(get_vobj_ts)
+export(plot_isofrequency)
+export(plot_isofrequency_lake)
+export(vgest_cost)
+export(vgest_read)
+export(vgest_read_all)
+export(vgest_read_chrono)
+export(vgest_read_one)
+export(vgest_read_qnat)
+export(vgest_run)
+export(vgest_run_store)
+export(vgest_write_batch)
diff --git a/README.md b/README.md
index 6c82cdd..8e35b95 100644
--- a/README.md
+++ b/README.md
@@ -10,31 +10,13 @@ The third party program 'VGEST' is required to perform the optimisations. Clone
Finally, copy a naturalised flow database in the `vgest/DONNEES` folder.
-### Local installation steps
+### Installation
-Installation of the package from source should be done in 3 steps:
+From INRAE Gitlab repository:
-- download sources
-- run `roxygen` for generating `NAMESPACE` file and documentation from sources
-- install the package
-
-### Download sources
-
-First possibility, clone the repository with git (recommended):
-
-If you have configured a SSH key for gitlab (See: https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html): `git clone git@gitlab-ssh.irstea.fr:in-wop/rvgest.git`
-
-Otherwise, use HTTPS: `git clone https://gitlab.irstea.fr/in-wop/rvgest.git`
-
-Second possibility, download the source code at https://gitlab.irstea.fr/in-wop/rvgest/-/archive/master/rvgest-master.zip
-
-### Build and install the package
-
-Open the project file `rvgest.Rproj` in RStudio and type:
-
-```
-roxygen2::roxygenise()
-remotes::install_local()
+```r
+install.packages("remotes")
+remotes::install_gitlab("in-wop/rvgest@master", host = "gitlab.irstea.fr")
```
## Usage
diff --git a/man/get_objectives.Rd b/man/get_objectives.Rd
new file mode 100644
index 0000000..a3b705b
--- /dev/null
+++ b/man/get_objectives.Rd
@@ -0,0 +1,40 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_objectives.R
+\name{get_objectives}
+\alias{get_objectives}
+\title{Load objective data for \code{\link{vgest_run}}}
+\usage{
+get_objectives(
+ objective_thresholds = app_sys("seine", "objective_thresholds.txt"),
+ objective_stations = app_sys("seine", "objective_stations.json"),
+ lakes = app_sys("seine", "lakes.txt")
+)
+}
+\arguments{
+\item{objective_thresholds}{File location of threshold table}
+
+\item{objective_stations}{File location of objective station table}
+
+\item{lakes}{File location of lake table}
+}
+\value{
+A dataframe containing one line by objective and the following columns:
+\itemize{
+\item station (character): identifier of the objective station
+\item flood (boolean): TRUE for high flow mitigation objective, and FALSE for low flow support
+\item level (character): code composed with "l" for low-flow and "h" for high flow followed by the number of the level
+\item threshold (numeric): value of the threshold in m3/s
+\item lakes (dataframe): Dataframe containing lake details (name, min storage, max storage)
+}
+}
+\description{
+Load objective data for \code{\link{vgest_run}}
+}
+\examples{
+# Get objectives stored in IRMaRA package
+df <- get_objectives()
+# Objectives at Paris
+df[df[,"station"] == "PARIS_05",]
+# Lake details concerning the 40th objective in the table
+df[57, "lakes"]
+}
diff --git a/man/get_vobj_ts.Rd b/man/get_vobj_ts.Rd
new file mode 100644
index 0000000..0531eae
--- /dev/null
+++ b/man/get_vobj_ts.Rd
@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_vobj_ts.R
+\name{get_vobj_ts}
+\alias{get_vobj_ts}
+\alias{get_vobj_ts.Vobj}
+\alias{get_vobj_ts.ListVobj}
+\title{Method to transform VOBJ data into time series}
+\usage{
+get_vobj_ts(x)
+
+\method{get_vobj_ts}{Vobj}(x)
+
+\method{get_vobj_ts}{ListVobj}(x)
+}
+\arguments{
+\item{x}{list of VOBJ provided by \link{vgest_read_all}}
+}
+\value{
+
+
+A dataframe with one column \code{date} and one column \code{storage} containing the time series of the lake storage in m3.
+
+Dataframe with the time series with a column \code{date} and one column by lake with the storage of the lake in m3.
+}
+\description{
+Transform VOBJ data read by \link{vgest_read}, \link{vgest_read_one} or \link{vgest_read_all}.
+
+Use for binding results of several lakes for one objective at one station.
+}
+\examples{
+\dontrun{
+dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database"))
+}
+\dontrun{
+# Get the first lake of the first objective
+dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database")[[1]])
+# Can also be done by
+dfTs <- get_vobj_ts(vgest_read_one(1, get_objectives()[1,], "./database"))
+}
+\dontrun{
+dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database"))
+}
+}
diff --git a/man/plot_isofrequency.Rd b/man/plot_isofrequency.Rd
new file mode 100644
index 0000000..89b8e84
--- /dev/null
+++ b/man/plot_isofrequency.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/plot_isofrequency.R
+\name{plot_isofrequency}
+\alias{plot_isofrequency}
+\title{Plot one lake isofrequency annual curves for one objective at one station}
+\usage{
+plot_isofrequency(x, freq, result.dir = "database")
+}
+\arguments{
+\item{x}{\link{list} containing one \link{data.frame} per lake}
+
+\item{freq}{\link{numeric} vector of frequencies to plot}
+
+\item{result.dir}{\link{character} The path to the result database (default: "database")}
+}
+\value{
+\link{NULL}
+}
+\description{
+Plot one lake isofrequency annual curves for one objective at one station
+}
diff --git a/man/plot_isofrequency_lake.Rd b/man/plot_isofrequency_lake.Rd
new file mode 100644
index 0000000..be63a95
--- /dev/null
+++ b/man/plot_isofrequency_lake.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/plot_isofrequency.R
+\name{plot_isofrequency_lake}
+\alias{plot_isofrequency_lake}
+\title{Plot one lake isofrequency annual curves for one objective at one station}
+\usage{
+plot_isofrequency_lake(vObj, frequencies, lake, top.margin)
+}
+\arguments{
+\item{vObj}{dataframe produced by \code{\link[=vgest_read_one]{vgest_read_one()}} and stored in a list by \code{\link[=vgest_read_all]{vgest_read_all()}}}
+
+\item{frequencies}{vector of frequencies to plot}
+
+\item{lake}{lake data extract from column \code{lakes} of objective data given by \code{\link[=get_objectives]{get_objectives()}}}
+
+\item{top.margin}{top margin applied on the plot for the title}
+}
+\value{
+\link{NULL}
+}
+\description{
+This function is mainly called by \code{\link[=plot_isofrequency]{plot_isofrequency()}}.
+}
diff --git a/man/vgest_cost.Rd b/man/vgest_cost.Rd
new file mode 100644
index 0000000..00f2b7d
--- /dev/null
+++ b/man/vgest_cost.Rd
@@ -0,0 +1,52 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_cost.R
+\name{vgest_cost}
+\alias{vgest_cost}
+\alias{vgest_cost.ListVobj}
+\alias{vgest_cost.Chrono}
+\alias{vgest_cost.ListChrono}
+\title{Calculate the cost function for one simulation (One objective at one station)}
+\usage{
+vgest_cost(data, objective)
+
+\method{vgest_cost}{ListVobj}(data, objective)
+
+\method{vgest_cost}{Chrono}(data, objective)
+
+\method{vgest_cost}{ListChrono}(data, objective)
+}
+\arguments{
+\item{data}{the \link{list} given by \code{\link[=vgest_read_chrono]{vgest_read_chrono()}}}
+
+\item{objective}{\link{data.frame} given by \code{\link[=get_objectives]{get_objectives()}}}
+}
+\value{
+the total cost for one objective at one station in m3/day
+
+the total cost for one objective at one station in m3/day
+
+A list with items named [station]\emph{[high/low]}[threshold] containing the total cost for a list of objectives and stations in m3/day
+}
+\description{
+Uses ouput of PaChrono.txt or VObj[1-4].dat for the calculation.
+}
+\examples{
+\dontrun{
+# This should be done after the execution of vgest for the concerned objective
+objective <- get_objectives()[1,]
+lResultVobj <- vgest_read_all(objective)
+vgest_cost(lResultVobj, objective)
+}
+\dontrun{
+# This should be done after the execution of vgest for the concerned objective
+objective <- get_objectives()[1,]
+lChrono <- vgest_read_chrono(objective)
+vgest_cost(lChrono[[1]], objective)
+}
+\dontrun{
+# This should be done after the execution of vgest for the concerned objective
+objective <- get_objectives()[1,]
+lChronos <- vgest_read_chrono(objective, distributionType = 2)
+vgest_cost(lChronos, objective)
+}
+}
diff --git a/man/vgest_cost_lakes.Rd b/man/vgest_cost_lakes.Rd
new file mode 100644
index 0000000..a1f97c8
--- /dev/null
+++ b/man/vgest_cost_lakes.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_cost.R
+\name{vgest_cost_lakes}
+\alias{vgest_cost_lakes}
+\title{Calculate the total cost for all the lakes}
+\usage{
+vgest_cost_lakes(Vobj, objective)
+}
+\arguments{
+\item{Vobj}{A \link{matrix} or a \link{data.frame} with one column by lake, in the same order as \code{objective$lakes}}
+
+\item{objective}{one row of the dataframe given by \code{\link[=get_objectives]{get_objectives()}}}
+}
+\value{
+total cost of all the lakes in m3/day
+}
+\description{
+For each lake, it's the mean daily storage for a low-flow support objective and the mean daily available storage capacity for a high flow mitigation objective.
+}
diff --git a/man/vgest_read.Rd b/man/vgest_read.Rd
new file mode 100644
index 0000000..d6dd019
--- /dev/null
+++ b/man/vgest_read.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_read.R
+\name{vgest_read}
+\alias{vgest_read}
+\title{Read result file \code{VOBJi.DAT} for one lake of one objective at one station}
+\usage{
+vgest_read(file, bFlood)
+}
+\arguments{
+\item{file}{complete path to the \code{VOBJi.DAT} file}
+
+\item{bFlood}{boolean \code{TRUE} for high flow mitigation objective, \code{FALSE} for low flow support}
+}
+\value{
+dataframe with the content of the \code{VOBJi.DAT} file
+}
+\description{
+This function is called by \code{\link[=vgest_read_one]{vgest_read_one()}}, please run this one instead.
+}
+\examples{
+\dontrun{
+df <- vgest_read("database/PARIS_05/high_800/VOBJ1.dat")
+}
+}
diff --git a/man/vgest_read_all.Rd b/man/vgest_read_all.Rd
new file mode 100644
index 0000000..367cd4e
--- /dev/null
+++ b/man/vgest_read_all.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_read.R
+\name{vgest_read_all}
+\alias{vgest_read_all}
+\title{Read all result files \code{VOBJi.DAT} for all the lakes of one objective at one station}
+\usage{
+vgest_read_all(x, result.dir = "database")
+}
+\arguments{
+\item{x}{one line of the dataframe produced by \code{\link[=get_objectives]{get_objectives()}}}
+
+\item{result.dir}{path where results of VGEST runs are stored (See \code{\link[=vgest_run_store]{vgest_run_store()}})}
+}
+\value{
+list with dataframes produced by
+}
+\description{
+Read all result files \code{VOBJi.DAT} for all the lakes of one objective at one station
+}
+\examples{
+\dontrun{
+vgest_read_all(get_objectives()[1,], "./database")
+}
+}
diff --git a/man/vgest_read_chrono.Rd b/man/vgest_read_chrono.Rd
new file mode 100644
index 0000000..4e681c5
--- /dev/null
+++ b/man/vgest_read_chrono.Rd
@@ -0,0 +1,77 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_read_chrono.R
+\name{vgest_read_chrono}
+\alias{vgest_read_chrono}
+\alias{vgest_read_chrono.default}
+\alias{vgest_read_chrono.Objectives}
+\title{Read Chrono.txt or PaChrono.txt}
+\usage{
+vgest_read_chrono(x, ...)
+
+\method{vgest_read_chrono}{default}(x, nLakes, distributionType, ...)
+
+\method{vgest_read_chrono}{Objectives}(
+ x,
+ distributionType,
+ result.dir = "database",
+ backward = TRUE,
+ ...
+)
+}
+\arguments{
+\item{x}{file to read with txt extension}
+
+\item{...}{further arguments passed to or from other methods}
+
+\item{nLakes}{number of lakes in the file}
+
+\item{distributionType}{Distribution type. See \link{vgest_write_batch} details}
+
+\item{result.dir}{path for storing the result of vgest run. The result is stored in a subfolder named high or low (depending on \code{bFlood}) followed by the threshold}
+
+\item{backward}{boolean \code{TRUE} for reading "PaChrono.txt", \code{FALSE} for reading "Chrono.txt"}
+}
+\value{
+
+
+\link{data.frame} with the content of the file
+
+A list with items named [station]\emph{[high/low]}[threshold] containing \link{data.frame} with the content of each file
+}
+\description{
+Read the time series provided by VGEST for the forward calculation (Chrono.txt) and backward calculation (PaChrono.txt)
+}
+\details{
+The format of the file is has follow. Headers are in line 53 followed by the complete time series which is backward in time for PaChrono.txt. The columns and respected widths are:
+\itemize{
+\item Downstream date (10)
+\item QXsous (22)
+}
+
+For each lake, we next have:
+\itemize{
+\item Upstream date (14)
+\item 25 columns of flow and storage data (22)
+\item if \code{DistributionType \%in\% c(4,5)}, 1 extra column (22)
+\item 5 columns of codes (6)
+}
+
+And then at the end:
+\itemize{
+\item 7 columns of flow (22)
+\item 3 columns of codes (8)
+\item 1 extra column of code for \code{DistributionType==5} (8)
+}
+
+The file is saved in RDS format for quicker reading the next time.
+}
+\examples{
+\dontrun{
+objective <- get_objectives()[1,]
+distributionType <- 2
+vgest_run_store(objective,
+ 1, 1, "Q_NAT_1900-2009.txt",
+ "01/01/1900", "31/12/2009", distributionType)
+lChrono <- vgest_read_chrono(objective, distributionType)
+}
+}
diff --git a/man/vgest_read_one.Rd b/man/vgest_read_one.Rd
new file mode 100644
index 0000000..79aff6f
--- /dev/null
+++ b/man/vgest_read_one.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_read.R
+\name{vgest_read_one}
+\alias{vgest_read_one}
+\title{Read result file \code{VOBJi.DAT} for one lake of one objective at one station}
+\usage{
+vgest_read_one(iLake, x, result.dir)
+}
+\arguments{
+\item{iLake}{Lake number for the current station}
+
+\item{x}{one line of the dataframe produced by \code{\link[=get_objectives]{get_objectives()}}}
+
+\item{result.dir}{path where results of VGEST runs are stored (See \code{\link[=vgest_run_store]{vgest_run_store()}})}
+}
+\value{
+dataframe with the content of the \code{VOBJi.DAT} file
+}
+\description{
+This function is preferred to \code{\link[=vgest_read]{vgest_read()}} because it builds the path for the file to read.
+}
+\examples{
+\dontrun{
+vgest_read_one(1, get_objectives()[1,], "./database")
+}
+}
diff --git a/man/vgest_read_qnat.Rd b/man/vgest_read_qnat.Rd
new file mode 100644
index 0000000..0f14570
--- /dev/null
+++ b/man/vgest_read_qnat.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_read_qnat.R
+\name{vgest_read_qnat}
+\alias{vgest_read_qnat}
+\title{Read daily flow time series used by VGEST}
+\usage{
+vgest_read_qnat(file)
+}
+\arguments{
+\item{file}{Path to the file to read}
+}
+\value{
+a \link{data.frame} with the content of the file
+}
+\description{
+Read daily flow time series used by VGEST
+}
+\details{
+The file should be an ASCII file with tab separators, the first column contains the date in format \code{YYYYMMDD}.
+The returned \link{data.frame} has the class attributes "Qnat" for further use with S3 methods.
+}
diff --git a/man/vgest_run.Rd b/man/vgest_run.Rd
new file mode 100644
index 0000000..c892e56
--- /dev/null
+++ b/man/vgest_run.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_run.R
+\name{vgest_run}
+\alias{vgest_run}
+\title{Run VGEST and stop execution if an error is encountered during execution}
+\usage{
+vgest_run(vgest_location = "../vgest")
+}
+\arguments{
+\item{vgest_location}{Location of VGEST installation (Default "../vgest")}
+}
+\value{
+Nil
+}
+\description{
+Run VGEST and stop execution if an error is encountered during execution
+}
+\details{
+Delete the content of the \code{RESULTAT} folder before running
+}
+\examples{
+\dontrun{
+# Run vgest with the current configuration
+vgest_run()
+}
+}
diff --git a/man/vgest_run_store.Rd b/man/vgest_run_store.Rd
new file mode 100644
index 0000000..8642fe4
--- /dev/null
+++ b/man/vgest_run_store.Rd
@@ -0,0 +1,102 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_run_store.R
+\name{vgest_run_store}
+\alias{vgest_run_store}
+\alias{vgest_run_store.character}
+\alias{vgest_run_store.Objectives}
+\title{Prepare, run and store results of one or several VGEST instances}
+\usage{
+vgest_run_store(x, ...)
+
+\method{vgest_run_store}{character}(
+ x,
+ reservoirRuleSet,
+ networkSet,
+ Qfile,
+ startDate,
+ endDate,
+ bFlood,
+ threshold,
+ distributionType,
+ distributionOption = NULL,
+ vgest_location = "../vgest",
+ objective_file = "BATCH",
+ formatResult = 1,
+ result.dir = "database",
+ ...
+)
+
+\method{vgest_run_store}{Objectives}(
+ x,
+ reservoirRuleSet,
+ networkSet,
+ Qfile,
+ startDate,
+ endDate,
+ ...
+)
+}
+\arguments{
+\item{x}{row(s) of a \link{data.frame} provided by \code{\link[=get_objectives]{get_objectives()}}}
+
+\item{...}{other parameter passed to the method \link{vgest_run_store.character}}
+
+\item{reservoirRuleSet}{rank of the set of parameters describing the reservoirs and their management rules (constraints and local instructions)}
+
+\item{networkSet}{rank of the set of parameters describing the network}
+
+\item{Qfile}{name of the flow data file (hydrological regime without reservoirs)}
+
+\item{startDate}{start of calculation period in "dd/mm/yyyy" format}
+
+\item{endDate}{end of calculation period in "dd/mm/yyyy" format}
+
+\item{bFlood}{boolean describing the objective type: \code{FALSE} for low flow support, \code{TRUE} for high flow lamination}
+
+\item{threshold}{value of the threshold in m3/s}
+
+\item{distributionType}{see in details the description of line 10 of CHOIX.TXT}
+
+\item{distributionOption}{for \code{distributionType=1}, this should contains the relative change in comparison with a repartition based on storage capacity of fixed repartition between reservoirs. If \code{distributionType=4} or \code{5}, see in details the description of line 11 of CHOIX.TXT (default \code{NULL})}
+
+\item{vgest_location}{location of the vgest software (default "../vgest")}
+
+\item{objective_file}{name of the file used for storing the threshold hydrograph}
+
+\item{formatResult}{code for output format of volume results: 1 for absolute values in m3 , 2 for relative values with respect to Vtot or sum(Vtot)}
+
+\item{result.dir}{path for storing the result of vgest run. The result is stored in a subfolder named high or low (depending on \code{bFlood}) followed by the threshold}
+}
+\value{
+\link{NULL}
+}
+\description{
+Prepare, run and store results of one or several VGEST instances
+}
+\examples{
+\dontrun{
+# Example with `vgest_run_store.Objectives`
+# Running vgest for:
+# - the first objective returned by `get_objectives()`
+# - the first configuration of reservoir rules
+# - the first configuration of network
+# - the naturalized hydrological flows of the file located in DONNEES/Q_NAT_1900-2009.txt
+# - doing the optimization on the period between 01/01/1900 and 31/12/2009
+# - a task distribution function of present volumes and maximum usable volume replenishment times from the start of time steps
+vgest_run_store(get_objectives()[1,],
+ 1, 1, "Q_NAT_1900-2009.txt",
+ "01/01/1900", "31/12/2009", 2)
+
+# Example with `vgest_run_store.character`
+# Running vgest for:
+# - the first configuration of reservoir rules
+# - the first configuration of network
+# - the naturalised hydrological flows of the file located in DONNEES/Q_NAT_1900-2009.txt
+# - doing the optimisation on the period between 01/01/1900 and 31/12/2009
+# - an objective located at "PARIS_05"
+# - for a flood threshold of 800 m3/s
+# - a fixed task distribution between reservoirs with a relative change of -20\%, -10\%, +50\%, -30\%
+vgest_run_store("PARIS_05", 1, 1, "Q_NAT_1900-2009.txt", "01/01/1900", "31/12/2009",
+ TRUE, 800, 1, c(-0.2, -0.1, 0.5, -0.3))
+}
+}
diff --git a/man/vgest_write_batch.Rd b/man/vgest_write_batch.Rd
new file mode 100644
index 0000000..a7b1117
--- /dev/null
+++ b/man/vgest_write_batch.Rd
@@ -0,0 +1,104 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/vgest_write_batch.R
+\name{vgest_write_batch}
+\alias{vgest_write_batch}
+\title{Write configuration files for running VGEST}
+\usage{
+vgest_write_batch(
+ reservoirRuleSet,
+ networkSet,
+ Qfile,
+ startDate,
+ endDate,
+ station,
+ bFlood,
+ threshold,
+ distributionType,
+ distributionOption = NULL,
+ vgest_location = "../vgest",
+ objective_file = "BATCH",
+ formatResult = 1,
+ subPrograms = 2
+)
+}
+\arguments{
+\item{reservoirRuleSet}{rank of the set of parameters describing the reservoirs and their management rules (constraints and local instructions)}
+
+\item{networkSet}{rank of the set of parameters describing the network}
+
+\item{Qfile}{name of the flow data file (hydrological regime without reservoirs)}
+
+\item{startDate}{start of calculation period in "dd/mm/yyyy" format}
+
+\item{endDate}{end of calculation period in "dd/mm/yyyy" format}
+
+\item{station}{name of the station where the flow target is located}
+
+\item{bFlood}{boolean describing the objective type: \code{FALSE} for low flow support, \code{TRUE} for high flow lamination}
+
+\item{threshold}{value of the threshold in m3/s}
+
+\item{distributionType}{see in details the description of line 10 of CHOIX.TXT}
+
+\item{distributionOption}{for \code{distributionType=1}, this should contains the relative change in comparison with a repartition based on storage capacity of fixed repartition between reservoirs. If \code{distributionType=4} or \code{5}, see in details the description of line 11 of CHOIX.TXT (default \code{NULL})}
+
+\item{vgest_location}{location of the vgest software (default "../vgest")}
+
+\item{objective_file}{name of the file used for storing the threshold hydrograph}
+
+\item{formatResult}{code for output format of volume results: 1 for absolute values in m3 , 2 for relative values with respect to Vtot or sum(Vtot)}
+
+\item{subPrograms}{\link{integer} 0 for running all sub programs, 1 for running only backward simulation (default value)}
+}
+\value{
+
+}
+\description{
+Write CHOIX.TXT, objective file and eventually REGLAGES.TXT in PARAMETR folder of VGEST.
+}
+\details{
+The format of the PARAMETR/CHOIX.TXT file is as follow:
+\itemize{
+\item line 1: name of the station where the flow target is located
+\item line 2: rank of the set of parameters describing the reservoirs and their management rules (constraints and local instructions)
+\item line 3: rank of the set of parameters describing the network
+\item line 4: name of the flow data file (hydrological regime without reservoirs)
+\item line 5: name of the file describing the annual objective hydrograph at the bottom station of the system
+\item line 6: objective type: 0 for low flow support, 1 for high flow lamination
+\item line 7: start of calculation period
+\item line 8: end of calculation period
+\item line 9: code indicating which sub programs should be run:
+\itemize{
+\item 0: All sub programs
+\item 1: Only backward simulation
+}
+\item line 10: code for output format of volume results: 1 for absolute values in m3 , 2 for relative values with respect to Vtot or sum(Vtot)
+\item line 11: code indicating how the flow to be stored is distributed between the reservoirs:
+\itemize{
+\item 1=fixed;
+\item 2=function of present volumes and maximum usable volume replenishment times from the start of time steps;
+\item 3=aimed at balancing the filling rates at the end of the time step;
+\item 4=aiming to balance at the end of the time step the times Tpot of reservoir evolution towards extreme state (see line 11) with average inputs;
+\item 5=aiming to balance at the end of the time step the times Tpot of evolution of the reservoir towards extreme state (see line 11) with given quantity of the contributions of each quantity.
+}
+\item line 12 (used only if 4 or 5 on line 11): code indicating the nature of Tpot :
+\itemize{
+\item 1: Tpot is the minimum potential duration Tpot1 of reconstitution of the maximum usable volume (obtaining V=Vtot or V=0, depending on the nature of the objective (support or rolling) and the direction of the calculations)
+\item 2: Tpot is the minimum potential duration Tpot2 of exhaustion of the usable volume (obtaining V=Vtot or V=0, depending on the nature of the objective (support or rolling) and the direction of the calculations)
+}
+}
+}
+\examples{
+\dontrun{
+# Preparing the run of vgest for:
+# - the first configuration of reservoir rules
+# - the first configuration of network
+# - the naturalised hydrological flows of the file located in DONNEES/Q_NAT_1900-2009.txt
+# - doing the optimisation on the period between 01/01/1900 and 31/12/2009
+# - an objective located at "PARIS_05"
+# - for a flood threshold of 800 m3/s
+# - a fixed task distribution between reservoirs with a relative change of -20\%, -10\%, +50\%, -30\%
+vgest_write_batch(1, 1, "Q_NAT_1900-2009.txt", "01/01/1900", "31/12/2009",
+ "PARIS_05", TRUE, 800, 1, c(-0.2, -0.1, 0.5, -0.3))
+}
+}
--
GitLab