4.4.1. Format and structure of the control file

The configuration file controls all user-adjustable settings for EF5, including input forcings, output options, and run methods. It is generally case insensitive (except for file paths on case-sensitive systems). Three styles of comments are supported: bash (#), C (/* */), and C++ (//).

This is an example of comments in the control file:

# All variables (except file paths) are case insensitive
// Multiple comment types are supported
/*
   Including multi-line C-style comments
*/

4.4.1.1. Format and taxonomy information

Tiff files requirements:

  1. -9999 as nodata value.

  2. No TILED format.

  3. float32 data type.

  4. The ESRI flow direction convention must be restricted to the following values: 1, 2, 4, 8, 16, 32, 64, and 128.

4.4.1.1.1. About time taxonomy

EF5 uses a time taxonomy to define the simulation period and timestep. The time format is specified in the configuration file, allowing for flexible simulation periods. This time taxonomy is also used in the precipitation and PET forcing files names.

TIMESTEP, TIME_BEGIN, TIME_END and tiff-file names

Simulation timing parameters. The timestep is the time interval for the simulation, and the begin and end times define the simulation period.

The time format is YYYYMMDDHHUU, where YYYY is the year, MM is the month, DD is the day, HH is the hour, and UU is the minute.

For time step, where d is for day step, h is for hour step, and u is for minute step.

4.4.1.2. Blocks

The control file is structured into blocks, each containing key-value pairs. Each block is defined by a header in square brackets, and the key-value pairs are separated by an equals sign (=).

4.4.1.2.1. Basic block

Specifies file locations for the digital elevation model (DEM), drainage direction map (DDM), and flow accumulation map (FAM).

[Basic]
DEM=/EF5Demo/FF/basic/DEM.asc
DDM=/EF5Demo/FF/basic/DDM.asc
FAM=/EF5Demo/FF/basic/FAM.asc
PROJ=laea
ESRIDDM=true
SELFFAM=true

4.4.1.2.2. Precipitation block

Defines the properties of the precipitation forcing files. EF5 considers the indicated layer units to be consistent with the simulation timestep.

[PrecipForcing Q2Precip]
TYPE=BIF
UNIT=mm/h
FREQ=5u
LOC=/EF5Demo/FF/precip
NAME=Q2_YYYYMMDDHHUU.bif

4.4.1.2.3. Potential Evapotranspiration (PET) block

Defines the PET forcing file details. EF5 considers the indicated layer units to be consistent with the simulation timestep.

[PETForcing PET]
TYPE=BIF
UNIT=mm/h
FREQ=m
LOC=/EF5Demo/FF/pet
NAME=PET_MM.bif

4.4.1.2.4. Gauge locations block(s)

Each gauge information is defined in a separate block, with the block name being the gauge identifier. The gauge identifier is used to reference the gauge in other blocks, such as the basin block. The gauge location block specifies the locations of gauges for output and parameter assignment. OUTPUTTS is an optional parameter that, when set to TRUE, indicates that the gauge will output time series data. OBS is an optional parameter that specifies the path to the observed data file for the gauge. OBS is required if the gauge will be used for calibration task. The BASINAREA parameter is also optional and indicates the area of the basin in square kilometers. When BASINAREA is indicated, EF5 will compare the basin area with the area of the flow accumulation map (FAM) to ensure they match. If they do not match, EF5 will look for nearest flow accumulation within a threshold. If no match is found, EF5 will raise a warning.

[Gauge OKC]
LON=-97.01
LAT=35.68
OBS=/EF5Demo/obs/okc.csv
BASINAREA=341.88
OUTPUTTS=TRUE

[Gauge AR]
LON=-93.62
LAT=34.37

4.4.1.2.5. Basin block(s)

Groups gauge locations into basins. The user can define multiple basins, each with its own set of gauges. This block doesn’t follow the classic basin definition, but rather groups gauges that are required by the user for a specific task. The basin block is used to define the basin name and the gauges that belong to it. The basin name is used to reference the basin in other blocks, such as the task block.

[Basin FF]
GAUGE=OKC
GAUGE=AR

4.4.1.3. Parameter Sets

The gauge parameter specifies the gauge identifier for which the parameters are defined. The user must specify at least the set of parameters for one gauge and use them for the entire domain, or can specify parameters for multiple gauges in the same block.

There are two ways to define parameters for a basin:

  1. Lumped (aggregated) parameter sets: Each parameter corresponds to a single (scalar) value. This is the traditional way of defining parameters for hydrological models.

  2. Distributed (grided) parameter sets: Parameters are defined in a grid format, where each parameter corresponds to a grid file. Grided parameters could be identified by _grid suffix in the parameter name. After the grided files are defined, the user must specify the parameters multiplier values for each grid, using the lumped parameter name without the _grid suffix.

Additional information about the parameters definition and units could be found in the calibration section.

_images/Parameters_definition.png

Guidance on how to interpret lumped and distributed parameters.

4.4.1.3.1. Hydrologic Water Balance Models

The listed water balance models are explained in detail in the water balance models section.

  1. CREST Parameter Set

  2. SAC-SMA Parameter Set

4.4.1.3.2. Routing Models

The listed routing models are explained in detail in the routing models section.

  1. Linear Reservoir Parameter Set

  2. Kinematic Wave Parameter Set

4.4.1.4. Snow-17 Parameter Set

Defines the parameters for the Snow-17 model.

[snow17paramset tarbela]
GAUGE=tarbela
UADJ=0.184653
MBASE=0.047224
MFMAX=1.068658
MFMIN=0.516059
TIPM=0.911706
NMF=0.077336
PLWHC=0.093812
SCF=2.219492

4.4.1.5. Full control file example

This is a full EF5 control file example for a basic simulation using the CREST model. It includes the basic block, precipitation forcing, PET forcing, gauge locations, basin definition, parameter set for CREST, and a task to run the simulation.

[Basic]
DEM=/EF5Demo/FF/basic/DEM.asc
DDM=/EF5Demo/FF/basic/DDM.asc
FAM=/EF5Demo/FF/basic/FAM.asc
PROJ=laea
ESRIDDM=true

[PrecipForcing Q2Precip]
TYPE=BIF
UNIT=mm/h
FREQ=5u
LOC=/EF5Demo/FF/precip
NAME=Q2_YYYYMMDDHHUU.bif

[PETForcing PET]
TYPE=BIF
UNIT=mm/h
FREQ=m
LOC=/EF5Demo/FF/pet
NAME=PET_MM.bif

[Gauge OKC]
LON=-97.01
LAT=35.68
OBS=/EF5Demo/obs/okc.csv

[Gauge AR]
LON=-93.62
LAT=34.37

[Basin FF]
GAUGE=OKC
GAUGE=AR

[CrestParamSet FF]
GAUGE=AR
COEM=24.230076 EXPM=0.502391 RIVER=1.73056
UNDER=0.291339 LEAKO=0.56668 LEAKI=0.251648
TH=63.20205 GM=1.364364 PWM=71.96465
PB=0.964355 PIM=6.508687 PKE=0.19952
PFC=2.578529 IWU=53.52593 ISO=5.899539
ISU=17.31128
GAUGE=OKC
COEM=24.230076 EXPM=0.502391 RIVER=1.73056
UNDER=0.291339 LEAKO=0.56668 LEAKI=0.251648
TH=63.20205 GM=1.364364 PWM=71.96465
PB=0.964355 PIM=6.508687 PKE=0.19952
PFC=2.578529 IWU=53.52593 ISO=5.899539
ISU=17.31128

[Task RunFF]
STYLE=SIMU
MODEL=CREST
BASIN=FF
PRECIP=Q2_PRECIP
PET=PET
OUTPUT=/EF5Demo/FF/output/
OUTPUT_GRIDS=MAXUNITSTREAMFLOW|MAXSTREAMFLOW|PRECIPACCUM|INUNDATION|MAXINUNDATION # Refer to
PARAM_SET=FF
TIMESTEP=5u
TIME_BEGIN=201006010000
TIME_END=201006010030

[Execute]
TASK=RunFF

Warning

🚧 This documentation is currently under active development. Content may change frequently and some sections may be incomplete.