
================================================================================
 Intel(R) Xeon Phi(TM) README_KNX_PRODUCT Performance Workloads:  micp
================================================================================
Version:  MPSSVERSION

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
may require enabled hardware, software or service activation. Learn more at
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.


================================================================================
 Table of Contents
================================================================================

  1. Requirements
    1.1   Intel(R) Parallel Studio XE requirements
    1.2   MATPLOTLIB requirements
    1.3   Memkind requirements
    1.4   Intel(R) MPI
    1.5   The fio benchmark

  2. Distributed Files

  3. RPM/DEB Installation

  4. Python Installation (optional)

  5. Python Uninstallation (optional)

================================================================================
1.   Requirements
================================================================================
--------------------------------------------------------------------------------
1.1  Intel(R) Parallel Studio XE Requirements
--------------------------------------------------------------------------------
Two options are available to fullfil the Intel(R) Parallel Studio XE
requirements. The first option is to install the full Intel(R) Parallel Studio
XE package and source the compilervars.sh or compilervars.csh script at run
time.

If the full installation of the software suite is not available, you can instead
install only the shared object libraries and Intel(R) Math Kernel Library
(Intel(R) MKL) Linpack benchmark packages. The required shared object libraries
can be installed via the Intel(R) Parallel Studio XE redistributable package,
freely distributed on the web here:

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

NOTE: It is important to use the version of Intel(R) Parallel Studio XE that is
      released in conjunction with the Intel(R) Xeon Phi(TM) processor software.

The Redistributable Libraries package contains the install.sh script for
installation. After installation, the compilervars.sh and compilervars.csh
scripts, which serve a similar purpose to the scripts in the full Intel(R)
Parallel Studio XE distribution, must be sourced at run time.

Besides the shared object libraries, the Intel(R) MKL Linpack benchmark is also
required. It is freely distributed on the web and can be downloaded from:

http://software.intel.com/en-us/articles/intel-math-kernel-library-
linpack-download

This download is a tarball that can be extracted anywhere. Once it is extracted
set the MKLROOT environment variable to point to the top level directory of
the extracted package. For example, if you extracted the tarball into your home
directory you should set MKLROOT as follows (in bash or bourne shell):

    [host]$ export MKLROOT=$HOME/l_mklb_p_<version>

Setting MKLROOT in the user's shell environment at run time allows micprun to
locate the linpack binaries.

NOTE: After extracting the tarball make sure the linpack binaries have the right
      execution permissions; you can change the permissions with the commands
      below:

    [host]$ cd ~/l_mklb_p_<version>/benchmarks_2017/linux/mkl/benchmarks/linpack
    [host]$ chmod +x xlinpack_xeon64
    [host]$ chmod +x xlinpack_mic
--------------------------------------------------------------------------------
1.2  MATPLOTLIB Requirements
--------------------------------------------------------------------------------
The micpplot and micprun applications use the MATPLOTLIB Python module to plot
performance statistics. The micprun application creates plots when the verbosity
setting is set to "2" or higher, and requires MATPLOTLIB for this use case.

MATPLOTLIB can be downloaded from http://matplotlib.sourceforge.net.

NOTE: If MATPLOTLIB is installed correctly but results are not plotted to the
      screen, visit http://matplotlib.org/users/customizing.html and refer to
      MATPLOTLIB's official documentation.

      Further details on configuring the MATPLOTLIB's backend can be found at
      http://matplotlib.org/faq/usage_faq.html#what-is-a-backend)
--------------------------------------------------------------------------------
1.3 memkind Requirements
--------------------------------------------------------------------------------
The memkind library is a user extensible heap manager, built on top of jemalloc,
which enables controlling memory characteristics and partitioning the heap
between kinds of memory. The kinds of memory are defined by the operating system
memory policies that were applied to virtual address ranges. Memory
characteristics supported by memkind without user extension include control of
NUMA and page size features. The jemalloc non-standard interface has been
extended to enable specialized arenas to make requests for virtual memory from
the operating system through the memkind partition interface. Through the other
memkind interfaces the user can control and extend memory partition features and
allocate memory while selecting the enabled features.

When the memory mode of the Intel(R) Xeon Phi(TM) processor is set to "Flat"
or "Hybrid" (refer to the BIOS Writer's Guide, IBL#545121 for more information
on how to switch between memory modes), some of the benchmarks shipped with
micperf use the memkind library to allocate high bandwidth memory and achieve
higher performance.

