HYPE Model Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[https://sourceforge.net/projects/hype/|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 [[http://hypecode.smhi.se/|hypecode.smhi.se]].  

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; [[start:hype_file_reference:info.txt|info.txt]]. If the [[start:hype_file_reference:info.txt|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'', [[start:hype_file_reference:info.txt:variables|list of output variables]]) from each subbasin, [[start:HYPE_file_reference:timeXXXX.txt|timeoutput]] is used. 

HYPE calculates performance criteria if so defined in [[start:hype_file_reference:info.txt|info.txt]]. The criterion and the variables to be compared, e.g. Nash-Sutcliffe efficiency (''MR2'', [[start:hype_file_reference:info.txt:criteria|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; [[start:HYPE_file_reference:pobs.txt|Pobs.txt]], [[start:hype_file_reference:tobs.txt|Tobs.txt]], [[start:hype_file_reference:par.txt|par.txt]], [[start:hype_file_reference:geodata.txt|GeoData.txt]], and [[start:hype_file_reference:geoclass.txt|GeoClass.txt]]. 

The forcing time series of precipitation and temperature are given in the files [[start:HYPE_file_reference:pobs.txt|Pobs.txt]] and [[start:HYPE_file_reference:tobs.txt|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 [[start:hype_file_reference:par.txt|par.txt]] file. Some basic model parameters are described in a [[start:hype_tutorials:short_intro#basic_model_parameters|section]] below. The main geographical input data for each subbasin is given in [[start:hype_file_reference:geodata.txt|GeoData.txt]] which is described in the [[start:hype_tutorials:short_intro#geographical_input_data|next section]] together with [[start:hype_file_reference:geoclass.txt|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 [[start:hype_file_reference:geodata.txt|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 [[start:hype_file_reference:geodata.txt|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 [[start:hype_file_reference:geoclass.txt|GeoClass.txt]] with one class per row in order. Lake classes also need to be defined in [[start:hype_file_reference:geoclass.txt|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 [[start:hype_file_reference:geoclass.txt|GeoClass.txt]] (information about crops for different crop regions is given in the file [[start:hype_file_reference:cropdata.txt|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 [[start:hype_file_reference:pointsourcedata.txt|PointSourceData.txt]].


==== Eleven basic model parameters ====


Model parameters ([[start:hype_file_reference:par.txt|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 [[start:hype_model_description|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 [[start:hype_file_reference:geoclass.txt|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 [[start:hype_file_reference:geodata.txt|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, ''gldep''i=5-10, ''gratk''=1-100, ''gratp''=1-2

===== To understand the results =====

With no settings given in the [[start:hype_file_reference:info.txt|info.txt]] the log-file ([[start:hype_file_reference:hyss_yymmddhhmm.log|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 [[start:hype_file_reference#output_files|options for output]] of simulation results, but all result in text-files. The example given above with [[start:HYPE_file_reference:timeXXXX.txt|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 [[start:hype_file_reference:qobs.txt|Qobs.txt]] with observed discharge, and the variables to be compared are given in [[start:hype_file_reference:info.txt|info.txt]]. A selection of performance criteria will be calculated for every subbasin (with observations) and printed in the [[start:hype_file_reference:subassx.txt|subassX.txt]] file, one subbasin per row. Example of performance criteria in [[start:hype_file_reference:subassx.txt|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 [[start:hype_file_reference:simass.txt|simass.txt]] file.
HYPE Model Documentation

User Tools

Site Tools

Page Tools
