
================================================================================
 Intel(R) Xeon Phi(TM) micperf Frequently Asked Questions
================================================================================
Version:  1.5.3

Disclaimer and Legal Information:

You may not use or facilitate the use of this document in connection with
any infringement or other legal analysis concerning Intel products described
herein. You agree to grant Intel a non-exclusive, royalty-free license to
any patent claim thereafter drafted which includes subject matter disclosed
herein.

No license (express or implied, by estoppel or otherwise) to any intellectual
property rights is granted by this document.
All information provided here is subject to change without notice. Contact your
Intel representative to obtain the latest Intel product specifications and
roadmaps. The products described 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.

Copies of documents which have an order number and are referenced in this
document may be obtained by calling 1-800-548-4725 or by visiting:
http://www.intel.com/design/literature.htm (http://www.intel.com/design/literature.htm)
Intel technologies' features and benefits depend on system configuration and
http://www.intel.com/ (http://www.intel.com/) or from the OEM or retailer.
No computer system can be absolutely secure.
Intel, Xeon, Xeon Phi and the Intel logo 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.

Copyright 2012-2017, Intel Corporation, All Rights Reserved.


================================================================================
 Contents
================================================================================

This document aims to provide answers for some of the most common question
about micperf, many details were intentionally omitted as this document is
intended to provide quick reference. For more information, please see the micperf
README, micperf INSTALL, micperf User's Guide, MPSS User's Guide, MPSS REAMDE and
micperf built-in help, which can be accessed by running micprun --help,
micpcsv --help, micpplot --help, etc.

Information in this document covers the micperf package that is released for
the Intel(R) Xeon Phi(TM) Processor X200 Product Family (hereby referred to as
the processor) and the Intel(R) Xeon Phi(TM) Coprocessor X200 Product Family
(hereby referred to as the coprocessor).

00. What is micperf?

01. Where do I find the micperf README and INSTALL?

02. Which kernels/workloads are included in micperf?

03. Why do I need to install Intel(R) Parallel Studio XE to run the micperf
    kernels/workloads?

04. Which version of Intel(R) Parallel Studio XE do I need to install?

05. Do I need to buy Intel(R) Parallel Studio XE to use micperf?

06. Which version of the Intel(R) Composer redistributable libraries do I need to
    install?

07. How do I install the Intel(R) Composer redistributable libraries?

08. I installed the Intel(R) Composer redistributable libraries but I still
    get error messages and I'm unable to execute workloads using micprun,
    what am I missing?

09. What are the MKL benchmarks?

10. How do I install the MKL benchmarks?

11. Do I need to install Intel(R) MPI?

12. Do I need to install matplotlib?

13. I installed matplotlib but I cannot create any plots or micprun/micpplot
    simply ignores my command line arguments, is this a bug?

14. What is a micperf 'pickle' file?

15. I ran different kernels/workloads using micprun and got some (performance)
    data points, how do know if my system is performing well?

16. I installed MPSS-4, the coprocessor is online but I'm unable to execute the
    micperf kernels. I get an error about micprun being unable to establish an
    SSH connection with the coprocessor, what's wrong?

17. What's an "offload method"? *Only for the coprocessor.

================================================================================

00. What is micperf?

    There are many benchmarks which can be used with the processor or the coprocessor
    to measure performance. These have different developers, and consequently
    different user interfaces, different methods of execution and different
    output. Micperf is designed to incorporate a variety of benchmarks into a
    simple user experience with a single interface for execution and a unified
    means of data inspection.  The user interface to micperf consists of five
    executables: one for execution of benchmarks (micprun), and four that
    interpret the output of the first one.  These executables are all well
    documented with standard UNIX style command line interfaces. The results can
    be displayed as professional quality plots, human readable text or comma
    separated values that can be easily imported into a variety of other
    applications. Results of different runs can be easily combined and compared.


01. Where do I find the micperf README and INSTALL?

    The micperf installation procedure conforms to Linux* conventions, after installing
    the micperf RPM the documentation can be found in:

        /usr/share/doc/micperf-<VERSION>/


