The main configuration file

3. The main configuration file#

This file sets the main parameters for running a simulation such as the starting and ending date and time, the modules to be activated, the results to be put in output files, etc…. The name of the file is chosen by user but, usually, the name fest.ini is assigned. The file includes a list of sections, mandatory or optional, that configure a specific module of FEST model. An example of main configuration file is shown below.

Example of main configuration file for running a simulation. In this example, all configuration files are stored in conf subfolder.

#set start and stop time. Always use UTC. MANDATORY
[time] 
  start = 2005-01-01-00:00:00+00:00
  stop  = 2022-08-31-23:00:00+00:00

# set folder for writing results. MANDATORY
# ./folder/ example for setting a folder
# ./folder/prefix_  append a prefix (prefix_) to all output files
[result]
  folder = ./results/sim0_

# simulation mask and general domain properties. MANDATORY
[domain]
  conf-file = ./conf/domain.ini

# set morphological properties. OPTIONAL
[morphology]
  conf-file = ./conf/morphology.ini

# meteorological forcings. MANDATORY
[meteo]
  dt = 3600
  conf-file = ./conf/meteo.ini
  dt-out-spatial = 3600
  out-point-file = ./conf/point_meteo.fts

# plants simulation. OPTIONAL
[plants]
  dt = 0 
  conf-file = ./conf/plants.ini

#snow accumulation and melting. OPTIONAL
[snow]
  dt = 3600 
  conf-file =  ./conf/snow.ini
  dt-out-spatial = 3600  

#soil balance. OPTIONAL
[soil-balance] 
  dt = 3600
  conf-file = ./conf/soil-balance.ini
  dt-out-spatial = 3600

#configure spatial average output. OPTIONAL
[spatial-average]
  conf-file = ./conf/spatial_average.ini

# discharge routing on hillslope,rivers, and lakes. OPTIONAL
[discharge-routing] 
  dt = 900 
  conf-file = ./conf/discharge-routing.ini  
  out-point-file = ./conf/discharge_out.fts 

3.1. Time#

This mandatory section, marked by [time], sets the starting and ending date and time of simulation. Keywords to be set are listed in Table 3.1.

Table 3.1 Definition of keywords to set simulation time#
Keyword	Description	Requirements
`[time]`	Marks the beginning line of time section	mandatory
`start`	Starting date and time of simulation formatted according to ISO 8601 specifications in UTC time zone.	mandatory
`stop`	Ending date and time of simulation formatted according to ISO 8601 specifications in UTC time zone.	mandatory

The following example sets the starting time of simulation at 2005-01-01-00:00:00+00:00 and ending time at 2022-08-31-23:00:00+00:00.

Example of [time] section configuration within the main configuration file

#set start and stop time. Always use UTC. MANDATORY
[time] 
  start = 2005-01-01-00:00:00+00:00
  stop  = 2022-08-31-23:00:00+00:00

Warning

Use always UTC time

3.2. Result#

This mandatory section, marked by [result], sets the folder where to save output files of simulation results. Keywords to be set are listed in Table 3.2.

Table 3.2 Definition of keywords to set result folder#
Keyword	Description	Requirements
`[result]`	Marks the beginning line of result section	mandatory
`folder`	Sets folder name to write results. A prefix to be appended to all files can be set as in the example: `folder = ./results/sim0_`. Use `folder = ./results/` instead, to leave prefix blank	mandatory

The following example sets the folder output for storing result files. This example uses the relative path nomenclature to specify the result folder as a subfolder of the current directory. The prefix sim0 is appended at the beginning of output files. For understanding how output files are named see the specific sections.

Example of [result] section configuration within the main configuration file

# set folder for writing results. MANDATORY
# ./folder/ example for setting a folder
# ./folder/prefix_  append a prefix (prefix_) to all output files
[result]
  folder = ./output/sim0_

3.3. Domain#

This mandatory section, marked by [domain], sets the file to configure simulation domain. Keywords to be set are listed in Table 3.3.

Table 3.3 Definition of keywords to set simulation domain configuration file#
Keyword	Description	Requirements
`[domain]`	Marks the beginning line of domain section	mandatory
`conf-file`	Sets the name of configuration file	mandatory

The following example sets the file ./conf/domain.ini for configuring simulation domain.

Example of [domain] section configuration within the main configuration file

# simulation mask and general domain properties. MANDATORY
[domain]
  conf-file = ./conf/domain.ini

