Online WaterGAP

Run WaterGAP 2.2e in your browser.

About this project

Online WaterGAP puts a web interface around the official ReWaterGAP (WaterGAP 2.2e) code. The model itself is untouched — same source, same dependencies, same results as running it locally. Everything web-related sits in the online/ directory and doesn't interfere with the rest of the repository.

Features

Configuration

Pick a time period, choose between natural and anthropogenic modes, select which variables to output, and decide between a global or basin-level run.

Remote execution

The simulation runs on a server, so you don't need WaterGAP installed locally. You can follow the log in real time or close the tab and come back later.

Visualization

View output variables as spatial maps, step through time, or upload your own NetCDF files to compare against.

Presets

Save a configuration under a name to reuse it later, or export/import configs as JSON files.

Getting started

Set up a simulation

Head to the Simulation tab. Load a preset or build your config from scratch — time period, output variables, global vs. basin extent.

Run it

Hit "Start Simulation". The Runs tab shows the live log and resource usage. The run keeps going even if you close the page.

Look at the output

Once the run finishes, open the Visualization tab. Pick the run and a variable, then browse the maps over time.

WaterGAP 2.2e (GitHub)

Load Preset

Input Data

WaterGAP requires three categories of input data:
Climate Forcing — Daily meteorological data: precipitation (pr), temperature (tas), downward longwave radiation (rlds), and downward shortwave radiation (rsds). Available from ISIMIP. Data is organized in 10-year files. Leap days must be removed.
Water Use — Monthly sectoral water withdrawal and consumption data (irrigation surface water, irrigation water withdrawal, net abstractions from surface water and groundwater). Must match the chosen climate forcing dataset.
Static Land Data — Time-invariant parameters: land cover, soil properties, river routing tables, reservoir locations, continental area fractions, and calibration parameters.
Important: The parameter file must be calibrated for the same climate forcing dataset used in the simulation.

Select the dataset bundle for your simulation

No input datasets found on the server.

Upload data via SSH or contact the administrator.

Simulation Mode

WaterGAP supports four simulation modes:
Naturalized Run — No human impacts. Compute natural flows and storages without human water use or reservoirs.
Standard Anthropogenic — Enable all options to simulate combined effects of human water use and man-made reservoirs on flows and storages.
Human Water Use Only — Enable Anthropogenic + Subtract Water Use, disable Reservoir Operation.
Reservoirs Only — Enable Anthropogenic + Reservoir Operation, disable Subtract Water Use.

Anthropogenic Run

Subtract Water Use

Reservoir Operation

Delayed Use

Neighbouring Cell Supply

Simulation Period

Start/End Date — Define the time range for the simulation. Climate forcing data must cover this period (plus spin-up). WaterGAP runs at daily resolution.
Spin-up Years — Number of years to repeat the first year of forcing data before the actual simulation begins. This initializes model storages (soil moisture, groundwater, snow, etc.) to realistic levels. Typical value: 5 years.
Reservoir Start/End Year — Only relevant when Reservoir Operation is enabled. Defines the time window during which man-made reservoirs become operational according to their commissioning year. Reservoirs built outside this window are treated as natural lakes.

Define the time range, spin-up, and reservoir operation period.

Scanning input data for valid time range...

Valid simulation period based on input data:

Start Date

End Date

Spin-up Years

Reservoir Start Year

Reservoir End Year

Simulation Extent

Global Run — Simulates all land grid cells worldwide. Requires more memory (~16 GB+).
Basin Run — Simulates only the upstream area of a specified outlet point. Much faster and uses less memory. You need a stations CSV file that defines the outlet coordinates.

Choose between global or basin-specific simulation.

Path to Stations File

Directory containing a stations.csv file with outlet coordinates (Lat, Lon columns). WaterGAP appends /stations.csv automatically.

Restart Options

Restart — Resume a previous simulation from saved model states instead of starting from scratch.
Save Model States — Save model states at the end of the simulation so it can be restarted later.
States Directory — Path where model states are saved to or read from.

Save or restore model states for continuing simulations.

Restart from saved states

Save model states for restart

States Directory

Calibration

