User Tools

Site Tools


start:hype_file_reference:info.txt

This is an old revision of the document!


info.txt

General

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:

  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.

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
modeldir directory path Gives the search path to all model input files, with exception of forcing data and initial state if forcingdir is set. Default is the same folder as info.txt. Relative path starts from the info-file folder.
forcingdir directory path Gives the search path to forcing files (Pobs, Qobs etc. and ForcKey) and initial state file. Default is modeldir. Relative path starts from the info-file folder.
resultdir 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.
bdate date-time Gives the start date for simulation. Format: yyyy-mm-dd [HH:MM].
cdate date-time Gives the start date for the output of results and calculations of criteria. Format: yyyy-mm-dd [HH:MM]. Defaults to bdate.
edate date-time Gives the last date for the simulation (including this date). Format: yyyy-mm-dd [HH:MM].
steplength 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.
instate 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 bdate.
outstatedate 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.
substance 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.
calibration 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 soilstretch functionality.
regestimate 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.
readformat 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
writeformat 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.
readoutregion Y/N defines if Outregions.txt is present and should be used. Give Y to use the file, or N (default).
resseqnr 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.
readdaily 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.
readobsid 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.
readsfobs 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).
readswobs 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).
readuobs 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 readwind.
readrhobs 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 readhumid.
readtminobs 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 readtminmaxobs.
readtmaxobs 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 readtminmaxobs.
readxomsfiles 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).
submodel 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.
irrrunlimited 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
soiliniwet Y/N initiates soil water to porosity instead of field capacity which is default (N). Set Y to use porosity.
soilstretch Y/N define if parameter soilcorr shall be used to stretch the soil depths given by GeoClass.txt.
modeloption 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.
indatacheckonoff 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.
indatachecklevel 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
usestop84 Y/N flag to use the old return code 84 for a successful run

Model options

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).
floodmodel0/1/2/3defines 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).
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/5defines 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/1/2/3defines 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.
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.
wetlandmodel0/1defines if wetland model is to be simulated. Default (0) is no wetland model, (1) is river wetland nutrient model.
soilleakage0/1defines if soil leakage concentrations is to be calculated or read from file. Default (0) is calculation, (1) is reading monthly values for each subbasin.

Output options

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:

  • 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.
  • class outout, which return multiple variables for a single subcatchment in one file or single variables for all sub-catchments in one file. The class output are thus similar to basin- and timeoutput, but the variables are for a specified group of classes. The file names has an extra suffix with the classgroup name.
  • 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 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
basinoutput
mapoutput
timeoutput
regionoutput
classoutput
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
classoutput
meanperiod0/1/2/3/4/5is given to define the period to which results are aggregated for the 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 'Agg.'.
basinoutput
mapoutput
timeoutput
regionoutput
classoutput
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
classoutput
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).
basinoutput
classoutput
allbasinNONEdefines that output is to be written for all subbasins. No further arguments.
basinoutput
classoutput
subbasinintegerdefines 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.
classoutputgroupname string(s)defines which class groups are to be printed for this output. Leave out if default class groups are used.
classoutputdefinegroupname string, integer(s)defines which slc-classes are included in the classgroup with this name. The name may be up to 6 letters.
classoutputdefinegroupallclassdefine default groups should be used for all classoutput. This means one class per classgroup.
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, while the runoff file from the first group is called timeCRUN_MO.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/4defines 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.
critdatalimitintegerdefines smallest amount of observations required for the performance criteria to be calculated. Default is 3.
critsubbasininteger(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.
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.
crit ncgroupnamename 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

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.1542378095.txt.gz · Last modified: 2023/11/16 14:28 (external edit)