Intel® Advisor User Guide

Download PDF
ID 766448
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
Intel® Advisor User Guide
Intel® Advisor User Guide x
Introduction Install and Launch Intel® Advisor Set Up Project Analyze Vectorization Perspective Analyze CPU Roofline Model Threading Designs Model Offloading to a GPU Analyze GPU Roofline Design and Analyze Flow Graphs Minimize Analysis Overhead Analyze MPI Applications Manage Results Command Line Interface Troubleshooting Reference Appendix
Introduction x
Design and Optimization Methodology Tutorials and Samples Get Help and Support
Install and Launch Intel® Advisor x
Install Intel® Advisor Set Up Environment Variables Set Up System to Analyze GPU Kernels Set Up Environment to Offload SYCL, OpenMP* target, and OpenCL™ Applications to CPU Launch Intel® Advisor GUI Navigation Quick Start
Set Up Project x
Configure Target Application Build Target Application Create Project
Configure Target Application x
Limit the Number of Threads Used by Parallel Frameworks Choose a Small, Representative Data Set
Create Project x
Configure Project Configure Binary/Symbol Search Directories Configure Source Search Directory Binary/Symbol Search and Source Search Locations
Analyze Vectorization Perspective x
Run Vectorization and Code Insights Perspective from GUI Run Vectorization and Code Insights Perspective from Command Line Explore Vectorization and Code Insights Results
Run Vectorization and Code Insights Perspective from GUI x
Vectorization Accuracy Presets Customize Vectorization and Code Insights Perspective
Run Vectorization and Code Insights Perspective from Command Line x
Vectorization Accuracy Levels in Command Line
Explore Vectorization and Code Insights Results x
Vectorization Report Overview Examine Not-Vectorized and Under-Vectorized Loops Analyze Loop Call Count Investigate Memory Usage and Traffic Find Data Dependencies
Analyze CPU Roofline x
Run CPU / Memory Roofline Insights Perspective from GUI Run CPU / Memory Roofline Insights Perspective from Command Line Explore CPU/Memory Roofline Results
Run CPU / Memory Roofline Insights Perspective from GUI x
CPU Roofline Accuracy Presets Customize CPU / Memory Roofline Insights Perspective
Run CPU / Memory Roofline Insights Perspective from Command Line x
CPU Roofline Accuracy Levels in Command Line
Explore CPU/Memory Roofline Results x
CPU Roofline Report Overview Examine Bottlenecks on CPU Roofline Chart Examine Relationships Between Memory Levels Compare CPU Roofline Results
Model Threading Designs x
Run Threading Perspective from GUI Run Threading Perspective from Command Line Annotate Code for Deeper Analysis Explore Threading Results Model Threading Parallelism Check for Dependencies Issues Add Parallelism to Your Program
Run Threading Perspective from GUI x
Customize Threading Perspective
Run Threading Perspective from Command Line x
Threading Accuracy Levels in Command Line
Annotate Code for Deeper Analysis x
Annotate Code to Model Parallelism Annotations Annotation Report
Annotate Code to Model Parallelism x
Before Annotating Code for Deeper Analysis Use Amdahl's Law and Measure the Program Task Organization and Annotations Annotate Parallel Sites and Tasks Task Patterns Choose the Tasks Use Partially Parallel Programs with Intel® Advisor
Task Patterns x
Multiple Parallel Sites Data and Task Parallelism Mix and Match Tasks
Choose the Tasks x
Task Interactions and Suitability How Big Should a Task Be?
Annotations x
Annotation Types Annotation Definitions Files Add Annotations into Your Source Code Tips for Annotation Use with C/C++ Programs
Annotation Types x
Annotation Types Summary Annotation General Characteristics Site and Task Annotations for Simple Loops With One Task Site and Task Annotations for Parallel Sites with Multiple Tasks Lock Annotations Pause Collection and Resume Collection Annotations Special-purpose Annotations
Annotation Definitions Files x
Reference the Annotations Definitions Directory Include the Annotations Header File in C/C++ Sources
Add Annotations into Your Source Code x
Copy Annotations and Build Settings Using the Annotation Assistant Pane Insert Annotations in a Text Editor
Tips for Annotation Use with C/C++ Programs x
Control the Expansion of advisor-annotate.h Handle Compilation Issues that Appear After Adding advisor-annotate.h
Annotation Report x
Annotation Report, Clear Description of Storage Row Annotation Report, Disable Observations in Region Row Annotation Report, Pause Collection Row Annotation Report, Inductive Expression Row Annotation Report, Lock Row Annotation Report, Observe Uses Row Annotation Report, Reduction Row Annotation Report, Re-enable Observations at End of Region Row Annotation Report, Resume Collection Row Annotation Report, Site Row Annotation Report, Task Row Annotation Report, User Memory Allocator Use Row Annotation Report, User Memory Deallocator Use Row
Model Threading Parallelism x
Suitability Report Overview Choose Modeling Parameters in the Suitability Report Fix Annotation-related Errors Detected by the Suitability Tool Advanced Modeling Options Reduce Parallel Overhead, Lock Contention, and Enable Chunking
Reduce Parallel Overhead, Lock Contention, and Enable Chunking x
Reduce Site Overhead Reduce Task Overhead Reduce Lock Overhead Reduce Lock Contention Enable Task Chunking
Check for Dependencies Issues x
Code Locations Pane Filter Pane (Dependencies Report) Problems and Messages Pane Dependencies Source Window
Dependencies Source Window x
Code Locations Pane (Dependencies Source Window) Focus Code Location Pane Focus Code Location Call Stack Pane Related Code Locations Pane Related Code Location Call Stack Pane Relationship Diagram Pane
Add Parallelism to Your Program x
Before You Add Parallelism: Choose a Parallel Framework Add the Parallel Framework to Your Build Environment Annotation Report Replace Annotations with Intel® oneAPI Threading Building Blocks (oneTBB) Code Replace Annotations with OpenMP* Code Next Steps for the Parallel Program
Before You Add Parallelism: Choose a Parallel Framework x
Parallel Frameworks Intel® oneAPI Threading Building Blocks (oneTBB) OpenMP* Microsoft Task Parallel Library* (TPL) Other Parallel Frameworks
Add the Parallel Framework to Your Build Environment x
Enable Intel® oneAPI Threading Building Blocks (oneTBB) in your Build Environment Define the TBBROOT Environment Variable Enable C++11 Lambda Expression Support with Intel® oneAPI Threading Building Blocks (oneTBB) Enable OpenMP* in your Build Environment
Annotation Report x
Annotation Report Overview Locate Annotations with the Annotation Report
Replace Annotations with Intel® oneAPI Threading Building Blocks (oneTBB) Code x
Intel® oneAPI Threading Building Blocks (oneTBB) Mutexes Intel® oneAPI Threading Building Blocks (oneTBB) Simple Mutex - Example Test the Intel® oneAPI Threading Building Blocks (oneTBB) Synchronization Code Parallelize Functions - Intel® oneAPI Threading Building Blocks (oneTBB) Tasks Parallelize Data - Intel® oneAPI Threading Building Blocks (oneTBB) Counted Loops Parallelize Data - Intel® oneAPI Threading Building Blocks (oneTBB) Loops with Complex Iteration Control
Replace Annotations with OpenMP* Code x
Add OpenMP Code to Synchronize the Shared Resources OpenMP Critical Sections Basic OpenMP Atomic Operations Advanced OpenMP Atomic Operations OpenMP Reduction Operations OpenMP Locks Test the OpenMP Synchronization Code Parallelize Functions - OpenMP Tasks Parallelize Data - OpenMP Counted Loops Parallelize Data - OpenMP Loops with Complex Iteration Control
Next Steps for the Parallel Program x
Use Intel® Inspector and Intel® VTune™ Profiler Debug Parallel Programs
Model Offloading to a GPU x
Run Offload Modeling Perspective from GUI Run Offload Modeling Perspective from Command Line Explore Offload Modeling Results Advanced Modeling Configuration
Run Offload Modeling Perspective from GUI x
Offload Modeling Accuracy Presets Customize Offload Modeling Perspective
Run Offload Modeling Perspective from Command Line x
Offload Modeling Accuracy Levels in Command Line Run GPU-to-GPU Performance Modeling from Command Line
Explore Offload Modeling Results x
Offload Modeling Report Overview Examine Regions Recommended for Offloading Examine Data Transfers for Modeled Regions Check for Dependency Issues Explore Performance Gain from GPU-to-GPU Modeling Investigate Non-Offloaded Code Regions
Advanced Modeling Configuration x
Model Application Performance on a Custom Target GPU Device Check How Assumed Dependencies Affect Modeling Manage Invocation Taxes Enforce Offloading for Specific Loops
Analyze GPU Roofline x
Test Topic for Embedded Help Run GPU Roofline Insights Perspective from GUI Run GPU Roofline Insights Perspective from Command Line Explore GPU Roofline Results
Run GPU Roofline Insights Perspective from GUI x
GPU Roofline Accuracy Presets Customize GPU Roofline Insights Perspective
Run GPU Roofline Insights Perspective from Command Line x
GPU Roofline Accuracy Levels in Command Line
Explore GPU Roofline Results x
Examine GPU Roofline Summary Examine Bottlenecks on GPU Roofline Chart Examine Kernel Details Compare GPU Roofline Results
Design and Analyze Flow Graphs x
Where to Find the Flow Graph Analyzer Launching the Flow Graph Analyzer Flow Graph Analyzer GUI Overview Flow Graph Analyzer Workflows Designer Workflow Generating C++ Stubs Preferences Scalability Analysis Collecting Traces from Applications Nested Parallelism in Flow Graph Analyzer Analyzer Workflow Experimental Support for OpenMP* Applications Sample Trace Files Additional Resources
Flow Graph Analyzer GUI Overview x
Menus Toolbars Tabs Main Canvas Charts
Designer Workflow x
Adding Nodes, Edges, and Ports Modifying Node Properties Viewing Edge Properties Validating a Graph Saving a Graph to a File
Scalability Analysis x
Activating the Graph Scalability Analysis Prerequisites Running the Scalability Analysis Exploring the Parallelism in a Concurrent Node Showing Non-Parallel Nature of a Serial Node Explore Parallelism Provided by the Topology of a Graph Understanding Analysis Color Codes
Scalability Analysis Prerequisites x
Setting Concurrency Specification Setting Data Count Setting Node Weight
Collecting Traces from Applications x
Building an Application for Trace Collection Collecting Trace Files
Building an Application for Trace Collection x
Building an Application on Windows* OS Building an Application on Linux* OS Building an Application on macOS*
Collecting Trace Files x
Collect Traces In the Flow Graph Analyzer GUI Collect Traces Outside the Flow Graph Analyzer GUI
Collect Traces Outside the Flow Graph Analyzer GUI x
Collecting Trace Files with fgtrun Script Collecting Trace Files without fgtrun Script
Analyzer Workflow x
Find Time Regions of Low Concurrency and Their Cause Finding a Critical Path Finding Tasks with Small Durations Reduce Scheduler Overhead using Lightweight Policy Identifying Tasks that Operate on Common Input Support for SYCL
Support for SYCL x
Collect SYCL Application Traces Examine a SYCL Application Graph Find Issues Using Static Rule-check Engine
Examine a SYCL Application Graph x
Hotspot View View Performance Inefficiencies of Data-parallel Constructs
Find Issues Using Static Rule-check Engine x
Issue: Const Reference to a Host Pointer Used to Initialize a Buffer Issue: Host Pointer Accessor Used in a Loop Issue: Data Parallel Construct Inefficiency
Experimental Support for OpenMP* Applications x
Collecting Traces for OpenMP* Applications OpenMP* Constructs in the Per-Thread Task View OpenMP* Constructs in the Graph Canvas
Sample Trace Files x
code_generation Samples performance_analysis Samples
Minimize Analysis Overhead x
Collection Controls to Minimize Analysis Overhead Loop Markup to Minimize Analysis Overhead Filtering to Minimize Analysis Overhead Execution Speed/Duration/Scope Properties to Minimize Analysis Overhead Miscellaneous Techniques to Minimize Analysis Overhead
Analyze MPI Applications x
Get Preconfigured Command Lines Use Intel® MPI Library Analyze a Single Rank of MPI Application with Intel MPI Library Analyze Multiple Ranks of MPI Application with Intel MPI Library Use Non-Intel MPI Library Analyze an MPI Application with Non-Intel MPI Library View Results Additional MPI Resources See Also Model MPI Application Performance on GPU Control Collection with an MPI_Pcontrol Function
Manage Results x
Open a Result Rename an Existing Result Delete a Result Save Results to a Custom Location Work with Standalone HTML Reports Create a Read-only Result Snapshot Create a Result Snapshot Dialog Box
Command Line Interface x
advisor Command Line Interface Reference Offload Modeling Command Line Reference Generate Pre-configured Command Lines
advisor Command Line Interface Reference x
advisor Command Action Reference advisor Command Option Reference
advisor Command Action Reference x
collect command create-project help import-dir mark-up-loops report snapshot version workflow
advisor Command Option Reference x
accuracy append app-working-dir assume-dependencies assume-hide-taxes assume-ndim-dependency assume-single-data-transfer auto-finalize batching benchmarks-sync bottom-up cache-binaries cache-binaries-mode cache-config cache-simulation cache-sources cachesim cachesim-associativity cachesim-cacheline-size cachesim-mode cachesim-sampling-factor cachesim-sets check-profitability clear config count-logical-instructions count-memory-instructions count-memory-objects-accesses count-mov-instructions count-send-latency cpu-scale-factor csv-delimiter custom-config data-limit data-reuse-analysis data-transfer data-transfer-histogram data-transfer-page-size data-type delete-tripcounts disable-fp64-math-optimization display-callstack dry-run duration dynamic enable-cache-simulation enable-data-transfer-analysis enable-task-chunking enforce-baseline-decomposition enforce-fallback enforce-offloads estimate-max-speedup evaluate-min-speedup exclude-files executable-of-interest exp-dir filter filter-by-scope filter-reductions flop force-32bit-arithmetics force-64bit-arithmetics format gpu gpu-carm gpu-kernel-of-interest gpu-sampling-interval hide-data-transfer-tax ignore ignore-app-mismatch ignore-checksums instance-of-interest integrated interval limit loop-call-count-limit loop-filter-threshold loops mark-up mark-up-list memory-level memory-operation-type mix mkl-user-mode model-baseline-gpu model-children model-extended-math model-system-calls module-filter module-filter-mode mpi-rank mrte-mode ndim-depth-limit option-file overlap-taxes pack profile-gpu profile-intel-perf-libs profile-jit profile-python profile-stripped-binaries project-dir quiet recalculate-time record-mem-allocations record-stack-frame reduce-lock-contention reduce-lock-overhead reduce-site-overhead reduce-task-overhead refinalize-survey remove report-output report-template result-dir resume-after return-app-exitcode search-dir search-n-dim select set-dependency set-parallel set-parameter show-all-columns show-all-rows show-functions show-loops show-not-executed show-report small-node-filter sort-asc sort-desc spill-analysis stack-access-granularity stack-stitching stack-unwind-limit stacks stackwalk-mode start-paused static-instruction-mix strategy support-multi-isa-binaries target-device target-gpu target-pid target-process target-system threading-model threads top-down trace-mode trace-mpi track-memory-objects track-stack-accesses track-stack-variables trip-counts verbose with-stack
Offload Modeling Command Line Reference x
run_oa.py Options collect.py Options analyze.py Options
Troubleshooting x
Error Message: Application Sets Its Own Handler for Signal Error Message: Cannot Collect GPU Hardware Metrics for the Selected GPU Adapter Error Message: Memory Model Cache Hierarchy Incompatible Error Message: No Annotations Found Error Message: No Data Is Collected Error Message: Stack Size Is Too Small Error Message: Undefined Linker References to dlopen or dlsym Problem: Broken Call Tree Problem: Code Region is not Marked Up Problem: Debug Information Not Available Problem: No Data Problem: Source Not Available Problem: Stack in the Top-Down Tree Window Is Incorrect Problem: Survey Tool does not Display Survey Report Problem: Unexpected C/C++ Compilation Errors After Adding Annotations Problem: Unexpected Unmatched Annotations in the Dependencies Report Warning: Analysis of Debug Build Warning: Analysis of Release Build
Reference x
Data Reference Dependencies Problem and Message Types Recommendation Reference User Interface Reference
Data Reference x
CPU Metrics Accelerator Metrics
Dependencies Problem and Message Types x
Dangling Lock Data Communication Data Communication, Child Task Inconsistent Lock Use Lock Hierarchy Violation Memory Reuse Memory Reuse, Child Task Memory Watch Missing End Site Missing End Task Missing Start Site Missing Start Task No Tasks in Parallel Site One Task Instance in Parallel Site Orphaned Task Parallel Site Information Thread Information Unhandled Application Exception
Recommendation Reference x
Vectorization Recommendations for C++ Vectorization Recommendations for Fortran
User Interface Reference x
Dialog Box: Corresponding Command Line Dialog Box: Create a Project Dialog Box: Create a Result Snapshot Dialog Box: Options - Assembly Editor Tab Dialog Box: Options - General Dialog Box: Options - Result Location Dialog Box: Project Properties - Analysis Target Dialog Box: Project Properties - Binary/Symbol Search Dialog Box: Project Properties - Source Search Pane: Advanced View Pane: Analysis Workflow Pane: Roofline Chart Pane: GPU Roofline Chart Project Navigator Pane Toolbar: Intel Advisor Annotation Report Window: Dependencies Source Window: GPU Roofline Regions Window: GPU Roofline Insights Summary Window: Memory Access Patterns Source Window: Offload Modeling Summary Window: Offload Modeling Report - Accelerated Regions Window: Perspective Selector Window: Refinement Reports Window: Suitability Report Window: Suitability Source Window: Survey Report Window: Survey Source Window: Threading Summary Window: Vectorization Summary
Window: Refinement Reports x
Tab: Dependencies Report Tab: Memory Access Patterns Report
Appendix x
Data Sharing Problems Notational Conventions Key Concepts Related Information
Data Sharing Problems x
Data Sharing Problem Types Problem Solving Strategies
Data Sharing Problem Types x
Incidental Sharing Independent Updates
Problem Solving Strategies x
Eliminate Incidental Sharing Synchronize Independent Updates Difficult Problems: Choosing a Different Set of Tasks Fix Problems in Code Used by Multiple Parallel Sites Memory That is Accessed Through a Pointer
Eliminate Incidental Sharing x
Examine the Task's Static and Dynamic Extent Verify Whether Incidental Sharing Exists Create the Private Memory Location Pointer Dereferences
Synchronize Independent Updates x
Synchronization Explicit Locking Assign Locks to Transactions Pitfalls from Using Synchronization
Key Concepts x
Glossary Parallelism
Parallelism x
Parallel Processing Terminology Add Parallelism Common Issues When Adding Parallelism Parallel Programming Implementations
Intel® Advisor User Guide