02. Which kernels/workloads are included in micperf?

    The following kernels/workloads are included in the micperf package:
        o SGEMM
        o DGEMM
        o STREAM
        o DEEPBENCH convolutions *Only for the processor
        o SHOC Download *Only for the coprocessor.
        o SHOC Readback *Only for the coprocessor.

    For further details about these kernels/workloads please refer to the micperf
    Users' Guide and the micperf README.

    micperf can also be used to execute the Intel MKL benchmarks, however, they
    are not included in the package and should be installed separately. Please refer
    to questions 7 and 8 for additional information.

    micperf can be used to run the following MKL benchmarks once they're installed:

        o SMP Linpack
        o Fio           *Only for the processor.
        o HPL           *Only for the processor.
        o HPCG          *Only for the processor.


03. Why do I need to install Intel(R) Parallel Studio XE to run the micperf
    kernels/workloads?

    Micperf kernels were compiled with the Intel(R) Compiler and linked to the
    Intel(R) Math Kernel Library (MKL) for maximum performance. At runtime micperf
    requires access to functions and symbols provided by the Intel(R) Composer
    and the Intel(R) MKL libraries (e.g. libiomp5.so, libmkl_ao_worker.so).
    Thus to be able to execute the micperf workloads the Intel(R) Composer and
    the MKL libraries should be installed.


04. Which version of Intel(R) Parallel Studio XE do I need to install?

    IMPORTANT: Please note you DO NOT need to buy Intel(R) Parallel Studio XE to
    use micperf, you can alternatively install the freely available runtime libraries.
    Refer to question 4 for details.

    There are different versions of the Intel(R) Parallel Studio XE available:
        o Composer Edition
        o Professional Edition
        o Cluster Edition

    Any of these packages provide all libraries required to run the micperf
    kernels. Intel(R) Parallel Studio can be purchased at:

        https://software.intel.com/en-us/intel-parallel-studio-xe.


05. Do I need to buy Intel(R) Parallel Studio XE to use micperf?

    It is not necessary to buy Intel(R) Parallel Studio XE. You can install the
    freely available Intel(R) Composer redistributable libraries and the Intel(R)
    MKL benchmark package:
        o Linux*   https://software.intel.com/en-us/articles/redistributables-for-intel-parallel-studio-xe-2017-composer-edition-for-linux
        o Windows* https://software.intel.com/en-us/articles/redistributables-for-intel-parallel-studio-xe-2017-composer-edition-for-windows
        o https://software.intel.com/en-us/articles/intel-mkl-benchmarks-suite

    Please refer to the micperf INSTALL and questions 6 and 7 for details on
    how to install these packages.


06. Which version of the Intel(R) Composer redistributable libraries do I need to
    install?

    There are two 'flavors' of the Intel(R) Composer redistributable libraries,
    the C++ libraries and the Fortran libraries. To use micperf there's no need
    to install both, you can choose to install either the C++ or the Fortan package.

    It is also important to notice that the packages are versioned: RTM is the
    initial release and Update 1, Update 2, ... , Update N are the consecutive updates.
    It is recommended to install the most recent version.


07. How do I install the Intel(R) Composer re-distributable libraries?

    Download the corresponding tarball (Linux*) or zip (Windows*) from the link in
    question 4, unpack the tarball/zip in your preferred directory and cd into
    the created directory.

    Instructions below will launch the installer in "silent" mode, for the
    interactive mode execute the command without the command line arguments.

    On Linux*

        $ ./install.sh -e -i <install path>

    Where:
      -e automatically accepts the terms and conditions of the license agreement
      -i <install path> specifies the directory where the software will be installed.
         Please note that depending on the <install path> you may need to run installer
         as root.

    On Windows*, use the msi file to install the libraries in the Command Prompt:

        > ww_icl_redist_msi_2017.0.109.msi /quiet /qn


08. I installed the Intel(R) Composer redistributable libraries but I still
    get error messages and I'm unable to execute workloads using micprun,
    what am I missing?

    On Linux* make sure to source the compilervars.sh file:

        $ source <composer install path>/bin/compilervars.sh intel64

    compilervars.sh defines a set of environment variables that micperf uses to
    find required binaries and libraries at runtime, for instance LD_LIBRARY_PATH,
    MIC_LD_LIBRARY_PATH, etc. Such environment variables are only valid in the
    terminal where compilervars.sh was sourced, if this terminal is closed or a
    new one is opened compilervars.sh must be sourced one more time to set the
    environment variables.

    On Windows*, when the Intel(R) Composer redistributable libraries are installed
    the PATH is automatically updated to include all the directories where the
    libraries are installed.


