Quickstart
**********

    **Warning**

    Before a run, the TZ variable must be set always be set to GMT. In
    bash, do:
    ::

        $ export TZ=GMT

Running analytical test cases
=============================

HDF5 version
------------

Pangolin supports the ASCII format to test the model quickly. However,
HDF5 is the current recommanded format (see below). Here we assume HDF5
is used. If you want ASCII, the main steps are highlighted in the
section.

First, generate the analytical data. For that, go into the ``generate``
folder and run

::

    $ python main.py
    Gaussian hills
    nb lat2 80
    Generating ./ratio_1_201301010000.h5
    Generating ./u_201301010000.h5
    Generating ./v_201301010000.h5
    Correcting ./v_201301010000.h5
    Correcting ./u_201301010000.h5
    Replacing old ascii files

This will generate the tracer data and 2D winds on the Pangolin grid in
HDF5 (if you configured for ASCII, you will have .dat files). The grid
will have 80 latitude on each hemisphere. For more information about the
Python script, see ?.

Then we can set up the model. Copy this freshly generated data into an
appropriate folder:

::

    $ mkdir input
    $ cp generate/*.dat input

Now create the following configuration file ``config``:

::

    nb_partitions = 9
    nb_lat2 = 80
    t_start = 201301010000
    t_end =   201301010100
    dt=20.
    T_winds =  130000
    T_output = 130000

    output_dir = ouput
    output_winds_dir = output

    input_dir = input
    input_winds_dir = input 

This will create a run of 1 hour with a timestep of 20 minutes. Data
will be read in the ``input/`` directory and written in ``output/``.
More information about the configuration file is given in ?.

Next, we configure and build the model:

::

    $ autoreconf --install
    $ ./configure
    $ make install

Reading ? is more than recommanded to ensure everything needed is
installed. The building process is detailed in ?. If you have any
trouble, see ?. Configuring HDF5 can be tricky, so please see ? for more
details.

Finally, we run the model with 9 MPI processes:

::

    $ ./simulation_run.pl --startend=9
    Simulation
    Nb partitions = 9
    logfilepangolin.log_6913                                                 
    Warning : Analytical case (for debug)
    Warning : CFL set from timestep
    Nb processes =       9
    Nb partitions =       9
    Warning : Directory ouput does not exist, creating it
    * Reading configuration file config.new done
    * Initializing simulation done
    New global grid with           80 latitudes on an hemisphere
    The last band is not the limiting factor, OK
    Correcting height of            0           0
    Correcting height of            0           0
    nb parts           9 nb procs           9
    Numerical ratio (always)
    Reading ratio (sequential)input/ratio_1_201301010000.dat
    Analytical winds
    skipping merid winds check (partition_class)
    * Partitioning done
    * Starting simulation...
    Run from 2013/01/01 00:00 to 2013/01/01 01:00
    Duration     0.042 days(nb iter=      3, dt=  20.00min, CFL=   0.95605)
    Mass :   3919.0299886725911165  3919.0299886725847500 -0.6366462912410498E-11
    * Simulation done
    * Cleaning...

This step and how to customize it is detailed in ?.

ASCII version
-------------

First, active ASCII support by setting has\_hdf5 to False in
``generate/pangolinGrid.py`` and run

::

    $ python main.py

Copy the data:

::

    $ mkdir input
    $ cp generate/*.dat input

Now create the following configuration file ``config``:

::

    nb_partitions = 9
    nb_lat2 = 80
    t_start = 201301010000
    t_end =   201301010100
    dt=20.
    T_winds =  130000
    T_output = 130000

    output_dir = ouput
    output_winds_dir = output

    input_dir = input
    input_winds_dir = input 

Next, we configure and build the model:

::

    $ autoreconf --install
    $ ./configure
    $ make install

Reading ? is more than recommanded to ensure everything needed is
installed. The building process is detailed in ?. If you have any
trouble, see ?.

Finally, we run the model with 9 MPI processes:

::

    $ ./simulation_run.pl --startend=9

This step and how to customize it is detailed in ?.