.. currentmodule:: rameau

.. _tomlfile:

=======================
TOML configuration file
=======================

|rameau| uses the `TOML <https://toml.io/en/>`_ 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:

.. code-block:: toml

    [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:

.. code-block:: toml

    # 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 }