-----------------
MKL Optimizations
-----------------

Developed specifically for science, engineering, and financial computations, 
Intel™ Math Kernel Library (MKL) is a set of threaded and vectorized math 
routines that work to accelerate various math functions and applications. 
Continuum has packaged MKL-powered binary versions of some of the most popular 
numerical/scientific Python libraries into MKL Optimizations for improved 
performance.

MKL Optimizations includes:
 * Speed-boosted NumPy, SciPy, scikit-learn, and NumExpr
 * The packaging of MKL with redistributable binaries in Anaconda for easy access to the MKL runtime library.
 * Python bindings to the low level MKL service functions, which allow for the modification of the number of threads being used during runtime.

Included Packages
-----------------

`Packages upgraded to use MKL <http://software.intel.com/en-us/articles/intel-math-kernel-library-documentation>`_
 * `NumPy <http://docs.scipy.org/doc/>`_
 * `NumExpr <http://code.google.com/p/numexpr/>`_
 * `SciPy <http://docs.scipy.org/doc/scipy/reference/>`_
 * `Scikit-Learn <http://scikit-learn.org/stable/user_guide.html>`_

.. toctree::
   :maxdepth: 1

   ../mkl-service/index

Installation
------------

In Anaconda versions 2.5 and later, MKL is `freely available by default in Anaconda 
<https://www.continuum.io/blog/developer-blog/anaconda-25-release-now-mkl-optimizations>`_.

If you already have the free `Anaconda <http://continuum.io/downloads.html>`_ 
Python distribution installed, get MKL by upgrading to the latest version::

    conda update conda
    conda update anaconda

If you do not have Anaconda installed, you can download it
`here <http://continuum.io/downloads.html>`_.

Existing MKL licenses can be viewed and removed with the 
graphical Anaconda Navigator license manager or manually with your 
operating system. For more information please see the 
:doc:`License installation </anaconda/license-installation>` page.

Configuration
-------------

Anaconda now also includes a small utility package called 
`mkl-service <../mkl-service/>`_ which provides a Python interface to some 
useful MKL functions that are declared in ``mkl_service.h``, such as setting 
the number of threads to use.

Uninstalling MKL
----------------

MKL takes roughly 100MB and some use cases do not need it, so users can opt out 
of MKL and instead use `OpenBLAS <http://www.openblas.net/>`_ for Linux or the 
native Accelerate Framework for MacOSX. To opt out, run ``conda install nomkl`` 
and then use ``conda install`` to install packages that would normally include 
MKL or depend on packages that include MKL, such as ``scipy``, ``numpy``, and 
``pandas``. Conda will install the non-MKL versions of these packages together 
with their dependencies. If you are using OS X or Linux, have already installed 
these packages or already installed all of Anaconda, and wish to switch away 
from MKL, use the command ``conda install nomkl numpy scipy scikit-learn numexpr`` 
followed by ``conda remove mkl mkl-service``.

Updating
--------

If you already have the free Anaconda Python distribution installed and wish to update MKL::

    conda update conda
    conda update mkl

Dismissing MKL Trial warnings
-----------------------------

Because past versions of Anaconda did not include MKL linked binaries by default, 
some users who have used ``conda update --all`` may see an MKL Trial warning or 
a license expiration error, even though MKL linked packages are now free and 
installed by default. A license expiration error message may read, "You cannot 
run MKL without a license any longer."

To resolve this, set your installation to use the mkl-linked libraries that do not require a license::

  conda remove mkl-rt
  conda install -f mkl

Then run conda install with the specific packages you choose::

  conda install numpy scipy scikit-learn numexpr

or with all of Anaconda::

  conda install anaconda

Resolving MKL shared library "permission denied" errors
-------------------------------------------------------

On Linux platforms that have SELinux enabled, you may encounter security errors like the following::

  error while loading shared libraries: <libmkl_intel.so>: cannot restore segment prot after reloc: Permission denied

This is because MKL requires text relocation permissions, which SELinux denies by default. This prevents MKL from being loaded by Numpy, preventing Numpy from being imported.  

There are two known solutions to this issue:

1. Does not require root privileges. Replace MKL with OpenBLAS by issuing the command::

     conda install nomkl numpy scipy scikit-learn numexpr

   You may revert back to the MKL default versions at any time by using::

     conda remove nomkl
     conda install mkl

2. Requires root privileges. Temporarily disable SELinux enforcement. From a root-privileged terminal enter::

     /usr/sbin/setenforce 0

   NOTE: If you prefer to make this change permanent, in the file ``/etc/selinux/config`` change "enforcing" to "disabled" and then reboot.

License Agreement
-----------------

The MKL Optimizations are included in the free Anaconda python distribution, and have been made available by the terms of the :doc:`../anaconda/eula`.

Past versions of MKL Optimizations were not freely available in Anaconda, and have been made available separately by the terms of the :doc:`eula`.

.. toctree::
   :hidden:

   eula
