TOML configuration file

Rameau uses the TOML configuration file format to describe and save all the settings and physical parameters related to a model. This configuration file can be used either through the Model.from_toml method or by passing the file name to the CLI rameau executable.

All settings and physical parameters have default values that are set during a simulation run. Two fields are nevertheless mandatory when using a TOML file: the rainfall and PET input data text file paths. Thus, a minimal working TOML file is:

[files]
rainfall = "rainfall.csv"
pet = "pet.csv"

The TOML configuration file is basically divided into two parts: one related to the general settings and one related to the physical parameters of each watershed.

A full example is provided below:

# Name of the simulation.
name = "My Simulation"
# Starting date of the simulation.
starting_date = 2005-01-01 00:00:00.000
[files]
# Rainfall data file path.
rainfall = "rainfall.csv"
# PET data file path.
pet = "pet.csv"
# Temperature data file path.
temperature = "temperature.csv"
# Snow data file path.
snow = "snow.csv"
# Observed river flow data file path.
riverobs = "riverobs.csv"
# Observed groundwater level data file path.
groundwaterobs = "groundwaterobs.csv"
# River pumping data file path.
riverpumping = "riverpumping.csv"
# Groundwater level pumping data file path.
groundwaterpumping = ""
# Branch tree file
tree = ""
# Initial states
states = ""
[input_format]
# Rainfall data file path.
meteo_files = false
# Starting date of the input data text files.
starting_date = 2000-01-01
# Time step of the input data text files.
time_step = { days = 5 }
[spinup]
# Starting date of the initialization period.
starting_date = 2000-01-01 00:00:00.000
# Ending date of the initialization period.
ending_date = 2004-12-31 00:00:00.000
# Number of spinup cycles.
cycles = 2
[optimization]
# Maximum number of iterations.
maxit = 40
# Objective function to minimize.
river_objective_function = "nse" # "kge" or "kge_2012"
# Starting date of the optimization period.
starting_date = 2000-01-01 00:00:00.000
# Ending date of the optimization period.
ending_date = 2010-12-31 00:00:00.000
# Transformation applied to the observed and simulated river flow values.
transformation = "square root" # "no", "inverse", "log" or "fifth root"
# Method used to optimize the parameters.
method = "all" # "independent" or "strahler"
# Selected watersheds for the optimization.
selected_watersheds = [1, 2]
# If true, the objective function value is printed at each iteration.
verbose = false
[forecast]
forecast = false
scope = { days = 30 }
year_members = [1999, 2000, 2001]
correction = "no"
pumping_date = 1999-07-01
quantiles_output = true
quantiles = [25, 50, 75]
norain = true
[watershed.all]
# Name of the watershed.
name = ""
# If true, the watershed is a confluence.
is_confluence = false
# Weight to assign to the meteorological columns defined for the watershed
meteo.weights = [ 1.00000 ]
# Halflife value of the output correction method for river flow (time step)
forecast.river.halflife = 0.00000
# Halflife value of the output correction method for groundwater level (time step)
forecast.groundwater.halflife = 0.00000
# Correction factor for the drainage area (-)
correction.area = { value = 1.00000, lower = 0.80000, upper = 1.20000, opti = false, sameas = 0 }
# Correction factor for rainfall (%)
correction.rainfall = { value = 0.00000, lower = -20.00000, upper = 20.00000, opti = false, sameas = 0 }
# Correction factor for potential evapotranspiration (%)
correction.pet = { lower = -20.00000, upper = 20.00000, opti = true, sameas = 0 }
# Weight assign to this watershed for optimizing river flow in the multi-objective function
river.weight = 5.00000
# Minimum and maximm limitations of the observed river flow
river.obslim = [ 0.00000, 0.00000 ]
# Drainage area of the watershed (km²)
river.area = { opti = false }
# Minimum river flow in the river (m3/s)
river.minimum_riverflow = { value = 0.00000, opti = false }
# Concentration time of the watershed (time step)
river.concentration_time = { lower = 0.00000, upper = 10.00000, opti = true, sameas = 0 }
# Propagation time of the watershed (time step)
river.propagation_time = { lower = 0.00000, upper = 15.00000, sameas = 0 }
# Soil capacity of the Thornthwaite reservoir (mm)
thornthwaite.capacity = { value = 0.00000, lower = 0.00000, upper = 500.00000, opti = false, sameas = 0 }
# If true, |PET| decrease when soil water content is lower than 50%
progressive.pet_decrease = false
# Soil capacity of the progressive reservoir (mm)
progressive.capacity = { lower = 0.10000, upper = 600.00000, opti = true, sameas = 0 }
# Runoff/seepage ratio of the transfer reservoir (-)
transfer.runsee = { lower = 0.10000, upper = 2.5000000000000000E+3, opti = true, sameas = 0 }
# Halflife time of the transfer reservoir (months)
transfer.halflife = { lower = 0.01000, upper = 10.00000, opti = true, sameas = 0 }
# Fate of the transfer reservoir overflow
transfer.overflow.loss = "no"
# Transfer reservoir overflow threshold (mm)
transfer.overflow.threshold = { value = 0.00000, lower = 0.00000, upper = 9.9990000000000000E+3, opti = false, sameas = 0 }
# Transfer reservoir overflow halflife time (time step)
transfer.overflow.halflife = { value = 0.00000, lower = 0.00100, upper = 20.00000, opti = false, sameas = 0 }
# Weight assign to this watershed for optimizing groundwater level in the multi-objective function
groundwater.weight = 1.00000
# Minimum and maximm limitations of the observed groundwater level
groundwater.obslim = [ 0.00000, 0.00000 ]
# Groundwater reservoir number for which observed groundwater level correspond.
groundwater.observed_reservoir = 1
# Base level of simulated groundwater level
groundwater.base_level = { opti = true }
# If true, optimization of the storage coefficient by regression
groundwater.storage.regression = true
# Storage coefficient of the groundwater reservoir (%)
groundwater.storage.coefficient = { lower = 0.10000, upper = 80.00000, opti = true, sameas = 0 }
# Halflife time for baseflow (months)
groundwater.1.halflife_baseflow = { lower = 0.00100, upper = 15.00000, opti = true, sameas = 0 }
# Halflife time for drainage (months)
groundwater.1.halflife_drainage = { lower = 0.00100, upper = 50.00000, sameas = 0 }
# Groundwater exchanges with the outside (%)
groundwater.1.exchanges = { lower = -60.00000, upper = 60.00000, sameas = 0 }
# Groundwater overflow threshold (mm)
groundwater.1.overflow.threshold = { value = 0.00000, lower = 0.00000, upper = 9.9990000000000000E+3, opti = false, sameas = 0 }
# Groundwater overflow halflife time (time step)
groundwater.1.overflow.halflife = { value = 0.00000, lower = 0.00100, upper = 20.00000, opti = false, sameas = 0 }
groundwater.2.halflife_baseflow = { lower = 0.00100, upper = 50.00000, sameas = 0 }
groundwater.2.halflife_drainage = { value = 0.00000, lower = 0.05000, upper = 50.00000, opti = false, sameas = 0 }
groundwater.2.exchanges = { value = 0.00000, lower = -20.00000, upper = 20.00000, opti = false, sameas = 0 }
groundwater.2.overflow.threshold = { value = 0.00000, lower = 0.00000, upper = 9.9990000000000000E+3, opti = false, sameas = 0 }
groundwater.2.overflow.halflife = { value = 0.00000, lower = 0.00100, upper = 20.00000, opti = false, sameas = 0 }
# Temperature correction (°C)
snow.correction.temperature = { value = 0.00000, lower = -20.00000, upper = 20.00000, opti = false, sameas = 0 }
# PET correction factor in the snowpack (%)
snow.correction.pet = { value = 0.00000, lower = -20.00000, upper = 20.00000, opti = false, sameas = 0 }
# Correction factor of snow melting by rainfall calories (%)
snow.correction.rainfall = { value = 0.00000, lower = 0.00100, upper = 20.00000, opti = false, sameas = 0 }
# Degree day model coefficient (-)
snow.degree_day.coefficient = { value = 0.00000, lower = 0.00100, upper = 7.00000, opti = false, sameas = 0 }
# Degree day model temperature threshold (°C)
snow.degree_day.temperature = { value = 0.00000, lower = -2.00000, upper = 2.00000, opti = false, sameas = 0 }
# Maximum snow retention in the snowpack (-)
snow.retention = { value = 0.00000, lower = 0.00000, upper = 0.00000, opti = false, sameas = 0 }
# Snow melting by soil calories (1/10 mm/day)
snow.melting = { value = 0.00000, lower = 0.00000, upper = 0.00000, opti = false, sameas = 0 }
# Pumping river coefficient (-)
pumping.river.coefficient = { value = 1.00000, opti = false }
# Rising halflife time of the river pumping reservoir (months)
pumping.river.halflife_rise = { value = 0.00000, lower = 0.05000, upper = 10.00000, opti = false, sameas = 0 }
# Falling halflife time of the river pumping reservoir (months)
pumping.river.halflife_fall = { value = 0.00000, lower = 0.05000, upper = 15.00000, opti = false, sameas = 0 }
# Fraction of groundwater pumping to take into account (-)
pumping.groundwater.coefficient = { value = 1.00000, opti = false }
# Rising halflife time of the groundwater pumping reservoir (months)
pumping.groundwater.halflife_rise = { value = 0.00000, lower = 0.05000, upper = 10.00000, opti = false, sameas = 0 }
# Falling halflife time of the groundwater pumping reservoir (months)
pumping.groundwater.halflife_fall = { value = 0.00000, lower = 0.05000, upper = 15.00000, opti = false, sameas = 0 }
[watershed.1]
# Name of the watershed with the identifier 1
name = "Watershed 1"
# Columns of the meteorological input csv file to use
meteo.columns = [1.0000]
groundwater.1.halflife_baseflow = { value = 5.0 }
river.area = { value = 525 }