================================================================================
 Intel(R) Xeon Phi(TM) micperf frequently asked questions
================================================================================

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
Intel technologies' features and benefits depend on system configuration and
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 is a quick reference to answer some common micperf questions, and
omits in-depth details. For more information, please see micperf README, micperf
INSTALL, micperf User's Guide, Intel(R) Xeon Phi(TM) Processor Software User's
Guide, and micperf built-in help accessed with the command “micprun --help”,
“micpcsv --help”, “micpplot --help”, etc.

This document covers the micperf package released for the Intel(R) Xeon Phi(TM)
product family.

00. What is micperf?

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

02. Which kernels and workloads are included in micperf?

03. Why do I need to install Intel(R) Parallel Studio XE to run the micperf
    kernels and 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) Parallel Studio XE redistributable libraries
    do I need to install?

07. How do I install the Intel(R) Parallel Studio XE redistributable libraries?

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

09. What are Intel(R) Math Kernel Library (Intel(R) MKL) benchmarks?

10. How do I install Intel(R) Math Kernel Library (Intel(R) 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 my command line
    arguments are ignored by micprun and micpplot, is this a bug?

14. What is a micperf 'pickle' file?

15. I ran different kernels and workloads using micprun and collected
    performance data. How do I know my system performance is good?

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

00. What is micperf?

    There are many benchmarks which can be used with the processor to measure
    performance. These have different developers, and consequently different
    user interfaces, methods of execution and outputs. Micperf is designed to
    incorporate a variety of benchmarks into a user-friendly single interface
    for execution and 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 are importable into a variety of other applications,
    allowing users to easily compare results of different runs.


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

    The micperf installation procedure conforms to Linux* conventions. After
    installing the micperf package, the documentation can be found in:

        /usr/share/doc/micperf/


02. Which kernels and workloads are included in micperf?

    The following kernels/workloads are included in the micperf package:
        o SGEMM
        o DGEMM
        o STREAM
        o DeepBench convolutions

    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 Intel(R) MKL benchmarks, however, they
    are not included in the package and must be installed separately. Please
    refer to questions 7 and 8 for additional information.

    Micperf can be used to run the following Intel(R) MKL benchmarks once
    they're installed:

        o SMP Linpack
        o Fio
        o HPL
        o HPCG


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

    IMPORTANT note: you do not need to purchase Intel(R) Parallel Studio XE to
    use micperf. You can alternatively install the freely available runtime
    libraries. Refer to question 5 for details.

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


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

    IMPORTANT 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 5 for details.

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

    Each of these packages provides all libraries required to run the micperf
    kernels. Intel(R) Parallel Studio XE 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?

    Purchase is not necessary. You can install the freely available Intel(R)
    Parallel Studio XE redistributable libraries and the Intel(R) MKL Benchmarks
    package:

    https://software.intel.com/en-us/articles/redistributables-for-intel-
parallel-studio-xe-2017-composer-edition-for-linux
    https://software.intel.com/en-us/articles/intel-mkl-benchmarks-suite

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


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

    There are two 'flavors' of the Intel(R) Parallel Studio XE 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
    Fortan package.

    Notice that the packages are versioned: RTM is the initial release and
    Update 1, Update 2, etc. are the consecutive releases. We recommend
    installing the most recent version.


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

    Download the corresponding tarball from the link in question 4, unpack the
    archive and change to the created directory.

    Instructions below launch the installers in "silent" mode. For interactive
    mode, launch the executables without added arguments.

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

    Where:
      -e automatically accepts the license agreement's terms and conditions.
      -i <install path> specifies the software's target install directory.
         Please note that depending on the <install path>, you may need to run
         the installer as root.


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

    Make sure you sourced the compilervars.sh file:

        $ source <libraries 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
    in the new window to set the environment variables.


09. What are the Intel(R) MKL benchmarks?

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


10. How do I install the Intel(R) MKL benchmarks?

    NOTE: If you use Intel(R) Parallel Studio XE, you DO NOT need to install the
    Intel(R) MKL benchmark package and the procedure below can be omitted. Don’t
    forget to source compilervars.sh before using micperf.

    For micperf to execute Intel(R) MKL benchmarks, first download the tarball
    from the following website:

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

    Extract the downloaded file to your preferred directory, e.g. HOME. Let's
    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:

            $ export MKLROOT=$HOME/l_mkl_VERSION


    NOTE: Environment variables set this way are only valid in the current
    terminal or command window session. If a terminal or commmand window is
    closed or a new one is opened, MKLROOT must be set again.


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

    The following two kernels require Intel(R) MPI:
        o STREAM in the SNC-4 mode
        o HPCG

    Intel(R) MPI is part of 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 component only needed if you plan to plot micprun
    results using micpplot or micprun plotting capabilities. For more info,
    visit http://matplotlib.org/.


13. I installed matplotlib but I cannot create plots, or micprun and micpplot
    ignore 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
    cases, 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 used to serialize objects. Micperf uses this
    module to create 'pickle' files for storing performance results 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 and workloads using micprun and collected
    performance data. How do I know my system performance is good?

    The micperf package includes a set of reference 'pickle' files. These pickle
    files represent measurements from Intel's reference systems. These pickle
    files can be inspected and compared to user-generated pickle files using the
    micperf tools. For more details, refer to the –R command line option in the
    built-in help, accessed by micprun --help, micpcsv --help, micpplot --help,
    micpinfo --help, etc.


