CrayPAT

Category: Tools-Performance

Description

CrayPat is the Cray performance analysis tool. CrayPat is an optional performance analysis tool for evaluating program execution on Cray systems. CrayPat consists of three major components:

These components are described in greater detail in the pat_build, pat_report, and app2 man pages, respectively. Note that you must have the xt-craypat (or apprentice2) module loaded first to get these man pages. In addition, more detail about CrayPat usage and environment variables is provided in the pat man page.

Use

Follow these steps to use CrayPat to perform a basic analysis of your program. Start with a debugged and executable program. CrayPat is a performance analysis tool, not a debugging tool. The program must be capable of running to planned completion or intentional termination before CrayPat can be useful. Load the programming environment module. This ensures that the correct links and libraries are in place for your choice of compiler and target execution environment. For example, if you are working on a Cray XT series system and using CNL on the compute nodes, enter this command:
  module avail xt-craypat
  module load xt-craypat

Then compile and link your program. With the CrayPat module(s) loaded, remake or recompile your program, using the compiler option to preserve all .o files (and .a files, if any) created during compilation. CrayPat requires access to the object files (and archive files, if any).

For example, if you are working with a Fortran program, enter commands like these examples:

  % ftn -c myprogram.f
  % ftn -o myprogram myprogram.o

Use the pat_build command to insert automatic profiling analysis (APA) code into your program. The instrumented copy is saved under a new name with the extension +pat; the original program remains unchanged.

  % pat_build -O apa myprogram

Execute the program. During execution, the specified performance analysis data is collected and written to one or more data files, depending on the experiment being conducted.

On a Cray XT series CNL system, programs are executed using the aprun command.

  % aprun myprogram+pat

On a Cray XT series system using the PBS Pro batch environment, programs are submitted using the qsub command, and yod or aprun are used as arguments to the qsub command depending on your site's choice of compute-node operating system. Report the results. After program execution completes or terminates, use the pat_report command to create a .apa report.

  % pat_report -o sample.txt myprogram+pat+PID

Once a .apa file has been created, you should open the file in your preferred text editor and verify that you do not wish to have more or less profiled. Lines that are preceeded with # will be ignored. Any option to pat_build may be added to this file. For most users, the file created by pat_report will be sufficient. After you have verified this file, reinstrument your executable as follows.

  % pat_build -O <apafile>.apa

The resulting executable will end with +apa; run again with this executable. As before, your executable will create either one .xf file, or a directory with multuple .xf files, depending on your processor count. Once you have completed execution, generate a .ap2 file for pat_report or apprentice2.

  % pat_report -f ap2 <output>.xf

You can use this file as input to pat_report, for text reports, or apprentice2, for graphical analysis. By default, your code will gather hardware counters from hwcp group 0. This can be overridden at runtime by setting the PAT_RT_HWPCenvironment variable (see man hwpc). To ignore hwpc data in your text reports, use the -H option to pat_report.

Support

This package has the following support level : Supported

Available Versions

All versions of this software are provided by the system vendor and are not installed by NICS staff.