3.4. Morphology#

This optional section, marked by [morphology], sets the file to configure morphological properties. Keywords to be set are listed in Table 3.4.

Table 3.4 Definition of keywords to set the file to configure morphological properties#
Keyword	Description	Requirements
`[morphology]`	Marks the beginning line of morphology section	optional
`conf-file`	name of configuration file	mandatory

The following example sets the file ./conf/morphology.ini for configuring morphological properties.

Example of [morphology] section configuration within the main configuration file:

# set morphological properties. OPTIONAL
[morphology]
  conf-file = ./conf/morphology.ini 

3.5. Meteo#

This mandatory section, marked by [meteo], sets parameters for configuring meteorological forcings management. Keywords to be set are listed in Table 3.5. List of created files in Table 3.6

Table 3.5 Definition of keywords to set parameters for configuring meteorological forcings#
Keyword	Description	Requirements
`[meteo]`	Marks the beginning line of meteo section	mandatory
`dt`	time step for new data reading (s)	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out-spatial`	Time step for writing spatial average data (s). If section is not present or `dt-out-spatial = 0`, output files are not created and data are not exported.	optional
`out-point-file`	File that contains coordinate of points for exporting site data. It is a plain text file in time series format with only the metadata section (see example below). The time step defined in the file, sets the export time step (s). If file is not assigned, data are not exported. List of created files in Table 3.6	optional

Table 3.6 Name of files created for exporting sites meteorological data. The folder assigned in [result] section is appended to the name of file as a prefix#
Variable	File name
Precipitation	`<folder>` `point_precipitation.fts`
Air temperature	`<folder>` `point_temperature.fts`
Solar radiation	`<folder>` `point_radiation.fts`
Air relative humidity	`<folder>` `point_RH.fts`
Wind speed	`<folder>` `point_WS.fts`

The following example sets the file ./conf/meteo.ini for configuring meteorological forcings, a time step for reading data = 3600, a time step for exporting spatial average data = 3600, and sets the file ./conf/point_meteo.fts for listing the coordinate of points to export site data. A new file is created for each meteorological variable used in the simulation run with file name listed in Table 3.6

Example of [meteo] section configuration within the main configuration file

# meteorological forcings. MANDATORY
[meteo]
  dt = 3600
  conf-file = ./conf/meteo.ini
  dt-out-spatial = 3600
  out-point-file = ./conf/point_meteo.fts

The following is an example of out-point-file for exporting data in five sites with time step of 3600 s. Keywords unit and offsetz are not used by the process but they must exist for adhering to standard time series data format.

Example of out-point-file

description	= points coordinate for meteo data export
unit	=	-
epsg	=	32632
count	=	5
dt	=	3600	
missing-data = -999.9
offsetz = 2 



metadata
site1      01  614452.00 5066300.00  0.00
site2      02  612452.00 5048300.00  0.00
site3      03  609952.00 5022550.00  0.00
site4      04  610702.00 5008550.00  0.00
site5      05  613702.00 5065550.00  0.00

3.6. Plants#

This optional section, marked by [plants], sets parameters to configure plants properties and simulation. Keywords to be set are listed in Table 3.7.

Table 3.7 Definition of keywords to set parameters to configure plants properties and simulation#
Keyword	Description	Requirements
`[plants]`	Marks the beginning line of plants section	optional
`dt`	time step for computation (s). If `dt = 0`, parameters are kept constant; if `dt > 0`, parameters are updated in time with a simulation.	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out-spatial`	Time step for writing spatial average data (s). If section is not present or `dt-out-spatial = 0`, output files are not created and data are not exported.	optional

The following example sets the file ./conf/plants.ini for configuring plants properties that are kept constant in time (dt = 0).

Example of [plants] section configuration within the main configuration file

# plants simulation. OPTIONAL
[plants]
  dt = 0 
  conf-file = ./conf/plants.ini

3.7. Snow#

This optional section, marked by [snow], sets parameters for configuring snow simulation (accumulation and melting). Keywords to be set are listed in Table 3.8.