Analyze MPI Applications

With Intel® Advisor, you can analyze parallel tasks running on a cluster to examine performance of your MPI application.

To start MPI jobs, use an MPI launcher such as mpirun, mpiexec, srun, aprun. You can use the Intel Advisor with the Intel® MPI Library or other MPI implementations only through the command line interface, but you can view the result using the standalone GUI, as well as the command line. The examples provided in this section use mpirun with the advisor command line interface (CLI) to spawn processes across the cluster and collect data about the application.

NOTE:
Use the MPI implementation that passes communication information using environment variables. The implementation needs to operate with the Intel Advisor process (advisor) being between the launcher process and the application process. Intel Advisor does not work on an MPI implementation that tries to pass communication information from its immediate parent process.

To analyze your MPI application:

  1. Prerequisite: Set up environment variables to enable Intel Advisor CLI.
  2. Optional: Get pre-configured command lines.
  3. Run Intel Advisor analyses with one of the following:
  4. View the results.

You can analyze your application as one of the following:

  • If you have a directory shared between remote and local systems: Collect data remotely to the shared directory. In this case, you do not need to move a project between the systems.
  • If you do not have a shared directory: Collect data to a directory on a remote system (for example, on a cluster), generate a snapshot (optionally), and copy the snapshot or a project to your local system to view the result. If you generate a snapshot, you do not need to configure the search paths for a project.

