INSTALL

INSTALL:

Short instructions:

* Modify Make.config in the top level directory to reflect your configuration.

* Type
    make lib
  in the top level directory (or the src/ subdirectory) to build libpampac.a 
  and move it into the lib/ subdirectory.

* Modify the file example/driver.config to reflect your configuration.

* Type
    make driver
  in the example/ subdirectory to build the executable driver

* Modify the example/parameters.txt to run the example provided. The files in
  the example/ subdirectory serve as a template from which to develop your
  own examples using the PAMPAC library.

Long instructions:

The principal file to modify to build the PAMPAC library is Make.config in the
top-level directory. This file contains the principal macros that need to be
defined for compilation and linking. You should customise the macros in that
file (notably PAMPACDIR and any specific include paths to the headers for the
GSL (GNU Scientific Library)). You should set the macros MPICC and MPIEXEC
to reflect the paths to the MPI-enabled compiler and the mpiexec (or mpirun)
executables on your system.

The example/ subdirectory contains code that uses the PAMPAC library to solve a
model continuation problem based on a modified Kuramoto-Sivashinsky equation.
To build the executable file "driver", you should modify the file
example/driver.config. The macros within that file specify (among other things)
the number of processors to use in runs (NPROCS), the location of the parameter
file needed to run a code using the PAMPAC library (PARAMETERFILE), and the
location in which output data will be written (DATADIR). This example requires
the GSL (>=1.16) and the LAPACK (>=3.10) libraries, so specific flags in the
file example/driver.config must be set to find those libraries on your system.

Once Make.config and driver.config are configured correctly, you should be
able to use GNU make to build the library and run the example problem. The
example problem can be used as a template for your own simulations. See the
User Manual for more details.

To reiterate:

(1) To make the PAMPAC library (after modifying Make.config), type

    make lib

inside either the top-level directory ${PAMPACDIR} or from the subdirectory
${PAMPACDIR}/src. By default, the library libpampac.a will be moved into
${PAMPACDIR}/lib. If you wish to install it elsewhere, you can copy it
manually or you can modify PAMPACLIBDIR in the file ${PAMPACDIR}/Make.config
to have the library installed eleswhere in your system.

(2) To build the example (after modifying example/driver.config), type

    make driver

inside the subdirectory ${PAMPACDIR}/example. This will create the binary
executable driver in ${PAMPACDIR}/example (assuming the required libraries
to link with have been appropriately specified).

(3) To run the example problem (once the driver has been created), type

    make run

inside the subdirectory ${PAMPACDIR}/example. This will commence an MPI
session with NPROCS processes using the data in PARAMETERFILE as input. The
Makefile variables can be set at the invocation of make, e.g.,

    make NPROCS=12 run

(4) There is the option of generating visualizations of the tree data
structure used within the core PAMPAC algorithm. Once the simulation has
been run (assuming that the parameter VERBOSE in the parameter file has
been set appropriately), a sequence of .gv files will have been created
withing the data directory (files in the dot language for graph
visualization). Invoking

    make trees

inside the subdirectory ${PAMPACDIR}/example will run the command dot on each
file to yield a corresponding .svg file showing the corresponding tree
structure. This is useful for understanding how well the PAMPAC library is
working for your computation.

(5) Running

    make clean

will clean all the object and binary files from the directories to allow a
fresh build.