The processor software contains an rmp file with the memkind package.
Alternatively it can be compiled from source. Visit https://github.com/memkind/
memkind for further details.
--------------------------------------------------------------------------------
1.4 Intel(R) MPI
--------------------------------------------------------------------------------
Intel(R) MPI Library is a multi-fabric message passing library that implements
the Message Passing Interface 3.0 (MPI-3.0) specification. The library can be
used to develop applications that can run on multiple cluster interconnects.

The Intel(R) MPI Library has the following features:

    o Scalability up to 262k processes
    o Low overhead, enables analyzing large amounts of data
    o Intel(R) MPI tuning utility for accelerating your applications
    o Interconnect independence and flexible runtime fabric selection

There are two options to installing the Intel(R) MPI package:

    o Installing Intel(R) MPI Library
    o Installing free Intel(R) MPI Runtimes

Both packages can be downloaded by following the link below.

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

After installing Intel(R) MPI, source the mpivars.sh or the mpivars.csh to setup
all the environment variables required at runtime.
--------------------------------------------------------------------------------
1.5 The fio benchmark
--------------------------------------------------------------------------------
Fio (Flexible I/O Tester) is a versatile IO benchmark that was designed to
simulate a variety of cases that are useful when examining performance of write
and read operations. Miperf uses fio to estimate drive to core read bandwidth.

The fio benchmark binary is not provided as part of the micperf suite. It can be
installed using a standard package manager. Use one of the commands below to
install fio for your operating system:

   CentOS*/RRHEL*:
       [host]# yum install fio

   SLES*:
       [host]# zypper install fio

   Ubuntu*:
       [host]# apt install fio

The fio benchmark can also be installed manually. For details please visit
https://github.com/axboe/fio

================================================================================
2.  Distributed Files
================================================================================

The micperf package is distributed as a single RPM or DEB file:

    o micperf-<version>+xpps-<release>.x86_64.rpm
    o micperf-<version>+xpps-<release>.amd64.deb

The package also contains the reference performance measurements.

================================================================================
3.  Installation
================================================================================

To install micperf simply change to the directory where its RPM or DEB packages
are located and run:

   CentOS*/RHEL*
       [host]# yum install --nogpgcheck --noplugins --disablerepo=* \
       micperf-<version>+xpps-<release>.x86_64.rpm

   SLES:
       [host]# zypper --no-gpg-checks install \
       micperf-<version>+xpps-<release>.x86_64.rpm

   Ubuntu*:
       [host]# apt install micperf-<version>+xpps-<release>.amd64.deb

This installs files to the following directories:

   o Documentation and licenses:  /usr/share/doc/micperf
   o Benchmark binaries:          /usr/libexec/micperf
   o Reference data:              /usr/share/micperf/data

Source code is distributed in a corresponding sRPM file or a tar.gz archive, for
 further details please refer to the README.txt and the Micperf User's Guide.

================================================================================
4.  Python Installation (optional)
================================================================================

After installation, the micperf executable scripts (micprun, micpinfo, etc.)
will be present in the user's PATH. These executable scripts are based on a
Python package called micp, which is installed as a source distribution in
/usr/share/micperf/micp with symbolic links to the executable scripts in
/usr/bin. However, to compile and fully integrate the micp package into the
installed Python distribution, the user must install the source distribution
with Python's distutils. This can be done with the following commands:

    [host]$ cd /usr/share/micperf/micp
    [host]# python setup.py install --install-scripts /usr/local/bin

The advantages of this procedure are that the micp Python module will be
available to be imported by all Python users, and the package is compiled to
byte-code at installation time rather than being compiled at run time.

================================================================================
5. Python Uninstall (optional)
================================================================================

When setup.py is run as presented in the previous section, it installs the micp
package to /usr/local/bin and /usr/lib/pythonX.Y/site-packages/micp.

An intermediate product of running the setup.py install command is creation of
the /usr/share/micperf/micp/build directory.

None of the products of running setup.py will be removed by uninstalling
micperf. The installation with setup.py uses Python's distutils module, which
does not support uninstalling. However, it should be possible to uninstall it w
ith the following commands:

    [host]$ sitepackages=`sudo python -c \
    "from distutils.sysconfig import get_python_lib; print(get_python_lib())"`
    [host]# rm -rf /usr/share/micperf/micp /usr/local/bin/micpcsv \
    /usr/local/bin/micpinfo
    [host]# rm -rf /usr/local/bin/micpplot /usr/local/bin/micpprint \
    /usr/local/bin/micprun
    [host]# rm -rf ${sitepackages}/micp ${sitepackages}/micp-<version>