Get Preconfigured Command Lines

You can generate pre-configured command lines for collecting results for the Intel MPI Library launcher or a custom launcher using Intel Advisor graphical user interface (GUI). In this case, you do not need to type each command with all options and paths to a project directory and an application executable manually.

See Generate Command Lines for details.

Use Intel® MPI Library

With the Intel MPI Library, you can analyze a single MPI rank or several ranks of your MPI application with the Intel Advisor. This can help you to decrease analysis overhead.

Recommended MPI ranks to analyze are rank 1 and higher, because rank 0 might include time for configuration and not be a good representative for the general MPI application performance.

MPI Command Syntax

To collect performance data for an MPI application with Intel Advisor using the mpirun launcher of the Intel MPI Library, use the following command syntax:

mpirun -gtool "advisor --collect=<analysis-type> --search-dir src:r=<source-dir> [--no-auto-finalize] --project-dir=<project-dir>:<rank-set>" -n <N><application-name> [<application-options>]

where:

  • -gtool allows you to run Intel Advisor analyses for the specified MPI ranks only. This option is available for Intel MPI Library 5.0.2 or higher.
  • <analysis-type> is an Intel Advisor analysis to run: survey, tripcounts, map. dependencies, projection.
  • <source-dir> is the path to the directory where application sources are stored. Specify it if you disabled autofinalization.
  • <project-dir> is the path/name of the project directory where the analysis results are saved. Specify the same project directory when running various Intel Advisor collections for the selected process.
  • <ranks-set> is a set of MPI ranks to analyze. Each rank corresponds to an MPI process and is used to identify the result data. Separate ranks with a comma or use a dash " - " to set a range of ranks. Use with -gtool option only. Do not specify if you want to analyze all ranks.
  • <N> is the number of MPI processes to launch.
  • --no-auto-finalize disables result finalization on the target system to decrease overhead. The results are finalized when you import them or open in Intel Advisor GUI. Do not use this option if you do not use a shared directory and plan to copy results from cluster with snapshot. See Temporarily Disable Finalization for details.

