User Tools

Site Tools


start:hype_file_reference

HYPE file reference

This part of the HYPE documentation is a reference guide to all mandatory and optional HYPE files. HYPE works with plain text files for model setup, data input/output, and calibration.

The tables in the following sections contain file names and short descriptions of mandatory and optional input and output files for HYPE, grouped by content type. More detailed descriptions on file content, format and requirements are found in the section of each file.

Input files marked mandatory in the tables below must exist for a basic HYPE setup. Other files are required only for optional model components, e.g. glaciers, or for specific model tasks, e.g. parameter calibration.

As a shortcut, here are three links to frequently used references when running an existing HYPE setup:

  • info.txt, which is the main instruction file of HYPE where all options are specified for a model simulation
  • par.txt, which holds the values of model parameters
  • HYPE variables, a list of variable names used for HYPE inputs and outputs

Setup files

Setup files contain information about a HYPE model domain, model parameters, model options (model choice and simulation settings).

File name Requirement Description
filedir.txt optional provides location of info.txt
info.txt mandatory model options and simulation settings
AssimInfo.txt optional/mandatory settings for data assimilation simulation
pmsf.txt optional partial model setup, defines part of model domain to simulate
update.txt optional for updating of model variables with observations
GeoClass.txt mandatory SLC class definition (HRUs)
ClassData.txt optional SLC class definition (HRUs), replaces GeoClass.txt for traveltime soil model
GeoData.txt mandatory subcatchment characteristics and flow connections between them
BranchData.txt optional bifurcations in the flow network
LakeData.txt optional properties of specific lakes (including regulated dams)
DamData.txt optional properties of specific regulated lakes, extends LakeData.txt
CropData.txt optional information about crops and vegetation
PointSourceData.txt optional information about point sources and water abstraction
PSTIMESeries.txt optional daily, monthly or yearly time-series of point sources and water abstractions
MgmtData.txt optional information about irrigation and water transfer
AquiferData.txt optional information about regional aquifers
FloodData.txt optional information about floodplain
GlacierData.txt optional information about glaciers
par.txt mandatory model parameters, some is calibrated
state_save optional files containing saved model states for model initialisation
reg_par.txt optional file containing regional regression coefficients, for parameter regionalization method
CatchDes.txt optional list of catchment descriptors, for parameter regionalization method
CatchGroup.txt optional list of catchment group membership of all subbasins, for parameter regionalization method
Outregions.txt optional information about output regions
ForcKey.txt optional link list between subcatchment IDs and forcing data IDs, as well as temperature observation elevations
LeakageData.txt optional soil leakage concentrations to replace subbasin runoff concentrations
LeakNN_SLCNNN.txt optional soil leakage concentrations from root zone
LoadNN_SLCNNN.txt optional soil leakage loads for travel time soil model
RiverRatingCurveData.txt optional rating curves for main river
AtmdepData.txt optional atmospheric deposition
nnnnnn_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states and variables for data assimilation
ensXstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states for data assimilation
ensFstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved forcing variables for data assimilation
ensAstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved auxiliary variables for data assimilation

Observation data files

Observation data files are HYPE input files which contain time series, both forcing data and evaluation data. Observation files are in the form of text files. Forcing data in the form of netcdf files, see NNobs.nc.

All HYPE variable IDs are described in the complete HYPE variable list, while HYPE variable IDs useable in Xobs.txt are also described in the Xobs.txt section.

Files for meteorological forcing data (found in forcingdir):

File name Requirement Description
Pobs.txtmandatoryprecipitation forcing (HYPE variable ID: prec)
Tobs.txtmandatoryair temperature forcing (HYPE variable ID: temp)
RHobs.txtoptionalrelative humidity forcing
SFobs.txtoptionalsnowfall fraction of precipitation forcing
SWobs.txtoptionalshortwave radiation forcing
TMINobs.txtoptionaldaily minimum air temperature forcing
TMAXobs.txtoptionaldaily maximum air temperature forcing
Uobs.txtoptionalwind speed forcing
UWobs.txtoptionalu-component of wind forcing
VWobs.txtoptionalv-component of wind forcing
NNobs.ncoptionalforcing data of all kinds

Files for other observations for evaluation (found in otherobsdir, or if not set in forcingdir). Observations in the form of netcdf files are optional, but all observations files must have the same file format (set in info.txt).

