Requirements
************

Mandatory
=========

Autotools
    Configuring the project is done with autoconf, and automake. It
    configures the projects by searching for the necessary dependencies
    and compiling source code. autoconf should tell you if anything
    vital is missing.

MPI
    Most of the code is in Fortran and is compiled with an MPI script
    (for example ``mpif90``). A very small part is in C and is compiled
    likewise (for examplewith a script ``mpicc``). This suppose you have
    a Fortran and C compiler which are needed for testing purposes
    mostly. The MPI library should support the MPI2 standard.

    You should also be able to run parallel jobs. The code is configured
    for PBS jobs, but you can also use ``mpirun`` and edit the batch
    file.

        **Warning**

        Pangolin has been tested with ``gfortran``, ``pgf90``, ``ifort``
        for the Fortran compiler and MPICH, OpenMPI, Intel MPI for the
        MPI library. However, we do not claim to support all
        implementations and all versions (even if it should eventually).

        We only guarantee at the moment the following configurations :

        +--------------+------------+-------------------+----------------+------------------------+
        | C            | Fortran    | MPI               | Architecture   | Machine                |
        +==============+============+===================+================+========================+
        | icc 13.1.0   | ifort      | IntelMPI 4.1.2    | amd64          | Neptune (CERFACS)      |
        +--------------+------------+-------------------+----------------+------------------------+
        | gcc 4.5.1    | gfortran   | OpenMPI 1.4.3     | amd64          | Pannus (CERFACS, PC)   |
        +--------------+------------+-------------------+----------------+------------------------+
        | gcc 4.7.2    | gfortran   | OpenMPI 1.4.5-1   | amd64          | Home PC                |
        +--------------+------------+-------------------+----------------+------------------------+

        Table: MPI support

Perl
    Needed to start the simulation (even though it can be done by hand).
    It should be installed by default.

HDF5
    An I/O format which allows for parallel I/O. Even though Pangolin
    can manage ASCII data, it is the preferred I/O format.

netCDF
    Input data is given in this format, which must be converted to HDF5
    in a preprocessing step.

Recommended
===========

Python 2.7+
    A script is available to generate analytical solution into ASCII or
    HDF5 format. It can also be used to plot data with matplotlib and
    basemap (ASCII only). This version is only compatible with Python
    2.7+ but not Python 3.\*.

h5py
    A Python package to manage the HDF5 format easily.

Perl modules
    The following modules can be installed with ``cpanm`` (see ? for
    more details).

    -  Config::IniFiles
       : to read .ini files
    -  DateTime
       : to manage date and times
    -  DateTime::Format::Strptime
       : to manage date and times
    -  TAP::Harness
        : to run unit and functional tests shipped with Pangolin
    -  Getopt::Long
       : to read command-line arguments
    -  File::Copy
       : copying files
    -  File::Slurp
       : reading files
    -  File::Find
       : finding files
    -  File::Which
       : finding executables

Docbook
    Docbook is actually a format for writing documentation. This manual
    was generated with Docbook XSL. For that, you will need the packages
    xsltproc, fop and docbook-xsl. For validating the documentation, you
    may add xmlstarlet.

    This should take care of the latest Docbook, but it also possible to
    generate documentation using Jade and DSSL. This was not tested and
    the XSL approach is recommended.

Doxygen
    The other half of this documentation is generated from the source
    code with Doxyegen. It will document everything you should need to
    know about the source code.

Basemap
    A python package to plot data on the sphere with a whole range of
    projections. The scripts shipped with Pangolin only works for ASCII
    data at the moment. You should get the latest version and install it
    from source. Do not forget to install matplotlib with it.

NCL
    A plotting program used for publication-quality plotting. It can
    manage HDF5 files.

Installation help
=================

Perl modules suite
------------------

Here, we will configure Perl to install modules without needing root
privileges. All of our packages will be installed in
~/perl5
in this example. First, we install the utility
cpanminus
:
::

    $ wget -O- http://cpanmin.us | perl - -l ~/perl5 App::cpanminus local::lib

Then we set the
local::lib
package to use
~/perl5
from now on:
::

    $  eval `perl -I ~/perl5/lib/perl5 -Mlocal::lib`

This can be put in
.bash\_profile
(or the equivalent for your shell) for future sessions:
::

    $ echo 'eval `perl -I ~/perl5/lib/perl5 -Mlocal::lib`'>> ~/.profile

Now we can install any package easily. For Pangolin, you may want to
install everything :
::

    $ cpanm TAP::Harness  Getopt::Long  File::Copy  File::Slurp  File::Find File::Which