Intel® Advisor User Guide

User Guide

Contents

Run
Threading
 Perspective from Command Line

Threading perspective includes several steps that you are recommended to run one by one:
  1. Collect performance metrics and find candidates for parallelizing using a
    Survey
     analysis.
  2. Annotate
     manually loops/functions to model parallelization for.
  3. Model parallel design options and estimate speedup for the annotated loops using a
    Suitability
     analysis.
  4. Check for loop-carried
    dependencies
     to make sure the loops/functions are safe to parallelize.

Prerequisites

Set
Intel Advisor
 environment variables with an automated script to enable the
advisor
 command line interface (CLI).

Run
Threading
 Perspective

Info
: In the commands below, make sure to replace the
myApplication
 with your application executable path and name
before
 executing a command. If your application requires additional command line options, add them
after
 the executable name.
  1. Run the Survey analysis. 
    advisor --collect=survey --project-dir=./advi_results -- ./myApplication
  2. Run the Characterization analysis to collect trip counts and FLOP data. 
    advisor --collect=tripcounts --project-dir=./advi_results --flop -- ./myApplication
  3. View the Survey report to identify candidates for parallelization. For example, run the following command to print the report in command line:
    advisor --report=survey --project-dir=
    <project-dir>
    Consider analyzing loops/functions with high total time.
  4. In the application source code, annotate loops/functions of interest to model parallelization for.
    Rebuild the application as usual to make the annotations available for the Intel Advisor.
  5. Run the Suitability analysis to model threading for the annotated loops/functions: 
    advisor --collect=suitability --project-dir=./advi_results -– ./myApplication
  6. Run the Dependencies analysis to check for loop-carried dependencies in the annotated loops: 
    advisor --collect=dependencies --project-dir=./advi_results -– ./myApplication
You can view the results in the Intel Advisor graphical user interface (GUI), print a summary to a command prompt/terminal, or save to a file. See View the Results below for details.
Analysis Details
Each analysis in the
Threading
 perspective has a set of additional options that modify its behavior and collect additional performance data.
Consider the following options:
Characterization Options
To run the Characterization analysis, use the following command line action:
--collect=tripcounts
.
Recommended action options:
Options
Description
--flop
Collect data about floating-point and integer operations, memory traffic, and mask utilization metrics for AVX-512 platforms.
--stacks
Enable advanced collection of call stack data.
Dependencies Options
To run the Dependencies analysis, use the following command line action:
--collect=dependencies
.
Recommended action options:
Options
Description
--filter-reductions
Mark all potential reductions with a specific diagnostic.
See advisor Command Option Reference for more options.

View the Results

Intel Advisor
 provides several ways to work with the
Threading
 results.
View Results in CLI
You can print the results collected in the CLI and save them to a
.txt
,
.csv
, or
.xml
 file.
For example, to generate the Suitability report for the OpenMP* threading model: 
advisor --report=suitability --project-dir=./advi_results -–threading-model=openmp
You should see a similar result: 
Target CPU Count: 8     Threading Model: OpenMP*
Maximum gain for all sites: 6.10998

All Sites
Site Label      Source Location       Impact to    Total Serial Time   Total Parallel Time   Site Gain   Average Serial Time   Average Parallel Time   Number of
                                      Program Gain                                                                                                     Instances 
__________________________________________________________________________________________________________________________________________________________________
     solve   nqueens_serial.cpp:154          6.11x            4.080s                0.631s       6.47x                4.080s                  0.631s           1


Site Details
Annotation     Annotation Label      Source Location       Number of Instances   Maximum Instance   Average Serial    Minimum Instance    Total Serial 
                                                                                 Time               Time              Time                Time
__________________________________________________________________________________________________________________________________________________________________
Selected Site             solve   nqueens_serial.cpp:154                     1             4.080s           4.080s              4.080s          4.080s
         Task          setQueen   nqueens_serial.cpp:156                    14             0.477s           0.267s              0.020s          3.734s
         Lock                                           ?                365596            < 0.001s         < 0.001s            < 0.001s        0.100s



Site Options
                                         Benefit   Loss If
Site            Option           Done?   If Done   Not Done   Recommended
_________________________________________________________________________
solve     Reduce Site Overhead                                      No
solve     Reduce Task Overhead                                      No
solve     Reduce Lock Overhead                                      No
solve   Reduce Lock Contention             0.16x                    No
solve     Enable Task Chunking                                      No
The result is also saved into a text file
advisor-suitability.txt
 located at
./advi_results/e
<NNN>
/st
<NNN>
.
You can generate a report for any analysis you run. The
generic
 report command looks as follows:
advisor --report=
<analysis-type>
 --project-dir=
<project-dir>
 --format=
<format>
where:
  • <analysis-type>
     is the analysis you want to generate the results for. For example,
    survey
     for the Survey report,
    suitability
     for the Suitability report, or
    dependencies
     for the Dependencies report.
  • --format=
    <format>
     is a file format to save the results to.
    <format>
     is
    text
     (default),
    csv
    ,
    xml
    .
If you generate the Suitability report, you can use additional options to control the result view:
  • --target-system=[cpu | xeon-phi | offload-to-xeon-phi]
     is a platform to model parallelization on.
  • --threading-model=[tbb | cilk | openmp | tpl | other]
     is a threading model to use.
  • --reduce-site-overhead=
    <string>
     is a list of annotated loops/functions to check if you can reduce overhead.
You can also generate a report with the data from all analyses run and save it to a CSV file with the
--report=joined
 action as follows:
advisor --report=joined --report-output=
<path-to-csv>
where
--report-output=<path-to-csv>
 is a path and a name for a
.csv
 file to save the report to. For example,
/home/report.csv
. This option is required to generate a joined report.
See advisor Command Option Reference for more options.
View Results in GUI
When you run
Intel Advisor
 CLI, a project is created automatically in the directory specified with
--project-dir
. All the collected results and analysis configurations are stored in the
.advixeproj
 project, that you can view in the
Intel Advisor
.
To open the project in GUI, you can run the following command:
advisor-gui <project-dir>
If the report does not open, click
Show Result
 on the Welcome pane.
You first see a Threading Summary report that includes the overall information about loops/functions performance in your code and the annotated parallel sites:
  • Performance metrics of your program and top five time-consuming loops/functions
  • Optimization recommendations for the whole application
  • Estimated performance gain for annotated loops/functions when parallelized
Threading summary report
Save a Read-only Snapshot
A snapshot is a read-only copy of a project result, which you can view at any time using the
Intel Advisor
 GUI. To save an active project result as a read-only snapshot:
advisor --snapshot --project-dir=
<project-dir>
 [--cache-sources] [--cache-binaries] --
<snapshot-path>
where:
  • --cache-sources
     is an option to add application source code to the snapshot.
  • --cache-binaries
     is an option to add application binaries to the snapshot.
  • <snapshot-path
     is a path and a name for the snapshot. For example, if you specify
    /tmp/new_snapshot
    , a snapshot is saved in a
    tmp
     directory as
    new_snapshot.advixeexpz
    . You can skip this and save the snapshot to a current directory as
    snapshot
    XXX
    .advixeexpz
    .
To open the result snapshot in the
Intel Advisor
 GUI, you can run the following command:
advisor-gui
<snapshot-path>
You can visually compare the saved snapshot against the current active result or other snapshot results.

Next Steps

Continue to model threading results. For details about the metrics reported, see CPU and Memory Metrics.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.