====== 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:
  * **[[start:hype_file_reference:info.txt|info.txt]]**, which is the main instruction file of HYPE where all options are specified for a model simulation
  * **[[start:hype_file_reference:par.txt|par.txt]]**, which holds the values of model parameters
  * **[[start:hype_file_reference:info.txt:variables|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).

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


===== 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 [[.:HYPE_file_reference:NNobs.nc|NNobs.nc]].

All HYPE variable IDs are described in the **[[start:hype_file_reference:info.txt:variables|complete HYPE variable list]]**, while HYPE variable IDs useable in Xobs.txt are also described in the [[start:hype_file_reference:xobs.txt|Xobs.txt]] section.

Files for meteorological forcing data (found in ''forcingdir''):

<sortable 2>
^ File name ^ Requirement ^ Description ^
|[[.:HYPE_file_reference:Pobs.txt|Pobs.txt]]|mandatory|precipitation forcing (HYPE variable ID: prec)|
|[[.:HYPE_file_reference:Tobs.txt|Tobs.txt]]|mandatory|air temperature forcing (HYPE variable ID: temp)|
|[[.:HYPE_file_reference:RHobs.txt|RHobs.txt]]|optional|relative humidity forcing|
|[[.:HYPE_file_reference:SFobs.txt|SFobs.txt]]|optional|snowfall fraction of precipitation forcing|
|[[.:HYPE_file_reference:SWobs.txt|SWobs.txt]]|optional|shortwave radiation forcing|
|[[.:HYPE_file_reference:TMINobs.txt|TMINobs.txt]]|optional|daily minimum air temperature forcing|
|[[.:HYPE_file_reference:TMAXobs.txt|TMAXobs.txt]]|optional|daily maximum air temperature forcing|
|[[.:HYPE_file_reference:Uobs.txt|Uobs.txt]]|optional|wind speed forcing|
|[[.:HYPE_file_reference:UWobs.txt|UWobs.txt]]|optional|u-component of wind forcing|
|[[.:HYPE_file_reference:VWobs.txt|VWobs.txt]]|optional|v-component of wind forcing|
|[[.:HYPE_file_reference:NNobs.nc|NNobs.nc]]|optional|forcing data of all kinds|
</sortable>

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).

<sortable 2>
^ File name ^ Requirement ^ Description ^
|[[.:HYPE_file_reference:Qobs.txt|Qobs.txt]]|optional|discharge observations (HYPE variable ID: rout)|
|[[.:HYPE_file_reference:Xobs.txt|Xobs.txt]]|optional|observations of evaluation variables for subbasins, e.g. nutrient concentrations, lake water stage|
|[[.:HYPE_file_reference:Wobs.txt|Wobs.txt]]|optional|observations of olake water stage (alternative to Xobs.txt for HYPE variable ID: wstr)|
|[[.:HYPE_file_reference:Xoregobs.txt|Xoregobs.txt]]|optional|observations of evaluation variables for output regions, e.g. snow|
|[[.:HYPE_file_reference:Xcgobs.txt|Xcgobs_cgname.txt]]|optional|observations of evaluation variables for classgroup with name cgname for subbasins|
|[[.:HYPE_file_reference:XobsXOMn.txt|XobsXOMn.txt]]|optional|observations of evaluation variables, one per file (HYPE variable ID: xom0-xom9)|
|[[.:HYPE_file_reference:XobsXOSn.txt|XobsXOSn.txt]]|optional|observations of evaluation variables, one per file (HYPE variable ID: xos0-xos9)|
|[[.:HYPE_file_reference:NNNNobs.nc|Qobs.nc]]|optional|discharge observations (HYPE variable ID: rout)|
|[[.:HYPE_file_reference:NNNNobs.nc|NNNNobs.nc]]|optional|observations of evaluation variables for subbasins (HYPE variable ID: nnnn)|
|[[.:HYPE_file_reference:NNNNobs.nc|RGNNNNobs.nc]]|optional|observations of evaluation variables for output regions (HYPE variable ID: nnnn)|
|[[.:HYPE_file_reference:NNNNobs_cgname.nc|NNNNobs_cgname.nc]]|optional|observations of evaluation variables for classgroup with name cgname for subbasins (HYPE variable ID: nnnn)|
</sortable>

===== 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 **[[start:hype_file_reference:info.txt:variables|complete HYPE variable list]]**.


