Index: for_developers/Sphinx/Makefile
===================================================================
--- for_developers/Sphinx/Makefile	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/Makefile	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -7,5 +7,5 @@
 SPHINXPROJ    = flex_extract
 SOURCEDIR     = source
-BUILDDIR      = ../../documentation
+BUILDDIR      = ../../Documentation
 
 # Put it first so that "make" without argument is like "make help".
Index: for_developers/Sphinx/source/Developers/gen_docu.rst
===================================================================
--- for_developers/Sphinx/source/Developers/gen_docu.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Developers/gen_docu.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -15,4 +15,11 @@
 - graphviz
 - sphinx
+- pip install sphinxcontrib-exceltable
+- pip install seqdiag
+- pip install sphinxcontrib-seqdiag
+- pip install sphinxcontrib-blockdiag
+- pip install pycallgraph
+
+#- pip install sphinx-fortran
 
 
@@ -27,4 +34,25 @@
 
 
+Sequence diagramms
+------------------
+
+You might need to adapt the fonts path for the diagrams to a true type font. Currently it is set to:
+
+.. code-block:: bash
+
+    # Fontpath for seqdiag (truetype font)
+    seqdiag_fontpath = '/usr/share/fonts/dejavu/DejaVuSerif.ttf'
+
+
+Block diagramms
+------------------
+
+You might need to adapt the fonts path for the diagrams to a true type font. Currently it is set to:
+
+.. code-block:: bash
+
+     # Fontpath for blockdiag (truetype font)
+     blockdiag_fontpath = '/usr/share/fonts/dejavu/DejaVuSerif.ttf'
+
 
 
Index: for_developers/Sphinx/source/Documentation/Api/api_fortran.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Api/api_fortran.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Api/api_fortran.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,26 @@
+**************************************
+Fortran's Auto Generated Documentation
+**************************************
+
+.. contents::
+    :local:
+    
+    
+    
+Link to other documentation!
+
+
+
+
+.... f:autoprogram:: preconvert    
+    
+    
+    
+    
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+    
+    
+
+    
Index: for_developers/Sphinx/source/Documentation/Api/api_python.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Api/api_python.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Api/api_python.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,96 @@
+*************************************
+Python's Auto Generated Documentation
+*************************************
+
+.. contents::
+    :local:
+    
+Programs
+========
+
+install
+-------
+
+.. automodule:: install
+    :members:
+    
+submit
+------
+
+.. automodule:: submit
+    :members:
+    
+Classes
+=======
+
+ControlFile
+-----------
+
+.. automodule:: ControlFile
+    :members:
+    
+EcFlexpart
+----------
+
+.. automodule:: EcFlexpart
+    :members:
+    
+GribUtil
+--------
+
+.. automodule:: GribUtil
+    :members:
+
+MarsRetrieval
+-------------
+
+.. automodule:: MarsRetrieval
+    :members:
+
+UioFiles
+--------
+
+.. automodule:: UioFiles
+    :members:
+
+
+
+Modules
+=======
+
+get_mars_data
+-------------
+
+.. automodule:: get_mars_data
+    :members:
+ 
+prepare_flexpart
+----------------
+
+.. automodule:: prepare_flexpart
+    :members:    
+    
+tools
+-----
+
+.. automodule:: tools
+    :members:
+
+checks
+------
+
+.. automodule:: checks
+    :members:
+    
+    
+disaggregation
+--------------    
+    
+.. automodule:: disaggregation
+    :members:
+    
+    
+    
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/changes.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/changes.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/changes.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,18 @@
+**********************
+CONTROL file changes
+**********************
+
+Changes from version 7.0.4 to version 7.1 
+    - removed ``M_`` (but is still available for downward compatibility)
+    - grid resolution not in 1/1000 degress anymore (but is still available for downward compatibility)
+    - comments available with ``#``
+    - only parameters which are needed to override the default values are necessary 
+    - number of type/step/time elements do not have to be 24 any more. Just select the interval you need. 
+    - the ``dtime`` parameter needs to be consistent with ``type/step/time``. For example ``dtime`` can be coarser as ``time`` intervals are available, but not finer.
+
+ 
+
+    
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/compilejob.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/compilejob.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/compilejob.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,116 @@
+********************************************
+The Compilation Jobscript ``compilejob.ksh``
+********************************************
+
+The compilejob is a Korn-shell script which will be created during the installation process for the application modes **remote** and **gateway** from a template called ``compilejob.template`` in the template directory.
+
+``Flex_extract`` uses the python package `genshi <https://genshi.edgewall.org/>`_ to generate
+the Korn-shell script from the template files by substituting the individual parameters. 
+These individual parameters are marked by a doubled ``$`` sign in ``job.temp``. 
+
+The jobscript has a number of settings for the batch system which are fixed and differentiates between the *ecgate* and the *cca/ccb* 
+server system to load the necessary modules for the environment when submitted to the batch queue.
+
+The submission is done by the ``ECaccess`` tool from within ``flex_extract`` with the command ``ecaccess-job-submit``.
+
+
+
+What does the compilation script do?
+------------------------------------
+
+ #. It sets necessary batch system parameters
+ #. It prepares the job environment at the ECMWF servers by loading the necessary library modules
+ #. It sets some environment variabels for the single session
+ #. It creates the ``flex_extract`` root directory in the ``$HOME`` path of the user
+ #. It untars the tar-ball into the root directory.
+ #. It compiles the Fortran programs's ``Makefile``.
+ #. At the end it checks if the script returned an error or not and send the log file via email to the user.
+
+
+
+
+
+Example ``compilejob.ksh``
+--------------------------
+  
+.. code-block::  bash
+   
+       
+    #!/bin/ksh
+
+    # ON ECGB:
+    # start with ecaccess-job-submit -queueName ecgb NAME_OF_THIS_FILE  on gateway server
+    # start with sbatch NAME_OF_THIS_FILE directly on machine
+
+    #SBATCH --workdir=/scratch/ms/at/km4a
+    #SBATCH --qos=normal
+    #SBATCH --job-name=flex_ecmwf
+    #SBATCH --output=flex_ecmwf.%j.out
+    #SBATCH --error=flex_ecmwf.%j.out
+    #SBATCH --mail-type=FAIL
+    #SBATCH --time=12:00:00
+
+    ## CRAY specific batch requests
+    ##PBS -N flex_ecmwf
+    ##PBS -q ns
+    ##PBS -S /usr/bin/ksh
+    ##PBS -o /scratch/ms/at/km4a/flex_ecmwf.${Jobname}.${Job_ID}.out
+    # job output is in .ecaccess_DO_NOT_REMOVE
+    ##PBS -j oe
+    ##PBS -V
+    ##PBS -l EC_threads_per_task=1
+    ##PBS -l EC_memory_per_task=3200MB
+
+    set -x
+    export VERSION=7.1
+    case ${HOST} in
+      *ecg*)
+      module unload grib_api
+      module unload eccodes
+      module unload python
+      module unload emos
+      module load python3
+      module load eccodes/2.12.0
+      module load emos/455-r64
+      export FLEXPART_ROOT_SCRIPTS=${HOME}
+      export MAKEFILE=Makefile.gfortran
+      ;;
+      *cca*)
+      module unload python
+      module switch PrgEnv-cray PrgEnv-intel
+      module load python3
+      module load eccodes/2.12.0
+      module load emos
+      echo ${GROUP}
+      echo ${HOME}
+      echo ${HOME} | awk -F / '{print $1, $2, $3, $4}'
+      export GROUP=`echo ${HOME} | awk -F / '{print $4}'`
+      export SCRATCH=/scratch/ms/${GROUP}/${USER}
+      export FLEXPART_ROOT_SCRIPTS=${HOME}
+      export MAKEFILE=Makefile.gfortran
+      ;;
+    esac
+
+    mkdir -p ${FLEXPART_ROOT_SCRIPTS}/flex_extract_v${VERSION}
+    cd ${FLEXPART_ROOT_SCRIPTS}/flex_extract_v${VERSION}   # if FLEXPART_ROOT is not set this means cd to the home directory
+    tar -xvf ${HOME}/flex_extract_v${VERSION}.tar
+    cd source/fortran
+    \rm *.o *.mod CONVERT2 
+    make -f ${MAKEFILE} >flexcompile 2>flexcompile
+
+    ls -l CONVERT2 >>flexcompile
+    if [ $? -eq 0 ]; then
+      echo 'SUCCESS!' >>flexcompile
+      mail -s flexcompile.${HOST}.$$ ${USER} <flexcompile
+    else
+      echo Environment: >>flexcompile
+      env >> flexcompile
+      mail -s "ERROR! flexcompile.${HOST}.$$" ${USER} <flexcompile
+    fi
+
+
+   
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/control.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/control.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Input/control.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -18,11 +18,10 @@
 The optional extra indications for the re-analysis datasets mark the files for *public users* 
 and *global* domain. For the operational datasets (*OD*) the file names contain also information of
-the stream, the field type for forecasts, the method for extracting the vertical coordinate and other 
-things like time or horizontal resolution.
+the stream, the field type for forecasts, the method for extracting the vertical coordinate and other things like time or horizontal resolution.
 
 
 Format of CONTROL files
 ----------------------------------
-
+The first string of each line is the parameter name, the following string(s) (separated by spaces) is (are) the parameter values.
 The parameters can be sorted in any order with one parameter per line. 
 Comments are started with a '#' - sign. Some of these parameters can be overruled by the command line
@@ -30,4 +29,5 @@
 All parameters have default values. Only those parameters which have to be changed
 must be listed in the :literal:`CONTROL` files. 
+
 
 Example CONTROL files
@@ -37,6 +37,5 @@
 They can be used as a template for adaptations and understand what's possible to 
 retrieve from ECMWF's archive.
-For each main dataset there is an example and additionally some variances in resolution, type of field
-or type of retrieving the vertical coordinate. 
+For each main dataset there is an example and additionally some variances in resolution, type of field or type of retrieving the vertical coordinate. 
 
 
@@ -50,5 +49,5 @@
 the setting of these parameters.
 
-.. literalinclude:: ../../../../../run/control/CONTROL.documentation 
+.. literalinclude:: ../../../../../Run/Control/CONTROL.documentation 
    :language: bash
    :caption: CONTROL.documentation
Index: for_developers/Sphinx/source/Documentation/Input/control_params.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/control_params.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Input/control_params.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -2,4 +2,5 @@
 The CONTROL parameters
 ======================
+     
     
     
@@ -9,8 +10,8 @@
 ************
     
-.. csv-table::
-   :file: ../../_files/CONTROLparameter-user.csv
-   :header-rows: 1
-   :widths: auto 
+.. exceltable:: User parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: UserSection 
+   :header: 1
 
 .. _ref-control-general:
@@ -19,18 +20,18 @@
 ***************
 
-.. csv-table::
-   :file: ../../_files/CONTROLparameter-general.csv
-   :header-rows: 1
-   :widths: auto 
+.. exceltable:: General parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: GeneralSection 
+   :header: 1
    
-.. _ref-control-time:
+.. _ref-control-time: 
    
 Time Section
 ************
    
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-time.csv
-   :header-rows: 1
-   :widths: auto        
+.. exceltable:: Time parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: TimeSection  
+   :header: 1      
     
 
@@ -38,10 +39,10 @@
    
 Data Section
-************
+************ 
    
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-data.csv
-   :header-rows: 1
-   :widths: auto   
+.. exceltable:: Data parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: DataSection 
+   :header: 1
    
    
@@ -51,8 +52,8 @@
 ******************
     
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-datafields.csv
-   :header-rows: 1
-   :widths: auto     
+.. exceltable:: Data field parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: DatafieldsSection 
+   :header: 1
    
    
@@ -62,32 +63,33 @@
 *****************
 
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-fluxdata.csv
-   :header-rows: 1
-   :widths: auto
+.. exceltable:: Flux data parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls
+   :sheet: FluxDataSection
+   :header: 1
 
  
- .. _ref-control-domain:
+.. _ref-control-domain:
    
 Domain Section
 **************
    
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-domain.csv
-   :header-rows: 1
-   :widths: auto     
+.. exceltable:: Domain parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls
+   :sheet: DomainSection
+   :header: 1
+   :widths: 10,10,10,5,20,20
    
    
          
- .. _ref-control-verticalwind:
+.. _ref-control-verticalwind:
    
 Vertical wind Section
 *********************
    
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-verticalwind.csv
-   :header-rows: 1
-   :widths: auto  
- 
+.. exceltable:: Vertical wind parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: VerticalWindSection 
+   :header: 1
+     
  
 .. _ref-control-adddata:
@@ -96,21 +98,10 @@
 ***********************
    
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-adddata.csv
-   :header-rows: 1
-   :widths: auto   
+.. exceltable:: Additional data parameter in CONTROL file 
+   :file: ../../_files/CONTROLparameter.xls 
+   :sheet: AddDataSection 
+   :header: 1
  
-  
-.. _ref-control-flexpart:
-   
-Flexpart Section
-****************
-   
-.. csv-table:: 
-   :file: ../../_files/CONTROLparameter-flexpart.csv
-   :header-rows: 1
-   :widths: auto  
-   
-   
+    
    
    
Index: for_developers/Sphinx/source/Documentation/Input/ecmwf_env.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/ecmwf_env.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/ecmwf_env.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,31 @@
+****************************************
+ECMWF User Credential file ``ECMWF_ENV``
+****************************************
+
+This file contains the user credentials for working on ECMWF servers and transfering files between the ECMWF servers and the local gateway server. It is located in the ``flex_extract_vX.X/run`` directory and will be created in the installation process for the application modes **remote** and **gateway**.
+
+This file is based on the template ``ECMWF_ENV.template`` which is located in the ``templates`` directory.
+
+.. note::
+ 
+   In the **local** mode it is not present.
+
+
+
+Content of ``ECMWF_ENV``
+------------------------
+
+The following shows an example of the content of an ``ECMWF_ENV`` file:
+  
+.. code-block:: bash
+
+   ECUID user_name
+   ECGID user_group
+   GATEWAY gateway_name
+   DESTINATION destination_name
+   
+   
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/examples.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/examples.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/examples.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,39 @@
+**********************
+CONTROL file examples
+**********************
+
+``Flex_extract`` has a couple of example ``CONTROL`` files for a number of different data set constellations in the directory path ``flex_extract_vX.X/run/control``. 
+
+Here is a list of the example files and a description of the data set:
+
+CONTROL.documentation
+   This file is not intended to be used with ``flex_extract``. It has a list of all possible parameters and their default values for a quick overview. 
+   
+CONTROL_CERA
+CONTROL_CERA.global
+CONTROL_CERA.public
+CONTROL_EA5
+CONTROL_EA5.global
+CONTROL_EA5.public
+CONTROL_EI
+CONTROL_EI.global
+CONTROL_EI.public
+CONTROL_OD.ELDA.FC.eta.ens.double
+CONTROL_OD.ENFO.CF
+CONTROL_OD.ENFO.CV
+CONTROL_OD.ENFO.PF
+CONTROL_OD.ENFO.PF.36hours
+CONTROL_OD.ENFO.PF.ens
+CONTROL_OD.OPER.4V.operational
+CONTROL_OD.OPER.FC.36hours
+CONTROL_OD.OPER.FC.eta.global
+CONTROL_OD.OPER.FC.eta.highres
+CONTROL_OD.OPER.FC.gauss.highres
+CONTROL_OD.OPER.FC.operational
+CONTROL_OD.OPER.FC.twiceaday.1hourly
+CONTROL_OD.OPER.FC.twiceaday.3hourly
+
+    
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/fortran_makefile.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/fortran_makefile.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Input/fortran_makefile.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,11 +1,14 @@
-**********************************
-The Fortran Program - ``CONVERT2``
-**********************************
+***********************************
+The Fortran Makefile - ``CONVERT2``
+***********************************
 
 .. _ref-convert:
 
-One of ``flex_extract``'s components is a Fortran program called ``CONVERT2``.
-This will be compiled during the installation process to get an executable. ``flex_extract`` 
-has a couple of makefiles prepared which are listed in the following. 
+``Flex_extract``'s Fortran program will be compiled during 
+the installation process to get the executable named ``CONVERT2``. 
+
+``flex_extract`` has a couple of ``Makefiles`` prepared which can be found in the directory 
+``flex_extract_vX.X/source/fortran``, where ``vX.X`` should be substituted with the current version number.
+A list of these ``Makefiles`` are shown below: 
 
 
@@ -28,42 +31,9 @@
     | For the use with ifort compiler.
 
-They can be found in the path ``flex_extract_vX.X/source/fortran``, where
-``vX.X`` should be substituted with the current version number.
 
-So starting from the root directory of ``flex_extract``, 
-go to the ``Fortran`` source directory and open the ``Makefile`` of your 
-choice to modify with an editor of your choice. We use the ``nedit`` in this case.
-So far, we tested ``flex_extract`` with a ``gfortran`` and an ``ifort`` compiler.  
-
-.. code-block:: bash 
-
-   $ cd flex_extract_vX.X/source/fortran
-   $ nedit Makefile.local.gfortran
+For instructions on how to adapt the ``Makefiles`` for the local application mode
+please see :ref:`ref-install-local`.
 
 
-Edit the pathes to the ``eccodes`` library on your local machine. 
-
-.. caution::
-   This can vary from system to system. 
-   It is suggested to use a command like 
-
-   .. code-block:: bash
-
-      # for the ECCODES_INCLUDE_DIR path do:
-      $ dpkg -L libeccodes-dev | grep eccodes.mod
-      # for the ECCODES_LIB path do:
-      $ dpkg -L libeccodes-dev | grep libeccodes.so
-      
-   to find out the path to the ``eccodes`` library.
-   
-Substitute these paths in the ``Makefile`` for parameters **ECCODES_INCLUDE_DIR**
-and **ECCODES_LIB** and save it.
-
-.. code-block:: bash
-
-   # these are the paths on a current Debian Testing system (May 2019)
-   ECCODES_INCLUDE_DIR=/usr/lib/x86_64-linux-gnu/fortran/gfortran-mod-15/
-   ECCODES_LIB= -L/usr/lib -leccodes_f90 -leccodes -lm  
-   
    
 .. toctree::
