User Guide

Contents

Analyze MPI Applications

With
Intel® Advisor
, you can analyze parallel tasks running on a cluster to examine performance of your MPI application. Use the Intel® MPI
gtool
with
mpiexec
or
mpirun
to invoke the
advisor
command and spawn MPI processes across the cluster.
You can analyze MPI applications
only
through the command line interface, but you can view the result through the standalone GUI, as well as the command line.

Tips

Consider the following when running collections for an MPI application:
  • Analysis data can be saved to a shared partition or to local directories on the cluster.
  • Only one processes' data can be viewed at a time.
  • Intel® Advisor
    saves collection results into a subdirectory under the
    Intel Advisor
    project directory. If you wish to collect and then view (in a separate session) data for more than one process, specify a new project directory when running new collection.
  • Specify one and the same project directory when running various
    Intel Advisor
    collections for the selected process.

MPI Implementations Support

You can use the
Intel Advisor
with the
Intel® MPI Library
and other MPI implementations, but be aware of the following details:
  • You may need to adjust the command examples in this section to work for non-Intel MPI implementations. For example, adjust commands provided for process ranks to limit the number of processes in the job.
  • An MPI implementation needs to operate in cases when there is the
    Intel Advisor
    process (
    advisor
    ) between the launcher process (
    mpiexec
    ) and the application process. This means that the communication information should be passed using environment variables, as most MPI implementations do.
    Intel Advisor
    does not work on an MPI implementation that tries to pass communication information from its immediate parent process.

Get Intel® MPI Library Commands

You can use
Intel Advisor
to generate the command line for collecting results on multiple MPI ranks. To do that,
  1. In
    Intel Advisor
    user interface, go to
    Project Properties
    >
    Analysis Target
    tab and select the analysis you want to generate the command line for. For example, go to
    Survey Analysis Types
    >
    Survey Hotspots Analysis
    to generate command line for the Survey analysis.
  2. Set properties to configure the analysis, if required.
  3. Select the
    Use MPI Launcher
    checkbox.
  4. Specify the MPI run parameters, ranks to profile, if required (for Intel MPI Library only), then copy the command line from
    Get command line
    text box to your clipboard.

Intel® MPI Library Command Syntax

Use the
-gtool
option of
mpiexec
with Intel® MPI Library 5.0.2 and higher:
$ mpiexec –gtool "advisor --collect=<analysis-type> --project-dir=<project-dir>:<ranks-set>" -n <N> <application-name> [myApplication-options]
where:
  • <analysis-type>
    is one of the
    Intel Advisor
    analyses:
    • survey
      runs the target process and collects basic information about the hotspots.
    • tripcounts
      collects data on the loop trip counts.
    • dependencies
      collects information possible dependencies in your application, requires one of the following:
      • Loop ID(s) as an additional parameter (
        -mark-up-list=<loop-ID>
        ). Find the loop ID in the Survey report (
        --report=survey
        ) or using the
        Command Line
        link in the
        Intel® Advisor
        GUI
        Workflow tab
        .
      • Loop source location(s) in the format
        file1
        :
        line1
      • Annotations in the source code
    • map
      collects information about memory access patterns for the selected loops. Also requires loop
      IDs
      or
      source locations
      for the analysis.
    • suitability
      checks suitability of the parallel site that you want to insert into your target application. Requires
      annotations
      to be added into the source code of your application, and also requires recompilation in Debug mode.
    • projection
      models your application performance on an accelerator.
  • <ranks-set>
    is the set of MPI ranks to run the analysis for. Separate ranks with a comma, or use a dash "-" to set a range of ranks. Use
    all
    to analyze all the ranks.
  • <N>
    is the number of MPI processes to launch.
gtool
option of
mpiexec
allows you to select MPI ranks to run analyses for. This can decrease overhead.

Generic MPI Command Syntax

Use
mpiexec
with the
advisor
command to spawn processes across the cluster and collect data about the application.
Each process has a rank associated with it. This rank is used to identify the result data.
To collect performance or dependencies data for an MPI program with
Intel Advisor
, the general form of the
mpiexec
command is:
$ mpiexec -n <N> "advisor --collect=<analysis-type> --project-dir=<project-dir> --search-dir src:r=<source-dir>" myApplication [myApplication-options]
where:
  • <N>
    is the number of MPI processes to launch.
  • <project-dir>
    specifies the path/name of the project directory.
  • <analysis_type>
    is
    survey
    ,
    tripcounts
    ,
    map
    ,
    suitability
    ,
    dependencies
    , or
    projection
    .
  • <source-dir>
    is the path to the directory where annotated sources are stored.
This command profiles all MPI ranks.
For details about analyzing the MPI application with the Offload Modeling perspective of the
Intel Advisor
, see Model MPI Application Performance on GPU.

Control Collection with an MPI_Pcontrol Function

By default,
Intel Advisor
analyzes performance of a whole application. In some cases, you may want to focus on the most time consuming section or disable collection for the initialization or finalization phases.
Intel Advisor
supports the MPI region control with the
MPI_Pcontrol()
function. This function allows you to enable and disable collection for specific application regions in the source code.
The region control affects only MPI and OpenMP* metrics, while the other metrics are collected for the entire application.
To use the function, add it to the your application source code as follows:
  • To pause data collection, add
    MPI_Pcontrol(0)
    before the code region that you want to disable the collection for.
  • To resume data collection, add
    MPI_Pcontrol(1)
    where you want the collection to start again.
  • To skip the initialization phase:
    1. Add the
      MPI_Pcontrol(1)
      function right after initialization. Build the application.
    2. Run the desired
      Intel Advisor
      analyses with the
      --start-paused
      option.
According to the MPI standard,
MPI_Pcontrol()
accepts other numbers as arguments. For the
Intel Advisor
, only the
0
and
1
are relevant.
You can also use
MPI_Pcontrol()
to mark specific code regions. Use
MPI_Pcontrol(
<region>
)
at the beginning of the region, and
MPI_Pcontrol(
-
<region>
)
at the end of the region, where
<region>
is 5 and higher.

View Results

As a result of collection,
Intel Advisor
creates a number of result directories in the directory specified with
--project-dir
. The nested result directories are named as
rank.0, rank.1, ... rank.n
, where the numeric suffix
n
corresponds to the MPI process rank.
To view the performance or dependency results collected for a specific rank, you can either open a result project file (
*.advixeproj
) that resides in the
--project-dir
via the
Intel Advisor
GUI, or run the
Intel Advisor
CLI report:
$ advisor --report=<analysis-type> --project-dir=<project-dir>:<ranks-set>
You can view only one rank's results at a time.
For
Offload Modeling
,
you do not need to run the
--report
command. The
reports are generated automatically after you run performance modeling. See Model MPI Application Performance on GPU for details.

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://software.intel.com/content/www/us/en/develop/tools/mpi-library/get-started.html
Hybrid applications:
Intel MPI Library
and OpenMP* on the
Intel Developer Zone
at https://software.intel.com/content/www/us/en/develop/articles/hybrid-applications-intelmpi-openmp.html

Product and Performance Information

1

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