User Tools

Site Tools


start:hype_file_reference:info.txt

info.txt

General

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:

  1. Model options, e.g. specification of time stepping, choice of optional modules, etc.
  2. Output options, i.e. type of result files and output variable specification
  3. Performance criteria options, i.e. specification of objective functions and criteria computation
  4. Updating options, specification of optional updating of subcatchment output variables with measurements

Conventionally, info files are sorted according to this order. The following tables describe all possible codes, grouped in the above order.

Model options

In order to write output files of results for other than daily time steps or the whole simulation period, bdate, cdate, and 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.

Code Argument Description
modeldirdirectory pathGives 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.
resultdirdirectory pathGives 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.
bdatedate-timeGives the start date for simulation. Format: yyyy-mm-dd [HH:MM].
cdatedate-timeGives the start date for the output of results and calculations of criteria. Format: yyyy-mm-dd [HH:MM]. Defaults to bdate.
edatedate-timeGives the last date for the simulation (including this date). Format: yyyy-mm-dd [HH:MM].
steplengthstringdefines 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.
instateY/Ndefines 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 bdate.
outstatedatedate-timedefines 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.
substancestringgives 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.
calibrationY/Ndefines 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.
regestimateY/Ndefines 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.
readformat0/1handles 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
writeformat0/1Set to 1 to write output in a format suitable for MATLAB (i.e. date without ‘-‘, ‘%’ in front of the column headings). Default is 0.
readoutregionY/Ndefines if Outregions.txt is present and should be used. Give Y to use the file, or N (default).
resseqnrY/Ndetermines 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.
readdailyY/Ndefines 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.
readobsidY/Ndefines 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.
readsfobsY/Ndefines if SFobs.txt with observed snowfall fractions is present and should be used. Give Y to use the file, or N (default).
readswobsY/Ndefines if SWobs.txt with observed shortwave radiation is present and should be used. Give Y to use the file, or N (default).
readuobsY/Ndefines if Uobs.txt with observed wind speeds is present and should be used. Give Y to use the file, or N (default). Replaces readwind.
readrhobsY/Ndefines if RHobs.txt with observed relative humidity is present and should be used. Give Y to use the file, or N (default). Replaces readhumid.
readtminobsY/Ndefines if TMINobs.txt with observed min air temperatures are present and should be used. Give Y to use the file, or N (default). Replaces readtminmaxobs.
readtmaxobsY/Ndefines if TMAXobs.txt with observed max air temperatures are present and should be used. Give Y to use the file, or N (default). Replaces readtminmaxobs.
readxomsfilesY/Ndefines 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).
submodelY/Ndefines 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.
irrrunlimitedY/Ndefines 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
soiliniwetY/Ninitiates soil water to porosity instead of field capacity which is default (N). Set Y to use porosity.
soilstretchY/Ndefine if parameter soilcorr shall be used to stretch the soil depths given by GeoClass.txt.
modeloptionprocessmodel #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.
check indata1/2defines 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.

Code 2 Argument Description
deepground0/1/2defines 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).
floodplain0/1/2defines 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).
growthstartmodel0/1defines 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).
lakeriverice0/1/2defines 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.
petmodel0/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).
snowdensity0/1defines which snowdensity model to use. Default is snow age dependent snowdensity (0), and alternative is snow compactation snow density model (1).
snowevaporation0/1defines 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.
snowfallmodel0/1defines if an alternative snowfall model should be used. Default is threshold temperature (0), alternative is snowfall fraction from SFobs.txt (1).
snowmeltmodel0/2defines 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.
swtemperature0/1defines 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.
glacierini0/1defines if initialization from SLC+parameters overrides saved state of glacier volume (1). Default is to use saved state (0).
infiltration0/1defines which infiltration model should be used. For infiltration model 1 infiltration (of snow melt) is limited by frozen soils.
erosionmodel0/1defines 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.

