##################################################################
First forward simulation with the toy Gaussian Model
##################################################################

.. role:: bash(code)
   :language: bash

========================
Configuration and set-up
========================

Here we generate pyCIF outputs for a forward run using
:doc:`the Toy Gaussian Model</documentation/plugins/models/dummy>`.
To do so, follow the steps.
Please note :doc:`here</documentation/paths>` some instructions about how pyCIF deals with paths.

1. Set up a Yaml configuration:

    - copy the content of the reference Yaml file available :doc:`here</yaml_examples/dummy/config_fwd_long_noMCF>` to a directory of your choice
    - the yaml is plug-and-play ready, you only have to modify the following variables in the file:
        - :bash:`rootdir`: path where the CIF sources are
        - :bash:`outdir`: where the outputs will be generated

      pyCIF automatically replaces them anywhere they are used in the yaml;
      please find details :doc:`here</documentation/paths>`

2. Run pyCIF based on your Yaml file:

    .. code-block:: bash

        python -m pycif path-to-your-yaml

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


Explore the results in :bash:`workdir`; if you used the default content of the yaml, you should find files in
:bash:`${outdir}/fwd_long_noMCF/` that is structured as follows:

::

    ${outdir}/fwd_long_noMCF/
    ├── config_fwd_long_noMCF.yml: a copy of the yml used for the run
    ├── pycif.logtest: the log file
    ├── VERSION: a log file giving the version (git commit ID) used for the run
    ├── controlvect/: directory storing data useful for the control vector
        └── correlations/
            └── horcor_hpixels_12x18_cs-999_cl500.bin:
                    binary file storing the horizontal correlation matrix used in this case
    ├── datavect/: all input data
        ├── concs/: directory with concentrations
                    (empty as observation file is randomly generated here)
            └── CH4/
        ├── fluxes/
            └── CH4/
                └── dummy_flx.txt: fluxes as generated from the formula in the yml
        └── meteo/
            └── dummy_meteo_%Y%m%d.txt: meteo files randomly generated
    ├── model/
        ├── H_matrix.pickle: saved H matrix after computation
        └── Pasquill-Gifford.txt:
                reference correspondance file between
                Pasquill-Gifford classes and Gaussian parameters
    ├── obsoperator/
        └── fwd_0000/: runs are identified by the mode (fwd, tl or adj) and an ID number
            ├── controlvect.pickle: a binary file with the control vector values used for this run
            ├── controlvect/: the same with netCDF user-friendly format
            ├── %Y-%m-%d_%H:%S: sub-directories for every individual model runs (one per day)
                └── Pasquill-Gifford.txt:
                        link to the original Pasquill-Gifford.txt file
                        in the model directory
            ├── obsvect/:
                directory with a structure following available observation
                components and species; Therein, for each component/species
                a monitor.nc with simulated concentrations
            └── chain/: empty in that case; can be used by models that need to chain sub-simulations

    └── obsvect/: the final observation vector with perturbed simulations

The example produces five days of simulations using a Gaussian model with arbitrary meteorological conditions,
fluxes distributed following the formula :math:`(cos(lat / 500) + sin(lon / 1000)) . ((lat / 1000)^2 + (lon / 1000)^2)`, 5 stations randomly distributed over the domain.

=============
Going further
=============

You can play with these parameters to see the different possible outputs:

    - :bash:`nstations` in the paragraph :bash:`datavect/components/concs/parameters/CH4`: you can reduce or increase the number of virtual sites
    - :bash:`flx_formula` in the paragraph :bash:`datavect/components/fluxes/parameters/CH4`: you can change the formula used to generate fluxes;
      accepted arguments to be changed are:

        - variables: :bash:`zlon` or :bash:`zlat`
        - period: a typical horizontal length scale
        - operations: :bash:`product` or :bash:`sum` or :bash:`square`

Many other examples using the Toy Gaussian model and various configurations (inversions, forwards, test of the adjoints, etc.)
are available :doc:`here</yaml_examples/dummy/index>`