Cactus Code Thorn PAPI
Authors    : Tom Goodale
CVS info   : $Header$
--------------------------------------------------------------------------

Purpose of the thorn:

This thorn uses the Performance API available from

http://icl.cs.utk.edu/projects/papi

to collect performance data about a cactus run.

Currently it can be used with the 1.0 release and the
1.0 Beta  release of the PerfTools.

Description:

Currently it uses the 'perfometer' library to connect to a gui
and to display the MFLOP/s of the code.

Optionally it marks the different evolution time bins with different
colours.

Usage:

To compile:

Get and build the libpapi.a and libperformeter.a libraries from the 1.0 release of
Papi and the 1.0 Beta release of the PerfTools.  Then copy these two files into a
directory, and set the environment variable

PAPILIBDIR

to point to that directory.

e.g.

cp libpapi.a libperfometer.a /home/goodale/lib/papi

export PAPILIBDIR=/home/goodale/lib/papi

Then build the thorn as normal.

Note that instead of setting the environment variable as above, you can
just pass it in on the _compile_ line, e.g.

gmake <config> PAPILIBDIR=/home/goodale/lib/papi

To build the GUI, you should set your path to point to a Java compiler, then
go into the PerfGUI directory and type make.


In parameter file:

To activate just include 'papi' in the ActiveThorns parameter.

To switch of colour marking, set

PAPI::mark = "no"

There are parameters which control the colours, these are

default_colour
initial_colour
prestep_colour
evol_colour
poststep_colour
analysis_colour

There are many allowed colours which are listed in the file COLOURS.
You may also specify a colour as a set of three decimal integers
specifying the Red, Green, and Blue values in ranges 0 to 255.

E.g. Red = 255 0 0
     White = 255 255 255

The COLOURS file lists the numbers next to each name so you have something to
go on.

These numbers should just be specified as a string, e.g.

default_colour = "255 0 0"
initial_colour = "magenta"
...

At runtime:

The code will stop saying something like

    Perfometer server awaiting connection on port # 3545

At this point you should start the performance GUI (perfGUI) 
available from the PAPI project, and tell it to connect to the machine
you are running cactus on.