User Tools

Site Tools


Quick Guide on using HYPE

The purpose of this guide is to give an overview of how a HYPE model is structured and where basic information is found. After reading it you should be able to download and run a demo model of HYPE.

Get and run the model

The HYPE model is available for download at sourceforge. You download the source code or precompiled executables and demos of small model applications. Included in download are a ReadMe-file with instructions for compiling the source files (ifort and gfortran compilers have been tested) to get an executable for your system.

The code is written in Fortran and is open source under the Lesser GNU Public License. SMHI took the initiative for a HYPE Open Source Community to strengthen international collaboration in hydrological modelling. More information about the initiative can be found at

A HYPE simulation is in its simplest way started from the command line with the path to the model simulation configuration file as argument. Note that the path ends with a slash. For example, if your model is put in the folder model1 in the modelsetups folder on the D-drive and your Windows executable is on the P-drive, your command will look like this:

Windows Command Prompt:

P:\> HYPE.exe D:\modelsetups\model1\

or Linux terminal:

$ ./hype /data/hypemodels/model2/

In the Windows example your model is put in the folder model1 in the modelsetups folder on the D-drive and your HYPE executable is in the current folder, i.e on the P-drive. In the Linux example, your model is put in the folder model2 in the hypemodels folder in the data folder and your HYPE executable is in the current folder.

Note: Older versions of the HYPE executable (before 5.6.0) return a Code 84 message after a successful run.

The HYPE model set-up

The HYPE model has a simple file structure, with all input files (text files) located in one model folder. The inputs are time series input data, e.g. forcing data, and more or less static geographical data, i.e. information about the landscape and human influence on it. The geographical data is coupled to subbasins (i.e. sub-catchments), which is the spatial division used within the model domain. Output is simulated time series and performance criteria.

Simulation configuration

The model simulation is determined by the configuration file; info.txt. If the info.txt file is located in another directory than the model folder, the path to this directory is given (modeldir). The simulation period (bdate, edate) is mandatory in the file. Water flow is always simulated by HYPE, but other substances can be added, e.g. nutrients (substance). Wanted results are determined. For example, to get a result file with time series for simulated outflow (cout, list of output variables) from each subbasin, timeoutput is used.

HYPE calculates performance criteria if so defined in info.txt. The criterion and the variables to be compared, e.g. Nash-Sutcliffe efficiency (MR2, list of performance criteria) for comparing simulated (cout) and observed (rout) discharge, has to be defined in the file.

Info-file snippet:

bdate 2000-01-01
edate 2010-12-31
timeoutput variable cout
crit 1 criterion MR2
crit 1 cvariable cout
crit 1 rvariable rout

Mandatory input data

Five input files are mandatory; Pobs.txt, Tobs.txt, par.txt, GeoData.txt, and GeoClass.txt.

The forcing time series of precipitation and temperature are given in the files Pobs.txt and Tobs.txt. Each subbasin is coupled to one precipitation and temperature time series. This may be done one to one, then each time series has a column id which is matched to the id number of a subbasin (subid), but other methods exist.

Model parameters determine the outcome of the simulation and are given in the par.txt file. Some basic model parameters are described in a section below. The main geographical input data for each subbasin is given in GeoData.txt which is described in the next section together with GeoClass.txt (characteristics of landscape) and some other related files.

Geographical input data

The basic geography of HYPE is the subbasins. Overlayered the subbasin division is different landscape types, e.g. lakes, forest, boulder-ridge etc. The combinations of land-use (or land-cover), soil type and other characteristics of the landscape are defined and called classes. The classes are the same for all model domain, but they are not present in all subbasins.

The main geographical input data is given in GeoData.txt, with one subbasin on each row. Necessary information is an identification number (subid), subbasin area (area), and area fractions of different classes (slc_nn). Other information that is often included in GeoData.txt is the routing, i.e. subid of downstream subbasin (maindown), main river length (rivlen), and outlet lake average depth (lake_depth). For nutrient simulations also crop region (region), atmospheric deposition (e.g. precipitation concentration of inorganic nitrogen, wetdep_n) and diffuse sources from rural households are common.

For each class, land use, soil type, stream drainage depth, number of soil layers and soillayer thickness is necessary. This information is given in GeoClass.txt with one class per row in order. Lake classes also need to be defined in GeoClass.txt, although not all the information is relevant (or used). The file can contain additional information on the classes. E.g. for a nutrient simulation crop type is necessary in GeoClass.txt (information about crops for different crop regions is given in the file CropData.txt).

Data on point sources discharging into a subbasin's river (e.g. outlet volume per day ps1_vol and it's phosphorus concentration ps1_tp) are given in the file PointSourceData.txt.

Eleven basic model parameters

Model parameters (par.txt) determine the function of the model. The model parameters may depend on land use, soil type or be a general value. The model parameters presented below make up a rudimentary water flow model for a cold climate catchment with lakes. Many more model parameters exist and add other functionality to HYPE. The default value of all model parameters are zero, so they need to be set to be included in the calculations. The model parameters are described in more detail in the HYPE model description in relation to their process.

For a soil runoff model: In a cold climate snow is present. Snow melt rate (cmlt) is a land use dependent parameter and need one value per land use defined in GeoClass.txt. The available storage of water in the soil is determined by the model parameters for field capacity (wcfc) and effective porosity (wcep), which both depend on soil type. Evapotranspiration is governed by a land use dependent parameter (cevp). For a model with more than one soil layer the maximum amount of percolation (mperc1, mperc2) need to be set for percolation to occur. Runoff from the soil is determined by runoff coefficients. The runoff coefficient of the top soil layer (rrcs1) depend on soil type and is necessary. The runoff coefficient of the other soil layers are calculated based on this parameter and others if they are set.

For a surface water model: Flow in rivers has a peak velocity (rivvel). This parameter determines the delay in the system. If you have lakes you can give a general lake depth (gldepi) and rating curve coefficients (gratp, gratk). They will be used for all lakes not having specifically defined values elsewhere. E.g. outlet lakes may have their lake depth given in GeoData.txt.

Typical intervals for above mentioned model parameters: cmlt=2-5, cevp=0.1-0.3, mperc1,mperc2=5-100, wcfc=0.05-0.5, wcep=0.05-0.5, rrcs1=0.05-0.5, rivvel=0.5-2, gldepi=5-10, gratk=1-100, gratp=1-2

To understand the results

With no settings given in the info.txt the log-file (hyss_seqnr_yymmddHHMM.log) is the only result of the simulation. The log-file contains information about running time and input files used. You will also get warning or error messages in the log-file.

There are several options for output of simulation results, but all result in text-files. The example given above with timeseries output of discharge will produce a file named timeCOUT.txt with time series for simulated outflow (cout) from each subbasin in the model set-up as columns (defined by subid). Similarly for other output the variable id and the subbasin id are given in the file name or in the heading of the file. It is also possible to print period mean values of a variable instead of time series.

HYPE can calculate performance criteria when observations are provided, e.g file Qobs.txt with observed discharge, and the variables to be compared are given in info.txt. A selection of performance criteria will be calculated for every subbasin (with observations) and printed in the subassX.txt file, one subbasin per row. Example of performance criteria in subassX.txt; NSE โ€“ Nash-Sutcliffe Efficiency, CC โ€“ correlation coefficient, and MAE โ€“ mean absolute error. Some average performance criteria for the whole model set-up are also printed in the log-file and the simass.txt file.

start/hype_tutorials/short_intro.txt ยท Last modified: 2024/01/25 11:37 (external edit)