Analyze a Single Rank of MPI Application with Intel MPI Library

Prerequisite: Set up environment variables to enable Intel Advisor CLI.

In the commands below:

  • Data is collected remotely to a shared directory.
  • The analyses are performed for an application running in four processes.
  • Path to an application executable is ./mpi_sample.

    Note: In the commands below, make sure to replace the application path and name before executing a command. If your application requires additional command line options, add them after the executable name.

  • Path to an Intel Advisor project directory is ./advi_results.

This example shows how to run a Survey, Trip Counts, and Roofline analyses for the rank 1 of the MPI application with the gtool option of the Intel MPI Library.

  1. Collect survey data for rank 1 into the shared ./advi_results project directory on a target system. 
    mpirun -gtool "advisor --collect=survey --project-dir=./advi_results:1" -n 4 ./mpi_sample
  2. Run the Trip Counts analysis with FLOP collection for rank 1 on the target system. 
    mpirun -gtool "advisor --collect=tripcounts --flop --project-dir=./advi_results:1" -n 4 ./mpi_sample

    After you collect the Survey, Trip Counts, and FLOP data, you also get the Roofline report for your application.

  3. If you did not collect data to a shared location and need to copy the data to the local system to view the results, do it now.
  4. On the local system, view the results with your preferred method. You can view only one process data at a time.