Calibrate WaterGAP — Run the calibration routine to adjust model parameters based on observed discharge data. Requires observed discharge files at the specified path.

Calibrate model parameters against observed discharge.

Run calibration

Path to Observed Discharge

Output Variables

Select which variables WaterGAP writes to NetCDF output files. Variables are grouped into four categories:
Vertical Water Balance — Fluxes: Water flows within each grid cell (evaporation, precipitation throughfall, snowmelt, surface runoff, groundwater recharge).
Vertical Water Balance — Storages: Water stored in vertical compartments (canopy, snow, soil).
Lateral Water Balance — Fluxes: Water flows between grid cells and water bodies (river discharge, lake/wetland outflows, groundwater discharge, water abstractions).
Lateral Water Balance — Storages: Water stored in rivers, lakes, wetlands, groundwater, and reservoirs.
Enabling more variables increases output file size and computation time slightly.

Toggle output variables per category. Hover over variable names for descriptions.

Configuration File

Export — Download the current settings as a Config_ReWaterGAP.json file. This is the same format used by the command-line version of WaterGAP.
Import — Load an existing Config_ReWaterGAP.json file to populate all fields on this page. Useful for reproducing a previous simulation.

Export or import a Config_ReWaterGAP.json file.

Simulation Runs

No simulation runs yet.

Data Source

ZIP

Uploading...

Select a data source above or drop a .nc file here

Choose from previous simulation runs, uploads, or upload a new NetCDF file

Variable

Date

Rendering map...

Loading map...

Save Image

File Browser

This page shows a summary of the online infrastructure. For the full ReWaterGAP documentation (model processes, user guide, tutorials, and more):

WaterGAP 2.2e Branch (GitHub) Full Documentation (dev version)

Online Infrastructure

OnlineWaterGap wraps the existing ReWaterGAP command-line application in a web-based frontend so that users can configure, launch, and visualize hydrological simulations from any modern browser.

Architecture

The stack consists of three components:

Frontend

Static HTML/JS served by Vercel. Single-page app, no build step required.

Backend

FastAPI running in Docker on a Hetzner cloud server. Spawns run_watergap.py as a subprocess.

Database

Supabase PostgreSQL instance tracking simulation jobs and uploaded datasets.

Request Flow

Browser
  │
  ▼
Vercel  (online-water-gap.vercel.app)
  │  serves static HTML/JS
  │  proxies /api/* via rewrite rules
  ▼
Hetzner Docker host  (FastAPI + Uvicorn)
  │  starts run_watergap.py as subprocess
  ▼
WaterGAP simulation
  │  reads input_data/ (mounted read-only)
  │  writes results to output_data/
  ▼
Browser receives status updates, logs, result maps

Repository Layout

online/
├── api/
│   ├── main.py          # FastAPI application
│   └── static/          # Frontend (HTML, JS, CSS)
├── Dockerfile           # Container image definition
├── docker-compose.yml   # Service orchestration + volumes
├── run_web.py           # Dev helper: installs deps + starts uvicorn
└── vercel.json          # Vercel routing & API proxy config

Docker Volumes

Volume	Mode	Purpose
input_data	read-only	Climate forcing, water use, static data
watergap-jobs	read-write	Per-run config, logs, status
watergap-uploads	read-write	User-uploaded NetCDF files
watergap-output	read-write	Simulation result files
watergap-presets	read-write	Saved configuration presets

API Endpoints

Method	Path	Description
GET	/api/health	Health check
POST	/api/simulate	Start a new simulation
GET	/api/status/{job_id}	Poll job status
POST	/api/cancel/{job_id}	Terminate a running simulation
GET	/api/jobs	List all runs with status
GET	/api/resources	Server resource usage (RAM, Swap, Disk)
GET	/api/presets	List saved presets
GET	/api/input-datasets	List available input data bundles
GET	/api/map/{source}/{var}	Render a spatial map (PNG)

Changes Relative to the Original Code Base

The online version keeps changes minimal. The core model code (model/, controller/, calibration/, view/) and requirements.txt are identical to the upstream ReWaterGAP repository. All additions live exclusively in the online/ directory.

View full Online Infrastructure documentation