mkl_random -- a NumPy-based Python interface to Intel® oneAPI Math Kernel Library (OneMKL) Random Number Generation functionality

mkl_random started as a part of Intel® Distribution for Python optimizations to NumPy.

Per NumPy's community suggestions, voiced in https://github.com/numpy/numpy/pull/8209, it is being released as a stand-alone package.

Prebuilt mkl_random can be installed into conda environment from Intel's channel using:

  conda install -c https://software.repos.intel.com/python/conda mkl_random

or from conda forge channel:

   conda install -c conda-forge mkl_random

To install mkl_random PyPI package please use following command:

   python -m pip install -i https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_random

If command above installs NumPy package from the Pypi, please use following command to install Intel optimized NumPy wheel package from Intel Pypi Cloud:

   python -m pip install -i https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_random numpy==<numpy_version>

Where <numpy_version> should be the latest version from https://software.repos.intel.com/python/conda/

mkl_random is not fixed-seed backward compatible drop-in replacement for numpy.random, meaning that it implements sampling from the same distributions as numpy.random.

For distributions directly supported in Intel® OneMKL, method keyword is supported:

   mkl_random.standard_normal(size=(10**5, 10**3), method='BoxMuller')

Additionally, mkl_random exposes different basic random number generation algorithms available in MKL. For example to use SFMT19937 use

   mkl_random.RandomState(77777, brng='SFMT19937')

For generator families, such that MT2203 and Wichmann-Hill, a particular member of the family can be chosen by specifying brng=('WH', 3), etc.

The list of supported by mkl_random.RandomState constructor brng keywords is as follows:

• 'MT19937'
• 'SFMT19937'
• 'WH' or ('WH', id)
• 'MT2203' or ('MT2203', id)
• 'MCG31'
• 'R250'
• 'MRG32K3A'
• 'MCG59'
• 'PHILOX4X32X10'
• 'NONDETERM'
• 'ARS5'

Patching Mechanisms

mkl_random provides convenient patch methods to enable MKL-accelerated random operations in NumPy with or without modifying your code.

CLI Quickstart

Persistent patch (all Python sessions)

# Install
python -m mkl_random --patch install

# Status (exit code: 0 = installed, 1 = not installed)
python -m mkl_random --patch status

# Remove
python -m mkl_random --patch uninstall

Verify current random backend

python -c "import numpy; print(f'numpy.random.normal.__module__: {numpy.random.normal.__module__}')"

One-shot patch (single command only)

# Script
python -m mkl_random --with-numpy-patch my_script.py

# Pytest
python -m mkl_random --with-numpy-patch -m pytest tests/

# One-liner
python -m mkl_random --with-numpy-patch -c "import numpy; print(f\"numpy.random.normal.__module__: {numpy.random.normal.__module__}\")"

# Non-Python command
python -m mkl_random --with-numpy-patch -- <command> [args...]

Programmatic Quickstart

import mkl_random
import numpy

mkl_random.patch_numpy_random()
print(mkl_random.is_patched())
# run your accelerated numpy workloads here!
mkl_random.restore_numpy_random()

import mkl_random
import numpy
with mkl_random.mkl_random():
   # run your accelerated workloads here!
   pass

Building from source

A C++ compiler, Intel® oneAPI Math Kernel Library (oneMKL), and NumPy are required to build mkl_random from source.

Executing

python -m pip install .

will pull in the required build dependencies, including mkl and numpy, and build mkl_random.

If you already have mkl and numpy installed (from your system or a conda environment) and want to reuse them instead of pulling fresh copies into an isolated build, first install the build dependencies:

pip install meson-python cmake ninja "cython>=3.1.0" numpy mkl-devel

then build against the existing installation with:

python -m pip install --no-build-isolation --no-deps .