This repository contains tools to run and calibrate different reservoir routines meant to be used in large-scale hydrological models like LISFLOOD Open Source.
Five different reservoir routines are implemented in this repository:
- Linear reservoir (class
Linear) - The routine in the hydrological model LISFLOOD (class
Lisflood) - The routine in the hydrological model CaMa-Flood (class
Camaflood) - The routine in the hydrological model mHM (class
mHM) - The reservoir model Starfit (class
Starfit)
Apart from the tools to train and fit these reservoir routines, it contains multiple Jupyter Notebooks to create datasets of reservoir attributes and observed time series in several countries: US, Mexico, Brazil, Spain... These datasets have the same structure as the CARAVAN dataset, and are meant not only as the input data for the reservoir routines in this repository, but also to be used as input for deep learning models.
Get a local copy of the repository. You can either download it from GitHub or clone it with Git:
git clone https://github.com/casadoj/lisflood-reservoirs.gitMove to the root directory of the repository you've just copied:
cd <YOUR_PATH>/lisflood-reservoirs/Install the package with PiP:
pip install .The repository contains 4 tools to calibrate and run reservoir models. The models included in the repository can be classified in two groups: those that can be calibrated with an iterative process (i.e., a genetic algorithm), and those that are simply fitted using standard SciPy tools. To the first group belong the linear, LISFLOOD, Camaflood and mHM models; the tools run_reservoir and cal_reservoir apply to this group. To the second group belongs the Starfit model; the tools run_starfit and fit_starfit apply to it.
All the tools require a configuration file as the input. A template of this configuration file can be found here. The structure of this template is applicable to all the tools.
The configuration file has three sections dedicated to data, simulation, and calibration, repectively.
- The data section defines the location of the reservoir data set and the files that defines the reservoirs to be used (TXT format) and the study period for each of those reservoirs (Pickle format). All the tools are based in a fixed dataset structure:
- Attributes must be in a subfolder named attributes within the dataset folder.
- Time series must be in a subolder named time_series/csv within the dataset folder.
- The simulation section defines the reservoir model to be used (
linear,lisflood,camaflood,mhmorstarfit) and the folder where the results of the simulation with default parameters will be saved. - The calibration section defines the name of the input variable, the target or targets of the calibration (
storage,outflowor both), the parameters of the SCE-UA algorithm, and the directory where results will be saved.
To run the tools from the command prompt, the instruction is always the same only changing the name of the tools. For instance, to fit the Starfit model:
fit_starfit --config-file config.ymlThis tool simulates the reservoir module with default parameters. It is applicable to the linear, LISFLOOD, Camaflood and mHM models.
usage: simulate.py [-h] -c CONFIG_FILE [-w]
Run the reservoir routine with default parameters
options:
-h, --help
Show this help message and exit
-c CONFIG_FILE, --config-file CONFIG_FILE
Path to the configuration file
-w, --overwrite
Overwrite existing simulation files. Default: False
This tool calibrates the reservoir model using the algorithm Shuffle Complex Evolution - University of Arizona (SCE-UA). It is applicable to the linear, LISFLOOD, Camaflood and mHM models, and it can calibrate the observed storage, outflow, or both at the same time. Eventually, the model is run with the optimised parameters.
usage: calibrate.py [-h] -c CONFIG_FILE [-w]
Run the calibration script with a specified configuration file.
It calibrates the reservoir model parameters of the defined routine using the
SCE-UA (Shuffle Complex Evolution-University of Arizona) algorithm for each of
the selected reservoirs.
The optimal parameters are simulated and plotted, if possible comparing against
a simulation with default parameters
options:
-h, --help
Show this help message and exit
-c CONFIG_FILE, --config-file CONFIG_FILE
Path to the configuration file
-w, --overwrite
Overwrite existing simulation files. Default: False
This tool fits the Starfit reservoir model to the observed data.
usage: fit_starfit.py [-h] -c CONFIG_FILE [-w]
Fit the storage and release rules for the Starfit reservoir routine.
The fitted models are saved as Pickle files and plotted against the
observed data used for fitting.
options:
-h, --help
Show this help message and exit
-c CONFIG_FILE, --config-file CONFIG_FILE
Path to the configuration file
-w, --overwrite
Overwrite existing model. Default: False
This tool runs the Starfit reservoir model that was previously fitted with the tool fit_starfit.
usage: run_starfit.py [-h] -c CONFIG_FILE [-w]
Run Starfit simulation with the paremeter fitted using `fit_starfit`.
The simulated time series are saved as CSV files. To analyse the results,
the code creates a CSV file of performance metrics, and a scatter and a
line plot comparing the observed and simulated time series.
options:
-h, --help
Show this help message and exit
-c CONFIG_FILE, --config-file CONFIG_FILE
Path to the configuration file
-w, --overwrite
Overwrite existing simulation files. Default: False
Casado Rodríguez, J., Disperati, J., & Salamon, P. (2025). ResOpsUS+CARS: Reservoir Operations US and CAtchment and Reservoir Static attributes (1.0) [Data set]. European Commission - Joint Research Centre. https://doi.org/10.5281/zenodo.15978041
Casado Rodríguez, J., Disperati, J., & Salamon, P. (2025). ResOpsBR+CARS: Reservoir Operations Brazil and CAtchment and Reservoir Static attributes (1.0) [Data set]. European Commission - Joint Research Centre. https://doi.org/10.5281/zenodo.16096623