Quick links to often-used pages:
Quick links to often-used pages:
info.txt files contains HYPE model options and output type specifications and 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 and resultdir, and time steps given after code steplength. Date-times are always specified as the beginning of the timestep.
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. Default is the same folder as info.txt. Relative path starts from the folder where you start the model.|
|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 folder where you start the model.|
|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 starting state is saved in the file state_saveyyyymmdd[HHMM].txt. The default is that no output state is written. Maximum 10 starting states (10 dates) may be written. The dates may be written on same or different rows. In the latter case with this code on every row.|
|string||gives the substances to be simulated. One or several of: N (inorganic (IN) and organic nitrogen (ON)), P (soluble reactive phosphorus (SP) and particulate phosphorus (PP)), C (organic carbon), S (suspended sediment (SS) and algae (AE)), T1 (tracers), 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. Substances may be given with either upper- or lower-case letters. 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 a model state through instate does not work with calibration.|
|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.|
|1/2||defines if model data and set-up files will be checked for formal errors prior to running the model. Default is to perform no checks. Available options are: checks on errors in info.txt, GeoData.txt, GeoClass.txt, and par.txt (1), or checks on forcing data files Pobs.txt/Pobs_nnn.txt, Tobs.txt/Tobs_nnn.txt, RHobs.txt, Qobs.txt, SFobs.txt, SWobs.txt, TMAXobs.txt, TMINobs.txt, UObs.txt, and ForcKey.txt/ForcKey_nnn.txt (2). NOTE that these checks are will not necessarily catch any possible error in the checked files. Disable option after successful checks to save model runtime.|
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/2||defines which model to use for floodplains. Default is none (0), alternative is a simple model (1) and a model with soilroutines (2) (both requires floodplain definition in input file FloodData.txt).|
|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||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||defines if an alternative snowfall model should be used. Default is threshold temperature (0), alternative is snowfall fraction from SFobs.txt (1).|
|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 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||defines if initialization from SLC+parameters overrides saved state of glacier volume (1). Default is to use saved state (0).|
|0/1||defines which infiltration model should be used. For infiltration model 1 infiltration (of snow melt) is limited by frozen soils.|
|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.|
HYPE offers three principal output types for standard model runs, all of which are formatted text files with tabular content which is controlled with code combinations in info.txt, as well as two further sets of output 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. If output with different mean period is to be had by the same output type, it is possible to number the outputs consequtively between the two codes. 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 meanperiods for the same type of output (basin- ,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 additional files will have a suffix to their name to separate them from the first group of files, e.g. timeCRUN_DD.txt.
|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. Only one period can be defined per type of output. The period is given using codes (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. Note: Period 5 aggregates are always means of annual aggregates. The type of aggregation is also documented in the list of variables in column 'Value'.
|integer||defines the number of significant figures written in the outputs.
Note: signfigures applies to all output variables within one output type. Default is zero and then a fixed number of decimals are used. If set, significant figures and mathematical format are used (e.g 9.5451E-03). Maximum allowed number of significant figures is 10.
|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.|
|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.|
The following example snippet give 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:
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
Mean period codes and corresponding file name suffix.
|The code give timesteply output, the suffix varies depending on time step length|
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/5||defines the period over which the performance criterion will be accumulated, i.e. daily, weekly, monthly or annually. 0-timesteply (for time step less than day), 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.|
|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.|
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|