Table 3.8 Definition of keywords to set parameters for configuring snow simulation#
Keyword	Description	Requirements
`[snow]`	Marks the beginning line of snow section	optional
`dt`	time step for computation (s)	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out-spatial`	Time step for writing spatial average data (s). If section is not present or `dt-out-spatial = 0`, output files are not created and data are not exported.	optional
`out-point-file`	File that contains coordinate of points for exporting site snow water equivalent data. It is a plain text file in time series format with only the metadata section. The time step defined in the file, sets the export time step (s). If file is not assigned, data are not exported. Name of file created: `<folder>` `point_swe.fts`	optional

The following example sets the file ./conf/snow.ini for configuring snow ù simulation, a time step for computing = 3600, and a time step for exporting spatial average data = 3600.

Example of [snow] section configuration within the main configuration file

#snow accumulation and melting. OPTIONAL
[snow]
  dt = 3600 
  conf-file =  ./conf/snow.ini
  dt-out-spatial = 3600

3.8. Glacier#

This optional section, marked by [glacier], sets parameters for configuring glacier simulation (accumulation and ablation). Keywords to be set are listed in Table 3.9.

Table 3.9. Definition of keywords to set parameters for configuring glacier simulation.

Table 3.9 Definition of keywords to set parameters for configuring glacier simulaion.#
Keyword	Description	Requirements
`[glacier]`	Marks the beginning line of snow section	optional
`dt`	time step for computation (s)	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out-spatial`	Time step for writing spatial average data (s). If section is not present or `dt-out-spatial = 0`, output files are not created and data are not exported.	optional
`out-point-file`	File that contains coordinate of points for exporting site snow water equivalent data. It is a plain text file in time series format with only the `metadata` section. The time step defined in the file, sets the export time step (s). If file is not assigned, data are not exported. Name of file created: `<folder>` `point_glacier.fts`	optional

The following example sets the file ./conf/glacier.ini for configuring glacier simulation, a time step for computing = 3600, and a time step for exporting spatial average data = 3600.

Example of [glacier] section configuration within the main configuration file

#glacier accumulation and ablation. OPTIONAL
[glacier]
  dt = 3600 
  conf-file =  ./conf/glacier.ini
  dt-out-spatial = 3600  

3.9. Soil water balance#

This optional section, marked by [soil-balance], sets parameters for configuring snow water balance simulation. Keywords to be set are listed in Table 3.10.