Analyze Multiple Ranks of MPI Application with Intel MPI Library

Prerequisite: Set up environment variables to enable Intel Advisor CLI.

In the commands below:

  • Data is collected remotely to a shared directory.
  • The analyses are performed for an application running in four processes.
  • Path to an application executable is ./mpi_sample.

    Note: In the commands below, make sure to replace the application path and name before executing a command. If your application requires additional command line options, add them after the executable name.

  • Path to an Intel Advisor project directory is ./advi_results.

Analyze a Set of Ranks

This example shows how to run a Survey, Trip Counts, and Roofline analyses for a set of ranks of the MPI application with the gtool option of the Intel MPI Library.

  1. Collect survey data for ranks 1, 2, and 4 into the shared ./advi_results project directory on a target system. 
    mpirun -gtool "advisor --collect=survey --project-dir=./advi_results:1-2,4" -n 4 ./mpi_sample
  2. Run the Trip Counts analysis with FLOP collection for ranks 1, 2, and 4 on a target system. 
    mpirun -gtool "advisor --collect=tripcounts --flop --project-dir=./advi_results:1-2,4" -n 4./mpi_sample

    After you collect the Survey, Trip Counts, and FLOP data, you also get the Roofline report for your application.

  3. If you did not collect data to a shared location and need to copy the data to the local system to view the results, do it now.
  4. On the local system, view the results with your preferred method. You can view only one process data at a time.

