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. The script enables the
advisor
command line interface (CLI).
In the commands below, the options in square brackets (
[--
<option>
]
) are recommended if you want to change what data is collected.

Run
Threading
Perspective

  1. Run the Survey analysis:
    advisor --collect=survey --project-dir=
    <project-dir>
    --
    <target-application>
    [
    <target-options>
    ]
  2. Run the Characterization analysis to collect trip counts and/or FLOP data:
    advisor --collect=tripcounts --project-dir=
    <project-dir>
    [--flop] [--stacks] --
    <target-application>
    [
    <target-options>
    ]
    where:
    • --flop
      is an option to collect data about floating-point and integer operations, memory traffic, and mask utilization metrics for AVX-512 platforms.
    • --stacks
      is an option to enable advanced collection of callstack data.
  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.
  5. Run the Suitability analysis for the annotated loops/functions:
    advisor --collect=suitability --project-dir=
    <project-dir>
    --
    <target-application>
    [
    <target-options>
    ]
  6. Run the Dependencies analysis to check for loop-carried dependencies in the annotated loops:
    advisor --collect=dependencies --project-dir=
    <project-dir>
    [--filter-reductions] --
    <target-application>
    [
    <target-options>
    ]
    where:
    • --filter-reductions
      is an option to mark all potential reductions with a specific diagnostic.
Example
Run the Survey, Trip Counts, Suitability, and Dependencies analyses assuming you have annotated the loops.
advisor --collect=survey --project-dir=./advi -- myApplication
advisor --collect=tripcounts --project-dir=./advi --flop --stacks -- myApplication
advisor --collect=suitability --project-dir=./advi -– myApplication
advisor --collect=dependencies --project-dir=./advi --filter-reductions -– myApplication

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.
Run the following command:
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.
For example, to generate the Suitability report for the OpenMP* threading model:
advisor --report=suitability --project-dir=./advi -–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-survey.txt
located at
<project-dir>
/e
NNN
/hs
NNN
.
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 CPU and Memory Metrics for more information about the metrics reported.
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.