Output options

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:

  • basin outputs, which return multiple variables for a single subcatchment in one file XXXXXXX.txt per subcatchment, where 'XXXXXXX' is the ID of the subcatchment, a number with maximum 7 digits (filled with leading zeros in case of shorter ID, e.g. 0001234.txt).
  • region outputs, similar to basin outputs (return multiple variables for a single region in one file) XXXXXXX.txt, where 'XXXXXXX' is the ID of the output region (must not overlap subids).
  • time outputs, which return single variables for all sub-catchments in one file timeXXXX.txt per variable, where 'XXXX' is the four-letter variable ID, e.g. timeCOUT.txt.
  • map outputs, which also return single variables for all sub-catchments in one file, mapXXXX.txt per variable, similar to time outputs but transposed, which makes it easier to connect the results to sub-catchment maps/GIS layers.
  • annual loads of nitrogen and phosphorus
  • water balances of subbasin water stores for each time step

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
basinoutput
mapoutput
timeoutput
regionoutput
variableID 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.
basinoutput
mapoutput
timeoutput
regionoutput
meanperiod0/1/2/3/4/5is 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'.
basinoutput
mapoutput
timeoutput
regionoutput
signfiguresintegerdefines 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.
basinoutput
mapoutput
timeoutput
regionoutput
decimalsintegerdefines 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 basinoutput combination, because a small number variable can require such a large number of decimals to give meaningful precision that the total number of digits of the large number variable exceeds HYPE's maximum output width, resulting in the printing of '****************' strings. A typical example is a combination of substance loads (kg/year) and discharge (m3/s).
basinoutputallbasinNONEdefines that output is to be written for all subbasins. No further arguments.
basinoutputsubbasinintegerdefines one or several SUBIDs (subcatchment IDs) for which output is to be written. One or several rows may be given.
regionoutputoutregionintegerdefines 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.
printloadY/Ndefines if output of annual loads is to be written. Y for load output. Default is N.
printwaterbalY/Ndefines 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.

Code Suffix Description
0TS / HR / DDThe code give timesteply output, the suffix varies depending on time step length
1DDdaily
2WKweekly
3MOmonthly
4YRyearly
5SPsimulation period
TStimesteply
HRhourly

Performance criteria options

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 cdate and edate, see Model options.

Performance criteria are specified in info.txt with code crit or 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 wcom and wstr are exchanged for the internal variables clwc and clws by the program. These variables are the water stages cleaned from w0ref reference level (clwc= wcom-w0ref, clws=wstr-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.

Code_1 Code 2 Argument Description
critmeanperiod1/2/3/4/5defines 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.
critdatalimitintegerdefines smallest amount of observations required for the performance criteria to be calculated. Default is 3.
crit ncriterionID stringa performance criterion to be calculated. See List of available performance criteria.
crit ncvariableID stringsimulated variable to calculate criterion with. See List of output variables.
crit nrvariableID stringobserved variable to calculate criterion with. See List of output variables.
crit nweightnumericweighting factor for the criteria if a combined criterion is to be calculated (should be a positive number)
crit nparameternumericparameter value used for RA-criteria coefficient value. See coefficient a in RA equation definition.
crit nconditionalnumericparameter 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

Updating options

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.

The updating methods are described in detail in the tutorial. Some updating routines require further settings in additional input file update.txt.

Code 1 Code 2 Argument Description
updatequseobsnone/keywordupdating 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.
updateqarnone/keywordAR 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.
updatetpcorrnoneupdating of total phosphorus. No further keywords may be given. Which stations and how much is given in file update.txt.
updatetploccorrnoneupdating of local phosphorus. No further keywords may be given. Which stations and how much is given in file update.txt.
updatetncorrnoneupdating of total nitrogen. No further keywords may be given. Which stations and how much is given in file update.txt.
updatetnloccorrnoneupdating of local nitrogen. No further keywords may be given. Which stations and how much is given in file update.txt.
updatewendupd wstrnone/keywordupdating 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.
updatewar wstrnone/keywordAR 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
start/hype_file_reference/info.txt.txt · Last modified: 2017/08/23 16:44 by cpers