Analyze All Ranks

This example shows how to run a Survey, Trip Counts, and Roofline analyses for all ranks of the MPI application with the gtool option of the Intel MPI Library.

  1. Collect survey data for all ranks into the shared ./advi_results project directory on a target system. 
    mpirun -gtool "advisor --collect=survey --project-dir=./advi_results" -n 4 ./mpi_sample
  2. Run the Trip Counts analysis with FLOP collection for all ranks on a target system. 
    mpirun -gtool "advisor --collect=tripcounts --flop --project-dir=./advi_results" -n 4./mpi_sample

    After you collect the Survey, Trip Counts, and FLOP data, you also get the Roofline report for your application.

  3. If you did not collect data to a shared location and need to copy the data to the local system to view the results, do it now.
  4. On the local system, view the results with your preferred method. You can view only one process data at a time.

Use Non-Intel MPI Library

With non-Intel MPI library implementation, you can only analyze all ranks of your MPI application with Intel Advisor. This might increase analysis overhead.

MPI Command Syntax

To collect performance data for an MPI application with Intel Advisor using the mpirun launcher, use the following command syntax:

mpirun -n <N> "advisor --collect=<analysis-type> --search-dir src:r=<source-dir>--trace-mpi [--no-auto-finalize] --project-dir=<project-dir>" <application-name> [<application-options>]

