
================================================================================
 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 (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/ (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) Composer XE Requirements
    1.2   MATPLOTLIB Requirements
    1.3   memkind Requirements (Only for the Intel(R) Xeon Phi(TM) Processor X200 Product Family)
    1.4   Intel(R) MPI
    1.5   fio benchmark

  2. Distributed Files

  3. RPM Installation

  4. Python Installation (optional)

  5. Python Uninstallation (optional)

================================================================================
1.   Requirements
================================================================================

1.1  Intel(R) Composer XE Requirements

There are two options to installing the Intel(R) Composer XE requirements.
The first option is to install the full Intel(R) Composer XE package and source
the compilervars.sh or compilervars.csh script at run time.

If the full composer installation is not available, you can instead choose to install
only the shared object libraries and MKL Linpack benchmark packages. The required
shared object libraries can be installed via the Intel(R) Composer 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) Composer that is
      released in conjunction with the Intel(R) MPSS or Intel(R) Xeon Phi(TM)
      Processor Software. For the version MPSSVERSION for Linux*, use Intel(R) Composer
      version l_comp_lib_2017.1.132_comp.cpp_redist.tgz.

This 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) Composer XE distribution, must be sourced at
run time.

Besides the shared object libraries, the 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):

    $ export MKLROOT=$HOME/l_mklb_p_2017.2.015

Setting MKLROOT in the user's shell environment at run time allows micprun to locate
the linpack binaries. Note that the version of linpack linked above may be newer
than 2017.2.015, and the MKLROOT variable should reflect that.

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

    $ cd $HOME/l_mklb_p_2017.2.015/benchmarks_2017/linux/mkl/benchmarks/linpack
    $ chmod +x xlinpack_xeon64
    $ 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 only creates plots when verbosity
is set to two or higher, and only requires MATPLOTLIB for this use case.
MATPLOTLIB must be installed in order to create plots. It can be downloaded from
http://matplotlib.sourceforge.net.

NOTE: If MATPLOTLIB is installed correctly but results are not plotted to the screen,
      please refer to the MATPLOTLIB official documentation, available at
      http://matplotlib.org/users/customizing.html. To get further details on how
      to configure the MATPLOTLIB's backend visit http://matplotlib.org/faq/usage_faq.html#what-is-a-backend)


1.3 memkind Requirements (Only for the Intel(R) Xeon Phi(TM) Processor X200 Product Family)

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 in the Intel(R) Xeon Phi(TM) Processor X200 is set to "Flat"
or "Hybrid" mode (Refer to the BIOS Writer's Guide, IBL#545121 for more information
on how to change between memory modes), some of the benchmarks shipped with
micperf use the memkind library to allocate high bandwidth memory and achieve
higher performance.

memkind is distributed as an rpm file within the processor software 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 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 from 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 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:

   For CentOS or Red Hat Enterprise Linux:
       $ sudo yum install fio
   For SUSE Linux:
       $ sudo zypper 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:

    o xppsl-micperf-VERSION-BUILDNUMBER.x86_64.rpm for the processor.

    o mpss-micperf-VERSION-BUILDNUMBER.x86_64.rpm for the coprocessor.

The package also contains the reference performance measurements.


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

To install the RPM files simply change to the directory where the micperf RPMs
are located and run:

    o Red Hat* Enterprise Linux**
    $ sudo yum install --nogpgcheck --noplugins --disablerepo=* *.rpm

    o SUSE* Linux** Enterprise Server
    $ sudo zypper --no-gpg-checks install *.rpm

This installs files to the following directories:

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

Source code is distributed in the corresponding micperf source RPM, 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:

    $ cd /usr/share/micperf/micp
    $ sudo 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 "setup.py install" is the creation of
the /usr/share/micperf/micp/build directory.

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

    $ sitepackages=`sudo python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"`
    $ sudo rm -rf /usr/share/micperf/micp /usr/local/bin/micpcsv /usr/local/bin/micpinfo
    $ sudo rm -rf /usr/local/bin/micpplot /usr/local/bin/micpprint /usr/local/bin/micprun
    $ sudo rm -rf ${sitepackages}/micp ${sigepackages}/micp-MPSSVERSION
