Using oneMKL with R

Viraj Malia, David Cortes

Introduction

This guide provides detailed instructions for integrating Intel® oneAPI Math Kernel Library(oneMKL) with R, enhancing performance for numerical computations. It covers installation, configuration, and usage across different operating systems, including Debian-based systems and Windows. Additionally, it explains how to make oneMKL an optional dependency in R packages and highlights the use of Conda for seamless integration.

Installation

Installing oneMKL

Via Conda: The easiest way to install oneMKL is through conda, which automatically configures R to use oneMKL for BLAS/LAPACK operations.
```
conda create -n renv blas=*=*mkl* libblas=*=*mkl* r-base
```
Direct Download: Alternatively, download oneMKL from Intel's website and follow the installation instructions for your operating system.

Installing R-OneMKL Package

From GitHub: Since the R-OneMKL package is not available on CRAN, install it directly from GitHub:

# Install pak if not already installed
install.packages("pak")

# Install R-OneMKL from GitHub
pak::pak("R-OneMKL/oneMKL")

When to Use R-OneMKL

Use Cases for R-OneMKL

Developing Custom Extensions: If you are creating R packages or extensions that require direct access to oneMKL routines for custom computations, consider using R-OneMKL. It provides an interface for calling oneMKL functions from C/C++ code within your R package.
Advanced Performance Optimization: For tasks that require fine-tuned performance optimization using oneMKL's advanced features, R-OneMKL can be a valuable tool.
Direct Access to oneMKL Features: When you need specialized functions from oneMKL that aren't accessible through R's standard linear algebra operations.

General Usage Without R-OneMKL

Standard BLAS/LAPACK Operations: For general usage, where R needs to perform standard numerical computations using oneMKL, installing R through conda with the oneMKL variant is sufficient. This setup automatically configures R to use oneMKL for its internal operations.
Typical R Packages: Most users and standard R packages do not require R-OneMKL, as the default configuration provided by conda or other package managers is adequate.

Configuration

Debian-Based Systems

Using Debian Alternatives: Configure oneMKL as the preferred BLAS/LAPACK implementation using the Debian alternatives system. This ensures persistence after package updates.
```
sudo update-alternatives --config libblas.so-x86_64-linux-gnu
sudo update-alternatives --config liblapack.so-x86_64-linux-gnu
```

Conda Approach

When R is installed via conda, it automatically links to oneMKL for BLAS/LAPACK operations.

# Activate the environment with oneMKL-enabled R
conda activate renv

Manual Configuration

For manual installations, configure R to use oneMKL by setting the appropriate library paths and linking options.

Environment Variables

Environment variables are used to specify the paths to oneMKL libraries, ensuring that the system can locate them during runtime.

Linux (Including Debian-Based and Other Distributions):

# Recommended: Use the oneAPI setvars script
source /opt/intel/oneapi/setvars.sh

# Alternative: Set variables directly
export MKLROOT=/opt/intel/oneapi/mkl/latest
export LD_LIBRARY_PATH=$MKLROOT/lib:$LD_LIBRARY_PATH

# Set threading model if linking with mkl_rt
# R is built using GNU toolchain by default,
# so match oneMKL’s OpenMP vendor
export MKL_THREADING_LAYER=GNU

Windows:

On Windows, adding oneMKL to the PATH environment variable will not make R use it, as R provides its own DLLs which take higher loading priority. To make an existing R installation use oneMKL, you would need to override these DLLs using one of the following methods.

Recommended Method: Custom DLL Builder

This method creates proper interface DLLs that connect R with oneMKL by exporting the same symbols as R's original DLLs:

Set up the oneAPI environment
1. Open a command prompt
2. Run the setvars script to set up the oneAPI environment:
```
"C:\Program Files (x86)\Intel\oneapi\setvars.bat"
```

Extract symbols from original R DLLs

dumpbin /exports Rblas.dll > Rblas_list
dumpbin /exports Rlapack.dll > Rlapack_list_R

Edit the extracted symbol files
1. Remove the header and footer information
2. Keep only the symbol names

Build the custom BLAS DLL

nmake libintel64 export=..path..\Rblas_list name=Rblas

Handle LAPACK symbols properly

# This will generate errors for undefined symbols
nmake libintel64 export=..path..\Rlapack_list_R name=Rlapack 1> undefined_symbols_list

# Edit undefined_symbols_list to keep only the names
# Create a new list with the difference
findstr /v /g:undefined_symbols_list Rlapack_list_R > Rlapack_list

# Build the LAPACK DLL with the corrected symbol list
nmake libintel64 export=..path..\Rlapack_list name=Rlapack

Check dependencies and ensure they're available
```
dumpbin /dependents Rlapack.dll
```

Note: The DLLs depend on `libiomp5md.dll`, which is included in the oneAPI installation.

Alternative Method: Direct DLL Override

This method is simpler but uses more disk space:

Copy oneAPI runtime files to R's binary folder

Copy all files from:
C:\Program Files (x86)\Intel\oneAPI\mkl\latest\bin
C:\Program Files (x86)\Intel\oneAPI\compiler\latest\bin
To your R binary directory:
C:\Program Files\R\R-x.x.x\bin\x64

