Configuration files: general tips

2. Configuration files: general tips#

Configuration files are used to initialize variables, assign file names, or choose options to run hydrological simulations. Configuration files follow the INI file format. INI files are plain text files with a basic structure composed of sections and subsections, properties, and values.

The basic element contained in an INI file is the key or property. Every key has a name and a value, delimited by an equals sign (=). Order of key-value pairs is arbitrary (i.e. there’s no need to pay attention to the position of lines in a file). The name appears to the left of the equals sign:

Example of name-value pair

name = value

Keys may be grouped into arbitrarily named sections or subsections. The section name appears on a line by itself, in square brackets ([ and ]). All keys after the section declaration are associated with that section. The subsection name appears on a line by itself, in double square brackets ([[ and ]]). All keys after the subsection declaration are associated with that subsection. Properties that are declared before any section and subsection are declared are considered “global” properties.

Hash (#) at the beginning or in the middle of the line indicates a comment. Comment lines are ignored.

Example of INI file with two sections and one subsection and comments.

name1 = value
name2 = value
# comment
[section1]
  name1 = value # comment
  name2 = value
 [[subsection]]
   name1 = value
   name2 = value

[section2]
  name1 = value
  name2 = value
  name3 = value

2.1. Assigning a map as input#

A common means to assign maps in FEST configuration files is by setting a section ( within square brakets [ ] ) or subsection ( within double square brakets [[ ]] ) that specifies the file to read, the format and optional properties that change according to the specified format. Supported formats are: esri-ascii, esri-binary, and net-cdf. For esri ascii and binary formats, spatial reference system is assigned by setting epsg property.

Example of section that defines a map in esri-ascii format with spatial reference system UTM 32 north wgs84 (EPSG code 3003).

[dem]  # section named dem defining a map
    file = ./data/dem.asc
    format = esri-ascii 
    epsg = 3003

NetCDF is the preferred format when a parameter is assumed to change during simulation time span, like in the case of leaf area index for vegetation, or the snow melt coefficient. When NetCdf format is assigned as input map, different options must or can be assigned in order to properly read the map. The variable to be read can be assigned by variable name (variable = ) or its standard name (standard_name = ). The first map to be read can be assigned by specifying a date and time (time = YYYY-MM-DDThh:mm:ss+hh:mm) or setting the sync-initial-time option (sync-initial-time = 1) that automatically sets the proper map to be read according to the simulation starting date and time.

Example of section that defines a map in net-cdf format with spatial reference system UTM 32 north wgs84 (EPSG code 3003), and lai as name of variable to be read. The date and time of the first map to be read is automatically assigned by the model (sync-initial-time = 1)

[lai]  # leaf area index map
    file = ./data/lai.nc
    format = net-cdf
    variable = lai
    epsg = 3003
    sync-initial-time = 1

For some parameters an option to set a constant value for the entire simulation domain is to use the scalar keyword, as in the example below.

Example of section that defines a map with a constant value. Spatial extent and reference system is inherited from the reference ones assigned to the simulation run.

[hydraulic-conductivity] 
    scalar = 0.00001

Parameter map values can be modified with scale_factor and offset keywords. The keyword scale_factor is used to multiply all cells value by a numerical factor. The keyword offset is used to add (or subtract) a fixed value to all cells value. Keywords valid_min and valid_max can be used optionally to bound the resulting values to a minimum and a maximum value.

Example of section follows that defines the map of hydraulic conductivity from a file in esri-ascii format. Values are multiplies by 0.1.

[hydraulic-conductivity] 
    file = ./data/ksat.asc
    format = esri-ascii 
    epsg = 3003
    scale_factor = 0.1

The following example shows a section that defines the map of curve number from a file in esri-ascii format. The value 10 is added to all cells value. The maximum value the curve number can reach is set to 100 (valid_max = 100).

[curve-number] 
    file = ./data/cn.asc
    format = esri-ascii 
    epsg = 3003
    offset = 10
    valid_max = 100
Contents