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. Its initial development 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 files 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.

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
}

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

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.

Contributors

• Tobias Stacke (tobias.stacke@mpimet.mpg.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/>.