.. _outputs:

=======
Outputs
=======

Outputs from a simulation are saved in a folder named after the
simulation name. The folder content depends on the type of run: single
simulation, calibration, or forecast.

Different kinds of ouptut are available. 

The ``outputs`` table in the TOML configuration file is used to select the
outputs to save. The following keys are available:

.. code-block:: toml

    [outputs]
    # Save water balance components of each watershed
    budget = true
    # Save the calibration results in a csv file
    metrics = true
    # Save the physical parameters in a csv file
    parameters = true
    # Save the simulation final states in a csv file
    states = true
    # Save the simulation settings in a toml file.
    toml = true

Simulation run
==============

Depending on the TOML configuration file settings, the output folder contains
the following files and folders:

* ``budget``: a folder containing csv files with the water balance components of
  each watershed,
* ``riverflow.csv``: a csv file containng the river flow at the outlet of each
  watershed,
* ``watertable.csv``: a csv file containng the groundwater level for each
  watershed,
* ``parameters.csv``: a csv file containing the physical parameters of each
  watershed,
* ``parameters.toml``: a toml file containing all the settings and the physical
  parameters of each watershed,
* ``final_states.csv``: a csv file containing the final states of each
  watershed,
* ``metrics_riverflow.csv``: a csv file containing the metrics for
  the river flow at the outlet of each watershed
* ``metrics_watertable.csv``: a csv file containing the metrics for
  the groundwater level of each watershed,

Metrics are computed from the simulation starting date to the simulation ending
date, which corresponds to the end of the meteorological data.

Optimization run
================

Two supplementary files are saved in the output folder:

* ``metrics_opti_riverflow.csv``: a csv file containing the metrics for
  the river flow at the outlet of each watershed
* ``metrics_opti_watertable.csv``: a csv file containing the metrics for
  the groundwater level of each watershed,

These metrics are computed from the starting date to the ending date specified
in the ``[optimization]`` table of the TOML configuration file.

The ``parameters.toml`` file contains the calibrated physical parameters of each
watershed. It can be reused for a new simulation run.

Forecast run
============

During a forecast run, results are stored in a folder named ``forecast``. This 
folder contains the following files:

* ``riverflow.csv``: a csv file containing the river flow at the outlet of each
  watershed from the simulation starting date to the emission date of the forecast,
* ``watertable.csv``: a csv file containing the groundwater levels of each
  watershed from the simulation starting date to the emission date of the
  forecast,
* ``riverflow_#.csv``: a cluster of files containing the river flow at the outlet
  of each watershed for each ensemble member from the emission date to the end of
  the forecast,
* ``watertable_#.csv``: a cluster of files containing the groundwater levels at
  the outlet of each watershed for each ensemble member from the emission date to
  the end of the forecast.

Format of the output files
==========================

|rameau| saves most of the outputs in csv files. Separator is a semicolon. The
header contains the watersheds ids. The first column is the date and the
subsequent columns contains the time series of the output variable for each
watershed.

Exceptions apply to some outputs for which the header corresponds to
the output variable name and each line to a watershed. 

.. csv-table:: parameters
   :file: parameter_outputs.csv
   :widths: 20, 70, 10
   :header-rows: 1

.. csv-table:: metrics csv files
   :file: metrics_outputs.csv
   :widths: 20, 80
   :header-rows: 1

final_states.csv
----------------

This file contains the states of each reservoir. It can be reused in
another simulation as initial states.