VTune Playbook with templates for Intel tools usage
====================================================

The Playbook contains command lines starting with $
Please change $PRG, $ARGS into the path,name and parameters of your program! 

Version 0.9 09.10.2018

Please send feedback to heinrich.bockhorst@intel.com

0. Environment
--------------

load environment by:

$ source env.sh

check for important executables

$ which amplxe-cl

check version 

$ amplxe-cl -version


1. Compile for VTune
========================

no extra compilation necessary but "-g" Flag helps for displaying function names and
source code. 

2. Open GUI
============

$ amplxe-gui &

All configurations collections can be done with the GUI. This might be more convenient. 
On clusters it is sometimes necessary to use the command line interface. 
Starting with the GUI the command line can be generated by the GUI.  

3. Command Line Interface
=========================

Project can be defined and run from GUI. See workflow in PDF presentation.
For more complex codes on clusters the command line interface can be used. 

$ amplxe-cl -help

shows basic help menu with hints for more detailed information

$ amplxe-cl -help collect 

shows analysis types etc. 

3.a Advanced Hotspots
======================

This is probably the best collection to start! 

$ amplxe-cl -c advanced-hotspots -r AH -- $PRG $ARG [PRG Parameter]

-c      : analysis type 
-r      : result directory
$PRG    : your program
$ARG    : program parameters

for more information on OpenMP:

$ amplxe-cl -c advanced-hotspots -knob analyze-openmp=true -r AH-omp -- <PRG.x> $ARG

further knobs (options):

-knob sampling-interval=0.1 

(higher sampling frequency, larger output)

-knob collection-detail=stack-sampling

(collects stack information, good for unknown programs)


Usage with Intel MPI Programs
================================


$ export I_MPI_GTOOL="amplxe-cl -c advanced-hotspots -knob analyze-openmp=true -r AH:0" 

for analysis on rank #0. 
run MPI program as usual. 
 
$ mpirun -n <N> <PRG.x>

Analysis on all ranks with :all

GTOOL can be used for all types of analysis and also for Advisor!

Only for KNL
============

-finalization-mode=deferred

(just collect the raw data, this is better for large jobs on KNL.
 Finalization might be done later. Probably on a Xeon node)

$ amplxe-cl -finalize -r <result-directory> 

3.b HPC Performance
===================

overview about several HPC performance metrics

$ amplxe-cl -c hpc-performance -r HP -- <PRG.x> 

use help system for more options (knobs)

$ amplxe-cl -help collect hpc-performance

3.c Memory Access
=================

$ amplxe-cl -c memory-access -r MA -- <PRG.x> 

more detailed information:

$ amplxe-cl --collect memory-access -knob analyze-mem-objects=true -r ME -- <PRG.x> 

3.d General Exploration
=======================

this is for expert users who want to get the complete CPU information. This can be 
quite confusing in the beginning. 

$ amplxe-cl -c general-exploration -r GE -- <PRG.x>


5. View results 
===============

Open GUI

$ amplxe-gui & 

and navigate to results directory

or do command line analysis

$ amplxe-cl -report summary -r <AH> 

<AH> is the directory generated by hotspot-analysis

see 

$ amplxe-cl -help report 

for more options.

-resume-after=<double>