File name Requirement Description
Qobs.txtoptionaldischarge observations (HYPE variable ID: rout)
Xobs.txtoptionalobservations of evaluation variables for subbasins, e.g. nutrient concentrations, lake water stage
Wobs.txtoptionalobservations of olake water stage (alternative to Xobs.txt for HYPE variable ID: wstr)
Xoregobs.txtoptionalobservations of evaluation variables for output regions, e.g. snow
Xcgobs_cgname.txtoptionalobservations of evaluation variables for classgroup with name cgname for subbasins
XobsXOMn.txtoptionalobservations of evaluation variables, one per file (HYPE variable ID: xom0-xom9)
XobsXOSn.txtoptionalobservations of evaluation variables, one per file (HYPE variable ID: xos0-xos9)
Qobs.ncoptionaldischarge observations (HYPE variable ID: rout)
NNNNobs.ncoptionalobservations of evaluation variables for subbasins (HYPE variable ID: nnnn)
RGNNNNobs.ncoptionalobservations of evaluation variables for output regions (HYPE variable ID: nnnn)
NNNNobs_cgname.ncoptionalobservations of evaluation variables for classgroup with name cgname for subbasins (HYPE variable ID: nnnn)

Output files

Output files contain model results. This includes time series of simulations and observations (for each time step or averaged/summed over a longer period) as well as model performance results.

All HYPE variable IDs used in HYPE output files are described in the complete HYPE variable list.

File name Requirement Description
hyss_seqnr_yymmdd_HHMM.logautomaticlog file, created for each model run
tests_seqnr_yymmdd_HHMM.logautomaticlog file, created for model tests
XXXXXXX.txtoptionalbasin output file, several output variables for one subbasin (subid=XXXXXXX)
XXXXXXX.txt (regional)optionalregion output file, several output variables for one output region (outregid=XXXXXXX)
timeXXXX.txtoptionaltime output file, output of single variable (HYPE variable ID=XXXX) for all subbasins
mapXXXX.txtoptionalmap output file, output of single variable (HYPE variable ID=XXXX) for all subbasins, formatted for GIS
XXXXXXX.txt or timeXXXX.txt (class)optionalclass output files, several output variables for a single subbasin or output of single variable for all subbasins, both file variants for a single class or class group
timeXXXX.ncoptionaltime output file in netcdf format, output of single variable (HYPE variable ID=XXXX) for all subbasins
subassX.txtoptionalsubbasin assessment, performance criteria for subbasins
simass.txtoptionalsimulation assessment, summarising performance criteria over model domain
yyyy_ss.txtoptionalresult files with annual nutrient transports per subbasin and source
Wbf_xxx.txtoptionalwater balance: flows per subbasin and day
Wbff_xxx.txtoptionalwater balance: floodplain related flows per subbasin and day
Wbfs_xxx.txtoptionalwater balance: irrigation flows per subbasin and day
Wbs_xxx.txtoptionalwater balance: storage per subbasin and day
state_saveyyyymmdd[HHMM] optionalfiles containing saved model states for model initialisation
reset_state_save.txtoptionalfile initial state values of soild nutrient soil states (eg. fastN,humusN).
nnnnnn_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states and variables for data assimilation (one file per variable)
ensXstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states for data assimilation
ensFstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved forcing variables for data assimilation
ensAstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved auxiliary variables for data assimilation

Calibration files

Calibration files are files related to the parameter calibration model option in HYPE, both for setup and results. Additional calibration information is given in info.txt where the objective function for the optimization (see performance criteria) is set and calibration turned on.

All HYPE variable IDs used in HYPE calibration files are described in the complete HYPE variable list.

File name Requirement Description
optpar.txtoptional (mandatory for calibration)calibration simulation settings including parameter ranges
qNstartpar.txtoptionalstarting values for parameter optimization using quasiNewton methods (including Brent)
respar.txtoptionaloptimal parameter values of calibration
bestsims.txtoptionalbest performance criteria and parameter values of calibration
allsim.txtoptionalperformance results (criteria and parameter values) of all runs during calibration
calibration.logautomaticcalibration log file

Data assimilation files

Data assimilation files are files related to setup and results. Additional data assimilation information is given in info.txt.

All HYPE variable IDs used in HYPE assimilation files are described in the complete HYPE variable list.

File name Requirement Description
AssimInfo.txtoptional (mandatory for data assimilation)data assimilation simulation settings
nnnnnn_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states and variables for data assimilation (one file per variable)
ensXstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved model states for data assimilation
ensFstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved forcing variables for data assimilation
ensAstates_yyyymmdd[HHMM].binoptionalfiles containing an ensemble of saved auxiliary variables for data assimilation

Water balance files

A set of output files giving subbasin water balance. The water balance is calculated for each time step and subbasin, and one file holds one flow or store.

File prefix Type Unit Description
WBsstorem3water volume in each store for each time step for all subbasins or for selected subbasins (irrigation, floodplains) or for aquifers
WBfflowm3 ts-1horizontal flows between subbasins and regional groundwater flows
WBfflowm3 ts-1vertical or horizontal flows within subbasin
WBfs/WBfflowm3 ts-1water management flows; irrigation (WBfs) for selected subbasins, water transfer flow (WBf) and point sources (WBf) for all subbasins
WBffflowm3 ts-1floodplain related flows

A description of the water balance files can be downloaded (HYPE water balance).

start/hype_file_reference.txt ยท Last modified: 2024/02/15 09:39 by cpers