/****************************************************************************
**  SCALASCA    http://www.scalasca.org/                                   **
*****************************************************************************
**  Copyright (c) 1998-2012                                                **
**  Forschungszentrum Juelich GmbH, Juelich Supercomputing Centre          **
**                                                                         **
**  See the file COPYRIGHT in the package base directory for details       **
****************************************************************************/

This directory contains several files which can be used to test a SCALASCA
or KOJAK installation or to explore the different features of the toolset.
For further detailed instructions see the Scalasca User Guide located in
the "doc/manuals" directory.


Instrumentation and Event Trace Generation
==========================================

"ctest.c" and "ftest.F90" are simple toy C and Fortran programs which can be
used to test the instrumentation and measurement features of the toolset.
Versions of these files including manual instrumentation using the EPIK API
and POMP directives include "-epik" and "-pomp" in their names.  The changes
can be examined using the diff utility and are documented in Chapter 3 of the
Scalasca User Guide.

Instrumentation and compilation can be invoked by "make ctest-pomp-mpi",
"make ftest-pomp-mpi", "make ctest-epik-mpi", or "make ftest-epik-mpi" to
generate MPI executables. To generate hybrid OpenMP/MPI executables,
replace "-mpi" with "-hyb".  These executables, when executed in parallel,
produce EPIK experiment archives.

Automatic instrumentation is supported by certain systems and compilers.
Here, you also can do "make ctest-mpi" or "make ftest-mpi" (or the "-hyb"
variants) to test the automatic user function instrumentation.

On systems where automatic instrumentation is only supported for separate
compile and link commands, such as Cray XT, instead use 
"make ctest-xt-mpi", "make ftest-xt-mpi", "make ctest-xt-hyb", etc.



Event Trace Processing
======================

The EPIK experiment archive "epik_ctest-mpi_smp32_trace" was generated by
building the ctest-mpi target from the ctest.c example code, and executing
it on IBM Blue Gene/P compute nodes as 32 MPI processes under the control
of the Scalasca analyzer with tracing configured: "scalasca -analyze -t".
It can be used to test the analysis report explorer, or can be re-analyzed
(overwriting the existing analysis).

The EPILOG trace file "ctest-pomp.elg" was generated by instrumenting the
"ctest-pomp.c" example code and executing it on 2 IBM SP compute nodes
each executing 4 MPI processes with 4 OpenMP threads each. It can be used
to test the following commands:
- elg_print
- elg_stat
- elg2vtf
- expert
- cube3

The EXPERT result file (ctest-pomp.cube) is the result of executing the
serial trace analyzer: "expert ctest-pomp.elg" -- and can also be examined
with the analysis report explorer: "cube3 ctest-pomp.cube"

Finally, the Vampir trace file "ctest-pomp.vpt" was generated by converting
the EPILOG trace file with "elg2vtf". Use "vampir ctest-pomp.vpt" to view it.
