Preprocessing
*************

Generating analytical data
==========================

Quickstart
----------

In the ``generate`` folder, edit the configuration file ``config.init``
then run

::

    $ make exec

This will generate the concentration data as well as the winds,
corrected to ensure mass is preserved.

Configuration file
------------------

The first section defines where the winds are to be written (center of
the cells or the borders), as well as if the winds are corrected
in-place. Finally, the grid is completely defined by the number of
latitudes on a hemisphere.

::

    [grid]
    winds_format = borders
    replace = True
    nb_lat2 = 40
            

Then we define the output folder, as well as the test case. Possible
values are

-  zonal
   : zonal advection
-  meridional
   : meridional advection
-  solid\_rot
   : solid rotation around an axis, defined by its angle to the z-axis
-  hourdin
   : test case defined in Hourdin's paper
-  gaussian\_hills
   : test case used in Lauritzen's test suite where the inital condition
   is a set of two "Gaussian hills"
-  cosine\_bells
   : idem, but with two "cosine bells"
-  cosine\_bells\_corr
   : idem, but with two "correlated cosine bells"

::

    [run]
    folder = /wkdir/pae2/praga/input/gaussianhills_40lat
    case = gaussian_hills
    gen_winds = True
    date_ref = 201301010000
    date_end = 201301130000
    dt = 000100
    # Only for solid rotation test case. In radians
    angle = 0
            

The dates are set using a starting date (YYYYMMDDHHMM), a stop date
(same format) as well as a time-step (DDHHMM).

Files
-----

A Python module ``pangolinGrid.py`` defines the Pangolin grid. Another
module, ``analyticalCase.py`` defines the test cases (see the source
code for more details). To speed-up data generation, the most expensive
computations are done in Fortran, in ``analytical_case.f90``.

Some information about the data
-------------------------------

Please note the model needs divergence-free winds. Also, the winds
defined in ``pangolingrid.py`` are set in m/s but the final winds
outputed by the script and read by Pangolin are in degree/s.

Interpolating MOCAGE data
=========================

Idea
----

We want to interpolate 3D data from the regular latitude-longitude grid
to a 2D Pangolin grid. This is done in a two-step processes. First, the
3D data is interpolated vertically using cubic splines onto an
isentropic plane. Then, data is interpolated horizontally from a 2D
lat-lon to a 2D Pangolin grid. The winds will be corrected to ensure
mass is preserved.

|Conversion between the different formats|

It should be noted that interpolation is done differently for winds.
Ratio and temperature are interpolated using the SCRIP library, which
allows for a conservative interpolation. However, winds are interpolated
using successive 1D cubic splines. More details can be found in the
thesis of A. Praga.

Usage
-----

First, edit the configuration file ``preprocessing/config`` to define
the input and output files, as well as the grid and the date:

::

    &list_files
      input_folder = "data/"
      input_file = "HMGLOB22+2008090100.nc"
      output_folder = "output/"
      date = "200810010000"
      nb_lat2 = 31/
            

Pleas note that comments are allowed. Then run:

::

    $ bin/interpolate_to_pangolin

Interpolating chemistry coefficients
====================================

We use a linear ozone chemistry scheme (see Cariolle and Teyssèdre,
2007). Only the first five coefficients are used. A semi-implicit scheme
is used for temporal discretization. The coefficients are given for the
year 2000 by the MOBIDIC model. There are interpolated vertically onto
an isentropic plane. At the moment, coefficients are constant, so the
simulation will only works for a month. For longer simulations, a linear
temporal interpolation should be used.

In practice, get the MOBIDIC coefficients by going into the
``preprocessing/`` folder and run:

::

    $ make download

Then, in the same folder, edit ``preprocessing/interpol_chemistry.F90``
and change the input and output folder. Go back to the root folder and
run:

::

    $ make install
    $ bin/interpol_chemistry

The resulting coefficients are placed at the root folder in
``chemistry.h5``.

    **Warning**

    During the simulation, Pangolin will not check the coefficients are
    on the proper grid so check to use the same grid for chemistry
    interpolation. Otherwise, the simulation will fail.

.. |Conversion between the different formats| image:: figures/grids_formats.png