Running Pangolin
****************

Configuration file
==================

Copy the template ``config.template`` to another file (the default is
``config``). Edit it following the information given in the comments (a
comment beging with !).

As an example, we show here a small config file :

::

    nb_partitions = 27
    nb_lat2 = 5
    t_start = 201301010000
    t_end =   201301020000
    dt=5.
    T_winds =  0100
    T_output = 0100

    output_dir = output
    output_winds_dir = output
    test_case = testsuite_cv

    input_dir = input
    input_winds_dir = input 

Here, we set the model with 27 MPI processes, which should be run with
27 cores to have true parallelism. The number of latitude on the grid is
10 (twice ``nb_lat2``). The simulation is set to run for two whole days,
with a time step of 5 minutes. Winds are read every hour and data is
written every hour. Ratio and winds have different input and output
folders for more flexibility. Finally, we use winds implemented in the
model for debug purposes with:

::

     test_case = testsuite_cv 

How to run
==========

Quickstart
----------

    **Warning**

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

        $ export TZ=GMT

Start the script simulation\_run and follow the instructions. You can
specify the number of processus (which should the number of partitions).
Here is an example run:

::

    $ ./simulation_run.pl
            Enter the number of processus:
            Number of partitions (start):
            3
            Number of partitions (end):
            9 

You can directly override the number of processus for several runs or a
single one:

::

    $ ./simulation_run.pl --start=3 --end=9
    $ ./simulation_run.pl --startend=126

Here is the result of a sample run:

::

    Simulation
    b partitions = 3
    logfilepangolin.log_4906
    Warning : Analytical case (for debug)
    Warning : CFL set from timestep
    Nb processes =       3
    Nb partitions =       3
    * Reading configuration file config.new done
    * Initializing simulation done
    New global grid with           80 latitudes on an hemisphere
    Three partitions
    Numerical ratio (always)
    Reading ratio (sequential)/wkdir/pae2/praga/input/gaussianhills_80lat/ratio_1_201301010000.h5
    Analytical winds
     skipping merid winds check (partition_class)
    * Partitioning done
    * Starting simulation...
    Run from 2013/01/01 00:00 to 2013/01/13 00:00
    Duration    12.000 days(nb iter=    864, dt=  20.00min, CFL=   0.95605)
    * Simulation done
    * Cleaning...

Customization
-------------

You can start the executable by hand with:

::

    $ mpirun -np 9 bin/pangolin

By default, ``config`` is the configuration file but this can be changed
with:

::

    $ mpirun -np 9 bin/pangolin --config=other.config

Starting jobs is done with a PBS script ``pbs_run.batch``. You must edit
it in order to specify the running time. Also, you can add you own
specifications in it (sourcing files, loading modules...).

Remarks
-------

Timesteps
~~~~~~~~~

In the configuration file, the different timesteps are given in minutes.
However, in the code, we only deal with times in seconds (possible
overflow for large simulations ?).

I/O
~~~

The simulation needs only a starting and ending time given in the format
YYYYMMDDHHMM. The period is on the form HHMM. It will deduce the needed
running time and the number of iterations according to the timestep. But
it will not check every data file is here. So a missing file will only
be found when needed.

Winds
~~~~~

-  Winds are interpolated linearly.
-  In input, winds are positive if they point towards the north.
   However, the correction will change the sign for the model : positive
   will thus mean toward the south.
-  They must be given in m/s on the Earth. The model will convert them
   in degree/s.