Quick links to often-used pages:
Quick links to often-used pages:
The info.txt file contain model options and simulation settings. The purpose of the file is to govern the simulation. It works as the user interface for a HYPE model run. The basic format in the info file is simply a row-wise code-argument(s) combination:
!! <comment> <code 1.1> [<code 1.2>] <argument 1> [<argument 2>] ... [<argument n>] <code 2.1> [<code 2.2>] <argument 1> [<argument 2>] ... [<argument m>] ...
Comment rows can be added anywhere and are marked with double exclamation marks, i.e. !!, or '!!' followed by a space. For other rows, the first (and sometimes second) code string decides what information is to be read. The code can be written within or without apostrophes ('…'). Most codes are optional and can be omitted if not required in a model run. Codes are not case sensitive, except for directory paths given after codes modeldir, forcingdir and resultdir, and time steps given after code steplength. Date-times are always specified as the beginning of the timestep. Maximum 18000 characters can be read on a single line.
A typical info file contains four groups of code-argument combinations:
Conventionally, info files are sorted according to this order. The following tables describe all possible codes, grouped in the above order.
In order to write output files of results for other than daily time steps or the whole simulation period,
edate must agree with the period chosen for output, e.g. for monthly output, cdate should be the first day of a calendar month and edate the last day of a month. This is true also for shorter time steps, e.g.
edate should be the last timestep of the date ending the period.
Mandatory codes denoted in bold face.
| ||directory path|| Gives the search path to all model input files, with exception of forcing data and initial state if
| ||directory path|| Gives the search path to forcing files (Pobs, Qobs etc. and ForcKey) and initial state file. Default is
| ||directory path||Gives the search path to the result files (except for hyss.log which is written in the folder of info.txt). The folder must exist. Default is same folder as info.txt. Relative path starts from the info-file folder.|
| ||date-time||Gives the start date for simulation. Format: yyyy-mm-dd [HH:MM].|
| ||date-time|| Gives the start date for the output of results and calculations of criteria. Format: yyyy-mm-dd [HH:MM]. Defaults to
| ||date-time||Gives the last date for the simulation (including this date). Format: yyyy-mm-dd [HH:MM].|
| ||string|| defines the length of the time step used in calculations. It consists of an integer followed directly by d, h or min. For example a daily time step is defined as 1d, while a time step of six hours is defined as 6h. The code has so far been tested with step lengths 1h, 6h and 1d. Default is 1d.
Time steps of a simulation with shorter time step than a day use hour and minute to denote their time. The hour is between 00 and 23. The date-time is the beginning of the time step. For example with 12h time step is the 2 times during a 1 January denoted 2010-01-01 00:00 and 2010-01-01 12:00.
| ||Y/N|| defines whether a starting state is to be read. Y for yes, N for no. Default is N. For yes, the file with a previously saved model state must exist (state_saveyyyymmdd[HHMM].txt) date in file name must be the same as
| ||date-time||defines that a starting state will be output for the given date. The date should be in the format yyyy-mm-dd [HH:MM]. The default is that no output state is written. Maximum 10 dates may be given. The dates may be written on same or different rows. In the latter case, the code first on every row. The starting state is saved in file state_saveyyyymmdd[HHMM].txt.|
| ||defines that a starting state will be output for every timestep of the model simulation. Default is that no output state is written. The starting states are saved in files state_saveyyyymmdd[HHMM].txt.|
| ||date-time date-time||defines that starting state will be output for all time steps within the period between the given dates. The dates should be in the format yyyy-mm-dd [HH:MM]. Default is that no output state is written. The starting states are saved in files state_saveyyyymmdd[HHMM].txt.|
| ||date-time||defines that nutrient soil states will be reset to the starting state. The date should be in the format yyyy-mm-dd [HH:MM]. The default is that no reset is done. Maximum 100 dates may be given. The dates may be written on same or different rows. In the latter case, the code first on every row. The reset starting state is saved in file reset_state_save.txt.|
| ||string||gives the substances to be simulated. One or several of: N P C S T1 T2. N - nitrogen, P - phosphorus, C - organic carbon, S - total suspended sediment, T1 - tracer, and T2 - water temperature. Substances may be defined on one or several rows (with the code preceding the substance on each row) with one or several substances per row (separated by space). The default is to simulate no substances, only water.|
| ||Y/N|| defines whether or not automatic calibration is to be done. Y for calibration. Default is N. Calibration method and parameters are defined in file optpar.txt. Note that reading of initial state does not work with automatic calibration of parameters rivvel and damp, or with the
| ||Y/N||defines if regional estimated parameters calculated by regression is used. This option requires the files reg_par.txt, CatchDes.txt and CatchGroup.txt. Y for yes or N for no. Default is N.|
| ||0/1||handles several different formats of input data. The default (0) is ASCII-files with dates in the format yyyy-mm-dd and normal months. ‘1’ is ASCII-files with date in MATLAB format|
| ||0/1||Set to 1 to write output in a format suitable for MATLAB (i.e. date without ‘-‘, ‘%’ in front of the column headings). Default is 0.|
| ||Y/N||defines if Outregions.txt is present and should be used. Give Y to use the file, or N (default).|
| ||Y/N||determines if result files have the sequence number as a suffix to their name, if HYPE is run with flag '-sequence', see How to run HYPE. Default is yes. Give No to remove the number from result file names.|
| ||Y/N||defines if time series input data should be read every day. The default is to read all data at the beginning of the simulation (N). However, for large input data files, memory limitations can preclude this. Set to ’Y’ to read input data every day instead.|
| ||Y/N||defines if columns pobsid/tobsid/etc. in ForcKey.txt will be used. Give Y to use the columns if they exist (default), or N to force the use of subid as connection between forcing data columns and and GeoData.|
| ||Y/N||defines if SFobs.txt with observed snowfall fractions is present and should be used. Give Y to use the file, or N (default).|
| ||Y/N||defines if SWobs.txt with observed shortwave radiation is present and should be used. Give Y to use the file, or N (default).|
| ||Y/N|| defines if Uobs.txt with observed wind speeds is present and should be used. Give Y to use the file, or N (default). Replaces
| ||Y/N|| defines if RHobs.txt with observed relative humidity is present and should be used. Give Y to use the file, or N (default). Replaces
| ||Y/N|| defines if TMINobs.txt with observed min air temperatures are present and should be used. Give Y to use the file, or N (default). Replaces
| ||Y/N|| defines if TMAXobs.txt with observed max air temperatures are present and should be used. Give Y to use the file, or N (default). Replaces
| ||Y/N||defines if files XobsXOMn.txt and XobsXOSn.txt are present and should be used (n=0-9). Files hold observations of optional, not predefined variables, XOSn are summed over time in output files while XOMn are averaged. Give Y to use the file, or N (default).|
| ||Y/N||defines if only a part of the model domain is to be simulated. Give Y for yes or N for no. Default is N. The submodel is then defined in the file pmsf.txt.|
| ||Y/N||defines if irrigation withdrawals should be taken from within the model domain (N, default) or from an unlimited outside source (Y). For further irrigation details, see MgmtData.txt|
| ||Y/N||initiates soil water to porosity instead of field capacity which is default (N). Set Y to use porosity.|
| ||Y/N||define if parameter soilcorr shall be used to stretch the soil depths given by GeoClass.txt.|
| ||processmodel #||takes two arguments and defines if an alternative processmodel should be used. Default is 0, alternative processmodels correspond to higher integers. For available processmodels, see below.|
| ||0-3||defines if setup- and observation files as well as hydrological processes and model options will be checked for formal errors prior to running the model. Default is to not perform any checks (0). 1) Tests will be performed and the simulation will be aborted if errors are found. 2) Tests will be performed and the simulation will be continued regardless if errors are found. 3) Tests will be performed and simulation will be aborted regardless if errors are found or not.|
| ||0-2||Printout level for verification and validation checks: 0) only passed/failed, 1) also show which tests were performed, 2) also show parameters/inputs|
| ||Y/N||flag to use the old return code 84 for a successful run|
The following process models are available as modeloptions. The second code and argument are given after the
modeloption code word.
|0/1/2||defines which model to use for regional groundwater flow and aquifers. Default is none (0), alternative is a regional groundwater flow model without dedicated aquifer volumes (subsurface transfer between subcatchments) (1) and an aquifer model with dedicated regional aquifer volumes (2) (requires aquifer definition in input file AquiferData.txt).|
|0/1||defines which soil erosion model to be used for simulation of suspended sediments. Default (0) is similar to erosion of PP (uses CropData), alternative (1) is based on HBV-sed.|
|0/1/2/3||defines which model to use for floodplains. Default is none (0), alternatives are a simple model (1) and a model with soilroutines (2). A fourth option (3) is to use the model with soil routines and connecting floodplains. All requires floodplain information in input file FloodData.txt).|
|0/1/2||defines which frozen soil model to use. Default is none (0), the alternatives calculates frozen volume as a function of temperature with (1) one temperature per soil layer (2) temperature distribution within soil layer. Frozen soil model uses parameters 'logsatmp', 'bcosby' and 'fzsexpand'.|
|0/1||defines if initialization from SLC+parameters overrides saved state of glacier volume (1). Default is to use saved state (0).|
|0/1||defines if temperature varying start of the growth season should be used. Default is 0, then CropData.txt constant parameter bd2 is used. The alternative is 1, i.e. to used varying growth season start. Then the season start is calculated based on degreedays (equation defined by parameters in CropData.txt).|
|0/1/2/3||defines which infiltration model should be used. Default is the basic infiltration model of HYPE. For infiltration model 1 infiltration is limited by frozen soils. Infiltration model 2 is an alternative model where infiltration and percolation is added after runoff and evaporation is calculated. Model 3 is a combination of model 2 and 1.|
|0/1/2||defines if ice on lakes and rivers should be simulated. Default is no (0), while a positive number means yes. The alternative models are (1) with temperature transfer between air and water and (2) with water surface heat balance. The ice calculations require that substance T2 (water temperature) is simulated.|
|0/1/2/3/4/5||defines if an alternative potential evapotranspiration model should be used. Default is temperature dependence or use of observations (0), alternatives are temperature dependent (1), modified Jensen-Haise/McGuinness (2), modified Hargreaves-Samani (3), Priestly-Taylor (4), and FAO Penman-Monteith reference crop evapotranspiration (5).|
|0/1||defines which snowdensity model to use. Default is snow age dependent snowdensity (0), and alternative is snow compactation snow density model (1).|
|0/1||defines if evaporation (sublimation) from snow and glaciers should be calculated. Default is off (0), and alternative is on (1). Snow and glacier evaporation is governed by the general parameters ‘fepotsnow’, ‘fepotglac’, and ‘fsceff’ in par.txt.|
|0/1/2||defines which snowfall distribution model to use. Default is none (0), alternatives are scaling using linear (1) or log-linear (2) Winstrals coefficients (WSF).|
|0/1||defines if an alternative snowfall model should be used. Default is threshold temperature (0), alternative is snowfall fraction from SFobs.txt (1).|
|0/1||defines if snow heat shall be calculated and used to limit snow melt. Default is no (0), and alternative is yes (1). Snow heat model uses parameters 'sdnsnew' and 'snkika'.|
|0/2||defines which snowmelt model should be used. Default is temperature index (0), the alternative is temperature and radiation index (2). Previous option (1) temperature index with snowcover scaling is no longer used. Snowcover scaling of melt and evaporation is controlled by parameter ‘fsceff’, see section par.txt.|
|0/1||defines if soil leakage concentrations is to be calculated or read from file. Default (0) is calculation, (1) is reading monthly values for each subbasin.|
|0/1||defines if T2 temperature should be used for WQ-processes in surface waters. Default is not (0), alternative is (1). The calculations require that substance T2 is simulated.|
|0/1/2||defines if wetland model is to be simulated. Default (0) is no wetland model, (1) is river wetland nutrient model, (2) wetlands as classes with water regulation capabilities.|
HYPE offers three principal output types for standard model runs, as well as two variants, all of which are formatted text files with tabular content which is controlled with code combinations in info.txt. Additional output are two types of files which are activated by single codes:
The principal outputs are specified with two codes in info.txt, first code giving the output type and second specifying content options. After the codes follow the arguments. Content option codes are identical for all basic output types. All outputs are technically optional.
It is possible to get output for several different aggregation periods for the same type of output (basin- , class-, region- or time-output) by specifying several groups of the same type of output with a ordinal number between Code 1 and Code 2. See example below the table. The files will then have a suffix to their name to separate them, e.g. timeCRUN_DD.txt. If only one non-numbered group is used no meanperiod suffix will be added to the file(s). The number between Code 1 and Code 2 is also used to hold together classoutput information for different variables/groups/meanperiods.
|Code 1||Code 2||Argument||Description|
| || ||ID string(s)||defines variables to be written. Multiple variables are separated by blanks or tabs. The order of the variables defines the order in basin output files. For time output files and map output files the order is irrelevant (one file per variable returned). Both internal and output variables are available, see Complete list of variables. One or several rows may be given.|
| || ||0/1/2/3/4/5|| is given to define the period to which results are aggregated for the output. The period is given using codes, e.g. 1 for daily (see table below).
The type of aggregation depends on variable and chosen period: Fluxes are given as sums, storages and states as averages, and concentrations as flow-weighted averages. It is documented in the list of variables in column 'Agg.'.
| || ||integer|| defines the number of significant figures written in the outputs. Allowed values 2-10. Default is to use a fixed number of decimals. If set, significant figures and mathematical format are used (e.g 9.5451E-03) instead.
Note: signfigures applies to all output variables within one output type. Note: signfigures less than 4 will round missing value to -1E4.
| || ||integer|| defines a fixed number of decimals written in the outputs, alternative to signfigures. Maximum allowed number of decimals is 9. Consider using signfigures instead, which is more flexible.
Note: decimals applies to all output variables within one output type. Output variables which contain small numbers and ones which contain large numbers can be impossible to combine in a single
| || ||NONE||defines that output is to be written for all subbasins. No further arguments.|
| || ||integer||defines one or several SUBIDs (subcatchment IDs) for which output is to be written. One or several rows may be given.|
| || ||integer||defines one or several OUTREGIDs for which output is to be written. One or several rows may be given. If no row with outregions is defined all outregions will be written.|
| || ||name string(s)||defines which class groups are to be printed for this output. Leave out if default class groups are used.|
| || ||name string, integer(s)||defines which slc-classes are included in the classgroup with this name. The name may be up to 6 letters.|
| || ||allclass||define default groups should be used for all classoutput. This means one class per classgroup.|
| || ||Y/N||defines if output of annual loads is to be written. Y for load output. Default is N.|
| || ||Y/N||defines if output of daily (time steply) water balance is to be written. Y for yes or N for no. Default is N.|
Aggregation period codes (used for
meanperiod) and corresponding file name suffix. Simulation period (
5) aggregates are means of annual aggregates.
|The code give timesteply output, the suffix varies depending on time step length|
The following example snippet gives daily discharge simulated and observed for two subbasins in the files 0000025.txt and 0000073.txt. It gives monthly time series of precipitation, evaporation, local runoff and discharge and daily time series of runoff. The additional file, in this case for daily runoff, is called timeCRUN_DD.txt, while the runoff file from the first group is called timeCRUN_MO.txt:
basinoutput variable cout rout basinoutput meanperiod 1 basinoutput subbasins 25 73 timeoutput 1 variable prec evap crun cout timeoutput 1 meanperiod 3 timeoutput 1 decimals 3 timeoutput 2 variable crun timeoutput 2 meanperiod 1 timeoutput 2 decimals 1
HYPE can calculate several performance criteria over the model domain. HYPE allows to set several criteria which evaluate the whole model domain, e.g. an average Nash-Sutcliffe efficiency over all stations. If several of these domain-wide criteria are set in the performance criteria options they will be added, optionally with weights, to give an overall performance measure. This measure will be used as objective function in the calibration routines. Performance measure and domain-wide criteria are written to output file simass.txt. Users can also access all criteria values for each subbasin (observation site at catchment outlet) seperately in output file subassX.txt. Criteria are calculated for all subbasins where observation data are available. Criteria are always based on the model evaluation period as defined with codes
edate, see Model options.
Performance criteria are specified in info.txt with code
crit n, followed by a second code.
n is used to number individual domain-wide performance criteria which are combined to the overall performance measure as described above. Up to 20 criteria are allowed, a complete list of available criteria is available as are equation definitions. Calibration routines require further settings in additional input files, see Calibration files.
For the calculation of criterion for lake water stage, the combination of variables
wstr are exchanged for the internal variables
clws by the program. These variables are the water stages cleaned from
w0ref reference level (
w0ref). This makes the criterion calculation more accurate, but note that relative criteria, e.g. relative bias, are now relative to the smaller cleaned water stage level.
|1/2/3/4||defines the period over which the data will be accumulated (i.e. no weighting on volume for concentrations) before calculating the performance criterion, i.e. criterion will be calculated from daily, weekly, monthly or annual values. 1-daily, 2-weekly, 3-monthly, 4-annually. Default is daily.|
|integer||defines smallest amount of observations required for the performance criteria to be calculated. Default is 3.|
|integer(s)||defines one or several SUBIDs which subbasins should be included in criteria calculations (optional). If not set all are used. One or several rows may be given.|
|ID string||a performance criterion to be calculated. See List of available performance criteria.|
|ID string||simulated variable to calculate criterion with. See List of output variables.|
|ID string||observed variable to calculate criterion with. See List of output variables.|
|numeric||weighting factor for the criteria if a combined criterion is to be calculated (should be a positive number)|
|numeric||parameter value used for RA-criteria coefficient value. See coefficient
|numeric||parameter value. Only used for DEMC-calibration. The parameter value is the threshold for the criterion.|
|name||name of the classgroup for which the simulated variable to calculate criterion with is to be taken. Note observed variables can not be specified on classgroup level. Suitable variable can be defined as e.g. xom1.|
The following example snippet combines a median Kling-Gupta performance measure for daily discharges and a mean relative bias for daily total nitrogen concentration observations at stations where at least 50 observations are available during the model period:
crit meanperiod 1 crit datalimit 50 crit 1 criterion MKG crit 1 cvariable cout crit 1 rvariable rout crit 1 weight 0.5 crit 2 criterion MRE crit 2 cvariable cctn crit 2 rvariable retn crit 2 weight 0.5
HYPE allows updating of simulated discharge and lake water level with observations during model run as well as updating of nitrogen and phosphorus concentrations using correction factors in individual subbasins. Discharge can be updated directly by discharge observations, by previously saved errors of simulated discharge, or previously saved errors of simulated lake water level. An auto-regressive (AR) model is used to model the errors for the last two methods. Lake water level can be updated by water level observations, or by previously saved errors of simulated lake water level.
|Code 1||Code 2||Argument||Description|
|none/keyword||updating of Q. Thereafter may follow one of the two keywords: 'allstation' for updating using all Q-stations in Qobs.txt or 'nostation' for no updating. If no keyword is given stations given in file update.txt is updated.|
|none/keyword||AR updating of Q on days without observed Q. Uses the switch(1/0) on column ‘qarupd’ in update.txt for on/off on individual stations. Can be followed by keyword 'nostation' for no AR updating.|
|none||updating of total phosphorus. No further keywords may be given. Which stations and how much is given in file update.txt.|
|none||updating of local phosphorus. No further keywords may be given. Which stations and how much is given in file update.txt.|
|none||updating of total nitrogen. No further keywords may be given. Which stations and how much is given in file update.txt.|
|none||updating of local nitrogen. No further keywords may be given. Which stations and how much is given in file update.txt.|
|none/keyword||updating of lake water levels from W observations. Thereafter there may follow one of the two keywords: 'allstation' for updating using all W-stations in Xobs.txt or 'nostation' for no updating.|
|none/keyword||AR updating of lake water level used to calculate Q. The lake water state variable is not updated. Uses the switch(1/0) on column ‘warupd’ in update.txt for on/off on individual stations. Can be followed by keyword 'nostation' for no AR updating|