Index: for_developers/Sphinx/source/Documentation/Input/jobscript.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/jobscript.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/jobscript.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,194 @@
+*************************
+The Jobscript ``job.ksh``
+*************************
+
+The jobscript is a Korn-shell script which will be created at runtime for each ``flex_extract`` execution in the application modes **remote** and **gateway**.
+
+It is based on the ``job.temp`` template file which is stored in the ``templates`` directory.
+This template is by itself generated in the installation process from a ``jobscript.template`` template file.
+
+``Flex_extract`` uses the python package `genshi <https://genshi.edgewall.org/>`_ to generate
+the Korn-shell script from the template files by substituting the individual parameters. 
+These individual parameters are marked by a doubled ``$`` sign in ``job.temp``. 
+
+The jobscript has a number of settings for the batch system which are fixed and differentiates between the *ecgate* and the *cca/ccb* 
+server system to load the necessary modules for the environment when submitted to the batch queue.
+
+The submission is done by the ``ECaccess`` tool from within ``flex_extract`` with the command ``ecaccess-job-submit``.
+
+
+
+What does the jobscript do?
+---------------------------
+
+ #. It sets necessary batch system parameters
+ #. It prepares the job environment at the ECMWF servers by loading the necessary library modules
+ #. It sets some environment variabels for the single session
+ #. It creates the directory structure in the users ``$SCRATCH`` file system
+ #. It creates a CONTROL file on the ECMWF servers whith the parameters set before creating the ``jobscript.ksh``. ``Flex_extract`` has a set of parameters which are given to the jobscript with its default or the user defined values. It also sets the ``CONTROL`` as an environment variable.
+ #. ``Flex_extract`` is started from within the ``work`` directory of the new directory structure by calling the ``submit.py`` script. It sets new pathes for input and output directory and the recently generated ``CONTROL`` file.
+ #. At the end it checks if the script returned an error or not and send the log file via email to the user.
+
+
+
+
+Example ``jobscript.ksh``
+-------------------------
+  
+.. code-block::  bash
+
+    #!/bin/ksh
+
+    # ON ECGB:
+    # start with ecaccess-job-submit -queueName ecgb NAME_OF_THIS_FILE  on gateway server
+    # start with sbatch NAME_OF_THIS_FILE directly on machine
+
+    #SBATCH --workdir=/scratch/ms/at/km4a
+    #SBATCH --qos=normal
+    #SBATCH --job-name=flex_ecmwf
+    #SBATCH --output=flex_ecmwf.%j.out
+    #SBATCH --error=flex_ecmwf.%j.out
+    #SBATCH --mail-type=FAIL
+    #SBATCH --time=12:00:00
+
+    ## CRAY specific batch requests
+    ##PBS -N flex_ecmwf
+    ##PBS -q np
+    ##PBS -S /usr/bin/ksh
+    ## -o /scratch/ms/at/km4a/flex_ecmwf.${PBS_JOBID}.out
+    ## job output is in .ecaccess_DO_NOT_REMOVE
+    ##PBS -j oe
+    ##PBS -V
+    ##PBS -l EC_threads_per_task=24
+    ##PBS -l EC_memory_per_task=32000MB
+
+    set -x
+    export VERSION=7.1
+    case ${HOST} in
+      *ecg*)
+      module unload grib_api
+      module unload eccodes
+      module unload python
+      module unload emos
+      module load python3
+      module load eccodes/2.12.0
+      module load emos/455-r64
+      export PATH=${PATH}:${HOME}/flex_extract_v7.1/source/python
+      ;;
+      *cca*)
+      module unload python
+      module switch PrgEnv-cray PrgEnv-intel
+      module load python3
+      module load eccodes/2.12.0
+      module load emos
+      export SCRATCH=${TMPDIR}
+      export PATH=${PATH}:${HOME}/flex_extract_v7.1/source/python
+      ;;
+    esac
+
+    cd ${SCRATCH}
+    mkdir -p python$$
+    cd python$$
+
+    export CONTROL=CONTROL
+
+    cat >${CONTROL}<<EOF
+    accmaxstep 24
+    acctime 18
+    acctype FC
+    accuracy 24
+    addpar None
+    area 74.0/-24.0/10.0/60.0
+    basetime None
+    cds_api None
+    controlfile CONTROL_CERA
+    cwc 1
+    dataset None
+    date_chunk 3
+    debug 1
+    destination annep@genericSftp
+    doubleelda 0
+    dpdeta 1
+    dtime 3
+    ec_api None
+    ecfsdir ectmp:/${USER}/econdemand/
+    ecgid at
+    ecstorage 0
+    ectrans 1
+    ecuid km4a
+    end_date 20000809
+    eta 1
+    etadiff 0
+    etapar 77
+    expver 1
+    format GRIB1
+    gateway srvx8.img.univie.ac.at
+    gauss 0
+    gaussian 
+    grib2flexpart 0
+    grid 1.0/1.0
+    inputdir /raid60/nas/tmc/Anne/Interpolation/flexextract/flex_extract_v7.1/run/workspace
+    install_target None
+    job_chunk 1
+    job_template job.temp
+    left -24.
+    level 91
+    levelist 1/to/91
+    logicals gauss omega omegadiff eta etadiff dpdeta cwc wrf grib2flexpart ecstorage ectrans debug oper request public purefc rrint doubleelda 
+    lower 10.
+    mailfail ${USER} 
+    mailops ${USER} 
+    makefile Makefile.gfortran
+    marsclass EP
+    maxstep 0
+    number 000
+    omega 0
+    omegadiff 0
+    oper 0
+    outputdir /raid60/nas/tmc/Anne/Interpolation/flexextract/flex_extract_v7.1/run/workspace
+    prefix CE
+    public 0
+    purefc 0
+    queue ecgate
+    request 2
+    resol 159
+    right 60.
+    rrint 0
+    smooth 0
+    start_date 20000809
+    step 00 00 00 00 00 00 00 00 
+    stream ENDA
+    time 00 03 06 09 12 15 18 21 
+    type AN AN AN AN AN AN AN AN 
+    upper 74.
+    wrf 0
+
+    EOF
+
+
+    submit.py --controlfile=${CONTROL} --inputdir=./work --outputdir=./work 1> prot 2>&1
+
+    if [ $? -eq 0 ] ; then
+      l=0
+      for muser in `grep -i MAILOPS ${CONTROL}`; do
+          if [ ${l} -gt 0 ] ; then 
+             mail -s flex.${HOST}.$$ ${muser} <prot
+          fi
+          l=$((${l}+1))
+      done
+    else
+      l=0
+      for muser in `grep -i MAILFAIL ${CONTROL}`; do
+          if [ ${l} -gt 0 ] ; then 
+             mail -s "ERROR! flex.${HOST}.$$" ${muser} <prot
+          fi
+          l=$((${l}+1))
+      done
+    fi
+
+
+   
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/run.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/run.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/run.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,117 @@
+**********************************
+The executable Script - ``run.sh``
+**********************************
+
+The execution of ``flex_extract`` is done by the ``run.sh`` Shell script, which is a wrapping script for the top-level Python script ``submit.py``. 
+The Python script constitutes the entry point to ECMWF data retrievals with ``flex_extract`` and controls the program flow. 
+
+``submit.py`` has two (three) sources for input parameters with information about program flow and ECMWF data selection, the so-called ``CONTROL`` file,  
+the command line parameters and the so-called ``ECMWF_ENV`` file. Whereby, the command line parameters will override the ``CONTROL`` file parameters. 
+
+Based on these input information ``flex_extract`` applies one of the application modes to either retrieve the ECMWF data via a Web API on a local maschine or submit a jobscript to ECMWF servers and retrieve the data there with sending the files to the local system eventually.
+
+
+
+PUT IN HERE A BLOCKDIAGRAM OF RAW PROGRAM FLOW
+
+
+
+Submission Parameter
+--------------------
+
+
+.. exceltable:: Parameter for Submission
+    :file:  ../../_files/SubmitParameters.xls
+    :header: 1  
+    :sheet: 0
+   
+   
+   
+
+Content of ``run.sh``
+---------------------
+  
+.. literalinclude:: ../../../../../Run/run.sh 
+   :language: bash
+   :caption: run.sh
+
+
+.. _ref-install-script:
+       
+Usage of ``submit.py`` (optional)
+---------------------------------
+
+It is also possible to start ``flex_extract`` directly from command line by using the ``submit.py`` script instead of the wrapping Shell script ``run.sh``.  This top-level script is located in 
+``flex_extract_vX.X/source/python`` and is executable. With the ``help`` parameter we see again all possible 
+command line parameter. 
+
+.. code-block:: bash
+
+   submit.py --help
+
+   usage: submit.py [-h] [--start_date START_DATE] [--end_date END_DATE]
+                 [--date_chunk DATE_CHUNK] [--job_chunk JOB_CHUNK]
+                 [--controlfile CONTROLFILE] [--basetime BASETIME]
+                 [--step STEP] [--levelist LEVELIST] [--area AREA]
+                 [--debug DEBUG] [--oper OPER] [--request REQUEST]
+                 [--public PUBLIC] [--rrint RRINT] [--inputdir INPUTDIR]
+                 [--outputdir OUTPUTDIR] [--ppid PPID]
+                 [--job_template JOB_TEMPLATE] [--queue QUEUE]
+
+    Retrieve FLEXPART input from ECMWF MARS archive
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --start_date START_DATE
+                            start date YYYYMMDD (default: None)
+      --end_date END_DATE   end_date YYYYMMDD (default: None)
+      --date_chunk DATE_CHUNK
+                            # of days to be retrieved at once (default: None)
+      --job_chunk JOB_CHUNK
+                            # of days to be retrieved within a single job
+                            (default: None)
+      --controlfile CONTROLFILE
+                            The file with all CONTROL parameters. (default:
+                            CONTROL_EA5)
+      --basetime BASETIME   base such as 0 or 12 (for half day retrievals)
+                            (default: None)
+      --step STEP           Forecast steps such as 00/to/48 (default: None)
+      --levelist LEVELIST   Vertical levels to be retrieved, e.g. 30/to/60
+                            (default: None)
+      --area AREA           area defined as north/west/south/east (default: None)
+      --debug DEBUG         debug mode - leave temporary files intact (default:
+                            None)
+      --oper OPER           operational mode - prepares dates with environment
+                            variables (default: None)
+      --request REQUEST     list all mars requests in file mars_requests.dat
+                            (default: None)
+      --public PUBLIC       public mode - retrieves the public datasets (default:
+                            None)
+      --rrint RRINT         Selection of old or new precipitation interpolation: 0
+                            - old method 1 - new method (additional subgrid
+                            points) (default: None)
+      --inputdir INPUTDIR   Path to the temporary directory for the retrieval grib
+                            files and other processing files. (default: None)
+      --outputdir OUTPUTDIR
+                            Path to the final directory where the final FLEXPART
+                            ready input files are stored. (default: None)
+      --ppid PPID           This is the specify parent process id of a single
+                            flex_extract run to identify the files. It is the
+                            second number in the GRIB files. (default: None)
+      --job_template JOB_TEMPLATE
+                            The job template file which are adapted to be
+                            submitted to the batch system on ECMWF server.
+                            (default: job.temp)
+      --queue QUEUE         The ECMWF server name for submission of the job script
+                            to the batch system (e.g. ecgate | cca | ccb)
+                            (default: None)
+
+
+
+
+
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Input/setup.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/setup.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Input/setup.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -3,22 +3,197 @@
 **************************************
 
-.. _ref-setup:
-
-
-The installation script ``setup.sh`` prepares the call of the Python 
-installation script (``install.py``) with its necessary command line arguments. 
-The ``setup.sh`` script is located in the root directory of ``flex_extract`` and has a 
-section labelled with "AVAILABLE COMMANDLINE ARGUMENTS TO SET" which
-contains the available command line parameters for ``install.py``. The user has to adapt these
-parameters for his personal use. The parameters are listed and described in the following table.
-The script also does some checks to guarantee necessary parameters were set.
-   
-.. csv-table:: 
-   :file: ../../_files/InstallationParameters.csv
-   :header-rows: 1
-   :widths: auto   
-
-After the installation some tests can be conducted. 
-They are described in section :ref:`ref-testinstallfe`.
+
+The installation of ``flex_extract`` is done by the Shell script ``setup.sh`` which is located in the root directory of ``flex_extract``.
+It calls the top-level Python script ``install.py`` which does all necessary operations to prepare the selected application environment. This includes:
+
+- preparing the file ``ECMWF_ENV`` with the user credentials for member state access to ECMWF servers (in **remote** and **gateway** mode)
+- preparation of a compilation Korn-shell script (in **remote** and **gateway** mode)
+- preparation of a job template with user credentials (in **remote** and **gateway** mode)
+- create a tar-ball of all necessary files
+- copying tar-ball to target location (depending on application mode and installation path)
+- submit compilation script to batch queue at ECMWF servers (in **remote** and **gateway** mode) or just untar tar-ball at target location (**local mode**)
+- compilation of the FORTRAN90 program ``CONVERT2``
+
+
+The Python installation script ``install.py`` has a couple of command line arguments which are defined in ``setup.sh`` in the section labelled with "*AVAILABLE COMMANDLINE ARGUMENTS TO SET*". The user has to adapt these parameters for his personal use. The parameters are listed and described in :ref:`ref-instparams`. The script also does some checks to guarantee necessary parameters were set.
+   
+After the installation process, some tests can be conducted. They are described in section :ref:`ref-testinstallfe`.
+
+The following diagram sketches the involved files and scripts in the installation process:
+
+.. _ref-install-blockdiag:
+
+.. blockdiag::
+
+   blockdiag {
+   
+     default_fontsize = 24; 
+     
+     // Set node metrix
+     node_width = 300; // default is 128
+   
+     // Set span metrix
+     span_width = 80;  // default value is 64
+     
+     ECMWF_ENV.template [shape = flowchart.input];
+     compilejob.template [shape = flowchart.input];
+     job.template [shape = flowchart.input];
+     
+     compilejob.ksh [shape = roundedbox];
+    // tarball
+    // ECMWF_ENV
+    // job.temp
+     
+     "CONTROL file" [shape = flowchart.input];
+     
+     setup.sh [shape = roundedbox];
+     install.py [shape = roundedbox];
+     
+     "ECMWF server"  [shape = flowchart.terminator];
+     
+     //beginpoint [shape = beginpoint];
+     
+     orientation = landscape;
+     
+     //beginpoint -> setup.sh;
+     setup.sh -> install.py;
+     
+     install.py <- "CONTROL file";
+                 
+     install.py -> ECMWF_ENV, job.temp, compilejob.ksh, tarball;   
+
+     ECMWF_ENV.template, job.template, compilejob.template  -> install.py; 
+     
+     tarball, compilejob.ksh -> "ECMWF server";
+     
+          
+     group exec {
+       // set backgound color
+       color = "#FF6633";
+       
+       orientation = portrait;
+       setup.sh;
+       install.py;
+     }
+     
+     group out {
+       color = "#FFFFFF";
+       group output {
+         color = "#99FF99";
+         ECMWF_ENV;
+         job.temp; 
+         compilejob.ksh; 
+       }
+        
+       group ECMWF {
+         color = "#006600";
+         tarball;
+         
+       }
+     }
+ 
+     group input {
+       
+       color = "#FFFFFF";
+       
+       group temps {
+         color = "#66CCFF";
+                  
+         ECMWF_ENV.template;
+         job.template;
+         compilejob.template;
+       }
+       
+       group in {
+         color = "#3366FF";
+         "CONTROL file";
+       }
+     }
+     
+   }
+
+
+.. blockdiag::
+   :caption: Diagram of data flow during the installation process. The trapezoids are input files with the light blue area being the template files. The edge-rounded, orange boxes are the executable files which start the installation process and reads the input files. The rectangular, green boxes are the output files. The light green files are files which are only needed in the remota and gateway mode.
+
+   blockdiag {
+   
+     group{
+       orientation = portrait;
+       label = "Legend";
+       fontsize = 28;
+       color = "#FFFFFF";
+       'executable scripts' [shape = roundedbox];
+       'input files' [shape = flowchart.input];
+       'output files';
+        server [shape = flowchart.terminator];
+     }
+   }
+
+.. _ref-instparams:
+
+Installation Parameter
+----------------------
+   
+.. exceltable:: Parameter for Installation
+    :file:  ../../_files/InstallationParameter.xls
+    :header: 1  
+   
+
+
+Content of ``setup.sh``
+-----------------------
+  
+.. literalinclude:: ../../../../../setup.sh 
+   :language: bash
+   :caption: setup.sh
+       
+       
+.. _ref-install-script:
+       
+Usage of ``install.py`` (optional)
+----------------------------------
+
+It is also possible to start the installation process of ``flex_extract`` directly from command line by using the ``install.py`` script instead of the wrapping Shell script ``setup.sh``.  This top-level script is located in 
+``flex_extract_vX.X/source/python`` and is executable. With the ``help`` parameter we see again all possible 
+command line parameter. 
+
+.. code-block:: bash
+ 
+    install.py --help
+    
+    usage: install.py [-h] [--target INSTALL_TARGET] [--makefile MAKEFILE]
+                  [--ecuid ECUID] [--ecgid ECGID] [--gateway GATEWAY]
+                  [--destination DESTINATION] [--installdir INSTALLDIR]
+                  [--job_template JOB_TEMPLATE] [--controlfile CONTROLFILE]
+
+    Install flex_extract software locally or on ECMWF machines
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --target INSTALL_TARGET
+                            Valid targets: local | ecgate | cca , the latter two
+                            are at ECMWF (default: None)
+      --makefile MAKEFILE   Name of Makefile to use for compiling the Fortran
+                            program (default: None)
+      --ecuid ECUID         The user id at ECMWF. (default: None)
+      --ecgid ECGID         The group id at ECMWF. (default: None)
+      --gateway GATEWAY     The name of the local gateway server. (default: None)
+      --destination DESTINATION
+                            The ecaccess association, e.g. myUser@genericSftp
+                            (default: None)
+      --installdir INSTALLDIR
+                            Root directory where flex_extract will be installed
+                            to. (default: None)
+      --job_template JOB_TEMPLATE
+                            The rudimentary template file to create a batch job
+                            template for submission to ECMWF servers. (default:
+                            job.template)
+      --controlfile CONTROLFILE
+                            The file with all CONTROL parameters. (default:
+                            CONTROL_EA5)
+
+
+
 
 
Index: for_developers/Sphinx/source/Documentation/Input/templates.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Input/templates.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Documentation/Input/templates.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,346 @@
+*********
+Templates
+*********
+
+In ``flex_extract`` we use the Python package ``genshi`` (`ref <https://genshi.edgewall.org/>`_) to create specific files from templates. It is the most efficient way to be able to quickly adapt e.g. the job scripts send to the ECMWF batch queue system or the namelist file für the Fortran program without the need to change the program code. 
+
+.. note::
+   Usually it is not recommended to change anything in these files without being able to understand the effects.
+   
+Each template file has its content framework and keeps so-called placeholder variables in the positions where the values needs to be substituted at run time. These placeholders are marked by a leading ``$`` sign. In case of the Kornshell job scripts, where (environment) variables are used the ``$`` sign needs to be doubled to `escape` and keep a single ``$`` sign as it is.
+   
+The following templates are used and can be found in directory ``flex_extract_vX.X/Templates``:
+
+convert.nl
+----------
+
+    This is the template for a Fortran namelist file called ``fort.4`` which will be read by ``CONVERT2``.
+    It contains all the parameters ``CONVERT2`` needs. 
+    
+    .. code-block:: fortran
+ 
+        &NAMGEN
+          maxl = $maxl,
+          maxb = $maxb,
+          mlevel = $mlevel,
+          mlevelist = "$mlevelist",
+          mnauf = $mnauf,
+          metapar = $metapar,
+          rlo0 = $rlo0,
+          rlo1 = $rlo1,
+          rla0 = $rla0,
+          rla1 = $rla1,
+          momega = $momega,
+          momegadiff = $momegadiff,
+          mgauss = $mgauss,
+          msmooth = $msmooth,
+          meta = $meta,
+          metadiff = $metadiff,
+          mdpdeta = $mdpdeta
+        /
+
+ecmwf_env.template
+------------------
+
+    This template is used to create the ``ECMWF_ENV`` file in the application modes **gateway** and **remote**. It contains the user credentials and gateway server settings for the file transfers.
+
+    .. code-block:: bash
+    
+        ECUID $user_name
+        ECGID $user_group
+        GATEWAY $gateway_name
+        DESTINATION $destination_name
+
+compilejob.template
+-------------------
+
+    This template is used to create the job script file called ``compilejob.ksh`` during the installation process for the application modes **remote** and **gateway**. 
+
+    At the beginning some directives for the batch system are set. 
+    On the **ecgate** server the ``SBATCH`` comments are the directives for the SLURM workload manager. A description of the single lines can be found at `SLURM directives <https://confluence.ecmwf.int/display/UDOC/Writing+SLURM+jobs>`_.
+    For the high performance computers **cca** and **ccb** the ``PBS`` comments are necessary and can be view at `PBS directives <https://confluence.ecmwf.int/display/UDOC/Batch+environment%3A++PBS>`_.
+
+    The software environment requirements mentioned in :ref:`ref-requirements` are prepared by loading the corresponding modules depending in the ``HOST``. It should not be changed without testing.
+    
+    Afterwards the installation steps as such are done. Including the generation of the root directory, putting files in place, compiling the Fortran program and sending a log file via email.
+
+    .. code-block:: ksh
+    
+        #!/bin/ksh
+
+        # ON ECGB:
+        # start with ecaccess-job-submit -queueName ecgb NAME_OF_THIS_FILE  on gateway server
+        # start with sbatch NAME_OF_THIS_FILE directly on machine
+
+        #SBATCH --workdir=/scratch/ms/$usergroup/$username
+        #SBATCH --qos=normal
+        #SBATCH --job-name=flex_ecmwf
+        #SBATCH --output=flex_ecmwf.%j.out
+        #SBATCH --error=flex_ecmwf.%j.out
+        #SBATCH --mail-type=FAIL
+        #SBATCH --time=12:00:00
+
+        ## CRAY specific batch requests
+        ##PBS -N flex_ecmwf
+        ##PBS -q ns
+        ##PBS -S /usr/bin/ksh
+        ##PBS -o /scratch/ms/$usergroup/$username/flex_ecmwf.$${Jobname}.$${Job_ID}.out
+        # job output is in .ecaccess_DO_NOT_REMOVE
+        ##PBS -j oe
+        ##PBS -V
+        ##PBS -l EC_threads_per_task=1
+        ##PBS -l EC_memory_per_task=3200MB
+
+        set -x
+        export VERSION=$version_number
+        case $${HOST} in
+          *ecg*)
+          module unload grib_api
+          module unload eccodes
+          module unload python
+          module unload emos
+          module load python3
+          module load eccodes/2.12.0
+          module load emos/455-r64
+          export FLEXPART_ROOT_SCRIPTS=$fp_root_scripts
+          export MAKEFILE=$makefile
+          ;;
+          *cca*)
+          module unload python
+          module switch PrgEnv-cray PrgEnv-intel
+          module load python3
+          module load eccodes/2.12.0
+          module load emos
+          echo $${GROUP}
+          echo $${HOME}
+          echo $${HOME} | awk -F / '{print $1, $2, $3, $4}'
+          export GROUP=`echo $${HOME} | awk -F / '{print $4}'`
+          export SCRATCH=/scratch/ms/$${GROUP}/$${USER}
+          export FLEXPART_ROOT_SCRIPTS=$fp_root_scripts
+          export MAKEFILE=$makefile
+          ;;
+        esac
+
+        mkdir -p $${FLEXPART_ROOT_SCRIPTS}/flex_extract_v$${VERSION}
+        cd $${FLEXPART_ROOT_SCRIPTS}/flex_extract_v$${VERSION}   # if FLEXPART_ROOT is not set this means cd to the home directory
+        tar -xvf $${HOME}/flex_extract_v$${VERSION}.tar
+        cd source/fortran
+        \rm *.o *.mod $fortran_program 
+        make -f $${MAKEFILE} >flexcompile 2>flexcompile
+
+        ls -l $fortran_program >>flexcompile
+        if [ $$? -eq 0 ]; then
+          echo 'SUCCESS!' >>flexcompile
+          mail -s flexcompile.$${HOST}.$$$$ $${USER} <flexcompile
+        else
+          echo Environment: >>flexcompile
+          env >> flexcompile
+          mail -s "ERROR! flexcompile.$${HOST}.$$$$" $${USER} <flexcompile
+        fi
+
+
+job.temp
+--------
+
+    This template is used to create the actual job script file called ``job.ksh`` for the execution of ``flex_extract`` in the application modes **remote** and **gateway**. 
+
+    At the beginning some directives for the batch system are set. 
+    On the **ecgate** server the ``SBATCH`` comments are the directives for the SLURM workload manager. A description of the single lines can be found at `SLURM directives <https://confluence.ecmwf.int/display/UDOC/Writing+SLURM+jobs>`_.
+    For the high performance computers **cca** and **ccb** the ``PBS`` comments are necessary and can be view at `PBS directives <https://confluence.ecmwf.int/display/UDOC/Batch+environment%3A++PBS>`_.
+
+    The software environment requirements mentioned in :ref:`ref-requirements` are prepared by loading the corresponding modules depending in the ``HOST``. It should not be changed without testing.
+    
+    Afterwards the run directory and the ``CONTROL`` file are created and ``flex_extract`` is executed. In the end a log file is send via email.
+    
+    .. code-block:: ksh
+    
+        #!/bin/ksh
+
+        # ON ECGB:
+        # start with ecaccess-job-submit -queueName ecgb NAME_OF_THIS_FILE  on gateway server
+        # start with sbatch NAME_OF_THIS_FILE directly on machine
+
+        #SBATCH --workdir=/scratch/ms/at/km4a
+        #SBATCH --qos=normal
+        #SBATCH --job-name=flex_ecmwf
+        #SBATCH --output=flex_ecmwf.%j.out
+        #SBATCH --error=flex_ecmwf.%j.out
+        #SBATCH --mail-type=FAIL
+        #SBATCH --time=12:00:00
+
+        ## CRAY specific batch requests
+        ##PBS -N flex_ecmwf
+        ##PBS -q np
+        ##PBS -S /usr/bin/ksh
+        ## -o /scratch/ms/at/km4a/flex_ecmwf.$${PBS_JOBID}.out
+        ## job output is in .ecaccess_DO_NOT_REMOVE
+        ##PBS -j oe
+        ##PBS -V
+        ##PBS -l EC_threads_per_task=24
+        ##PBS -l EC_memory_per_task=32000MB
+
+        set -x
+        export VERSION=7.1
+        case $${HOST} in
+          *ecg*)
+          module unload grib_api
+          module unload eccodes
+          module unload python
+          module unload emos
+          module load python3
+          module load eccodes/2.12.0
+          module load emos/455-r64
+          export PATH=$${PATH}:$${HOME}/flex_extract_v7.1/source/python
+          ;;
+          *cca*)
+          module unload python
+          module switch PrgEnv-cray PrgEnv-intel
+          module load python3
+          module load eccodes/2.12.0
+          module load emos
+          export SCRATCH=$${TMPDIR}
+          export PATH=$${PATH}:$${HOME}/flex_extract_v7.1/source/python
+          ;;
+        esac
+
+        cd $${SCRATCH}
+        mkdir -p python$$$$
+        cd python$$$$
+
+        export CONTROL=CONTROL
+
+        cat >$${CONTROL}<<EOF
+        $control_content
+        EOF
+
+
+        submit.py --controlfile=$${CONTROL} --inputdir=./work --outputdir=./work 1> prot 2>&1
+
+        if [ $? -eq 0 ] ; then
+          l=0
+          for muser in `grep -i MAILOPS $${CONTROL}`; do
+              if [ $${l} -gt 0 ] ; then 
+                 mail -s flex.$${HOST}.$$$$ $${muser} <prot
+              fi
+              l=$(($${l}+1))
+          done
+        else
+          l=0
+          for muser in `grep -i MAILFAIL $${CONTROL}`; do
+              if [ $${l} -gt 0 ] ; then 
+                 mail -s "ERROR! flex.$${HOST}.$$$$" $${muser} <prot
+              fi
+              l=$(($${l}+1))
+          done
+        fi
+        
+
+job.template
+------------
+
+    This template is used to create the template for the execution job script ``job.temp`` for ``flex_extract`` in the installation process. A description of the file can be found under ``job.temp``. A couple of parameters are set in this process, such as the user credentials and the ``flex_extract`` version number.
+        
+    .. code-block:: ksh
+    
+        #!/bin/ksh
+
+        # ON ECGB:
+        # start with ecaccess-job-submit -queueName ecgb NAME_OF_THIS_FILE  on gateway server
+        # start with sbatch NAME_OF_THIS_FILE directly on machine
+
+        #SBATCH --workdir=/scratch/ms/$usergroup/$username
+        #SBATCH --qos=normal
+        #SBATCH --job-name=flex_ecmwf
+        #SBATCH --output=flex_ecmwf.%j.out
+        #SBATCH --error=flex_ecmwf.%j.out
+        #SBATCH --mail-type=FAIL
+        #SBATCH --time=12:00:00
+
+        ## CRAY specific batch requests
+        ##PBS -N flex_ecmwf
+        ##PBS -q np
+        ##PBS -S /usr/bin/ksh
+        ## -o /scratch/ms/$usergroup/$username/flex_ecmwf.$$$${PBS_JOBID}.out
+        ## job output is in .ecaccess_DO_NOT_REMOVE
+        ##PBS -j oe
+        ##PBS -V
+        ##PBS -l EC_threads_per_task=24
+        ##PBS -l EC_memory_per_task=32000MB
+
+        set -x
+        export VERSION=$version_number
+        case $$$${HOST} in
+          *ecg*)
+          module unload grib_api
+          module unload eccodes
+          module unload python
+          module unload emos
+          module load python3
+          module load eccodes/2.12.0
+          module load emos/455-r64
+          export PATH=$$$${PATH}:$fp_root_path
+          ;;
+          *cca*)
+          module unload python
+          module switch PrgEnv-cray PrgEnv-intel
+          module load python3
+          module load eccodes/2.12.0
+          module load emos
+          export SCRATCH=$$$${TMPDIR}
+          export PATH=$$$${PATH}:$fp_root_path
+          ;;
+        esac
+
+        cd $$$${SCRATCH}
+        mkdir -p python$$$$$$$$
+        cd python$$$$$$$$
+
+        export CONTROL=CONTROL
+
+        cat >$$$${CONTROL}<<EOF
+        $$control_content
+        EOF
+
+
+        submit.py --controlfile=$$$${CONTROL} --inputdir=./work --outputdir=./work 1> prot 2>&1
+
+        if [ $? -eq 0 ] ; then
+          l=0
+          for muser in `grep -i MAILOPS $$$${CONTROL}`; do
+              if [ $$$${l} -gt 0 ] ; then 
+                 mail -s flex.$$$${HOST}.$$$$$$$$ $$$${muser} <prot
+              fi
+              l=$(($$$${l}+1))
+          done
+        else
+          l=0
+          for muser in `grep -i MAILFAIL $$$${CONTROL}`; do
+              if [ $$$${l} -gt 0 ] ; then 
+                 mail -s "ERROR! flex.$$$${HOST}.$$$$$$$$" $$$${muser} <prot
+              fi
+              l=$(($$$${l}+1))
+          done
+        fi
+
+
+
+
+
+
+
+  
+
+
+
+
+
+   
+   
+
+ 
+   
+   
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/Overview/app_modes.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Overview/app_modes.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Overview/app_modes.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -14,21 +14,21 @@
 Arising from the two user groups described in :doc:`../../Ecmwf/access`, ``flex_extract`` has 4 different :underline:`user application modes`:
 