<sortable 2>
^ File name ^ Requirement ^ Description ^
|[[.:HYPE_file_reference:hyss_yymmddHHMM.log|hyss_seqnr_yymmdd_HHMM.log]]|automatic|log file, created for each model run|
|[[.:HYPE_file_reference:tests_yymmddHHMM.log|tests_seqnr_yymmdd_HHMM.log]]|automatic|log file, created for model tests|
|[[.:HYPE_file_reference:XXXXXXX.txt|XXXXXXX.txt]]|optional|basin output file, several output variables for one subbasin (subid=XXXXXXX)|
|[[.:HYPE_file_reference:XXXXXXX.txt(regional)|XXXXXXX.txt (regional)]]|optional|region output file, several output variables for one output region (outregid=XXXXXXX)|
|[[.:HYPE_file_reference:timeXXXX.txt|timeXXXX.txt]]|optional|time output file, output of single variable (HYPE variable ID=XXXX) for all subbasins|
|[[.:HYPE_file_reference:mapXXXX.txt|mapXXXX.txt]]|optional|map output file, output of single variable (HYPE variable ID=XXXX) for all subbasins, formatted for GIS|
|[[.:HYPE_file_reference:class_output|XXXXXXX.txt or timeXXXX.txt (class)]]|optional|class 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|
|[[.:HYPE_file_reference:timeXXXX.nc|timeXXXX.nc]]|optional|time output file in netcdf format, output of single variable (HYPE variable ID=XXXX) for all subbasins|
|[[.:HYPE_file_reference:subassX.txt|subassX.txt]]|optional|subbasin assessment, performance criteria for subbasins|
|[[.:HYPE_file_reference:simass.txt|simass.txt]]|optional|simulation assessment, summarising performance criteria over model domain|
|[[.:HYPE_file_reference:yyyy_ss.txt|yyyy_ss.txt]]|optional|result files with annual nutrient transports per subbasin and source|
|[[.:HYPE_file_reference:Wbf_xxx.txt|Wbf_xxx.txt]]|optional|water balance: flows per subbasin and day|
|[[.:HYPE_file_reference:Wbff_xxx.txt|Wbff_xxx.txt]]|optional|water balance: floodplain related flows per subbasin and day|
|[[.:HYPE_file_reference:Wbfs_xxx.txt|Wbfs_xxx.txt]]|optional|water balance: irrigation flows per subbasin and day|
|[[.:HYPE_file_reference:Wbs_xxx.txt|Wbs_xxx.txt]]|optional|water balance: storage per subbasin and day|
|[[.:HYPE_file_reference:state_save|state_saveyyyymmdd[HHMM] ]]|optional|files containing saved model states for model initialisation|
|[[.:HYPE_file_reference:reset_state_save|reset_state_save.txt]]|optional|file initial state values of soild nutrient soil states (eg. fastN,humusN).|
|[[.:HYPE_file_reference:daens_staten|nnnnnn_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved model states and variables for data assimilation (one file per variable)|
|[[.:HYPE_file_reference:ensxstates.bin|ensXstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved model states for data assimilation|
|[[.:HYPE_file_reference:ensfstates.bin|ensFstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved forcing variables for data assimilation|
|[[.:HYPE_file_reference:ensastates.bin|ensAstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved auxiliary variables for data assimilation|
</sortable>

===== 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 [[.:HYPE_file_reference:info.txt|info.txt]] where the objective function for the optimization (see [[.:HYPE_file_reference:info.txt#performance_criteria_options|performance criteria]]) is set and calibration turned on.

All HYPE variable IDs used in HYPE calibration files are described in the **[[start:hype_file_reference:info.txt:variables|complete HYPE variable list]]**.


<sortable>
^ File name ^ Requirement ^ Description ^
|[[.:HYPE_file_reference:optpar.txt|optpar.txt]]|optional (mandatory for calibration)|calibration simulation settings including parameter ranges|
|[[.:HYPE_file_reference:qNstartpar.txt|qNstartpar.txt]]|optional|starting values for parameter optimization using quasiNewton methods (including Brent)|
|[[.:HYPE_file_reference:respar.txt|respar.txt]]|optional|optimal parameter values of calibration|
|[[.:HYPE_file_reference:bestsims.txt|bestsims.txt]]|optional|best performance criteria and parameter values of calibration|
|[[.:HYPE_file_reference:allsim.txt|allsim.txt]]|optional|performance results (criteria and parameter values) of all runs during calibration|
|[[.:HYPE_file_reference:calibration.log|calibration.log]]|automatic|calibration log file|
</sortable>

===== Data assimilation files =====

Data assimilation files are files related to setup and results. Additional data assimilation information is given in [[.:HYPE_file_reference:info.txt|info.txt]].

All HYPE variable IDs used in HYPE assimilation files are described in the **[[start:hype_file_reference:info.txt:variables|complete HYPE variable list]]**.


<sortable>
^ File name ^ Requirement ^ Description ^
|[[.:HYPE_file_reference:AssimInfo.txt|AssimInfo.txt]]|optional (mandatory for data assimilation)|data assimilation simulation settings|
|[[.:HYPE_file_reference:daens_staten|nnnnnn_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved model states and variables for data assimilation (one file per variable)|
|[[.:HYPE_file_reference:ensxstates.bin|ensXstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved model states for data assimilation|
|[[.:HYPE_file_reference:ensfstates.bin|ensFstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved forcing variables for data assimilation|
|[[.:HYPE_file_reference:ensastates.bin|ensAstates_yyyymmdd[HHMM].bin]]|optional|files containing an ensemble of saved auxiliary variables for data assimilation|
</sortable>

===== 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. 


<sortable 2>
^ File prefix ^ Type ^ Unit ^ Description ^
|WBs|store|//m<sup>3</sup>//|water volume in each store for each time step for all subbasins or for selected subbasins (irrigation, floodplains) or for aquifers|
|WBf|flow|//m<sup>3</sup> ts<sup>-1</sup>//|horizontal flows between subbasins and regional groundwater flows|
|WBf|flow|//m<sup>3</sup> ts<sup>-1</sup>//|vertical or horizontal flows within subbasin|
|WBfs/WBf|flow|//m<sup>3</sup> ts<sup>-1</sup>//|water management flows; irrigation (WBfs) for selected subbasins, water transfer flow (WBf) and point sources (WBf) for all subbasins|
|WBff|flow|//m<sup>3</sup> ts<sup>-1</sup>//|floodplain related flows|
</sortable>

A description of the water balance files can be downloaded ([[.:HYPE_file_reference:printwaterbal.txt|HYPE water balance]]).