Source code for the global hydrological model HydroPy

Synopsis

HydroPy is a global hydrological model combining hydrological land surface processes and river routing. It is based on its predecessor, the Max Planck Institut for Meteorology's Hydrology Model (MPI-HM), however it is fully revised and written in Python. This model is actively developed and will get regular updates. The initial development of HydroPy was founded by the Helmholtz-Zentrum Hereon and the DAAD project *The Ocean's Alkalinity*.

Motivation

While the older Fortran code of the MPI-HM made the model very fast, its further development was hampered by an inflexible structure and a large overhead whenever new processes were implemented. Additionally, it only generated output data in the simple binary service format, so that time consuming post-processing was needed to produce netCDF files. The python version uses much more high-level routines and its object-oriented programming style enables a much faster and easier development. HydroPy is the official successor of the MPI-HM.

Installation

HydroPy requires a python 3.x environment with numpy, netCDF4, xarray and termcolor packages installed. A convenient way of employing this environment would be to setup an Anaconda installation and create a new environment dedicated to the hydropy model, e.g.

conda create -n hydropy numpy xarray netCDF4 termcolor

Then, you can switch to this environment using

conda activate hydropy

Run HydroPy

HydroPy is called from command line using the main function ./hydro.py. Required options are the paths to a netCDF file containing meteorological forcing data and a json-style setup file containing the path of the land surface conditions file, and optionally further path information and model parameters:

./hydro.py -f forcing.nc -s setup.json

The forcing file has to provide the variables TSurf [K], Precip [kg m-2 s-1], and PET [kg m-2 s-1] at a temporal resolution of 1 day and a spatial resolution similar to the land surface conditions file. Example scripts to generate adequate forcing files from different datasets are located in the directory ./util.

A full list of all available options with either the default or user defined values (if set in the setup.json file or via command line) can be printed with

./hydro.py -p [-s setup.json] [-c '{"option": value, ...}']

Using this command also creates a file called hydropy_options.json, in which all options are stored. This can be used as a template to create a user-specific setup file and also provides an overview about all available settings.

The setup file must follow json-style syntax, e.g.:

{
    "para": "hydropy_landsurface_parameter_v1.0.0.nc",
    "opt1" : val1,
    "opt2" : val2
}

Further json examples are provided in the ./scr directory, together with example scripts to run HydroPy. Note that only those options need to be set that are different from the defaults. If options are provided via command line using the -c parameter, their syntax has to follow the json-style as well. Command line options override options defined in the setup file.

Further options can be displayed with

hydro.py --help

Example scripts

Example scripts to run HydroPy are located in the directory ./scr, e.g. using forcing based on EOBS31, ERA5, WFDE5 or Cosmo-CLM.

Documentation and References

A documentation paper is published in GMD. A public version of the HydroPy Model and an example land surface parameter dataset at 0.5 degree can be found on Zenodo.

Specific Notes

Restart file handling

If the restart date is set in the setup file:

• First it is checked whether this is larger than the restart day of the present simulation. If yes, a warning is launched.
• If the restart date agrees with the restart day of the present simulation, the restart file from the json setup file is used as a restart file restfile.

In each each case, it is checked whether the variable restfile is already defined, i.e. whether it is included in the dictionary of globally defined variables. Note that all variables defined in the __main__ module or outside of any function are global. If restfile is not defined (e.g. if the restart date is later than the restart day of the present simulation), it is checked whether the restart file <expid>_restart_<restart day>.nc exists in the 'input'-directory, which is defined in the json setup file. If it exists it will be taken as the restart file. If it does not exist, the restart file from the json setup file will be used even if the date does not fit .

Land fraction derived from forcing data

A land mask is derived from the forcing data based on the near surface air temperature *TSurf*, which is used to determine land fraction weights (internal variable *weights*/*landweights*). However, this may be time dependent if the forcing data have a varying number of land points with time for *Tsurf*. This is, e.g., the case for EOBS data. Currently, the weights only affect consistency checks and statistical calculations, but not the actual simulation itself. This means, for example, that the log output of the mean values over land of the variables *swe* and *rootmoist* are different when writing the restart in 1950 from those when reading the restart in 1951.

Contributors

• Tobias Stacke (tobias.stacke@hereon.de)
• Stefan Hagemann (stefan.hagemann@hereon.de)

License

HydroPy

Copyright (C) 2021 Helmholtz-Zentrum Hereon Copyright (C) 2020 Helmholtz-Zentrum Geesthacht

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.