Install the MKL module

This is an optional module that enables Chrono to use the Intel MKL Pardiso solver.

Read the introduction to modules for a technical background on the modularity of the Chrono project.

Chrono::Engine usually relies on its built-in solvers, whose good perfomance are guaranteed by leveraging the internal data structure. In fact, for a wide range of applications, these suffice.
However, for higher accuracy results, a direct solver could still be needed.

This module provides access to the third-party Intel MKL Pardiso solver. The interface to Pardiso is provided by Eigen.

Features

Two Chrono-specific features are implemented:

  • sparsity pattern lock
    In many cases, the internal data structures undergo very little changes between different timesteps. In these cases it is useful to inform the solver that the sparsity pattern does not change consistently in order to speed up the matrix assembly.
  • sparsity pattern learner
    The sparsity pattern learning feature acquires the sparsity pattern in advance, in order to speed up matrix assembly. Enabled by default, the sparsity matrix learner identifies the exact matrix sparsity pattern (without actually setting any nonzeros) Look at the API section of this module for a more details.

Requirements

  • To build applications based on this unit:
  • To run applications based on this unit:
The Intel MKL Redistributables are included into Intel MKL Library
The Intel MKL Library is now distributed for free!

Building instructions

  1. Install the Intel MKL Library following the Developer Guide. No particular skills are needed.
    • if you are not installing to the default directory, then you have to set the environment variable MKLROOT in order to point to
      <install_folder>/IntelSWTools/compilers_and_libraries/windows/mkl (Windows + MKL>=2016)
      <install_folder>/intel/compilers_and_libraries/linux/mkl (Linux + MKL>=2016)
  2. Repeat the instructions for the full installation, but when you see the CMake window,
    you must set ENABLE_MODULE_MKL as 'on'.
    The CMake output window, on Windows OS, should return the following: (Please mind that the MATH library is not required.)
    Find MKL libraries
    MKL include dirs: C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/mkl/include
    MKL libraries: C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/mkl/lib/intel64/mkl_rt.lib
    IOMP5 library: C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/compiler/lib/intel64/libiomp5md.lib
    MATH library: C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/compiler/lib/intel64/libmmd.lib
    MKL library dirs: C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/mkl/lib/intel64;C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/compiler/lib/intel64
  3. Press 'Generate' and build the project.

Building this unit will produce an additional shared library, called ChronoEngine_mkl, that can be linked to your application if you want to use it.
The file extension will be .dll for Win and .so on Linux.

Beware! If you run the demos using Chrono::MKL, you might find that they are not able to find the MKL run time libraries in your PATH. The reason is that you should execute the mklvars.bat configuration in your shell, using the appropriate parameters to set the paths to find the Intel run time libraries, as stated in Intel MKL documentation about the installation. For example, in Windows, do cd "C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2019\windows" then mklvars intel64 then execute the MKL demos from the shell.

However, if you find annoying to call mklvars all times from a shell, or if you do not want to embed it in your system startup, you can manually do the following:

  1. Add MKL libraries to your system path: The MKL installer sets a wide set of environment variables, but not the one needed by MKL.
    In order to set the variables once for all you have to add these directories in your PATH (Windows) or LD_LIBRARY_PATH (Linux or MacOS) environment variable: <install_folder>/IntelSWTools/compilers_and_libraries/windows/redist/intel64_win/mkl
    <install_folder>/IntelSWTools/compilers_and_libraries/windows/redist/intel64_win/tbb/vc_mt
    <install_folder>/IntelSWTools/compilers_and_libraries/windows/redist/intel64_win/compiler
    or
    <install_folder>/intel/compilers_and_libraries/linux/redist/intel64/mkl
    <install_folder>/intel/compilers_and_libraries/linux/redist/intel64/tbb/vc_mt
    <install_folder>/intel/compilers_and_libraries/linux/redist/intel64/compiler
    (on ia32 platforms replace intel64 with ia32 in the lines above).
  2. Add these system environment variables
    MKL_INTERFACE_LAYER = LP64
    MKL_THREADING_LAYER = INTEL
    or, more in general, you can have different options, depending on your Architecture and the desired Threading Layer.

By doing this, you will be able to start the MKL-based demos and programs by just double clocking on them, without the need of the mklvars.bat script.

How to use it

  • Simply add this snippet anywhere in your code, before running the main simulation loop.
    This will inform Chrono to use the Eigen interface to the Intel MKL Pardiso solver.
    auto mkl_solver = std::make_shared<ChSolverMKL>();
    my_system.SetSolver(mkl_solver);
  • (Optional) Turn on the sparsity pattern lock (see chrono::ChSolverMKL and chrono::ChDirectSolverLS for further details)
    auto mkl_solver = std::make_shared<ChSolverMKL>();
    mkl_solver->SetSparsityPatternLock(true);
    my_system.SetSolver(mkl_solver);
  • By default, this solver uses the sparsity pattern learner (see chrono::ChDirectSolverLS) to infer the sparsity pattern before actually loading the non-zero elements. To disable the use of the sparsity pattern learner, call
    mkl_solver->UseSparsityPatternLearner(false);
  • Look at the API section of this module for documentation about classes and functions.