-.. _ref-remote-des:
+.. _ref-remote-desc:
 
   1. Remote (member)
       In the **Remote mode** the user works directly on ECMWF Linux member state server, such as ``ecgate`` or ``cca``. The software will be installed in the ``$HOME`` directory. The user does not need to install any of the additional third-party libraries mentioned in :ref:`ref-requirements` as ECMWF provides everything with environment modules. The module selection will be done automatically in ``flex_extract``. 
       
-.. _gateway:
+.. _ref-gateway-desc:
       
   2. Gateway (member)
-      The **Gateway mode** can be used if a local member state gateway server is in place. Then the job scripts can be submitted to the ECMWF Linux member state server via the ECMWF web access tool ``ecaccess``. The installation script of ``flex_extract`` must be executed at the local gateway server such that the software will be installed in the ``$HOME`` directory at the ECMWF server and some extra setup is done in the local ``flex_extract`` directory at the local gateway server. For more information about establishing a gateway server please see section ???. For the **Gateway mode** the necessary environment has to be established which is described in :ref:`ref-local-prep`.
+      The **Gateway mode** can be used if a local member state gateway server is in place. Then the job scripts can be submitted to the ECMWF Linux member state server via the ECMWF web access tool ``ecaccess``. The installation script of ``flex_extract`` must be executed at the local gateway server such that the software will be installed in the ``$HOME`` directory at the ECMWF server and some extra setup is done in the local ``flex_extract`` directory at the local gateway server. For more information about establishing a gateway server please see section ???. For the **Gateway mode** the necessary environment has to be established which is described in :ref:`ref-prep-gateway`.
 
-.. _local:
+.. _ref-local-desc:
       
   3. Local member
-      Scripts are installed and executed on a local machine, either in the current ``flex_extract`` directory or in a path given to the installation script. Under this scenario a software environment similar to that at ECMWF is required. Additionally, Web API's have to be installed to access ECMWF server. The complete installation process is described in :ref:`ref-local-prep`.
+      Scripts are installed and executed on a local machine, either in the current ``flex_extract`` directory or in a path given to the installation script. Under this scenario a software environment similar to that at ECMWF is required. Additionally, Web API's have to be installed to access ECMWF server. The complete installation process is described in :ref:`ref-local-mode`.
       
   4. Local public
-      Scripts are installed and executed on a local machine, either in the current ``flex_extract`` directory or in a path given to the installation script. Under this scenario a software environment similar to that at ECMWF is required. Additionally, Web API's have to be installed to access ECMWF server. The complete installation process is described in :ref:`ref-local-prep`. In this case a direct registration at ECMWF is necessary and the user has to accept a specific license agreement for each dataset he/she intends to retrieve. 
+      Scripts are installed and executed on a local machine, either in the current ``flex_extract`` directory or in a path given to the installation script. Under this scenario a software environment similar to that at ECMWF is required. Additionally, Web API's have to be installed to access ECMWF server. The complete installation process is described in :ref:`ref-local-mode`. In this case a direct registration at ECMWF is necessary and the user has to accept a specific license agreement for each dataset he/she intends to retrieve. 
       
       
Index: for_developers/Sphinx/source/Documentation/Overview/convert.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Overview/convert.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,7 +1,0 @@
-=======
-CONVERT
-=======
-
- 
-    UNDER CONSTRUCTION
-    
Index: for_developers/Sphinx/source/Documentation/Overview/prog_flow.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/Overview/prog_flow.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/Overview/prog_flow.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,5 +1,56 @@
+************
 Program Flow
-================
+************
 
- 
-    UNDER CONSTRUCTION
+
+
+
+General program flow
+====================
+
+
+The following flow diagram shows the general steps performed by ``flex_extract``. 
+    
+.. _ref-fig-submit:
+
+.. figure:: ../../_files/submit.png    
+    
+    Overview of the call of python's ``submit.py`` script and raw sequence of working steps done in ``flex_extract``.
+
+    
+The ``submit.py`` Python program is called by the Shell script ``run.sh`` or ``run_local.sh`` and accomplish the following steps: 
+
+    1. Setup the control data:
+        It gets all command-line and ``CONTROL`` file parameters as well as optionally the ECMWF user credentials. Depending the :doc:`app_modes`, it might also prepare a job script which is then send to the ECMWF queue. 
+    2. Retrieves data from MARS:
+        It creates and sends MARS-requests either on the local machine or on ECMWF server, that receives the data and stores them in a specific format in GRIB files. If the parameter ``REQUEST`` was set ``1`` the data are not received but a file ``mars_requests.csv`` is created with a list of MARS requests and their settings. If it is set to ``2`` the file is created in addition to retrieving the data. The requests are created in an optimised way by splitting in time, jobs  and parameters.   
+    3. Post-process data to create final ``FLEXPART`` input files:
+        After all data is retrieved, the disaggregation of flux fields (`see here <../disagg.html>`_ ) is done as well as the calculation of vertical velocity (`see here <../vertco.html>`_) by the Fortran program ``COVERT2``. Eventually, the GRIB fields are merged together such that a single grib file per time step is available with all fields for ``FLEXPART``. Since model level fields are typically in *GRIB2* format whereas surface level fields are still in *GRIB1* format, they can be converted into GRIB2 if parameter ``FORMAT`` is set to *GRIB2*. Please note, however, that older versions of FLEXPART may have difficulties reading pure *GRIB2* files since some parameter IDs change in *GRIB2*. If the retrieval is executed remotely at ECMWF, the resulting files can be communicated to the local gateway server via the ``ECtrans`` utility if the parameter ``ECTRANS`` is set to ``1`` and the parameters ``GATEWAY``, ``DESTINATION`` have been set properly during installation. The status of the transfer can be checked with the command ``ecaccess-ectrans-list`` (on the local gateway server). If the script is executed locally the progress of the script can be followed with the usual Linux tools.
+
+
+
+Workflows of different application modes
+========================================
+
+More details on how different the program flow is for the different :doc:`app_modes` is sketched in the following diagrams:  
+
++-------------------------------------------------+------------------------------------------------+
+| .. figure:: ../../_files/mode_remote.png        | .. figure:: ../../_files/mode_gateway.png      |
++-------------------------------------------------+------------------------------------------------+   
+
++-------------------------------------------------+------------------------------------------------+
+| .. figure:: ../../_files/mode_local_member.png  | .. figure:: ../../_files/mode_local_public.png |
++-------------------------------------------------+------------------------------------------------+   
+
+
+Example application setting for a local member user
+===================================================
+
+.. figure:: ../../_files/ex_runlocal_en.png  
+
+
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Documentation/api.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/api.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/api.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,82 +1,17 @@
+****************************
 Auto Generated Documentation
-============================
+****************************
+    
+    
+:doc:`Api/api_python`
+  
+:doc:`Api/api_fortran`
 
-.. contents::
-    :local:
+  
+        
+.. toctree::
+    :hidden:
+    :maxdepth: 2
     
-Porgrams
---------
-
-install
-*******
-
-.. automodule:: install
-    :members:
-    
-submit
-******
-
-.. automodule:: submit
-    :members:
-    
-Classes
--------
-
-ControlFile
-***********
-
-.. automodule:: ControlFile
-    :members:
-    
-EcFlexpart
-**********
-
-.. automodule:: EcFlexpart
-    :members:
-    
-GribUtil
-*********
-
-.. automodule:: GribUtil
-    :members:
-
-MarsRetrieval
-*************
-
-.. automodule:: MarsRetrieval
-    :members:
-
-UioFiles
-********
-
-.. automodule:: UioFiles
-    :members:
-
-
-
-Modules
--------
-
-get_mars_data
-*************
-
-.. automodule:: get_mars_data
-    :members:
- 
-prepare_flexpart
-****************
-
-.. automodule:: prepare_flexpart
-    :members:    
-    
-tools
-*****
-
-.. automodule:: tools
-    :members:
-
-disaggregation
-**************    
-    
-.. automodule:: disaggregation
-    :members:
+    Api/api_python
+    Api/api_fortran
Index: for_developers/Sphinx/source/Documentation/disagg.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/disagg.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/disagg.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,7 +1,183 @@
-===========================
+***************************
 Disaggregation of Flux Data
-===========================
+***************************
     
