------------------------------------------
Intel(R) Advisor XE
MPI Sample Application
README
------------------------------------------

Introduction
------------------------------------------

This is the README file for the mpi sample application written using the C++ programming language. It explains how to open, build, and run this sample application using the Intel(R) Advisor XE 2015. This sample contains MPI code and assumes the mpiicpc compiler is in the PATH.

Acquiring the Sample Application
------------------------------------------

Copy the mpi_sample.tgz from the <INSTALL_DIR>/samples/en/C++ directory to a writable directory or share on your system. Extract the sample.

Running a Survey Analysis
------------------------------------------

Build the release version of the serial sample with the following command: make 1_mpi_sample_serial 

Run a Survey analysis of the application using a command line similar to the following:

mpirun -n 4 advixe-cl -collect survey --project-dir ./survey -- ./1_mpi_sample_serial 100000000

This command line will use 4 mpi processes and save the results in a directory named "survey" in the current working directory.

Import the results from one of the ranks into a new project using the command line. For example:

advixe-cl -project-dir ./survey_project -import-dir ./survey -search-dir src:=../mpi_sample -mpi-rank=3

The directory specified by the "src" argument is the location of the sample source code. This command will analyze rank number 3 from the results collected and create a project in the directory "survey_project" in the current working directory.

Create a Survey report via the command line:

advixe-cl -project-dir ./survey_project -report survey

Notice the loop in the main function of the application. This loop is a good candidate for OpenMP parallelism. Examine the code for possible sites to add annotations. The file mpi_sample_annotated.cpp has annotations and comments added.

Running a Suitability Analysis
------------------------------------------

Build the release version of the annotated sample with the following command: make 2_mpi_sample_annotated 

Note: The Makefile requires that the ADVISOR_XE_2015_DIR environment variable is set to the install directory of the Intel Advisor XE. This environment variable can be set by running the Intel Advisor XE setup script <install-dir>/advixe-vars.sh.

Run a Suitability analysis of the application using a command line similar to the following:

mpirun -n 4 advixe-cl -collect suitability --project-dir ./suitability -- ./2_mpi_sample_annotated 100000000

This command line will use 4 mpi processes and save the results in a directory named "suitability" in the current working directory.

Import the results from one of the ranks into a new project using the command line. For example:

advixe-cl -project-dir ./suitability_project -import-dir ./suitability -search-dir src:=../mpi_sample -mpi-rank=3

The directory specified by the "src" argument is the location of the sample source code. This command will analyze rank number 3 from the results collected and create a project in the directory "suitability_project" in the current working directory.

Create a Suitability report via the command line:

advixe-cl -project-dir ./suitability_project -report suitability


The annotated application appears to scale well.

Running a Dependencies Analysis
------------------------------------------

Build the debug version of the annotated sample with the following command: make 2_mpi_sample_annotated_debug 

Note: The Makefile requires that the ADVISOR_XE_2015_DIR environment variable is set to the install directory of the Intel Advisor XE. This environment variable can be set by running the Intel Advisor XE setup script <install-dir>/advixe-vars.sh.

Run a Dependencies Analysis of the application using a command line similar to the following:

mpirun -n 4 advixe-cl -collect correctness --project-dir ./correctness -- ./2_mpi_sample_annotated_debug 1000000

This command line will use 4 mpi processes and save the results in a directory named "correctness" in the current working directory. Notice that the application argument has been decreased to 1000000 to decrease the runtime of the analysis.

Import the results from one of the ranks into a new project using the command line. For example:

advixe-cl -project-dir ./correctness_project -import-dir ./correctness -search-dir src:=../mpi_sample -mpi-rank=3

The directory specified by the "src" argument is the location of the sample source code. This command will analyze rank number 3 from the results collected and create a project in the directory "correctness_project" in the current working directory.

Create a Correctness report via the command line:

advixe-cl -project-dir ./correctness_project -report correctness

Correctness reports 1 Data communication problems in the annotated application. Follow the comments in the file mpi_sample_annotated.cpp to fix the correctness issue. Once you have fixed the issues, rebuild the application and run the analysis again. 

Adding Parallelism
------------------------------------------
The file mpi_sample_omp.cpp has OpenMP pragmas in place of the annotations. Build debug or release versions of this application with the following commands:
make 3_mpi_sample_omp
make 3_mpi_sample_omp_debug

Run these applications to see how the performance improves over the serial version.

Conclusion
------------------------------------------

You have successfully followed the Intel Advisor XE Workflow to parallelize a MPI program.

Feel free to experiment with the tool using your own MPI programs.

Please contact us if you have any feedback or questions at http://software.intel.com/en-us/articles/intel-software-developer-support/


Legal Information
------------------------------------------

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. 

UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR. 

Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information. 

The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or go to: http://www.intel.com/design/literature.htm 

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. Go to: http://www.intel.com/products/processor_number/

BlueMoon, BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Cilk, Core Inside, E-GOLD, i960, Intel, the Intel logo, Intel AppUp, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Insider, the Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel StrataFlash, Intel vPro, Intel XScale, InTru, the InTru logo, the InTru Inside logo, InTru soundmark, Itanium, Itanium Inside, MCS, MMX, Moblin, Pentium, Pentium Inside, Puma, skoool, the skoool logo, SMARTi, Sound Mark, The Creators Project, The Journey Inside, Thunderbolt, Ultrabook, vPro Inside, VTune, Xeon, Xeon Inside, X-GOLD, XMM, X-PMU and XPOSYS are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Microsoft, Windows, Visual Studio, Visual C++, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries. 

Copyright (C) 2017, Intel Corporation. All rights reserved. 