where:

  • <N> is the number of MPI processes to launch.
  • <analysis-type> is an Intel Advisor analysis to run: survey, tripcounts, map. dependencies, projection.
  • <source-dir> is the path to the directory where application sources are stored. Specify it if you disabled autofinalization.
  • <project-dir> is the path/name of the project directory where the analysis results are saved. Specify the same project directory when running various Intel Advisor collections for the selected process.
  • --trace-mpi enables analyzing non-Intel MPI library implementations. This option is required for non-Intel MPI implementation.
  • --no-auto-finalize disables result finalization on the target system to decrease overhead. The results are finalized when you import them or open in Intel Advisor GUI. Do not use this option if you do not use a shared directory and plan to copy results from cluster with snapshot. See Temporarily Disable Finalization for details.

Analyze an MPI Application with Non-Intel MPI Library

Prerequisite: Set up environment variables to enable Intel Advisor CLI.

In the commands below:

  • Data is collected remotely to a shared directory.
  • The analyses are performed for an application running in four processes.
  • Path to an application executable is ./mpi_sample.

    Note: In the commands below, make sure to replace the application path and name before executing a command. If your application requires additional command line options, add them after the executable name.

  • Path to an Intel Advisor project directory is ./advi_results.

This example shows how to run a Survey, Trip Counts, and Roofline analyses for all 4 ranks of the MPI application.

  1. Collect survey data for all ranks into the shared ./advi_results project directory on a target system. 
    mpirun -n 4 "advisor --collect=survey --project-dir=./advi_results"./mpi_sample
  2. Run the Trip Counts analysis with FLOP collection on the target system. 
    mpirun -n 4 "advisor --collect=tripcounts --flop --project-dir=./advi_results" ./mpi_sample

    After you collect the Survey, Trip Counts, and FLOP data, you also get the Roofline report for your application.

  3. If you did not collect data to a shared location and need to copy the data to the local system to view the results, do it now.
  4. On the local system, view the results with your preferred method. You can view only one process data at a time.