-    UNDER CONSTRUCTION    
+``FLEXPART`` interpolates meteorological input data linearly to the position of computational particles in time and space. This method requires point values in the discrete input fields. However, flux data (as listed in table :ref:`ref-table-fluxpar`) from the ECMWF represent cell averages or integrals and are accumulated over a specific time interval, depending on the dataset. Hence, to conserve the integral quantity with ``FLEXPART``'s linear interpolation a pre-processing scheme has to be applied. 
+
+.. _ref-table-fluxpar:
+
+.. csv-table:: flux fields
+    :header: "Short Name", "Name", "Units", "Interpolation Type"
+    :align: center
+    :widths: 5,15,5,10
+    
+    LSP,  "large-scale precipitation",          ":math:`m`",          "modified linear interpolation"
+    CP,   "convective precipitation",           ":math:`m`",          "modified linear interpolation"
+    SSHF, "surface sensible heat flux",         ":math:`J m^{-2}`",   "bicubic interpolation"
+    EWSS, "eastward turbulent surface stress",  ":math:`N m^{-2} s`", "bicubic interpolation"
+    NSSS, "northward turbulent surface stress", ":math:`N m^{-2} s`", "bicubic interpolation"
+    SSR,  "surface net solar radiation",        ":math:`J m^{-2}`",   "bicubic interpolation"
+    
+
+The first step is to *de-accumulate* the fields in time so that each value represents an integral in x, y, t space.
+Afterwards, a *disaggregation* scheme is applied which means to break down the integral value into point values. 
+In order to be able to carry out the disaggregation procedure proposed by Paul James, additional flux data is retrieved automatically for one day at the beginning and one day at the end of the period specified. Thus, data for flux computation will be requested for the period START_DATE-1 to END_DATE+1. Note that these (additional) dates are used only for interpolation within ``flex_extract`` and are not communicated to the final ``FLEXPART`` input files.
+
+The flux disaggregation produces files named ``fluxYYYYMMDDHH``, where ``YYYYMMDDHH`` is the date format. Note, that the first two and last two flux files do not contain any data.
+
+.. note::
+
+    Note also that for operational retrievals (``BASETIME`` set to 00 or 12) forecast fluxes are only available until ``BASETIME``, so that no polynomial interpolation is possible in the last two time intervals. This is the reason why setting ``BASETIME`` is not recommended for on demand scripts.        
+        
+
+Disaggregation for precipitation in older versions
+--------------------------------------------------
+
+In ``flex_extract`` up to version 5 the disaggregation was done with a Fortran program (FLXACC2). In version 6 this part was converted to Python.
+
+
+In the old versions (below 7.1) a relatively simple method processes the precipitation fields in a way that is consistent with the scheme applied in ``FLEXPART`` for all variables: linear interpolation between times where input fields are available.
+At first the accumulated values are divided by the number of hours (i.e., 3 or 6).
+The best option for disaggregation, which was realised, is conservation within the interval under consideration plus the two adjacent ones. 
+Unfortunately, this leads to undesired temporal smoothing of the precipitation time series – maxima are damped and minima are raised. 
+It is even possible to produce non-zero precipitation in dry intervals bordering a precipitation period as shown in Fig. 1.
+This is obviously undesirable as it will affect wet scavenging, a very efficient removal process for many atmospheric trace species. 
+Wet deposition may be produced in grid cells where none should occur, or too little may be produced in others. This could lead to an unrealistic, checkerboard-like deposition fields.
+Horizontally, the precipitation values are averages for a grid cell around the grid point to which they are ascribed, and ``FLEXPART`` uses bilinear interpolation to obtain precipitation rates at particle positions. 
+However, the supporting points in space are not shifted between precipitation and other variables as is the case for the temporal dimension.
+
+
+.. _ref-fig-olddisagg:
+
+.. figure:: ../_files/old_disagg.png
+    :figclass: align-center
+
+    Fig. 1: Example of disaggregation scheme as implemented in older versions for an isolated precipitation event lasting one time interval (thick blue line). The amount of original precipitation after de-accumulation is given by the blue-shaded area. The green circles represent the discrete grid points after disaggregation and linearly interpolate in between them as indicated by the green line and the green-shaded area. Note that supporting points for the interpolation are shifted by a half-time interval compared to the times when other meteorological fields are available (Hittmeir et al. 2018).
+
+
+
+Disaggregation is done for 4 adjacent timespans (:math:`a_0, a_1, a_2, a_3`) which generates a new, disaggregated value which is output at the central point of the 4 adjacent timespans. 
+
+.. math::
+
+       p_{ac} &= 0.5 * a_1\\
+            m &= a_0 + a_2 > 0.\\
+    p_{ac}(m) &= a_1(m) * a_2(m) / (a_0(m) + a_2(m))\\
+       p_{bd} &= 0.5 * a_2\\
+            m &= a_1 + a_3 > 0.\\
+    p_{bd}(m) &= a_1(m) * a_2(m) / (a_1(m) + a_3(m))\\
+
+
+This new point :math:`p` is used for linear interpolation of the complete timeseries afterwards. If one of the 4 original timespans has a value below 0 it is set to 0 prior to the calculation.
+    
+.. math::
+
+    p = p_{ac} + p_{bd}
+
+
+
+
+
+
+Disaggregation for precipitation in version 7.1
+-----------------------------------------------
+
+Due to the problems with generating precipitation in originally dry (or lower) intervals and the temporal smoothing a new algorithm was developed. The approach is based on a one dimensional piecewise linear function with two additional supporting grid points within each grid cell, dividing the interval into three pieces. It fulfils the desired requirements by preserving the integral precipitation in each time interval, guaranteeing continuity at interval boundaries, and maintaining non-negativity. An additional monotonicity filter helps to gain monotonicity. 
+The more natural requirements of symmetry, reality, computational efficiency and easy implementation motivates the linear formulation.
+These requirements on the reconstruction algorithm imply that time intervals with no precipitation remain unchanged, i.e. the reconstructed values vanish throughout this whole time interval, too. 
+In the simplest scenario of an isolated precipitation event, where in the time interval before and after the data values are zero, the reconstruction algorithm therefore has to vanish at the boundaries of the interval, too. 
+The additional conditions of continuity and conservation of the precipitation amount then require us to introduce sub-grid points if we want to keep a linear interpolation (Fig. 2). 
+The height is thereby determined by the condition of conservation of the integral of the function over the time interval.
+  
+    
+.. _ref-fig-newdisagg:                       
+
+.. figure:: ../_files/new_disagg.png         
+    :figclass: align-center
+    
+    Fig. 2: Precipitation rate linearly interpolated using a sub-grid with two additional points. Colours as in Fig. 1 (Hittmeir et al. 2018).        
+    
+
+Figure 3 shows an overview of the new algorithm and its components.
+    
+.. _ref-fig-IA3:                       
+
+.. figure:: ../_files/IA3.png         
+    :figclass: align-center		  
+   
+    Fig. 3: Schematic overview of the basic notation in a precipitation interval with the original precipitation rate g (green) as a step function and the interpolated data :math:`f` (dark blue) as the piecewise linear function. The original time interval with fixed grid length :math:`\delta t` is split equidistantly in three subintervals denoted by :math:`I_i^{1,2,3}`, with the slopes in the subintervals as denoted by :math:`k_i^{1,2,3}` . The sub-grid function values :math:`f_i, f_i^{1,2}, f_{i+1}` are marked by red diamonds (Hittmeir et al. 2018).
+   
+
+The following lists the equations of the new algorithm. 
+   
+.. math::
+
+    f_i^{(1)}=&\frac32 g_i -\frac{1}{12}f_{i}-\frac{5}{12}f_{i+1}
+    
+    f_i^{(2)}=&\frac32 g_i -\frac{5}{12}f_{i}-\frac{1}{12}f_{i+1}
+    
+    f_{i+1}=&\min\{3 g_i,3 g_{i+1},\sqrt{g_ig_{i+1}}\} 
+    
+.. math::
+    
+    \textbf{if}  \quad
+    \mathrm{sgn}(k_{i}^{(2)})\cdot \mathrm{sgn}(k_{i  }^{(3)})&=-1 \quad \wedge \\
+    \mathrm{sgn}(k_{i  }^{(3)})\cdot \mathrm{sgn}(k_{i+1}^{(1)})&=-1 \quad \wedge \\
+    \mathrm{sgn}(k_{i+1}^{(1)})\cdot \mathrm{sgn}(k_{i+1}^{(2)})&=-1  \quad
+    \textbf{then} 
+
+.. math:: 
+    
+    f_{i+1}^\diamond=&\frac{18}{13}g_i-\frac{5}{13}f_i
+    
+    f_{i+1}^{\diamond\diamond}=&\frac{18}{13}g_{i+1}-\frac{5}{13}f_{i+2}
+    
+    f_{i+1} =& \min\left\{3 g_i,\, 3 g_{i+1},\, \sqrt{(f_{i+1}^\diamond\,f_{i+1}^{\diamond\diamond})_+}\right\}   
+    
+    f_i^{(1)}=& \frac32 g_i -\frac{1}{12}f_{i}-\frac{5}{12}f_{i+1}^{\textrm{mon}}
+    
+    f_i^{(2)}=& \frac32 g_i -\frac{5}{12}f_{i}-\frac{1}{12}f_{i+1}^{\textrm{mon}}
+    
+    \textbf{endif}
+
+
+In the case of the new disaggregation method for precipitation, the two new sub grid points are added in the ``flux`` output files. They are identified by the forecast step parameter ``step`` which is 0 for the original time interval and 1 or 2 for the two new sub grid points respectively. The filenames do not change.   
+
+   
+.. note::
+
+    The new method for disaggregation was published in the Geoscientific Model Development Journal in 2018:
+    
+    Hittmeir, S., Philipp, A., and Seibert, P.: A conservative reconstruction scheme for the interpolation of extensive quantities in the Lagrangian particle dispersion model FLEXPART, Geosci. Model Dev., 11, 2503-2523, https://doi.org/10.5194/gmd-11-2503-2018, 2018.
+
+      
+   
+
+ 
+
+
+Disaggregation for the rest of the flux fields
+----------------------------------------------
+      
+The accumulated values for the other variables are first divided by the number of hours and
+then interpolated to the exact times X using a bicubic interpolation which conserves the integrals of the fluxes within each timespan.
+Disaggregation is done for 4 adjacent timespans (:math:`p_a, p_b, p_c, p_d`) which generates a new, disaggregated value which is output at the central point of the 4 adjacent timespans.
+
+.. math::
+    
+    p_a &= (a_3 - a_0 + 3. * (a_1 - a_2)) / 6. \\    
+    p_b &= (a_2 + a_0) / 2. - a_1 - 9. * p_a / 2. \\
+    p_c &= a_1 - a_0 - 7. * p_a / 2. - 2. * p_b \\    
+    p_d &= a_0 - p_a / 4. - p_b / 3. - p_c / 2. 
+
+This new point :math:`p` is used for linear interpolation of the complete timeseries afterwards.
+
+.. math::
+    
+    p = 8. * p_a + 4. * p_b + 2. * p_c + p_d
+
+
+
+        
         
 .. toctree::
Index: for_developers/Sphinx/source/Documentation/input.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/input.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/input.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,7 +1,68 @@
-====================
+********************
 Control & Input Data
-====================
+********************
+
+Input Data
+    - :doc:`Input/control`
+          ``Flex_extract`` needs a number of controlling parameters to decide on the behaviour and the actual dataset to be retrieved. They are initialized by ``flex_extract`` with their default values and can be overwritten with definitions set in the so called :doc:`Input/control`. 
+
+          To be able to successfully retrieve data from the ECMWF Mars archive it is necessary to understand these parameters and set them to proper and consistent values. They are described in :doc:`Input/control_params` section. 
+
+          We also have some :doc:`Input/examples` and description of :doc:`Input/changes` changes to previous versions and downward compatibilities.
         
-    UNDER CONSTRUCTION
+    - :doc:`Input/ecmwf_env` 
+         For ``flex_extract`` it is necessary to be able to reach ECMWF servers in the **remote mode** and the **gateway mode**. Therefore a :doc:`Input/ecmwf_env` is created during the installation process.
+
+    - :doc:`Input/templates` 
+         A number of files which are created by ``flex_extract`` are taken from templates. This makes it easy to adapt for example the jobscripts regarding its settings for the batch jobs.         
+
+
+
+
+
+.. _setup : Input/setup.html
+.. _run : Input/run.html
+.. _install : Input/setup.html#ref-install-script
+.. _submit : Input/submit.html#ref-submit-script
+
+.. _ref-controlling:
+
+Controlling
+    The main tasks and behaviour of ``flex_extract`` are controlled by its Python scripts. There are two top-level scripts, one for installation called install_ and one for execution called submit_. 
+    They can interpret a number of command line arguments which can be seen by typing ``--help`` after the script call. Go to the root directory of ``flex_extract`` to type:
+
+    .. code-block:: bash
+
+       cd flex_extract_vX.X
+       python3 source/python/install.py --help
+       python3 source/python/submit.py --help
+   
+    In this new version we provide also the wrapping Shell scripts setup_ and run_, which sets the command line parameters, do some checks and execute the corresponing Python scripts ``install.py`` and ``submit.py`` respectivley. 
+     
+    It might be faster and easier for beginners. See :doc:`../quick_start` for information on how to use them.
+
+    Additionally, ``flex_extract`` creates the Korn Shell scripts :doc:`Input/compilejob` and :doc:`Input/jobscript` which will be send to the ECMWF serves in the **remote mode** and the **gateway mode** for starting batch jobs.
+
+    The Fortran program will be compiled during the installation process by the :doc:`Input/fortran_makefile`. 
+    
+    To sum up, the following scripts controls ``flex_extract``:
+
+    Installation 
+       - :doc:`Input/setup` 
+       - :doc:`Input/compilejob`
+       - :doc:`Input/fortran_makefile`    
+
+    Execution 
+      - :doc:`Input/run` 
+      - :doc:`Input/jobscript` 
+             
+             
+    
+
+
+                 
+
+          
+        
         
 .. toctree::
@@ -9,4 +70,13 @@
     :maxdepth: 2
     
+    Input/setup
+    Input/compilejob
+    Input/fortran_makefile   
+    Input/run
+    Input/jobscript
     Input/control
-    Input/control_params
+    Input/control_params  
+    Input/examples
+    Input/changes 
+    Input/ecmwf_env
+    Input/templates
Index: for_developers/Sphinx/source/Documentation/output.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/output.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/output.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,7 +1,288 @@
-===========
+***********
 Output Data