09. What are the MKL benchmarks?

    The Intel(R) MKL Benchmarks include: Intel(R) Optimized LINPACK Benchmark,
    Intel(R) Optimized MP LINPACK Benchmark for Clusters, and Intel(R) Optimized
    High Performance Conjugate Gradient Benchmark.


10. How do I install the MKL benchmarks?

    NOTE: If you're using Intel(R) Parallel Studio XE you DO NOT need to install
          the MKL benchmarks package and the procedure below can be omitted, just
          make sure to source compilervars.sh before using micperf.

    For micperf to execute the MKL benchmarks, first download the tarball (Linux*)
    or zip (Windows*) from the following website:

    https://software.intel.com/en-us/articles/intel-mkl-benchmarks-suite

    Extract the downloaded file to your preferred directory, for instance $HOME (Linux*)
    or %HOMEDRIVE%%HOMEPATH% (Windows*). Let's also assume the directory where we
    unpacked the Intel(R) MKL benchmarks is called l_mkl_VERSION. Finally we should
    inform micperf where the benchmarks are located. To do this use the MKLROOT
    environment variable:

        On Linux*:
            $ export MKLROOT=$HOME/l_mkl_VERSION

        On Windows*:
            > set MKLROOT=%HOMEDRIVE%%HOMEPATH%\l_mkl_VERSION

    NOTE: Environment variables set this way are only valid in the current
          terminal or command line prompt, if such terminal/commmand line prompt
          is closed or a new one is open MKLROOT has to be set again.


11. Do I need to install Intel(R) MPI?

    The following two kernels require Intel(R) MPI:
        o STREAM in the SCN-4 mode *Only for the processor
        o HPCG *Only for the processor

    Intel(R) MPI is part of the Intel(R) Parallel Studio XE Cluster Edition, alternatively
    the Intel(R) MPI runtimes are freely available for download here:

        https://software.intel.com/en-us/intel-mpi-library

    After installing the runtimes it is necessary to source mpivars.sh before
    using micprun.


12. Do I need to install matplotlib?

    matplotlib is an optional requirement, only needed if you're planning to use
    micpplot or micprun capabilities to plot micprun results. Visit http://matplotlib.org/
    for more information.


13. I installed matplotlib but I cannot create any plots or micprun/micpplot
    simply ignores my command line arguments, is this a bug?

    Please make sure the matplotlib backend is configured correctly for your
    environment. The default backend should work fine but we have observed that
    some backends might not work when X Server is not running (no GUI), in such
    case a different backend should be selected either by modifying your matplotlibrc
    or by setting the MPLBACKEND environment variable. For more information please
    refer to:

        http://matplotlib.org/faq/usage_faq.html#what-is-a-backend


14. What is a micperf 'pickle' file?

    Pickle is a python module that can be used to serialize objects, micperf uses
    this module to create 'pickle' files where performance results are stored for
    future reference. 'pickle' files can be inspected and compared using the
    following micperf tools: micpinfo, micpcsv, micpprint and micpplot.


15. I ran different kernels/workloads using micprun and got some (performance)
    data points, how do know if my system is performing well?

    The micperf package includes a set of reference 'pickle' files. These pickle
    files represent the measurements run on Intel's reference systems, as any
    other pickle file they can be inspected and compared with the user-generated
    pickle files using the micperf tools. Please refer to the built-in
    help e.g. micprun --help, micpcsv --help, micpplot --help, micpinfo --help
    for further details. In particular look for the -R command line option.


16. I installed MPSS 4, the coprocessor is online but I'm unable to execute the
    micperf kernels. I get an error about micprun being unable to establish an
    SSH connection with the coprocessor, what's wrong?

    Please make sure you can ssh the coprocessor (without a password) by using
    its name (micN). For example:
        # ssh mic0

    Also make sure that:

        o You created a set of SSH keys and passed those keys to the coprocessor.
        o You added the hostname and IP address of the coprocessor to /etc/hosts

    For additional information please refer to the MPSS user's guide and the MPSS
    README.


17. What's an "offload method"? *Only for the coprocessor

    Benchmarking the coprocessor differs from benchmarking other platforms due
    to the fact that it runs an independent Linux* OS communicating with the host
    system across the PCIe bus. As the name "coprocessor" implies, the use model
    is to offload work from the host system. There are several offload methods
    and one of the important features of micperf is the ability to compare their
    performance characteristics on the same benchmark.