NOTE:
For all analysis types and MPI libraries: When using a shared partition on Windows* OS, specify the network paths to the project and executable location or use the MPI options mapall or map to specify these locations on the network drive.

For example:

mpiexec -gwdir \\<host1>\mpi -hosts 2 <host1> 1 <host2> 1 advisor --collect=survey --project-dir=\\<host1>\mpi\advi_results -- \\<host1>\mpi\mpi_sample.exe

advisor --import-dir=\\<host1>\mpi\advi_results --project-dir=\\<host1>\mpi\new_advi_results --search-dir src:=\\<host1>\mpi --mpi-rank=1

advisor --report=survey --project-dir=\\<host1>\mpi\new_advi_results

or:

mpiexec -mapall -gwdir z:\ -hosts 2 <host1> 1 <host2> 1 advisor --collect=survey --project-dir=z:\advi_results -- z:\mpi_sample.exe

or:

mpiexec -map z:\\<host1>\mpi -gwdir z:\ -hosts 2 <host1> 1 <host2> 1 advisor --collect=survey --project-dir=z:\advi_results -- z:\mpi_sample.exe

View Results

Intel Advisor saves collection results into subdirectories for each rank analyzed under the project directory specified with --project-dir. The subdirectories are named as rank.<n> , where the numeric suffix <n> corresponds to an MPI rank analyzed. You can only view results for one rank at a time.

To view the performance results collected for a specific rank, you can do one of the following.

View Results in GUI

From the Intel Advisor GUI, open a result project file *.advixeproj that resides in the <project-dir> /rank.<n> directory.

You can also open the GUI from command line: 

advisor-gui ./advi_results/rank.1
NOTE:
If you used --no-auto-finalize when collecting data, make sure to set paths to application binaries and sources before viewing the result so that Intel Advisor can finalize it properly.

View Results in Command Line

Run the Intel Advisor --report action to print the result summary in a terminal:

advisor --report=<analysis-type> --project-dir=<project-dir> --mpi-rank=<n>

where:

  • <analysis-type> is the Intel Advisor analysis you want to print the results for.
  • <project-dir> is the same project directory as you used for data collection.
  • <n> is the number of MPI rank you want to view results for.

View Results in a File

You can save results for a specified rank to a TXT, CSV, or a XML file. For example, save the results to a advisor_result.csv file, run the following command:

advisor --report=<analysis-type> --format=csv --report-output=advisor_result.csv --project-dir=<project-dir> --mpi-rank=<n>

where:

  • <analysis-type> is the Intel Advisor analysis you want to print the results for.
  • <project-dir> is the same project directory as you used for data collection.
  • <n> is the number of MPI rank you want to view results for.
  • --format specified the file format to save the results to. In the command above, it is CSV.

Additional MPI Resources

For more details on analyzing MPI applications, see the Intel MPI Library and online MPI documentation on the Intel® Developer Zone at https://www.intel.com/content/www/us/en/developer/tools/oneapi/mpi-library.html

For detailed syntax, refer to the Intel® MPI Library Developer Reference for Linux* OS or Intel® MPI Library Developer Reference for Windows* OS.

Hybrid applications: Intel MPI Library and OpenMP* on the Intel Developer Zone at https://www.intel.com/content/www/us/en/developer/articles/technical/hybrid-applications-mpi-openmp.html

Parent topic: Intel® Advisor User Guide

See Also

Level Two Title