Hide code cell content
# Suppress distracting outputs in these examples
# Note: this cell should be hidden with the tag "hide-cell"
import logging
import warnings

warnings.filterwarnings("ignore", category=UserWarning)
logger = logging.getLogger("esmvalcore")
logger.setLevel(logging.WARNING)

Introduction

This user manual will explain how the eWaterCycle Python package can be used to perform hydrological experiments. We will walk through the following chapters:

Each of these chapters correspond to a so-called “subpackage” of eWaterCycle Python package. Before we continue, however, we will briefly explain the configuration file.

Configuration

To be able to find all needed data and models eWaterCycle comes with a configuration object. This configuration contains system settings for eWaterCycle (which container technology to use, where is the data located, etc). In general these should not need to be changed by the user for a specific experiment, and ideally a user would never need to touch this configuration on a properly managed system. However, it is good to know that it is there.

You can see the default configuration on your system like so:

from rich import print

from ewatercycle import CFG

print(CFG)
Configuration(
    grdc_location=PosixPath('/home/bart/ewatercycle/grdc-observations'),
    container_engine='docker',
    apptainer_dir=PosixPath('.'),
    singularity_dir=None,
    output_dir=PosixPath('/home/bart/ewatercycle/output'),
    parameterset_dir=PosixPath('/home/bart/ewatercycle/parameter-sets'),
    parameter_sets={
        'pcrglobwb_rhinemeuse_30min': ParameterSet(
            name='pcrglobwb_rhinemeuse_30min',
            directory=PosixPath('/home/bart/ewatercycle/parameter-sets/pcrglobwb_rhinemeuse_30min'),
            config=PosixPath('/home/bart/ewatercycle/parameter-sets/pcrglobwb_rhinemeuse_30min/ini_and_batch_files/
deltares_laptop/setup_natural_test.ini'),
            doi='https://doi.org/10.5281/zenodo.1045339',
            target_model='pcrglobwb',
            supported_model_versions={'setters'},
            downloader=GitHubDownloader(
                org='UU-Hydro',
                repo='PCR-GLOBWB_input_example',
                branch='master',
                subfolder='RhineMeuse30min'
            )
        ),
        'wflow_rhine_sbm_nc': ParameterSet(
            name='wflow_rhine_sbm_nc',
            directory=PosixPath('/home/bart/ewatercycle/parameter-sets/wflow_rhine_sbm_nc'),
            config=PosixPath('/home/bart/ewatercycle/parameter-sets/wflow_rhine_sbm_nc/wflow_sbm_NC.ini'),
            doi='N/A',
            target_model='wflow',
            supported_model_versions={'2020.1.2', '2020.1.3', '2020.1.1'},
            downloader=GitHubDownloader(
                org='openstreams',
                repo='wflow',
                branch='master',
                subfolder='examples/wflow_rhine_sbm_nc'
            )
        )
    },
    ewatercycle_config=PosixPath('/home/bart/.config/ewatercycle/ewatercycle.yaml')
)

Note: a path on the local filesystem is always denoted as “dir” (short for directory), instead of folder, path, or location. Especially location can be confusing in the context of geospatial modeling.

It is also possible to store and load custom configuration files. For more information, see system setup