Getting Started

1 Installation

Install all three WaterGAP3 packages from GitHub. This only needs to be done once, or after a package update.

remotes::install_github("HydroSimul/HydroGalleryCpp")
remotes::install_github("HydroSimul/WaterGAP3Cpp")
remotes::install_github("HydroSimul/WG3Tools")

If any of these commands fail — for example with an authentication error or a “Repository not found” error — your computer likely still needs the full setup (R, Rtools, RStudio, Git, GitHub access and a Personal Access Token). Follow the WaterGAP3 Setup guide and then retry the commands above.

2 Setup

Load the required libraries and define the root data path at the start of every new R session.

library(WaterGAP3Cpp)
library(WG3Tools)

# Root path for all input/output data
path_Root <- "/projects/WaterGAP/WaterGAP3M/ProjectRun/Demo/Data/"

str_Continent <- c("eu", "af", "as", "au", "na", "sa")
names(str_Continent) <- str_Continent

3 Single-block run

The examples below demonstrate a single-block run for Australia (au), year 1979, in natural mode ("N").

name_Region <- "au"
mark_Time   <- "1979"
n_Time      <- 365
n_Spat      <- 109084

3.1 Without initial state

Run the model from scratch (no prior state). The final model state is exported and can be used as the initial state for subsequent years.

CELL_discharge_m3 <- run_WaterGAP3M(
  "N",
  name_Region, mark_Time, n_Time, n_Spat,
  path_MeteoInput = paste0(path_Root, "MeteoInput/"),
  path_HydroParam = paste0(path_Root, "HydroParam/"),
  path_FinalState = paste0(path_Root, "InitialState/")
)

3.2 With initial state

Continue from a previously saved model state.

CELL_discharge_m3 <- run_WaterGAP3M(
  "N",
  name_Region, mark_Time, n_Time, n_Spat,
  path_MeteoInput   = paste0(path_Root, "MeteoInput/"),
  path_HydroParam   = paste0(path_Root, "HydroParam/"),
  path_InitialState = paste0(path_Root, "InitialState/"),
  path_FinalState   = paste0(path_Root, "InitialState/")
)

3.3 With variable export

Same as above, but additionally writes all intermediate output variables to disk.

CELL_discharge_m3 <- run_WaterGAP3M(
  "N",
  name_Region, mark_Time, n_Time, n_Spat,
  path_MeteoInput   = paste0(path_Root, "MeteoInput/"),
  path_HydroParam   = paste0(path_Root, "HydroParam/"),
  path_InitialState = paste0(path_Root, "InitialState/"),
  path_VariExport   = paste0(path_Root, "WG3Output/"),
  path_FinalState   = paste0(path_Root, "InitialState/")
)

4 Run with water use

Switch to water-use mode ("U") and provide a path to the water-use input data. This input data is produced by the Water-Use Pre-Processing workflow.

4.1 Without initial state

CELL_discharge_m3 <- run_WaterGAP3M(
  "U",
  name_Region, mark_Time, n_Time, n_Spat,
  path_MeteoInput    = paste0(path_Root, "MeteoInput/"),
  path_HydroParam    = paste0(path_Root, "HydroParam/"),
  path_WateruseInput = paste0(path_Root, "WateruseInput/"),
  path_FinalState    = paste0(path_Root, "InitialState/")
)

4.2 With initial state

CELL_discharge_m3 <- run_WaterGAP3M(
  "U",
  name_Region, mark_Time, n_Time, n_Spat,
  path_MeteoInput    = paste0(path_Root, "MeteoInput/"),
  path_HydroParam    = paste0(path_Root, "HydroParam/"),
  path_WateruseInput = paste0(path_Root, "WateruseInput/"),
  path_InitialState  = paste0(path_Root, "InitialState/"),
  path_FinalState    = paste0(path_Root, "InitialState/")
)

5 Global run

Iterate over all six continents. Results are collected as a named list.

lst_CELL_discharge_m3 <- list()

for (idx_Conti in str_Continent) {
  lst_CELL_discharge_m3[[idx_Conti]] <- run_WaterGAP3M(
    "N",
    idx_Conti, mark_Time, n_Time, n_Cell_Conti[idx_Conti],
    path_MeteoInput = paste0(path_Root, "MeteoInput/"),
    path_HydroParam = paste0(path_Root, "HydroParam/"),
    path_FinalState = paste0(path_Root, "InitialState/")
  )
}

6 Multi-year run

For multi-year runs, output is written directly to files rather than returned as an R object.

6.1 Spin-up (initial year, no prior state)

Run one year without an initial state to generate a starting state for subsequent years. n_Repeat controls how many times the spin-up year is repeated.

run_wg3_initial(
  "N",
  name_Region, n_Spat,
  year_Initial = 1979,
  n_Repeat     = 1,
  path_MeteoInput = paste0(path_Root, "MeteoInput/"),
  path_HydroParam = paste0(path_Root, "HydroParam/"),
  path_FinalState = paste0(path_Root, "InitialState/")
)

6.2 Continued run

Run consecutive years starting from a saved initial state.

run_wg3_multiyears(
  "N",
  name_Region, n_Spat,
  year_Start = 1979,
  year_End   = 1979,
  path_MeteoInput   = paste0(path_Root, "MeteoInput/"),
  path_HydroParam   = paste0(path_Root, "HydroParam/"),
  path_InitialState = paste0(path_Root, "InitialState/")
)