User Tools

Site Tools


start:hype_tutorials:short_intro

This is an old revision of the document!


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 hypecode.smhi.se.

A HYPE simulation is 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:

Windows Command Prompt:

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

or Linux terminal:

$ ./hype /data/hypemodels/model2/

The HYPE executable 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.

Basic model parameters

Model parameters (par.txt) determine the function of the model. The model parameters may depend on land use type, soil type or be a general value. The model parameters to be presented make up a rudimentary water flow model, but many more exist and include other functions to the model. The function of model parameters are described in more detail in the HYPE model description.

For a soil runoff model compartment: In a cold climate snow melt is necessary (cmlt). It is a land use dependent parameter and need one value per land use defined in GeoClass.txt. Evapotranspiration is governed by a land use dependent parameter (cevp). The default value of all model parameters are zero, so if these are not set no snow melt or evapotranspiration will occur. For a model with more than one soil layer the maximum amount of percolation (mperc1, mperc2) need to be set for percolation to occur. The available storage of water in the soil needs to be set. The model parameters for “field capacity” (wcfc) and effective porosity (wcep) depend on soil type. Runoff from the soil is determined by runoff coefficients. The runoff coefficient of the top soil layer is necessary (rrcs1), and depend on soil type.

For surface water model compartment: 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 internal lakes. They will also be used for outlet lakes if no other data is given for them. 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 called 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.1483022333.txt.gz · Last modified: 2023/11/16 14:28 (external edit)