Backup original R DLLs
1. Rename `Rblas.dll` to `Rblas.dll.bak`
2. Rename `Rlapack.dll` to `Rlapack.dll.bak`
Create MKL-based replacements
1. Make two copies of `mkl_rt.2.dll`
2. Rename one copy to `Rblas.dll` and the other to `Rlapack.dll`

Important Notes

The custom DLL builder method is recommended as it properly matches the required symbol exports.
Remember to back up your original DLLs before making any changes.
These methods need to be reapplied after R updates.
Verify the installation by checking `sessionInfo()` in R.

Additional Resources

For more detailed information about building custom DLLs with oneMKL, refer to Intel oneAPI MKL Custom DLL Builder Guide: https://www.intel.com/content/www/us/en/develop/documentation/onemkl-windows-developer-guide/top/building-custom-dynamic-link-libraries.html

Linking Options

Linking options are used when compiling or running applications to ensure they use oneMKL for numerical computations.

Using oneMKL with R package extensions (C, C++, Fortran):

When compiling R extensions, specify oneMKL libraries in the Makevars file of your package.

# ~/.R/Makevars or package src/Makevars
PKG_CPPFLAGS = -I$(MKLROOT)/include
PKG_LIBS = -L$(MKLROOT)/lib -lmkl_rt -Wl,-rpath,$(MKLROOT)/lib

For detailed instructions and best practices on configuring oneMKL libraries, refer to the oneMKL Link Line Advisor to generate the correct linking options for your specific setup.

Using oneMKL in Extensions

Integration with package extensions

oneMKL can be used in C, C++, or Fortran extensions within R packages:

// For C++ with Rcpp (in a .cpp file)
#include <Rcpp.h>
#include <mkl.h>

// [[Rcpp::export]]
void example_mkl_function() {
    // oneMKL-specific code
}

/* For C extensions (in a .c file) */
#include <R.h>
#include <Rinternals.h>
#include <mkl.h>

SEXP c_mkl_function(SEXP arg) {
    // oneMKL-specific code
}

! For Fortran extensions (in a .f or .f90 file)
subroutine fort_mkl_function()
    ! Include oneMKL functionality
end subroutine

Note: Ensure that your main R installation is configured to use oneMKL before linking any extensions to it. Linking an extension to oneMKL while R itself uses a different BLAS/LAPACK backend can lead to multiple libraries being loaded, which may cause conflicts, thread management issues, and degraded performance.

Optional Dependency in R Packages

Conditional oneMKL Usage

In DESCRIPTION file:

Suggests: oneMKL

Check for oneMKL availability in your R package:

has_mkl <- FALSE
try({
    # Check for oneMKL capability
    has_mkl <- requireNamespace("oneMKL", quietly = TRUE) ||
               grepl("MKL", La_library(), ignore.case = TRUE)
}, silent = TRUE)

if (has_mkl) {
    message("Using optimized oneMKL routines")
    library(oneMKL)
    # Now you can use oneMKL functions from oneMKL::
} else {
    message("Using standard BLAS routines")
    # Standard implementation
}

Conda Integration

oneMKL Variant: Create conda environments that use the oneMKL variant of BLAS, ensuring R uses oneMKL for numerical computations.

# Create an environment with R and oneMKL
conda create -n renv blas=*=*mkl* r-base

# Activate the environment
conda activate renv

# Verify oneMKL usage in R
R -e "sessionInfo()"

Container Integration

Docker with oneMKL and R

FROM intel/oneapi-basekit:latest

RUN apt-get update && apt-get install -y --no-install-recommends \
    r-base r-base-dev libcurl4-openssl-dev \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Configure R to use oneMKL
RUN echo "MKL_THREADING_LAYER=GNU" >> /etc/environment

# Install R-OneMKL package
RUN R -e 'install.packages("pak"); pak::pak("R-OneMKL/oneMKL")'

# Verify oneMKL is being used
RUN R -e 'library(oneMKL); sessionInfo()'

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Integrating Intel® oneAPI Math Kernel Library (oneMKL) with R

Introduction

Installation

Installing oneMKL

Installing R-OneMKL Package

When to Use R-OneMKL

Use Cases for R-OneMKL

General Usage Without R-OneMKL

Configuration

Debian-Based Systems

Conda Approach

Manual Configuration

Environment Variables

Linux (Including Debian-Based and Other Distributions):

Windows:

Recommended Method: Custom DLL Builder

Alternative Method: Direct DLL Override

This method is simpler but uses more disk space:

Important Notes

Additional Resources

For more detailed information about building custom DLLs with oneMKL, refer to Intel oneAPI MKL Custom DLL Builder Guide: https://www.intel.com/content/www/us/en/develop/documentation/onemkl-windows-developer-guide/top/building-custom-dynamic-link-libraries.html

Linking Options

Using oneMKL with R package extensions (C, C++, Fortran):

Using oneMKL in Extensions

Integration with package extensions

oneMKL can be used in C, C++, or Fortran extensions within R packages:

Optional Dependency in R Packages

Conditional oneMKL Usage

Conda Integration

Container Integration

Docker with oneMKL and R

Additional Resources

Product and Performance Information