-===========
-    
-    UNDER CONSTRUCTION
+***********
+
+The output data of ``flex_extract`` are separated mainly into temporary files and the final ``FLEXPART`` input files:
+
++-----------------------------------------------+----------------------------------------------+   
+|   ``FLEXPART`` input files                    |  Temporary files (saved in debug mode)       | 
++-----------------------------------------------+----------------------------------------------+
+| - Standard output filenames                   | - MARS request file (opt)                    | 
+| - Output for pure forecast                    | - flux files                                 | 
+| - Output for ensemble members                 | - VERTICAL.EC                                |
+| - Output for new precip. disaggregation       | - index file                                 | 
+|                                               | - fort files                                 | 
+|                                               | - MARS grib files                            | 
++-----------------------------------------------+----------------------------------------------+ 
+
+
+
+``FLEXPART`` input files
+========================
+
+The final output files of ``flex_extract`` are also the meteorological ``FLEXPART`` input files.
+The naming of these files depend on the kind of data extracted by ``flex_extract``. 
+
+Standard output files
+---------------------
+ 
+In general, there is a file for each time step with the filename format:
+
+.. code-block:: bash
+
+    <prefix>YYMMDDHH
+    
+The ``prefix`` is by default defined as ``EN`` and can be re-defined in the ``CONTROL`` file.
+Each file contains all meteorological fields needed by ``FLEXPART`` for all selected model levels for a specific time step. 
+
+Here is an example output which lists the meteorological fields in a single file called ``CE00010800`` where we extracted only the lowest model level for demonstration reasons:
+
+.. code-block:: bash
+
+        $ grib_ls CE00010800
+        
+        edition      centre       date         dataType     gridType     stepRange    typeOfLevel  level        shortName    packingType
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           u            grid_simple
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           v            grid_simple
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           etadot       grid_simple
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           t            grid_simple
+        2            ecmf         20000108     an           regular_ll   0            surface      1            sp           grid_simple
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           q            grid_simple
+        2            ecmf         20000108     an           regular_ll   0            hybrid       91           qc           grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            sshf         grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            ewss         grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            nsss         grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            ssr          grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            lsp          grid_simple
+        1            ecmf         20000108     fc           regular_ll   0            surface      0            cp           grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            sd           grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            msl          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            tcc          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            10u          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            10v          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            2t           grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            2d           grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            z            grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            lsm          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            cvl          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            cvh          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            lcc          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            mcc          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            hcc          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            skt          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            depthBelowLandLayer  0            stl1         grid_simple
+        1            ecmf         20000108     an           regular_ll   0            depthBelowLandLayer  0            swvl1        grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            sr           grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            sdor         grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            cvl          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            cvh          grid_simple
+        1            ecmf         20000108     an           regular_ll   0            surface      0            fsr          grid_simple
+        35 of 35 messages in CE00010800
+
+
+Output files for pure forecast
+------------------------------
+
+``Flex_extract`` can retrieve forecasts which can be longer than 23 hours. To avoid collisions of time steps for forecasts of more than one day a new scheme for filenames in pure forecast mode is introduced:
+
+.. code-block:: bash
+
+    <prefix>YYMMDD.HH.<FORECAST_STEP>
+
+The ``<prefix>`` is, as in the standard output, by default ``EN`` and can be re-defined in the ``CONTROL`` file. ``YYMMDD`` is the date format and ``HH`` the forecast time which is the starting time for the forecasts. The ``FORECAST_STEP`` is a 3 digit number which represents the forecast step in hours. 
+    
+
+Output files for ensemble predictions
+-------------------------------------
+
+Ensembles can be retrieved and are addressed by the grib message parameter ``number``. The ensembles are saved per file and standard filenames are supplemented by the letter ``N`` and the ensemble member number in a 3 digit format.
+
+.. code-block:: bash
+
+    <prefix>YYMMDDHH.N<ENSEMBLE_MEMBER>
+
+
+Additional fields with new precipitation disaggregation
+-------------------------------------------------------
+
+The new disaggregation method for precipitation fields produces two additional precipitation fields for each time step and precipitation type. They serve as sub-grid points in the original time interval. For details of the method see :doc:`disagg` ??????????????????.
+The two additional fields are marked with the ``step`` parameter in the Grib messages and are set to "1" and "2" for sub-grid point 1 and 2 respectively.
+The output filenames do not change in this case.  
+Below is an example list of precipitation fields in an output file generated with the new disaggregation method:
+
+.. code-block:: bash 
+
+    $ grib_ls 
+
+    edition      centre       date         dataType     gridType     stepRange    typeOfLevel  level        shortName    packingType
+    1            ecmf         20000108     fc           regular_ll   0            surface      0            lsp          grid_simple
+    1            ecmf         20000108     fc           regular_ll   1            surface      0            lsp          grid_simple
+    1            ecmf         20000108     fc           regular_ll   2            surface      0            lsp          grid_simple
+    1            ecmf         20000108     fc           regular_ll   0            surface      0            cp           grid_simple
+    1            ecmf         20000108     fc           regular_ll   1            surface      0            cp           grid_simple
+    1            ecmf         20000108     fc           regular_ll   2            surface      0            cp           grid_simple
+
+
+
+
+Temporary files
+===============
+
+``Flex_extract`` works with a number of temporary data files which are usually deleted after a successful data extraction. They are only stored if the ``DEBUG`` mode is switched on (see :doc:`Input/control_params`. 
+
+MARS grib files
+---------------
+
+``Flex_extract`` retrieves all meteorological fields from MARS and stores them in files ending with ``.grb``.
+Since the request times and data transfer of MARS access are limited and ECMWF asks for efficiency in requesting data from MARS, ``flex_extract`` splits the overall data request in several smaller requests. Each request is stored in an extra ``.grb`` file and the file names are put together by several pieces of information:
+
+    .. code-block:: bash
+    
+       <field_type><grid_type><temporal_property><level_type>.<date>.<ppid>.<pid>.grb
+
+Description:
+       
+Field type: 
+    ``AN`` - Analysis, ``FC`` - Forecast, ``4V`` - 4d variational analysis, ``CV`` - Validation forecast, ``CF`` - Control forecast, ``PF`` - Perturbed forecast
+Grid type: 
+   ``SH`` - Spherical Harmonics, ``GG`` - Gaussian Grid, ``OG`` - Output Grid (typically lat/lon), ``_OROLSM`` - Orography parameter
+Temporal property:
+    ``__`` - instantaneous fields, ``_acc`` - accumulated fields
+Level type: 
+    ``ML`` - Model Level, ``SL`` - Surface Level
+ppid:
+    The process number of the parent process of submitted script.
+pid:
+    The process number of the submitted script.
+
+The process ids should avoid mixing of fields if several ``flex_extract`` jobs are performed in parallel (which is, however, not recommended). The date format is YYYYMMDDHH.
+
+Example ``.grb`` files for a day of CERA-20C data:
+
+    .. code-block:: bash
+
+        ANOG__ML.20000908.71851.71852.grb  
+        FCOG_acc_SL.20000907.71851.71852.grb
+        ANOG__SL.20000908.71851.71852.grb  
+        OG_OROLSM__SL.20000908.71851.71852.grb
+        ANSH__SL.20000908.71851.71852.grb
+
+
+MARS request file 
+-----------------
+
+This file is a ``csv`` file called ``mars_requests.csv`` with a list of the actual settings of MARS request parameters (one request per line) in a flex_extract job. It is used for documenting the data which were retrieved and for testing reasons.
+
+Each request consist of the following parameters, whose meaning mainly can be taken from :doc:`Input/control_params` or :doc:`Input/run`: 
+request_number, accuracy, area, dataset, date, expver, gaussian, grid, levelist, levtype, marsclass, number, param, repres, resol, step, stream, target, time, type
+  
+Example output of a one day retrieval of CERA-20c data: 
+
+.. code-block:: bash
+
+    request_number, accuracy, area, dataset, date, expver, gaussian, grid, levelist, levtype, marsclass, number, param, repres, resol, step, stream, target, time, type
+    1, 24, 40.0/-5.0/30.0/5.0, None, 20000107/to/20000109, 1, , 1.0/1.0, 1, SFC, EP, 000, 142.128/143.128/146.128/180.128/181.128/176.128, , 159, 3/to/24/by/3, ENDA, /mnt/nas/Anne/Interpolation/flexextract/flex_extract_v7.1/run/./workspace/CERA_testgrid_local_cds/FCOG_acc_SL.20000107.23903.23904.grb, 18, FC
+    1, 24, 40.0/-5.0/30.0/5.0, None, 20000108/to/20000108, 1, , 1.0/1.0, 85/to/91, ML, EP, 000, 130.128/133.128/131.128/132.128/077.128/246.128/247.128, , 159, 00, ENDA, /mnt/nas/Anne/Interpolation/flexextract/flex_extract_v7.1/run/./workspace/CERA_testgrid_local_cds/ANOG__ML.20000108.23903.23904.grb, 00/03/06/09/12/15/18/21, AN
+    2, 24, 40.0/-5.0/30.0/5.0, None, 20000108/to/20000108, 1, , OFF, 1, ML, EP, 000, 152.128, , 159, 00, ENDA, /mnt/nas/Anne/Interpolation/flexextract/flex_extract_v7.1/run/./workspace/CERA_testgrid_local_cds/ANSH__SL.20000108.23903.23904.grb, 00/03/06/09/12/15/18/21, AN
+    3, 24, 40.0/-5.0/30.0/5.0, None, 20000108, 1, , 1.0/1.0, 1, SFC, EP, 000, 160.128/027.128/028.128/244.128, , 159, 000, ENDA, /mnt/nas/Anne/Interpolation/flexextract/flex_extract_v7.1/run/./workspace/CERA_testgrid_local_cds/OG_OROLSM__SL.20000108.23903.23904.grb, 00, AN
+    4, 24, 40.0/-5.0/30.0/5.0, None, 20000108/to/20000108, 1, , 1.0/1.0, 1, SFC, EP, 000, 141.128/151.128/164.128/165.128/166.128/167.128/168.128/129.128/172.128/027.128/028.128/186.128/187.128/188.128/235.128/139.128/039.128/173.128, , 159, 00, ENDA, /mnt/nas/Anne/Interpolation/flexextract/flex_extract_v7.1/run/./workspace/CERA_testgrid_local_cds/ANOG__SL.20000108.23903.23904.grb, 00/03/06/09/12/15/18/21, AN
+
+
+VERTICAL.EC
+-----------
+
+The vertical discretization of model levels. This file contains the ``A`` and ``B`` parameters to calculate the model level height in meters.
+
+
+Index file
+----------
+
+This file is usually called ``date_time_stepRange.idx``. It contains indices pointing to specific grib messages from one or more grib files. The messages are selected with a composition of grib message keywords. 
+
+
+flux files
+----------
+
+The flux files contain the de-accumulated and dis-aggregated flux fields of large scale and convective precipitation, eastward turbulent surface stress, northward turbulent surface stress, surface sensible heat flux and the surface net solar radiation. 
+
+.. code-block:: bash
+
+    flux<date>[.N<xxx>][.<xxx>]
+
+The date format is YYYYMMDDHH. The optional block ``[.N<xxx>]`` marks the ensemble forecast number, where ``<xxx>`` is the ensemble member number. The optional block ``[.<xxx>]`` marks a pure forecast with ``<xxx>`` being the forecast step.
+
+.. note::
+
+    In the case of the new dis-aggregation method for precipitation, two new sub-intervals are added in between each time interval. They are identified by the forecast step parameter which is ``0`` for the original time interval and ``1`` or ``2`` for the two new intervals respectively. 
+
+    
+fort files
+----------
+
+There are a number of input files for the ``CONVERT2`` Fortran program named
+
+.. code-block:: bash
+
+    fort.xx
+    
+where ``xx`` is the number which defines the meteorological fields stored in these files. 
+They are generated by the Python part of ``flex_extract`` by just splitting the meteorological fields for a unique time stamp from the ``*.grb`` files into the ``fort`` files. 
+The following table defines the numbers with their corresponding content.   
+
+.. csv-table:: Content of fort - files
+    :header: "Number", "Content"
+    :widths: 5, 20
+ 
+    "10", "U and V wind components" 
+    "11", "temperature" 
+    "12", "logarithm of surface pressure" 
+    "13", "divergence (optional)" 
+    "16", "surface fields"
+    "17", "specific humidity"
+    "18", "surface specific humidity (reduced gaussian)"
+    "19", "vertical velocity (pressure) (optional)" 
+    "21", "eta-coordinate vertical velocity (optional)" 
+    "22", "total cloud water content (optional)"
+
+Some of the fields are solely retrieved with specific settings, e.g. the eta-coordinate vertical velocity is not available in ERA-Interim datasets and the total cloud water content is an optional field for ``FLEXPART v10`` and newer. Please see section ????????? for more information. 
+
+The ``CONVERT2`` program saves its results in file ``fort.15`` which typically contains:
+
+.. csv-table:: Output file of the Fortran program ``CONVERT2``
+    :header: "Number", "Content"
+    :widths: 5, 20
+ 
+    "15", "U and V wind components, eta-coordinate vertical velocity, temperature, surface pressure, specific humidity " 
+    
+More details about the content of ``CONVERT2`` can be found in :doc:`vertco`.    
+    
+.. note::
+ 
+    The ``fort.4`` file is the namelist file to drive the Fortran program ``CONVERT2``. It is therefore also an input file and is described in ???????????????
+    
+    Example of a namelist:
+    
+    .. code-block:: bash
+    
+        &NAMGEN
+          maxl = 11,
+          maxb = 11,
+          mlevel = 91,
+          mlevelist = "85/to/91",
+          mnauf = 159,
+          metapar = 77,
+          rlo0 = -5.0,
+          rlo1 = 5.0,
+          rla0 = 30.0,
+          rla1 = 40.0,
+          momega = 0,
+          momegadiff = 0,
+          mgauss = 0,
+          msmooth = 0,
+          meta = 1,
+          metadiff = 0,
+          mdpdeta = 1
+        /
+        
         
 .. toctree::
Index: for_developers/Sphinx/source/Documentation/overview.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/overview.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/overview.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -2,11 +2,40 @@
 Overview
 ========
-        
-    UNDER CONSTRUCTION    
-    
-    
-    
-The system retrieves the data from the European Centre for
-Medium-Range Weather Forecasts (ECMWF) situated in Reading, United Kingdom.
+
+``Flex_extract`` is an open-source software to retrieve meteorological fields from the European Centre for Medium-Range Weather Forecasts (ECMWF) Mars archive to serve as input files for the ``FLEXTRA``/``FLEXPART`` Atmospheric Transport Modelling system.
+``Flex_extract`` was created explicitly for ``FLEXPART`` users who wants to use meteorological data from ECMWF to drive the ``FLEXPART`` model. 
+The software retrieves the minimal number of parameters ``FLEXPART`` needs to work and provides the data in the explicity format ``FLEXPART`` understands.
+
+``Flex_extract`` consists of 2 main parts:
+    1. a Python part, where the reading of parameter settings, retrieving data from MARS and preparing the data for ``FLEXPART`` is done and 
+    2. a Fortran part, where the calculation of the vertical velocity is done and if necessary the conversion from spectral to regular latitude/longitude grids.
+
+Additionally, it has some Korn shell scripts which are used to set the environment and batch job features on ECMWF servers for the *gateway* and *remote* mode. See :doc:`Overview/app_modes` for information of application modes.   
+
+A number of Shell scripts are wrapped around the software package for easy installation and fast job submission. 
+
+The software depends on a number of third-party libraries which can be found in :ref:`ref-requirements`.
+
+Some details on the tasks and program worksteps are described in :doc:`Overview/prog_flow`.
+
+
+..  - directory structure (new diagramm!)
+           
+    - Software components - complete component structure (table or diagram)
+           
+       - Python package
+           
+           - Package diagram
+           - Files and modules as table with information about unit tests
+           - Api
+             
+       - Fortran program - CONVERT2
+           
+           - Package diagram
+           - Api
+             
+
+
+
 
     
@@ -17,3 +46,2 @@
     Overview/app_modes
     Overview/prog_flow
-    Overview/convert
Index: for_developers/Sphinx/source/Documentation/vertco.rst
===================================================================
--- for_developers/Sphinx/source/Documentation/vertco.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Documentation/vertco.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,7 +1,59 @@
-===================
+*******************
 Vertical Coordinate
-===================
+*******************
+        
+Calculation of vertical velocity and preparation of Output-files
+================================================================
+
+``flex_extract`` has two ways to calculate the vertical velocity for ``FLEXTRA``/``FLEXPART``: 
+    (i) from the horizontal wind field, 
+    (ii) from the MARS parameter 77, which is available for operational forecasts and analyses since September 2008 and for reanalysis datasets **ERA5** and **CERA-20C**.
+
+Especially for high resolution data, use of the ``MARS`` parameter 77 is recommended,
+since the computational cost (measured in ECMWF HPC units) is reduced by 90-95% at
+T799. The extraction time, which depends heavily also on the performance of ``MARS``, is
+generally reduced by 50% as well. The ``MARS`` parameter 77 is then multiplied by ``dp/deta`` to
+give a vertical velocity in Pa/s as needed by ``FLEXPART``.
+
+Calculation from the horizontal wind field is still required for historical case studies using
+**ERA-40**, **ERA-Interim** or operational data prior to September 2008.    
     
-    UNDER CONSTRUCTION
+    
+Calculation of vertical velocity from horizontal wind using the continuity equation
+===================================================================================
+
+The vertical velocity is computed by the FORTRAN90 program ``CONVERT2`` in the ECMWF
+vertical coordinate system by applying the equation of continuity and thereby ensuring mass consistent 3D wind fields. A detailed description of ``CONVERT2`` can be found in the
+documents v20_update_protocol.pdf, V30_update_protocol.pdf and
+V40_update_protocol.pdf. The computational demand and accuracy of ``CONVERT2`` is highly
+dependent on the specification of parameters ``GAUSS``, ``RESOL`` and ``SMOOTH``. The
+following guidance can be given for choosing the right parameters:
+
+    * For very fine output grids (0.25 degree or finer) the full resolution T799 or even T1279 of the operational model is required (``RESOL=799``, ``SMOOTH=0``). The highest available resolution (and the calculation of vertical velocity on the Gaussian grid (``GAUSS=1``) is, however, rather demanding and feasible only for resolutions up to T799. Higher resolutions are achievable on the HPC. If data retrieval at T1279  needs to be performed on *ecgate*, the computation of the vertical velocity is feasible only on the lat/lon grid (``GAUSS=0``), which also yields very good results. Please read document v20_update_protocol.pdf-v60_update_protocol.pdf to see if the errors incurred are acceptable for the planned application.
+    * For lower resolution (often global) output grids, calculation of vertical velocities with lower than operational spectral resolution is recommended. For global grids the following settings appear optimal:
+        - For 1.0 degree grids: ``GAUSS=1``, ``RESOL=255``, ``SMOOTH=179``
+        - For 0.5 degree grids: ``GAUSS=1``, ``RESOL=399``, ``SMOOTH=359``
+        - Calculation on the lat/lon grid is not recommended for less than the operational (T1279) resolution.    
+        - If ``GAUSS`` is set to 1, only the following choices are possible for ``RESOL`` on *ecgate*: 159,255,319,399,511,799, (on the HPC also 1279, 2047 in future models). This choice is restricted because a reduced Gaussian grid is defined in then ECMWF EMOSLIB only for these spectral resolutions. For ``GAUSS=0``, ``RESOL`` can be any value below the operational resolution.
+        - For ``SMOOTH`` any resolution lower than ``RESOL`` is possible. If no smoothing is desired, ``SMOOTH=0`` should be chosen. ``SMOOTH`` has no effect if vertical velocity is calculated on lat\/lon grid (``GAUSS=0``).
+    * The on demand scripts send an error message for settings where ``SMOOTH`` (if set) and ``RESOL`` are larger than 360./``GRID``/2, since in this case, the output grid cannot resolve the highest wave numbers. The scripts continue operations, however.
+    * Regional grids are not cyclic in zonal directions, but global grids are. The software assumes a cyclic grid if ``RIGHT``-``LEFT`` is equal to ``GRID`` or is equal to ``GRID``-360. 
+    * Finally, model and flux data as well as the vertical velocity computed are written to files ``<prefix>yymmddhh`` for application in ATM modelling. If the parameters ``OMEGA`` or ``OMEGADIFF`` are set, also files ``OMEGAyymmddhh`` are created, containing the pressure vertical velocity (omega) and the difference between omega from ``MARS`` and the surface pressure tendency. ``OMEGADIFF`` should be zero except for debugging, since it triggers expensive calculations on the Gaussian grid.
+    
+    
+Calculation of vertical velocity from pre-calculated MARS parameter 77
+======================================================================
+
+Since November 2008, the parameter 77 (deta/dt) is stored in ``MARS`` on full model levels. ``FLEXTRA``/``FLEXPART`` in its current version requires ``deta/dt`` on model half levels, multiplied by ``dp/deta``. In ``flex_extract``, the program ``CONVERT2`` assumes that this parameter is available if the ``CONTROL`` parameter ``ETA`` is set to 1. 
+
+It is recommended to use the pre-calculated parameter 77 by setting ``ETA`` to 1 whenever possible.
+
+Setting parameter ``ETA`` to 1 normally disables calculation of vertical velocity from the horizontal wind field, which saves a lot of computational time. 
+
+.. note::
+   However, the calculation on the Gaussian grid are avoided only if both ``GAUSS`` and ``ETADIFF`` are set to 0. Please set ``ETADIFF`` to 1 only if you are really need it for debugging since this is a very expensive option. In this case ``ETAyymmddhh`` files are produced that contain the vertical velocity from horizontal winds and the difference to the pre-calculated vertical velocity.
+
+The parameters ``RESOL``, ``GRID``, ``UPPER``, ``LOWER``, ``LEFT``, ``RIGHT`` still apply. As for calculations on the Gaussian grid, the spectral resolution parameter ``RESOL`` should be compatible with the grid resolution (see previous subsection).
+    
         
 .. toctree::
Index: for_developers/Sphinx/source/Ecmwf/access.rst
===================================================================
--- for_developers/Sphinx/source/Ecmwf/access.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Ecmwf/access.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -5,13 +5,19 @@
 .. _public datasets: https://confluence.ecmwf.int/display/WEBAPI/Available+ECMWF+Public+Datasets
 .. _Computing Representative: https://www.ecmwf.int/en/about/contact-us/computing-representatives
+.. _Climate Data Store: https://cds.climate.copernicus.eu
+.. _CDS API: https://cds.climate.copernicus.eu/api-how-to
 
 Access to the ECMWF Mars archive is divided into two groups: **member state** users and **public** users.
 
 **Member state user**: 
-    This access mode allows the user to work directly on the ECMWF Linux Member State Servers or via a Web Access Toolkit ``ecaccess`` through a local Member State Gateway Server. This enables the user to have direct and full access to the Mars archive. There might be some limitations in user rights such as the declined access to the latest forecasts. This has to be discussed with the `Computing Representative`_. This user group is also able to work from their local facilities without a gateway server in the same way a **public** user would. The only difference is the method of Web API which is automatically selected by ``flex_extract``.
+    This access mode allows the user to work directly on the ECMWF Linux Member State Servers or via a Web Access Toolkit ``ecaccess`` through a local Member State Gateway Server. This enables the user to have direct and full access to the Mars archive. There might be some limitations in user rights such as the declined access to the latest forecasts. This has to be discussed with the `Computing Representative`_. This user group is also able to work from their local facilities without a gateway server in the same way a **public** user would. The only difference is the connection with the Web API. However, this is automatically selected by ``flex_extract``.
     
 
 **Public user**: 
-    This access mode allows every user to access the ECMWF `public datasets`_ from their local facilities. ``Flex_extract`` is able (tested for the use with ``FLEXPART``) to extract the re-analysis datasets such as ERA5, ERA-Interim and CERA-20C. The main difference to the **member state user** is the method of access with the Web API and the availability of data. For example, in ERA-Interim there is only a 6-hourly temporal resolution instead of 3 hours. The access method is selected by providing the command line argument "public=1" and providing the Mars keyword "dataset" in the ``CONTROL`` file. Also, the user has to explicitly accept the license of the dataset to be retrieved. This can be done as described in the installation process at section :ref:`ref-licence`.   
+    This access mode allows every user to access the ECMWF `public datasets`_ from their local facilities. ``Flex_extract`` is able (tested for the use with ``FLEXPART``) to extract the re-analysis datasets such as ERA-Interim and CERA-20C. The main difference to the **member state user** is the method of access with the Web API and the availability of data. For example, in ERA-Interim there is only a 6-hourly temporal resolution instead of 3 hours. The access method is selected by providing the command line argument "public=1" and providing the MARS keyword "dataset" in the ``CONTROL`` file. Also, the user has to explicitly accept the license of the dataset to be retrieved. This can be done as described in the installation process at section :ref:`ref-licence`.   
+     
+.. note::
+    
+   The availability of the public dataset *ERA5* with the ECMWF Web API was cancelled in March 2019. The oportunity of local retrieval of this dataset was moved to the `Climate Data Store`_ which uses another Web API named `CDS API`_. This Data Store stores the data on explicit webservers for faster and easier access. Unfortunately, for *ERA5* there are only surface level and pressure level data available for *public users*. In the case of a *member user* it is possible to bypass the request to the MARS archive from ECMWF to retrieve the data. ``Flex_extract`` is already modified to use this API so *member user* can already retrieve *ERA5* data while *public users* have to wait until model level are available. 
         
 For information on how to register see :ref:`ref-registration`. 
Index: for_developers/Sphinx/source/Ecmwf/ec-links.rst
===================================================================
--- for_developers/Sphinx/source/Ecmwf/ec-links.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Ecmwf/ec-links.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -21,4 +21,6 @@
     
     `MARS Actions <https://confluence.ecmwf.int/display/UDOC/MARS+actions>`_
+    
+    `Parameter Database <https://apps.ecmwf.int/codes/grib/param-db>`_
   
 Registration
@@ -46,5 +48,16 @@
 Datasets
     Overview
+        `Complete list of datasets <https://www.ecmwf.int/en/forecasts/datasets>`_
+                
         `What is climate reanalysis <https://www.ecmwf.int/en/research/climate-reanalysis>`_
+        
+        `Forecast user guide <https://confluence.ecmwf.int/display/FUG/1+Introduction>`_
+
+    Real-time (Operational)        
+        `List of real_time datasets <https://www.ecmwf.int/en/forecasts/datasets/catalogue-ecmwf-real-time-products>`_
+
+        `Atmospheric model - HRES (our typical operational dataset) <https://www.ecmwf.int/en/forecasts/datasets/set-i>`_
+        
+        `Atmospheric model - ENS (15-day ensemble forecast) <https://www.ecmwf.int/en/forecasts/datasets/set-iii>`_
 
     ERA-Interim
@@ -58,6 +71,6 @@
         `What is CERA-20C <https://software.ecmwf.int/wiki/display/CKB/What+is+CERA-20C>`_
         
-        `CERA-20C documentation <https://www.ecmwf.int/en/forecasts/datasets/archive-datasets/reanalysis-datasets/cera-20c>`_
-    
+        `CERA-20C dataset <https://www.ecmwf.int/en/forecasts/datasets/archive-datasets/reanalysis-datasets/cera-20c>`_
+            
     ERA5
         `What is ERA5 <https://software.ecmwf.int/wiki/display/CKB/What+is+ERA5>`_
@@ -69,6 +82,5 @@
         `How to migrate from ECMWF Web API to CDS API <https://confluence.ecmwf.int/display/CKB/How+to+migrate+from+ECMWF+Web+API+to+CDS+API>`_
         
-        `ERA5 Documentation <https://software.ecmwf.int/wiki/display/CKB/ERA5+data+documentation>`_
-        
+        `ERA5 Documentation <https://software.ecmwf.int/wiki/display/CKB/ERA5+data+documentation>`_        
 
 Third Party Libraries
@@ -97,4 +109,8 @@
 
 
+Technical Information of ECMWF serves
+
+    `Introduction presentation to SLURM  <https://confluence.ecmwf.int/download/attachments/73008494/intro-slurm-2017.pdf?version=1&modificationDate=1488574096323&api=v2>`_
+
 Troubleshooting
     `ECMWF Web API Troubleshooting <https://confluence.ecmwf.int/display/WEBAPI/Web-API+Troubleshooting>`_
Index: for_developers/Sphinx/source/Evaluation/metrics.rst
===================================================================
--- for_developers/Sphinx/source/Evaluation/metrics.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/Evaluation/metrics.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,4 +1,6 @@
 Metrics
 =======
+
+   UNDER CONSTRUCTION
 
 .. csv-table: TTEST 
@@ -7,2 +9,7 @@
 ..   :header-rows: 1
 
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Evaluation/staticcode.rst
===================================================================
--- for_developers/Sphinx/source/Evaluation/staticcode.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Evaluation/staticcode.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,9 @@
+********************
+Static Code Analysis
+********************
+
+   UNDER CONSTRUCTION
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/Evaluation/testcases.rst
===================================================================
--- for_developers/Sphinx/source/Evaluation/testcases.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/Evaluation/testcases.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,22 @@
+********************
+Testcases
+********************
+
+
+Comparison of MARS requests
+===========================
+
+
+
+
+
+Comparison of grib files
+========================
+
+
+
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
Index: for_developers/Sphinx/source/_files/CONTROLparameter-adddata.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-adddata.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-adddata.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-data.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-data.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-data.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-datafields.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-datafields.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-datafields.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-domain.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-domain.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-domain.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-flexpart.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-flexpart.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-flexpart.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-fluxdata.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-fluxdata.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-fluxdata.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-general.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-general.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-general.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-time.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-time.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-time.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-user.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-user.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-user.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter-verticalwind.csv
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter-verticalwind.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/CONTROLparameter-verticalwind.csv
Index: for_developers/Sphinx/source/_files/CONTROLparameter.xls
===================================================================
--- for_developers/Sphinx/source/_files/CONTROLparameter.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/_files/CONTROLparameter.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,1 @@
+../../../CONTROLparameter.xls
Index: for_developers/Sphinx/source/_files/ECMWF_FPparameter-sfc.csv
===================================================================
--- for_developers/Sphinx/source/_files/ECMWF_FPparameter-sfc.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/ECMWF_FPparameter-sfc.csv
Index: for_developers/Sphinx/source/_files/InstallationParameter.xls
===================================================================
--- for_developers/Sphinx/source/_files/InstallationParameter.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/_files/InstallationParameter.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,1 @@
+../../../InstallationParameter.xls
Index: for_developers/Sphinx/source/_files/InstallationParameters.csv
===================================================================
--- for_developers/Sphinx/source/_files/InstallationParameters.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/InstallationParameter-csv.csv
Index: for_developers/Sphinx/source/_files/SubmitParameters.csv
===================================================================
--- for_developers/Sphinx/source/_files/SubmitParameters.csv	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,1 +1,0 @@
-../../../../for_developers/SubmitParameters.csv
Index: for_developers/Sphinx/source/_files/SubmitParameters.xls
===================================================================
--- for_developers/Sphinx/source/_files/SubmitParameters.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/_files/SubmitParameters.xls	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,1 @@
+../../../SubmitParameters.xls
Index: for_developers/Sphinx/source/_files/packages.png
===================================================================
--- for_developers/Sphinx/source/_files/packages.png	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/_files/packages.png	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,1 +1,1 @@
-../../../../for_developers/packages.png
+../../../packages.png
Index: for_developers/Sphinx/source/_static/python/hidden_code_block.py
===================================================================
--- for_developers/Sphinx/source/_static/python/hidden_code_block.py	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/_static/python/hidden_code_block.py	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,127 @@
+"""Simple, inelegant Sphinx extension which adds a directive for a
+highlighted code-block that may be toggled hidden and shown in HTML.  
+This is possibly useful for teaching courses.
+
+The directive, like the standard code-block directive, takes
+a language argument and an optional linenos parameter.  The
+hidden-code-block adds starthidden and label as optional 
+parameters.
+
+Examples:
+
+.. hidden-code-block:: python
+    :starthidden: False
+
+    a = 10
+    b = a + 5
+
+.. hidden-code-block:: python
+    :label: --- SHOW/HIDE ---
+
+    x = 10
+    y = x + 5
+
+Thanks to http://www.javascriptkit.com/javatutors/dom3.shtml for 
+inspiration on the javascript.  
+
+Thanks to Milad 'animal' Fatenejad for suggesting this extension 
+in the first place.
+
+Written by Anthony 'el Scopz' Scopatz, January 2012.
+
+Released under the WTFPL (http://sam.zoy.org/wtfpl/).
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.directives.code import CodeBlock
+
+HCB_COUNTER = 0
+
+js_showhide = """\
+<script type="text/javascript">
+    function showhide(element){
+        if (!document.getElementById)
+            return
+
+        if (element.style.display == "block")
+            element.style.display = "none"
+        else
+            element.style.display = "block"
+    };
+</script>
+"""
+
+def nice_bool(arg):
+    tvalues = ('true',  't', 'yes', 'y')
+    fvalues = ('false', 'f', 'no',  'n')
+    arg = directives.choice(arg, tvalues + fvalues)
+    return arg in tvalues
+
+
+class hidden_code_block(nodes.General, nodes.FixedTextElement):
+    pass
+
+
+class HiddenCodeBlock(CodeBlock):
+    """Hidden code block is Hidden"""
+
+    option_spec = dict(starthidden=nice_bool, 
+                       label=str,
+                       **CodeBlock.option_spec)
+
+    def run(self):
+        # Body of the method is more or less copied from CodeBlock
+        code = u'\n'.join(self.content)
+        hcb = hidden_code_block(code, code)
+        hcb['language'] = self.arguments[0]
+        hcb['linenos'] = 'linenos' in self.options
+        hcb['starthidden'] = self.options.get('starthidden', True)
+        hcb['label'] = self.options.get('label', '+ show/hide code')
+        hcb.line = self.lineno
+        return [hcb]
+
+
+def visit_hcb_html(self, node):
+    """Visit hidden code block"""
+    global HCB_COUNTER
+    HCB_COUNTER += 1
+
+    # We want to use the original highlighter so that we don't
+    # have to reimplement it.  However it raises a SkipNode 
+    # error at the end of the function call.  Thus we intercept
+    # it and raise it again later.
+    try: 
+        self.visit_literal_block(node)
+    except nodes.SkipNode:
+        pass
+
+    # The last element of the body should be the literal code 
+    # block that was just made.
+    code_block = self.body[-1]
+
+    fill_header = {'divname': 'hiddencodeblock{0}'.format(HCB_COUNTER), 
+                   'startdisplay': 'none' if node['starthidden'] else 'block', 
+                   'label': node.get('label'), 
+                   }
+
+    divheader = ("""<a href="javascript:showhide(document.getElementById('{divname}'))">"""
+                 """{label}</a><br />"""
+                 '''<div id="{divname}" style="display: {startdisplay}">'''
+                 ).format(**fill_header)
+
+    code_block = js_showhide + divheader + code_block + "</div>"
+
+    # reassign and exit
+    self.body[-1] = code_block
+    raise nodes.SkipNode
+
+
+def depart_hcb_html(self, node):
+    """Depart hidden code block"""
+    # Stub because of SkipNode in visit
+
+
+def setup(app):
+    app.add_directive('hidden-code-block', HiddenCodeBlock)
+    app.add_node(hidden_code_block, html=(visit_hcb_html, depart_hcb_html))
Index: for_developers/Sphinx/source/authors.rst
===================================================================
--- for_developers/Sphinx/source/authors.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/authors.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -3,5 +3,5 @@
 **************
 
-| MSc. Anne Philipp
+| Anne Philipp
 | Department of Meteorology and Geophysics /
 | Aerosol Physics and Environmental physics
@@ -14,5 +14,9 @@
 
 | Leopold Haimberger 
-| University of Vienna
+| Department of Meteorology and Geophysics 
+| University of Vienna 
+| Althanstraße 14 / UZA II
+| 1090 Vienna, Austria
+| mail: leopold.haimberger [at] univie.ac.at
 
     
Index: for_developers/Sphinx/source/conf.py
===================================================================
--- for_developers/Sphinx/source/conf.py	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/conf.py	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -14,10 +14,13 @@
 #
 import os
-import sys
-sys.path.insert(0, os.path.abspath('../../../source/python'))
-sys.path.insert(0, os.path.abspath('../../../source/python/mods'))
-sys.path.insert(0, os.path.abspath('../../../source/python/classes'))
-
-
+import sys, glob
+sys.path.insert(0, os.path.abspath('../../../Source/Python'))
+sys.path.insert(0, os.path.abspath('../../../Source/Python/Mods'))
+sys.path.insert(0, os.path.abspath('../../../Source/Python/Classes'))
+
+sys.path.insert(0, os.path.abspath('_static/python'))
+
+#fortran_src = [f for f in os.listdir('../../../source/fortran') if '.f90' in f or '.f' in f]
+#print(fortran_src)
 
 # -- Project information -----------------------------------------------------
@@ -52,8 +55,22 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
-#    'sphinx_pyreverse',
     'sphinx-jsonschema',
-    'sphinx.ext.intersphinx'
-]
+    'sphinx.ext.intersphinx',
+    'hidden_code_block',
+    'sphinxcontrib.exceltable',
+    'sphinxcontrib.seqdiag',
+    'sphinxcontrib.blockdiag',
+    'sphinx.ext.todo',
+#    'sphinxfortran.fortran_autodoc',
+#    'sphinxfortran.fortran_domain'
+]
+
+
+# Fontpath for seqdiag (truetype font)
+seqdiag_fontpath = '/usr/share/fonts/dejavu/DejaVuSerif.ttf'
+
+# Fontpath for blockdiag (truetype font)
+blockdiag_fontpath = '/usr/share/fonts/dejavu/DejaVuSerif.ttf'
+
 
 # Add any paths that contain templates here, relative to this directory.
@@ -186,4 +203,5 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
+#todo_link_only = True
 
 
@@ -194,3 +212,2 @@
 
 
-
Index: for_developers/Sphinx/source/documentation.rst
===================================================================
--- for_developers/Sphinx/source/documentation.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/documentation.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -1,88 +1,21 @@
-=============
+*************
 Documentation
-=============
+*************
         
-    Overview
-      - What is ``flex_extract``?
+    Overview (Under construction)
       
-        - general overview
-        - motivation, aim
-        - directory structure
-        
-      - Software components
-        complete component structure (table or diagram)
-        
-        - Python package
-        
-          - Package diagram
-          - Files and modules as table with information about unit tests
-          - Api
-          
-        - Fortran program - CONVERT2
-        
-          - Package diagram
-          - Api
-          
-        - Wrapping shell-scripts
-        
-      - Dependencies
-      - General context (for who?, Usecases, work tree)
-      - Access to ECMWF
-      - Application modes
-      - Call tree
-      - Sequence diagram
+    Control & Input Data 
     
-    Control & Input Data
-      - Controlling files
-      
-        - setup.sh (explain input parameters)            
-        - job scripts
-        - compile job
-        - run[_local].sh
-        
-      - Input Data
-      
-        - CONTROL files
-        
-          - The CONTROL file
-          - CONTROL parameters
-          - Examples
-          - Changes and its downward compatibilities (eg M _ /grid)
-          
-        - ECMWF_ENV file
-        - Templates
-        
-    Output Data
-      - mars request file
-      - Mars grib files
-      - flux files
-      - index.idx
-      - CONTROL (neu)
-      - fort files
-      - EN* files
-      
-        - Usual  output
-        - Output for pure forecast
-        - Output for ensemble members
-        - Output for new precipitation disaggregation
+    Output Data (Under construction)
     
-    Disaggregation
-      - What is disaggregation?
-      - Why do we need it/ which fields?
-      - Method for precipitation
-      
-        - Old method
-        - New method
-        - Differences in resulting Gribfiles
-        
-      - Method for rest fields
+    Disaggregation of Flux Data (Under construction)
     
-    Vertical Coordinate
+    Vertical Coordinate (Under construction)
       - Methods (GAUSS, ETA, OMEGA)
-      - CONVERT (Petra)
+      - CONVERT 
     
     Auto Generated Documentation
       - Python
-      - Fortran
+      - Fortran (Under construction)
 
     
Index: for_developers/Sphinx/source/evaluation.rst
===================================================================
--- for_developers/Sphinx/source/evaluation.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/evaluation.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -4,32 +4,35 @@
     UNDER CONSTRUCTION
     
+  
+  
+  
     
     
-Tests
-- unit tests
-  - table with all files and their functions and which already have unit tests
-- regression tests
-- performance
-- test runs with control files
+.. Tests
+    - unit tests
+      - table with all files and their functions and which already have unit tests
+    - regression tests
+    - performance
+    - test runs with control files
 
-Metriken
-- list all of them
+    Metriken
+    - list all of them
 
 
-Coverage
-- test coverage?! 
-- documentation coverage
+    Coverage
+    - test coverage?! 
+    - documentation coverage
 
-Static Analysis
-- pylint
-- pyreverse
-- radon
-    
-Performance analysis:
--	Whole software
--	Disaggregation
--	Convert2
--   prepare_flexpart
--	Andere komponenten
+    Static Analysis
+    - pylint
+    - pyreverse
+    - radon
+        
+    Performance analysis:
+    -	Whole software
+    -	Disaggregation
+    -	Convert2
+    -   prepare_flexpart
+    -	Andere komponenten
 
     
@@ -39,4 +42,6 @@
     :maxdepth: 2
     
-..    evaluation/code
+    Evaluation/staticcode
+    Evaluation/testcases
+    Evaluation/metrics
     
Index: for_developers/Sphinx/source/first_steps.rst
===================================================================
--- for_developers/Sphinx/source/first_steps.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ 	(revision )
@@ -1,14 +1,0 @@
-First Steps
-===========
- 
-    UNDER CONSTRUCTION
-    
-.. toctree::
-    :hidden:
-    :maxdepth: 2
-    
-..    user_guide/oper_modes
-..    user_guide/ecmwf
-..    user_guide/how_to
-..    user_guide/control_templates
-    
Index: for_developers/Sphinx/source/index.rst
===================================================================
--- for_developers/Sphinx/source/index.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/index.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -4,16 +4,9 @@
    contain the root `toctree` directive.
 
-========================================================
-Welcome to :literal:`flex_extract's` user documentation!
-========================================================
+=================================================
+Welcome to ``flex_extract``'s user documentation!
+=================================================
 
-:literal:`flex_extract` is an open-source software to retrieve meteorological fields from the European Centre for Medium-Range Weather Forecasts (ECMWF) Mars archive to serve as input files for the FLEXTRA/FLEXPART Atmospheric Transport Modelling system. 
-
-
-.. The scripts can be 1) executed locally using the ECMWF WebMARS interface, or 2) on the ECMWF member
-.. state gateway server or HPC facility using the ecaccess software package. As another option the scripts can 3)
-.. also be triggered using ecflow scheduling software used by ECMWF for data dissemination.
-
-.. All third-party software and libraries required by :literal:`flex_extract` are open source and free of charge. 
+``Flex_extract`` is an open-source software to retrieve meteorological fields from the European Centre for Medium-Range Weather Forecasts (ECMWF) Mars archive to serve as input files for the FLEXTRA/FLEXPART Atmospheric Transport Modelling system. 
 
 .. raw:: html
@@ -60,5 +53,5 @@
             <img style="position:absolute;height:90%;vertical-align:bottom;" src="_static/guide_icon.png">
           </div>
-          <h2><a href="first_steps.html">First Steps</a></h2>
+          <h2><a href="quick_start.html">Quick Start</a></h2>
           <ul>
             <li><a href="">...</a></li>
@@ -140,5 +133,5 @@
 
    installation
-   first_steps
+   quick_start
    ecmwf_data
    documentation
Index: for_developers/Sphinx/source/installation.rst
===================================================================
--- for_developers/Sphinx/source/installation.rst	(revision 41c9dbc9816a48a73dd439140ea7f56de10d8f43)
+++ for_developers/Sphinx/source/installation.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -67,6 +67,10 @@
 
 **Public user**: 
-    To be able to download all intended public datasets with ``flex_extract`` such as **ERA-Interim**, **CERA-20C** and **ERA5**, the public user has to create 2 accounts. 
-    At first, registration at the ECMWF website by filling out this `registration form`_ is needed to be able to retrieve *ERA-Interim* and *CERA-20C* data. For the retrievement of *ERA5* a registration at the `Copernicus Climate Data Store <https://cds.climate.copernicus.eu/user/register>`_ is needed in addition.
+    To be able to download public datasets with ``flex_extract`` such as **ERA-Interim** and **CERA-20C** (**ERA5** is not supported via ECMWF Web API anymore), the public user has to create an account at ECMWF. 
+    Use the registration at the ECMWF website by filling out this `registration form`. 
+    
+    .. note::
+
+        In the future retrievement of *ERA5* will be possible via the CDS API for public users also. Then a registration at the `Copernicus Climate Data Store <https://cds.climate.copernicus.eu/user/register>`_ is needed in addition.
     
     
@@ -77,5 +81,5 @@
 .. _ref-licence:
     
-Agree on Licences for Public Datasets
+Agree on licences for public datasets
 =====================================
 
@@ -123,5 +127,5 @@
 .. _ref-requirements: 
  
-Environment Requirements
+Environment requirements
 ========================
 
@@ -173,10 +177,10 @@
 .. _ref-remote-mode: 
 
-Remote Mode
+Remote mode
 -----------
 
 .. _ref-req-remote: 
  
-Remote Environment Requirements
+Remote environment requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -196,5 +200,5 @@
 .. _ref-prep-remote:
 
-Prepare Remote Environment
+Prepare remote environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  
@@ -206,5 +210,5 @@
 .. _ref-install-remote:
 
-Remote Installation
+Remote installation
 ^^^^^^^^^^^^^^^^^^^
 
@@ -266,5 +270,5 @@
 ``flex_extract`` root directory for installation. 
 Before executing it, it is necessary to adapt some parameters from ``setup.sh``
-described in :ref:`ref-setup`. 
+described in :doc:`Documentation/Input/setup`. 
 
 Open ``setup.sh`` with your editor and adapt the values:  
@@ -275,5 +279,5 @@
 | .. code-block:: bash                         | .. code-block:: bash                         | 
 |                                              |                                              | 
-|   ...                                        |   ...                                        |     
+|   ...                                        |   ...                                        |   
 |   # -----------------------------------------|   # -----------------------------------------|
 |   # AVAILABLE COMMANDLINE ARGUMENTS TO SET   |   # AVAILABLE COMMANDLINE ARGUMENTS TO SET   |
@@ -290,5 +294,5 @@
 |   JOB_TEMPLATE='job.template'                |   JOB_TEMPLATE='job.template'                |
 |   CONTROLFILE='CONTROL_EA5'                  |   CONTROLFILE='CONTROL_EA5'                  | 
-|   ...                                        |   ...                                        |    
+|   ...                                        |   ...                                        |   
 +----------------------------------------------+----------------------------------------------+
 
@@ -359,5 +363,5 @@
 .. _ref-gateway-mode:
 
-Gateway Mode
+Gateway mode
 ------------
 
@@ -365,5 +369,5 @@
 .. _ref-req-gateway: 
  
-Gateway Environment Requirements
+Gateway environment requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -379,9 +383,9 @@
 .. _ref-prep-gateway:
 
-Prepare Gateway Environment
+Prepare gateway environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The easiest way to install all required packages is to use the package management system of your Linux distribution. To do so, it is necessary to use a user with admin rights.
-The installation was tested on a *Debian GNU/Linux buster/sid* and an *Ubuntu 18.04 Bionic Beaver* system.
+The installation was tested on a *GNU/Linux Debian buster* and an *Ubuntu 18.04 Bionic Beaver* system.
 
 .. code-block:: sh
@@ -389,13 +393,13 @@
    # On a Linux Debian or Ubuntu system do
    # (if not already available):
-   sudo apt -PV install python3
-   sudo apt -PV install pip
-   pip install genshi
-   pip install numpy
+   apt-get install python3
+   apt-get install pip
+   apt-get install genshi
+   apt-get install numpy
 
 
 .. _ref-test-gateway:
 
-Test Gateway Environment
+Test gateway environment
 ^^^^^^^^^^^^^^^^^^^^^^^^
  
@@ -414,5 +418,5 @@
 .. _ref-install-gateway:
 
-Gateway Installation
+Gateway installation
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -431,5 +435,5 @@
    Your passcode: ***
    
-``Flex_extract`` will be run on an ECMWF server which makes the setup the same as for the **remote mode**. In the ``setup.sh`` script :ref:`[ref] <ref-setup>`, select the ``Makefile.gfortran`` for the ``CONVERT2`` Fortran program and the ECMWF server (*target*) you would like to use. 
+``Flex_extract`` will be run on an ECMWF server which makes the setup the same as for the **remote mode**. In the ``setup.sh`` script `[ref] <Documentation/Input/setup.html>`_, select the ``Makefile.gfortran`` for the ``CONVERT2`` Fortran program and the ECMWF server (*target*) you would like to use. 
 The job script, send to the job queue via the ECaccess software, selects again automatically the correct libraries from the module system. For enableing the file transfer you have to set the *ECUID*, *ECGID*, *GATEWAY* and *DESTINATION* parameter values.
  
@@ -506,5 +510,5 @@
 .. _ref-local-mode:
 
-Local Mode
+Local mode
 ----------
 
@@ -513,5 +517,5 @@
 .. _ref-req-local: 
  
-Local Environment Requirements
+Local environment requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -536,5 +540,5 @@
 .. _ref-prep-local:
 
-Prepare Local Environment
+Prepare local environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -546,13 +550,13 @@
    # On a Linux Debian or Ubuntu system do
    # (if not already available):
-   sudo apt -PV install python3
-   sudo apt -PV install pip
-   sudo apt -PV install gfortran
-   sudo apt -PV install fftw3-dev 
-   sudo apt -PV install libeccodes-dev
-   sudo apt -PV install libemos-dev 
-   sudo apt -PV install python3-eccodes
-   pip install genshi
-   pip install numpy
+   apt-get install python3 (usually available on normal Linux systems)
+   apt-get install pip
+   apt-get install gfortran
+   apt-get install fftw3-dev 
+   apt-get install libeccodes-dev
+   apt-get install libemos-dev 
+   apt-get install python3-eccodes
+   apt-get install genshi
+   apt-get install numpy
    pip install cdsapi 
    pip install ecmwf-api-client 
@@ -571,4 +575,8 @@
 The CDS API (cdsapi) and the ECMWF Web API (ecmwf-api-client) have both to be installed since ERA5 can only be retrieved with the ``CDS API`` and all other datasets with the ``ECMWF Web API``.     
        
+.. note:: 
+
+    Since **public users** currently don't have access to the full *ERA5* dataset they can skip the installation of the ``CDS API``. 
+    
 Both user groups have to provide key's with their credentials for the Web API's in their home directory. Therefore, follow these instructions:
    
@@ -582,5 +590,5 @@
 .. _ref-test-local:
    
-Test Local Environment
+Test local environment
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -615,50 +623,30 @@
 """""""""""""
 
-**Member user**
-    Please use this piece of python code:
-
-    .. code-block:: python
-
-        from ecmwfapi import ECMWFService
+
++----------------------------------------------------------+----------------------------------------------------------+
+|Please use this piece of python code for **Member user**: |Please use this piece of python code for **Public user**: |
++----------------------------------------------------------+----------------------------------------------------------+
+|.. code-block:: python                                    |.. code-block:: python                                    |
+|                                                          |                                                          |
+|    from ecmwfapi import ECMWFService                     |    from ecmwfapi import ECMWFDataServer                  |
+|                                                          |                                                          |
+|    server = ECMWFService('mars')                         |    server = ECMWFDataServer()                            |
+|                                                          |                                                          |
+|    server.retrieve({                                     |    server.retrieve({                                     |
+|        'stream'    : "oper",                             |        'stream'    : "enda",                             |
+|        'levtype'   : "sfc",                              |        'levtype'   : "sfc",                              |
+|        'param'     : "165.128/166.128/167.128",          |        'param'     : "165.128/166.128/167.128",          |
+|        'dataset'   : "interim",                          |        'dataset'   : "cera20c",                          |
+|        'step'      : "0",                                |        'step'      : "0",                                |
+|        'grid'      : "0.75/0.75",                        |        'grid'      : "1./1.",                            |
+|        'time'      : "00/06/12/18",                      |        'time'      : "00/06/12/18",                      |
+|        'date'      : "2014-07-01/to/2014-07-31",         |        'date'      : "2000-07-01/to/2000-07-31",         |
+|        'type'      : "an",                               |        'type'      : "an",                               |
+|        'class'     : "ei",                               |        'class'     : "ep",                               |
+|        'target'    : "download_erainterim_ecmwfapi.grib" |        'target'    : "download_cera20c_ecmwfapi.grib"    |
+|    })                                                    |    })                                                    |
++----------------------------------------------------------+----------------------------------------------------------+
+
             
-        server = ECMWFService('mars')
-            
-        server.retrieve({
-            'stream'    : "oper",
-            'levtype'   : "sfc",
-            'param'     : "165.128/166.128/167.128",
-            'dataset'   : "interim",
-            'step'      : "0",
-            'grid'      : "0.75/0.75",
-            'time'      : "00/06/12/18",
-            'date'      : "2014-07-01/to/2014-07-31",
-            'type'      : "an",
-            'class'     : "ei",
-            'target'    : "download_erainterim_ecmwfapi.grib"
-        })
-
-
-**Public user**
-    Please use this piece of python code: 
-
-    .. code-block:: python
-
-        from ecmwfapi import ECMWFDataServer
-            
-        server = ECMWFDataServer()
-            
-        server.retrieve({
-            'stream'    : "enda",
-            'levtype'   : "sfc",
-            'param'     : "165.128/166.128/167.128",
-            'dataset'   : "cera20c",
-            'step'      : "0",
-            'grid'      : "1./1.",
-            'time'      : "00/06/12/18",
-            'date'      : "2000-07-01/to/2000-07-31",
-            'type'      : "an",
-            'class'     : "ep",
-            'target'    : "download_cera20c_ecmwfapi.grib"
-        })
     
 CDS API 
@@ -667,58 +655,61 @@
 Since ERA5 extraction with CDS API might take some time due to the very high number of requests, you can start by retrieving some online stored pressure levels (not from MARS). This is usually much faster and gives a quick result to find out if the web API works:
 
-**All users**
-    Please use this piece of python code:
-    
-    .. code-block:: python
-
-        import cdsapi
-        
-        c = cdsapi.Client()
-        
-        c.retrieve("reanalysis-era5-pressure-levels",
-        {
-        "variable": "temperature",
-        "pressure_level": "1000",
-        "product_type": "reanalysis",
-        "year": "2008",
-        "month": "01",
-        "day": "01",
-        "time": "12:00",
-        "format": "grib"
-        },
-        "download_cdsapi.grib")
+Please use this piece of python code to retrieve a small sample of *ERA5* pressure levels:
+
+.. code-block:: python
+
+    import cdsapi
+    
+    c = cdsapi.Client()
+    
+    c.retrieve("reanalysis-era5-pressure-levels",
+    {
+    "variable": "temperature",
+    "pressure_level": "1000",
+    "product_type": "reanalysis",
+    "year": "2008",
+    "month": "01",
+    "day": "01",
+    "time": "12:00",
+    "format": "grib"
+    },
+    "download_cdsapi.grib")
 
 
 Afterwards, when you know that the CDS API generally works, you can try to extract some
-data from the MARS archive. From the latest experience this can take a while.    
-
-**Member user**
-    Please use this piece of python code:
-    
-    .. code-block:: python
-
-       import cdsapi
-       
-       c = cdsapi.Client()
-       
-       c.retrieve('reanalysis-era5-complete',
-       {
-           'class'   : 'ea',
-           'expver'  : '1',
-           'stream'  : 'oper',
-           'type'    : 'fc',
-           'step'    : '3/to/12/by/3',
-           'param'   : '130.128',
-           'levtype' : 'ml',
-           'levelist': '135/to/137',
-           'date'    : '2013-01-01',
-           'time'    : '06/18',
-           'area'    : '50/-5/40/5',
-           'grid'    : '1.0/1.0', 
-           'format'  : 'grib',
-       }, 'download_era5_cdsapi.grib')
-
-
-**Public user**
+data from the MARS archive. From the latest experience we know that this can take a while.    
+
+.. **Member user**
+
+Please use this piece of python code to retrieve a small *ERA5* data sample as a **member user**! The **public user** doesn't have access to the full *ERA5* dataset!
+
+.. code-block:: python
+
+   import cdsapi
+   
+   c = cdsapi.Client()
+   
+   c.retrieve('reanalysis-era5-complete',
+   {
+       'class'   : 'ea',
+       'expver'  : '1',
+       'stream'  : 'oper',
+       'type'    : 'fc',
+       'step'    : '3/to/12/by/3',
+       'param'   : '130.128',
+       'levtype' : 'ml',
+       'levelist': '135/to/137',
+       'date'    : '2013-01-01',
+       'time'    : '06/18',
+       'area'    : '50/-5/40/5',
+       'grid'    : '1.0/1.0', 
+       'format'  : 'grib',
+   }, 'download_era5_cdsapi.grib')
+
+
+..  ********************** COMMENTED OUT FOR FUTURE 
+    ********************** PUBLIC RETRIEVAL IS CURRENTLY NOT ACCESSIBLE 
+   
+    **Public user**
     Please use this piece of python code: 
 
@@ -754,5 +745,5 @@
 .. _ref-install-local:
 
-Local Installation
+Local installation
 ^^^^^^^^^^^^^^^^^^
 
@@ -763,6 +754,6 @@
 the ``ifort`` compiler:
 
- *Makefile.local.gfortran
- *Makefile.local.ifort
+ * Makefile.local.gfortran
+ * Makefile.local.ifort
 
 They can be found in the path ``flex_extract_vX.X/source/fortran``, where
@@ -928,13 +919,9 @@
    
 
-Mars request test
------------------
-
-    IN PREPARATION ...
 
 Full test
 ---------
 
-    IN PREPARATION ...
-
-    
+    see :doc:`quick_start`
+
+    
Index: for_developers/Sphinx/source/quick_start.rst
===================================================================
--- for_developers/Sphinx/source/quick_start.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/quick_start.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,500 @@
+***********
+Quick Start
+***********
+
+``Flex_extract`` by itself is a command-line tool. With version 7.1 an upstream shell script was implemented which calls ``flex_extract`` with the command-line parameters. 
+
+To submit a job with ``flex_extract`` change the working directory to the ``Run`` directory  which is placed directly under the ``flex_extract_vX.X`` root directory  (``X.X`` is the version number):
+
+.. code-block:: bash
+
+    cd <path-to-flex_extract_vX.X>/Run
+
+Within this directory you can find everything you need to modify and run ``flex_extract``. The following tree shows a shortened list of directories and important files. The ``*`` serves as a wildcard. The brackets ``[]`` means that the file appearance depends on the mode of application and night not be present.
+
+.. code-block:: bash
+        
+    Run
+    ├── Control
+    │   ├── CONTROL_*
+    ├── Jobscripts
+    │   ├── compilejob.ksh
+    │   ├── job.ksh
+    │   ├── [joboper.ksh]
+    ├── Workspace
+    │   ├── CERA_example
+    │   │   ├── CE000908*
+    ├── [ECMWF_ENV]
+    ├── run_local.sh
+    └── run.sh
+
+The ``Jobscripts`` directory is used to store the Korn shell job scripts generated by a ``flex_extract`` run in the **Remote** or **Gateway** mode. They are used to submit the setup information to the ECMWF server and start the jobs in ECMWF's batch mode. The typical user must not touch these files. They will be generated from template files which are stored in the ``Templates`` directory under ``flex_extract_vX.X``. Usually there will be a ``compilejob.ksh`` and a ``job.ksh`` script which are explained in the section :doc:`Documentation/input`. In the rare case of operational data extraction there will be a ``joboper.ksh`` which is designed to get the time parameters from environment variables at the ECMWF servers.
+
+The ``Controls`` directory contains a number of example ``CONTROL`` files. These``CONTROL`` files represent the current range of possible dataset retrievals with ``flex_extract``. Some parameters in the ``CONTROL`` files can be adapted and some others should not be changed. In this :doc:`quick_start` guide we explain how an extraction with ``flex_extract`` can be started in the different :doc:`Documentation/Overview/app_modes` and point out some specifics of each dataset and ``CONTROL`` file.
+
+Directly under ``Run`` you find the files ``run.sh`` and ``run_local.sh`` and according to your selected :doc:`Documentation/Overview/app_modes` there might also be a file named ``ECMWF_ENV`` for the user credentials to quickly and automatically access ECMWF servers.  
+
+From version 7.1 on, the ``run.sh`` (or ``run_local.sh``) script is the main access point to ``flex_extract``. 
+
+.. note::
+
+    Note that, for experienced users (or users of older versions), it is still possible to access ``flex_extract`` directly via the ``submit.py`` script which can be found in the directory ``flex_extract_vX.X/Source/Python``.
+    
+
+
+Job preparation
+===============
+
+To actually start a job with ``flex_extract`` it is only necessary to submit the ``run.sh`` or ``run_local.sh`` script on the command-line. For the specification of dataset and the selection of the access mode it is necessary to select and modify a ``CONTROL`` file and change the parameters in the user section of the ``run`` scripts. The following sections describes the differences in the application modes and where the results will be stored. 
+    
+
+Remote and gateway modes
+------------------------
+
+For member state users it is recommended to use the *remote* or *gateway* mode, especially for more demanding tasks, to retrieve and convert data on ECMWF machines and to transfer only the final output files to the local host. 
+
+Remote mode
+    The only difference between both modes is the users working location. In the *remote* mode you have to login to the ECMWF server and then go to the ``Run`` directory as shown above. At ECMWF servers ``flex_extract`` is installed in the ``$HOME`` directory. However, to be able to start the program you have to load the ``Python3`` environment with the module system first. 
+
+    .. code-block:: bash
+
+        # Remote mode
+        ssh -X <ecuid>@ecaccess.ecmwf.int
+
+    .. code-block:: bash
+    
+        # On ECMWF server
+        [<ecuid>@ecgb11 ~]$ module load python3
+        [<ecuid>@ecgb11 ~]$ cd flex_extract_vX.X/Run
+        
+
+Gateway mode        
+    For the gateway mode you have to log in on the gateway server and go to the ``Run`` directory of ``flex_extract``:
+
+    .. code-block:: bash
+
+        # Gateway mode
+        ssh <user>@<gatewayserver>
+        cd <path-to-flex_extract_vX.X>/Run
+
+        
+From here on the working process is the same for both modes.   
+
+For your first submission you should use one of the example ``CONTROL`` files stored in the ``Control`` directory. We recommend to extract *CERA-20C* data since they usually guarantee quick results and are best for testing reasons.
+ 
+Therefore open the ``run.sh`` file and modify the parameter block marked in the file as shown below:
+
+.. code-block:: bash
+
+    # -----------------------------------------------------------------
+    # AVAILABLE COMMANDLINE ARGUMENTS TO SET
+    # 
+    # THE USER HAS TO SPECIFY THESE PARAMETERS:
+
+    QUEUE='ecgate'
+    START_DATE=None
+    END_DATE=None
+    DATE_CHUNK=None
+    JOB_CHUNK=3
+    BASETIME=None
+    STEP=None
+    LEVELIST=None
+    AREA=None
+    INPUTDIR=None
+    OUTPUTDIR=None
+    PP_ID=None
+    JOB_TEMPLATE='job.temp' 
+    CONTROLFILE='CONTROL_CERA' 
+    DEBUG=0
+    REQUEST=2
+    PUBLIC=0   
+
+
+This would retrieve a one day (08.09.2000) *CERA-20C* dataset with 3 hourly temporal resolution and a small 1° domain over Europe. Since the ``ectrans`` parameter is set to ``1`` the resulting output files will be transferred to the local gateway into the path stored in the destination (SEE INSTRUCTIONS FROM INSTALLATION).  The parameters listed in the ``run.sh`` file would overwrite existing settings in the ``CONTROL`` file.   
+
+To start the retrieval you only have to start the script by:
+
+.. code-block:: bash
+ 
+    ./run.sh
+
+``Flex_extract`` will print some information about the job. If there is no error in the submission to the ECMWF server you will see something like this: 
+    
+.. code-block:: bash
+    
+    ---- On-demand mode! ----
+    The job id is: 10627807
+    You should get an email per job with subject flex.hostname.pid
+    FLEX_EXTRACT JOB SCRIPT IS SUBMITED!
+  
+
+Once submitted you can check the progress of the submitted job using ``ecaccess-job-list``. You should get an email after the job is finished with a detailed protocol of what was done. 
+
+In case the job fails you will receive an email with the subject ``ERROR!`` and the job name. You can then check for information in the email or you can check on ECMWF server in the ``$SCRATCH`` directory for debugging information.    
+
+.. code-block:: bash
+        
+    cd $SCRATCH
+    ls -rthl
+
+The last command lists the most recent logs and temporary retrieval directories (usually ``pythonXXXXX``, where XXXXX is the process id). Under ``pythonXXXXX`` a copy of the ``CONTROL`` file is stored under the name ``CONTROL``, the protocol is stored in the file ``prot`` and the temporary files as well as the resulting files are stored in a directory ``work``. The original name of the ``CONTROL`` file is stored in this new file under parameter ``controlfile``.
+
+.. code-block:: bash
+    :caption: "Example structure of ``flex_extract`` output directory on ECMWF servers."
+        
+    pythonXXXXX
+    ├── CONTROL
+    ├── prot
+    ├── work
+    │   ├── temporary files
+    │   ├── CE000908* (resulting files)
+
+If the job was submitted to the HPC ( ``queue=cca`` ) you may login to the HPC and look into the directory ``/scratch/ms/ECGID/ECUID/.ecaccess_do_not_remove`` for job logs. The working directories are deleted after job failure and thus normally cannot be accessed.
+
+To check if the resulting files are still transferred to local gateway server you can use the command ``ecaccess-ectrans-list`` or check the destination path for resulting files on your local gateway server. 
+   
+
+Local mode 
+----------
+    
+To get to know the working process and to start your first submission you could use one of the example ``CONTROL`` files stored in the ``Control`` directory as they are. For quick results and for testing reasons it is recommended to extract *CERA-20C* data.
+ 
+Open the ``run_local.sh`` file and modify the parameter block marked in the file as shown below. The differences are highlighted. 
+
++-----------------------------------------------+-----------------------------------------------+ 
+|   Take this for **member-state user**         |  Take this for **public user**                | 
++-----------------------------------------------+-----------------------------------------------+
+| .. code-block:: bash                          | .. code-block:: bash                          | 
+|    :emphasize-lines: 16,20,23                 |    :emphasize-lines: 16,20,23                 |
+|                                               |                                               | 
+|    # -----------------------------------------|    # -----------------------------------------|
+|    # AVAILABLE COMMANDLINE ARGUMENTS TO SET   |    # AVAILABLE COMMANDLINE ARGUMENTS TO SET   |
+|    #                                          |    #                                          |
+|    # THE USER HAS TO SPECIFY THESE PARAMETERs:|    # THE USER HAS TO SPECIFY THESE PARAMETERs:| 
+|    #                                          |    #                                          |
+|                                               |                                               |
+|    QUEUE=''                                   |    QUEUE=''                                   |
+|    START_DATE=None                            |    START_DATE=None                            |
+|    END_DATE=None                              |    END_DATE=None                              |
+|    DATE_CHUNK=None                            |    DATE_CHUNK=None                            |
+|    JOB_CHUNK=None                             |    JOB_CHUNK=None                             | 
+|    BASETIME=None                              |    BASETIME=None                              | 
+|    STEP=None                                  |    STEP=None                                  |
+|    LEVELIST=None                              |    LEVELIST=None                              | 
+|    AREA=None                                  |    AREA=None                                  |
+|    INPUTDIR='./Workspace/CERA'                |    INPUTDIR='./Workspace/CERApublic'          |
+|    OUTPUTDIR=None                             |    OUTPUTDIR=None                             |
+|    PP_ID=None                                 |    PP_ID=None                                 |
+|    JOB_TEMPLATE=''                            |    JOB_TEMPLATE=''                            | 
+|    CONTROLFILE='CONTROL_CERA'                 |    CONTROLFILE='CONTROL_CERA.public'          |
+|    DEBUG=0                                    |    DEBUG=0                                    |
+|    REQUEST=0                                  |    REQUEST=0                                  |
+|    PUBLIC=0                                   |    PUBLIC=1                                   |
+|                                               |                                               |
++-----------------------------------------------+-----------------------------------------------+
+
+
+This would retrieve a one day (08.09.2000) *CERA-20C* dataset with 3 hourly temporal resolution and a small 1° domain over Europe. The destination location for this retrieval will be within the ``Workspace`` directory within ``Run``. This can be changed to whatever path you like. The parameters listed in ``run_local.sh`` would overwrite existing settings in the ``CONTROL`` file.  
+    
+To start the retrieval you then start the script by:
+
+.. code-block:: bash
+ 
+    ./run_local.sh
+    
+  
+While job submission on the local host is convenient and easy to monitor (on standard output), there are a few caveats with this option:
+
+    1. There is a maximum size of 20GB for single retrieval via ECMWF Web API. Normally this is not a problem but for global fields with T1279 resolution and hourly time steps the limit may already apply.
+    2. If the retrieved MARS files are large but the resulting files are relative small (small local domain) then the retrieval to the local host may be inefficient since all data must be transferred via the Internet. This scenario applies most notably if ``etadot`` has to be calculated via the continuity equation as this requires global fields even if the domain is local. In this case job submission via ecgate might be a better choice. It really depends on the use patterns and also on the internet connection speed.    
+        
+
+
+
+Selection and adjustment of ``CONTROL`` files
+=============================================
+
+
+This section describes how to work with the ``CONTROL`` files. A detailed explanation of ``CONTROL`` file parameters and naming compositions can be found `here <Documentation/Input/control.html>`_. The more accurately the ``CONTROL`` file describes the retrieval needed, the fewer command-line parameters are needed to be set in the ``run`` scripts. With version ``7.1`` all ``CONTROL`` file parameters have default values. They can be found in section `CONTROL parameters <Documentation/Input/control_params.html>`_ or in the ``CONTROL.documentation`` file within the ``Control`` directory. Only those parameters which need to be changed for a dataset retrieval needs to be set in a ``CONTROL`` file!
+
+The limitation of a dataset to be retrieved should be done very cautiously. The datasets can differ in many ways and vary over the time in resolution and parameterisations methods, especially the operational model cycles improves through a lot of changes over the time. If you are not familiar with the data it might be useful or necessary to check for availability of data in ECMWF’s MARS:
+
+    - **Public users** can use a web mask to check on data or list available data at this `Public datasets web interface <https://apps.ecmwf.int/datasets/>`_. 
+    - **Member state users** can check availability of data online in the `MARS catalogue <https://apps.ecmwf.int/mars-catalogue/>`_.
+
+There you can select step by step what data suits your needs. This would be the most straightforeward way of checking for available data and therefore limit the possibility of ``flex_extract`` to fail. The following figure gives an example how the web interface would look like: 
+
+
+.. _ref-fig-mars-catalogue-ss:
+
+.. figure:: _files/MARS_catalogue_snapshot.png
+
+    
+!!!!!!!! ADD HERE ANOTHER SCREENSHOT OF THE PARAMETER SELECTION AREA ( HAS TO BE DONE AT HOME )
+
+Additionally, you can find a lot of helpful links to dataset documentations, direct links to specific dataset web catalogues or further general information at the `link collection <Ecmwf/ec-links.html>`_ in the ECMWF data section.    
+
+
+``Flex_extract`` is specialised to retrieve a limited number of datasets, namely *ERA-Interim*, *CERA-20C*, *ERA5* and *HRES (operational data)* as well as the *ENS (operational data, 15-day forecast)*. The limitation relates mainly to the dataset itself, the stream (what kind of forecast or what subset of dataset) and the experiment number. Mostly, the experiment number is equal to ``1`` to signal that the actual version should be used. 
+
+The next level of differentiation would be the field type, level type and time period. ``Flex_extract`` currently only supports the main streams for the re-analysis datasets and provides extraction of different streams for the operational dataset. The possibilities of compositions of dataset and stream selection are represented by the current list of example ``CONTROL`` files. You can see this in the naming of the example files: 
+
+
+.. code-block:: bash
+    :caption: "Current example ``CONTROL`` files distributed with ``flex_extract``. "
+
+    CONTROL_CERA    
+    CONTROL_CERA.global   
+    CONTROL_CERA.public     
+    CONTROL_EA5      
+    CONTROL_EA5.global        
+    CONTROL_EI   
+    CONTROL_EI.global    
+    CONTROL_EI.public       
+    CONTROL_OD.ELDA.FC.eta.ens.double
+    CONTROL_OD.ENFO.CF 
+    CONTROL_OD.ENFO.CV 
+    CONTROL_OD.ENFO.PF                          
+    CONTROL_OD.ENFO.PF.36hours    
+    CONTROL_OD.ENFO.PF.ens
+    CONTROL_OD.OPER.4V.operational 
+    CONTROL_OD.OPER.FC.36hours 
+    CONTROL_OD.OPER.FC.eta.global
+    CONTROL_OD.OPER.FC.eta.highres  
+    CONTROL_OD.OPER.FC.gauss.highres  
+    CONTROL_OD.OPER.FC.operational            
+    CONTROL_OD.OPER.FC.twiceaday.1hourly
+    CONTROL_OD.OPER.FC.twiceaday.3hourly
+    
+    
+
+The main differences and features in the datasets are listed in the table shown below:    
+          
+
+.. _ref-tab-dataset-cmp:
+
+.. figure:: _files/dataset_cmp_table.png
+
+   DO THIS TABLE AGAIN BY HAND!
+                    
+A common problem for beginners in retrieving ECMWF datasets is the mismatch in the definition of these parameters. For example, if you would like to retrieve operational data before ``June 25th 2013`` and set the maximum level to ``137`` you will get an error because this number of levels was first introduced at this effective day. So, be cautious in the combination of space and time resolution as well as the field types which are not available all the time. 
+
+
+.. note::
+
+    Sometimes it might not be clear how specific parameters in the control file must be set in terms of format. Please see the description of the parameters in section `CONTROL parameters <Documentation/Input/control_params.html>`_ or have a look at the ECMWF user documentation for `MARS keywords <https://confluence.ecmwf.int/display/UDOC/MARS+keywords>`_
+
+
+In the following we shortly discuss the main retrieval opportunities of the different datasets and  categoize the ``CONTROL`` files.    
+                    
+     
+Public datasets
+---------------         
+
+The main difference in the definition of a ``CONRTOL`` file for a public dataset is the setting of the parameter ``DATASET``. This specification enables the selection of a public dataset in MARS. Otherwise the request would not find the dataset.
+For the two public datasets *CERA-20C* and *ERA-Interim* an example file with the ending ``.public`` is provided and can be used straightaway. 
+
+.. code-block:: bash
+  
+    CONTROL_CERA.public  
+    CONTROL_EI.public      
+
+For *CERA-20C* it seems that there are no differences in the dataset against the full dataset, while the *public ERA-Interim* has only analysis fields every 6 hour without filling forecasts in between for model levels. Therefore it is only possible to retrieve 6-hourly data for *public ERA-Interim*.
+
+.. note:: 
+
+    In general, *ERA5* is a public dataset. However, since the model levels are not yet publicly available, it is not possible to retrieve *ERA5* data to drive the ``FLEXPART`` model. As soon as this is possible it will be announced at the community website and per newsletter. 
+                     
+
+CERA
+----
+
+For this dataset it is important to keep in mind that the dataset is available for the period 09/1901 until 12/2010 and the temporal resolution is limited to 3-hourly fields. 
+It is also a pure ensemble data assimilation dataset and is stored under the ``enda`` stream. It has ``10`` ensemble members. The example ``CONTROL`` files will only select the first member (``number=0``). You may change this to another number or a list of numbers (e.g. ``NUMBER 0/to/10``).
+Another important difference to all other datasets is the forecast starting time which is 18 UTC. Which means that the forecast in *CERA-20C* for flux fields is  12 hours long. Since the forecast extends over a single day we need to extract one day in advance and one day subsequently. This is automatically done in ``flex_extract``. 
+
+
+ERA 5
+-----
+
+This is the newest re-analysis dataset and has a temporal resolution of 1-hourly analysis fields. Up to date it is available until April 2019 with regular release of new months. 
+The original horizontal resolution is ``0.28125°`` which needs some caution in the definition of the domain, since the length of the domain in longitude or latitude direction  must be an exact multiple of the resolution. It might be easier for users to use ``0.25`` for the resolution which MARS will automatically interpolate. 
+The forecast starting time is ``06/18 UTC`` which is important for the flux data. This should be set in the ``CONTROL`` file via the ``ACCTIME 06/18`` parameter in correspondence with ``ACCMAXSTEP 12`` and ``ACCTYPE FC``. 
+
+.. note::
+
+    We know that *ERA5* also has an ensemble data assimilation system but this is not yet retrievable with ``flex_extract`` since the deaccumulation of the flux fields works differently in this stream. Ensemble retrieval for *ERA5* is a future ToDo.
+
+
+
+ERA-Interim
+-----------
+
+This re-analysis dataset will exceed its end of production at 31st August 2019!
+It is then available from 1st January 1979 to 31st August 2019. The ``etadot`` is not available in this dataset. Therefore ``flex_extract`` must select the ``GAUSS`` parameter to retrieve the divergence field in addition. The vertical velocity is the calculated with the continuity equation in the Fortran program ``CONVERT2``. Since the analysis fields are only available for every 6th hour, the dataset can be made 3 hourly by adding forecast fields in between. No ensemble members are available.
+
+
+.. todo::
+
+    @LEO: please check the complete describtion and functionality of the CONTROL FILEs
+    
+Operational data
+----------------
+
+This is the real time atmospheric model in high resolution with a 10-day forecast. This means it underwent regular adaptations and improvements over the years. Hence, retrieving data from this dataset needs extra attention in selecting correct settings of parameter. See :ref:`ref-tab-dataset-cmp` for the most important parameters. 
+Nowadays, it is available 1 hourly by filling the gaps of the 6 hourly analysis fields with 1 hourly forecast fields. Since 4th June 2008 the eta coordinate is directly available so that ``ETA`` should be set to ``1`` to save computation time. The horizontal resolution can be up to ``0.1°`` and in combination with ``137`` vertical levels can lead to troubles in retrieving this high resolution dataset in terms of job duration and quota exceedence. 
+It is recommended to submit such high resolution cases for single day retrievals (see ``JOB_CHUNK`` parameter in ``run.sh`` script) to avoid job failures due to exceeding limits.   
+
+``CONTROL`` files for normal daily retrievals with a mix of analysis and forecast fields are listed below:
+
+.. code-block:: bash
+
+    CONTROL_OD.OPER.4V.eta.global 
+    CONTROL_OD.OPER.FC.eta.global
+    CONTROL_OD.OPER.FC.eta.highres  
+    CONTROL_OD.OPER.FC.gauss.highres  
+    
+These files defines the minimum number of parameters necessary to retrieve a daily subset. The setup of field types is optimal and should only be changed if the user understands what he does. The grid, domain and temporal resolution can be changed according to availability.      
+    
+.. todo:: 
+    
+    @LEO - explain the setup with 4V fields! Who can extract it, when would this be useful? 
+
+
+.. note:: 
+
+     Please see `Information about MARS retrievement <https://confluence.ecmwf.int/display/UDOC/Retrieve#Retrieve-Retrievalefficiency>`_ to get to know hints about retrieval efficiency and troubleshooting. 
+  
+    
+
+Pure forecast
+    It is possible to retrieve pure forecasts exceeding a day. The forecast period available depends on the date and forecast field type. Please use MARS catalogue to check the availability. Below are some examples for 36 hour forecast of *Forecast (FC)*, *Control forecast (CF)* and *Calibration/Validation forecast (CV)*. 
+    The *CV* field type was only available 3-hourly from 2006 up to 2016. It is recommended to use the *CF* type since this is available from 1992 (3-hourly) on up to today in 1-hourly temporal resolution. *CV* and *CF* field types belong to the *Ensemble prediction system (ENFO)* which contain 50 ensemble members. 
+    Please be aware that in this case it is necessary to set the specific type for flux fields explicitly, otherwise it could select a default value which might be different from what you expect!
+    
+    .. code-block:: bash
+
+        CONTROL_OD.ENFO.CF.36hours
+        CONTROL_OD.ENFO.CV.36hours    
+        CONTROL_OD.OPER.FC.36hours  
+
+
+
+Half-day retrievals
+    If a forecast for just half a day is wanted it can be done by substituting the analysis fields also by forecast fields as shown in files with ``twiceaday`` in it. They produce a full day retrieval with pure 12 hour forecasts twice a day. It is also possible to use the operational version which would get the time information from ECMWF's environmental variables and therefore get the newest forecast per day. This version uses a ``BASETIME`` parameter which tells MARS to extract the exact 12 hours upfront to the selected date. If the ``CONTROL`` file with ``basetime`` in the filename is used this can be done for any other date too.
+    
+    .. code-block:: bash
+
+        CONTROL_OD.OPER.FC.eta.basetime
+        CONTROL_OD.OPER.FC.operational            
+        CONTROL_OD.OPER.FC.twiceaday.1hourly
+        CONTROL_OD.OPER.FC.twiceaday.3hourly
+
+
+
+
+Ensemble members
+    The retrieval of ensemble members were already mentioned in the pure forecast section and for *CERA-20C* data. 
+    In this ``flex_extract`` version there is an additional possibility to retrieve the *Ensemble Long window Data Assimilation (ELDA)* stream from the real-time dataset. This model version has (up to May 2019) 25 ensemble members and a control run (``number 0``). Starting from June 2019 it has 50 ensemble members. Therefore we created the possibility to double up the 25 ensemble members (before June 2019) to 50 members by taking the original 25 members from MARS and subtracting 2 times the difference between the member value and the control value. This is done by selecting the parameter ``DOUBLEELDA`` and set it to ``1``. 
+     
+    
+    .. code-block:: bash
+
+        CONTROL_OD.ELDA.FC.eta.ens.double   
+        CONTROL_OD.ENFO.PF.ens
+
+.. todo::
+
+    @LEO: Please tell me why perturbed forecast are possible? Is it because of some user rights? I have no opportunity of retrieve PF data.       
+    
+    
+    
+Specific features
+-----------------
+
+rrint
+    Decides if the precipitation flux data uses the old (``0``) or new (``1``) disaggregation scheme. See :doc:`Documentation/disagg` for explanaition. 
+cwc
+    Decides if the total cloud water content will be retrieved (set to ``1``) in addition. This is the sum of cloud liquid and cloud ice water content.
+addpar
+    With this parameter an additional list of 2-dimensional, non-flux parameters can be retrieved. Use format ``param1/param2/.../paramx`` to list the parameters. Please be consistent in using either the parameter IDs or the short names.
+doubleelda
+    Use this to double the ensemble member number by adding further disturbance to each member. 
+debug
+    If set to ``1`` all temporary files were kept at the end. Otherwise everything except the final output files will be deleted.
+request
+    This produces an extra *csv* file ``mars_requests.csv`` where the content of each mars request of the job is stored. Useful for debugging and documentation.
+mailfail
+    At default the mail is send to the mail connected with the user account. Add additional email addresses if you want. But as soon as you enter a new mail, the default will be overwritten. If you would like to keep the mail from your user account, please add ``${USER}`` to the list ( comma seperated ) or mail addresses.
+      
+        
+        
+Hints for definition of some parameter combinations
+---------------------------------------------------
+
+Field types and times
+    This combination is very important. It defines the temporal resolution and which field type is extracted per time step. 
+    The time declaration for analysis (AN) fields uses the times of the specific analysis and (forecast time) steps have to be ``0``. The forecast field types (e.g. FC, CF, CV, PF) need to declare a combination of (forescast start) times and the (forecast) steps. Both of them together defines the actual time step. It is important to know the forecast starting times for the dataset to be retrieved, since they are different. In general it is enough to give information for the exact time steps, but it is also possible to have more time step combinations of ``TYPE``, ``TIME`` and ``STEP`` because the temporal (hourly) resolution with the ``DTIME`` parameter will select the correct combinations. 
+
+    .. code-block:: bash
+       :caption: Example of a setting for the field types and temporal resolution.
+
+        DTIME 3
+        TYPE AN FC FC FC AN FC FC FC
+        TIME 00 00 00 00 12 12 12 12
+        STEP 00 03 06 09 00 03 06 09
+    
+ 
+Vertical velocity           
+    The vertical velocity for ``FLEXPART`` is not directly available from MARS. Therefore it has to be calculated. There are a couple of different options. The following parameters are responsible for the selection. See :doc:`Documentation/vertco` for a detailed explanation. The ``ETADIFF``, ``OMEGA`` and ``OMEGADIFF`` versions are only recommended for debugging and testing reasons. Usually it is a decision between ``GAUSS`` and ``ETA``, where for ``GAUSS`` spectral fields of the horizontal wind fields and the divergence are to be retrieved and used with the continuity equation to calculate the vertical velocity. For ``ETA`` the latitude/longitude fields of horizontal wind fields and eta-coordinate are to be retrieved. It is recommended to use ``ETA`` where possible due to a reduced computation time.  
+
+    .. code-block:: bash
+        :caption: Example setting for the vertical coordinate retrieval.
+        
+        GAUSS 0
+        ETA 1
+        ETADIFF 0
+        DPDETA 1
+        OMEGA 0
+        OMEGADIFF 0
+        
+
+Grid resolution and domain
+    The grid and domain selection depends on each other. The grid can be defined in the format of normal degrees (e.g. ``1.``) or as in older versions by 1/1000. degrees (e.g. ``1000`` for ``1°``).
+    After selecting the grid, the domain has to be defined in a way that the length of the domain in longitude or latitude direction  must be an exact multiple of the grid. 
+    The horizontal resolution for spectral fields will be set by the parameter ``RESOL``. For information about how to select an appropriate value you can read the explanation of the MARS keyword `here <https://confluence.ecmwf.int/display/UDOC/Post-processing+keywords#Post-processingkeywords-resol>`_ and in `this table  <https://confluence.ecmwf.int/display/UDOC/Retrieve#Retrieve-Truncationbeforeinterpolation>`_.
+    
+    .. code-block:: bash
+        :caption: Example setting for a northern hemisphere domain with a grid of ``0.25°``.
+    
+        GRID 0.25
+        RESOL 799
+        SMOOTH 0
+        UPPER 90.
+        LOWER 0.
+        LEFT -179.75
+        RIGHT 180.
+    
+
+Flux data
+    The flux fields are accumulated forecast fields all the time. Since some re-analysis dataset nowadays have complete set of analysis fields in their temporal resolution it was important to define a new parameter set to define the flux fields since the information could not be taken from ``TYPE``, ``TIME`` and ``STEP`` any longer. Select a forecast field type ``ACCTYPE``, the forecast starting time ``ACCTIME`` and the maximum forecast step ``ACCMAXSTEP``. The ``DTIME`` parameter defines the temporal resolution for the whole period. 
+    
+    .. code-block:: bash
+       :caption: Example setting for the definition of flux fields.
+    
+        DTIME 3
+        ACCTYPE FC
+        ACCTIME 00/12
+        ACCMAXSTEP 36
+
+
+    
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+    
+..    user_guide/oper_modes
+..    user_guide/ecmwf
+..    user_guide/how_to
+..    user_guide/control_templates
+    
Index: for_developers/Sphinx/source/todo.rst
===================================================================
--- for_developers/Sphinx/source/todo.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
+++ for_developers/Sphinx/source/todo.rst	(revision 0b0060763be4ba958df1a992d707fc4fe1efed3a)
@@ -0,0 +1,8 @@
+=====
+ToDos
+=====
+
+
+
+
+.. todolist::