Table 3.10 Definition of keywords to set parameters for configuring soil water balance simulation#
Keyword	Description	Requirements
`[soil-balance]`	Marks the beginning line of `soil-balance` section	optional
`dt`	time step for computation (s)	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out-spatial`	Time step for writing spatial average data (s). If section is not present or `dt-out-spatial = 0`, output files are not created and data are not exported.	optional

The following example sets the file ./conf/soil-balance.ini for configuring soil water balance simulation, a time step for computing = 3600, and a time step for exporting spatial average data = 3600.

Example of [soil-balance] section configuration within the main configuration file

#soil balance. OPTIONAL
[soil-balance] 
  dt = 3600
  conf-file = ./conf/soil-balance.ini
  dt-out-spatial = 3600

3.10. Discharge routing#

This optional section, marked by [discharge-routing], sets parameters for configuring discharge routing. Keywords to be set are listed in Table 3.11.

Table 3.11 Definition of keywords to set parameters for configuring discharge routing#
Keyword	Description	Requirements
`[discharge-routing]`	Marks the beginning line of `discharge-routing` section	optional
`dt`	time step for computation (s)	mandatory
`conf-file`	name of configuration file	mandatory
`out-point-file`	File that contains coordinate of points for exporting river discharge data at selected sections. It is a plain text file in time series format with only the `metadata` section. The time step defined in the file, sets the export time step (s). If file is not assigned, data are not exported. Name of file created: `<folder>` `point_discharge.fts`	optional

The following example sets the file ./conf/discharge-routing.ini for configuring discharge routing, a time step for computing = 900, and sets the file ./conf/discharge_out.fts for listing the coordinate of points to export data at selected sections.

Example of [discharge-routing] section configuration within the main configuration file

# discharge routing on hillslope, rivers, and lakes. OPTIONAL
[discharge-routing] 
  dt = 900 
  conf-file = ./conf/discharge-routing.ini  
  out-point-file = ./conf/discharge_out.fts 

3.11. Groundwater#

This optional section, marked by [groundwater], sets parameters for configuring discharge routing. Keywords to be set are listed in Table 3.12.

Table 3.12 Definition of keywords to set parameters for configuring groundwater#
Keyword	Description	Requirements
`[groundwater]`	Marks the beginning line of groundwater section	optional
`dt`	time step for computation (s)	mandatory
`conf-file`	name of configuration file	mandatory
`out-point-file`	File that contains coordinate of points for exporting groundwater head data at selected sites. It is a plain text file in time series format with only the `metadata` section. The time step defined in the file, sets the export time step (s). If file is not assigned, data are not exported. One file is created for each of n simulated aquifer. Name of file created: `<folder>` `point_aquifer_<i>.fts` with `i=1,n`	optional
`dt-out-aquifer`	Time step for writing average data (s). If section is not present or `dt-out-aquifer = 0`, output file are not created and data are not exported. Name of file created: `<folder>` `aquifer.out`	optional

The following example sets the file ./conf/groundwater.ini for configuring groundwater simulation, a time step for computing = 3600, and sets the file ./conf/point_groundwater.fts for listing the coordinate of points to export data at selected sites. Results are written every hour.

Example of [groundwater] section configuration within the main configuration file

#configure groundwater simulation. OPTIONAL 
[groundwater]
dt = 3600  
conf-file = ./conf/groundwater.ini 
out-point-file = ./conf/point_groundwater.fts 
dt-out-aquifer = 3600 

3.12. Spatial average#

This optional section, marked by [spatial-average], sets the configuration file for exporting spatial average data. Keywords to be set are listed in Table 3.13.

Table 3.13 Definition of keywords to set the configuration file for exporting spatial average data#
Keyword	Description	Requirements
`[spatial-average]`	Marks the beginning line of `spatial-average` section	optional
`conf-file`	name of configuration file	mandatory

The following example sets the file ./conf/spatial-average.ini for configuring exporting of spatial average data.

Example of [spatial-average] section configuration within the main configuration file

#configure spatial average output. OPTIONAL
[spatial-average]
  conf-file = ./conf/spatial_average.ini

3.13. Irrigation#

This optional section, marked by [irrigation], sets parameters for configuring water derivation from rivers and distribution to irrigation districts. Keywords to be set are listed in the following table.

Table 3.14 Definition of keywords to set parameters for configuring irrigation#
Keyword	Description	Requirements
`[irrigation]`	Marks the beginning line of irrigation section	optional
`dt`	time step for updating irrigation parameters (s)	mandatory
`conf-file`	name of configuration file	mandatory
`dt-out`	time step for writing into output file. It must be equal to or a multiple of `dt`	mandatory

The following example sets the file ./conf/intakes.ini for configuring irrigation, a time step for updating values to 3600 s, as well as the time step for exporting data.

Example of [irrigation] section configuration within the main configuration file

# irrigation management. OPTIONAL
[irrigation] 
  dt = 3600 # time step for new update (s)
  conf-file = ./conf/intakes.ini  #configuration file
  dt-out = 3600  # time step for exporting data (s)

3.14. Basin average#

This optional section, marked by [basin-average], sets the configuration file for exporting average values over river basins given by the coordinate of outlet sections. Keywords to be set are listed in the following table.

Table 3.15 Definition of keywords to set the configuration file for exporting basin average data#
Keyword	Description	Requirements
`[basin-average]`	Marks the beginning line of `basin-average` section	optional
`conf-file`	name of configuration file	mandatory
`out-point-file`	File that contains coordinate of points for exporting basin average data at selected sections. It is a plain text file in time series format with only the metadata section (see example in Section 1.4). The time step defined in the file, sets the export time step (s). For name of created files see Section 15	mandatory

The following example sets the file ./conf/basin-average.ini for configuring exporting of basin average data for basin outlets listed in ./conf/basin_out.fts file

Example of [basin-average] section configuration within the main configuration file

#configure basin average output. OPTIONAL
[basin-average]
  conf-file = ./conf/basin-average.ini
  out-point-file = ./conf/basin_out.fts

3.15. Raster exporting#

This optional section, marked by [raster-export], sets the configuration file for exporting raster maps of a list of variables. Keywords to be set are listed in the following table.

Table 3.16 Definition of keywords to set the configuration file for exporting raster maps#
Keyword	Description	Requirements
`[raster-export]`	Marks the beginning line of raster-export section	optional
`conf-file`	name of configuration file	mandatory

The following example sets the file ./conf/raster-export.ini for configuring exporting of raster maps.

Example of [raster-export] section configuration within the main configuration file

#configure variables for raster export. OPTIONAL
[raster-export]
  conf-file = ./conf/raster-export.ini