Development/MKL

From bwHPC Wiki
< Development
Revision as of 15:34, 26 February 2014 by M Neuer (talk | contribs)
Jump to: navigation, search
Navigation: bwHPC BPR


1 Math Kernel Library (MKL)

Intel MKL (Math Kernel Library) is a library of optimized math routines for numerical computations such as linear algebra (using BLAS, LAPACK, ScaLAPACK) and discrete Fourier Transformation. With its standard interface in matrix computation and the interface of the popular fast Fourier transformation library fftw, MKL can be used to replace other libraries with minimal code changes. In fact a program which uses FFTW without MPI doesn't need to be changed at all. Just recompile it with the MKL linker flags.

Online documentation: http://software.intel.com/en-us/articles/intel-math-kernel-library-documentation

Local documentation: There is some information in the module help file accessible via

$ module help numlib/mkl

and after loading the module, the environment variable $MKL_DOC_DIR points to the local documentation folder. Various examples can be found in $MKLROOT/examples.

Compiling and linking: Compilation is possible with both GCC and Intel compilers but it is easier for Intel compilers, so this case is explained here. After loading the compiler and the library module with

$ module load compiler/intel
$ module load numlib/mkl

you can include the MKL header file in your program:

#include <mkl.h>

Compilation is simple:

$ icpc -c example_mkl.c

When linking the program you have to tell the compiler to link against the mkl library:

$ icpc example_mkl.o -mkl

With the -mkl switch the intel compiler automatically sets the correct linker flags but you can specify them explicitly for example to enable static linking or when non-intel compilers are used. Information about the different options can be found at http://software.intel.com/en-us/node/438568 and especially helpful is the MKL link line advisor at http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor. By default $MKL_NUM_THREADS is set to 1 and so only one thread will be created, but if you feel the need to run the computation on more cores (after benchmarking) you can set $MKL_NUM_THREADS to a higher number.

Examples: To help getting started we provide two C++ examples. The first one computes the square of a 2x2 matrix:

#include <iostream>
#include <mkl.h>
using namespace std;

int main()
{
    double m[2][2] = {{2,1}, {0,2}};
    double c[2][2];

    for(int i = 0; i < 2; ++i)
    {
        for(int j = 0; j < 2; ++j)
            cout << m[i][j] << " ";

        cout << endl;
    }

    cblas_dgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 2, 2, 2, 1.0, &m[0][0], 2, &m[0][0], 2, 0.0, &c[0][0], 2);

    cout << endl;

    for(int i = 0; i < 2; ++i)
    {
        for(int j = 0; j < 2; ++j)
            cout << c[i][j] << " ";

        cout << endl;
    }

    return 0;
}

And the second one does a fast Fourier transformation using the Intel MKL interface (DFTI):

#include <iostream>
#include <complex>
#include <cmath>
#include <mkl.h>
using namespace std;

int main()
{
    const int N = 3;
    complex<double> x[N] = {2, -1, 0.5};

    cout << "Input: " << endl;

    for(int i = 0; i < N; i++)
        cout << x[i] << endl;

    DFTI_DESCRIPTOR_HANDLE desc;

    DftiCreateDescriptor(&desc, DFTI_DOUBLE, DFTI_COMPLEX, 1, N);
    DftiCommitDescriptor(desc);
    DftiComputeForward(desc, x);
    DftiFreeDescriptor(&desc);

    cout << "\nOutput: " << endl;

    for(int i = 0; i < N; i++)
        cout << x[i] << endl;

    cout << "\nTest the interpolation function f:" << endl;

    for(int i = 0; i < N; i++)
    {
        double t = i/(double)N;
        complex<double> u(0, 2*M_PI*t);
        complex<double> z = exp(u);
        complex<double> w = 1.0/N * (x[0] + x[1]*z + x[2]*z*z);

        cout << "f(" << t << ") = " << w << endl;
    }

    return 0;
}

2 FFTW

FFTW is a C subroutine library for computing the discrete Fourier transform (DFT) in one or more dimensions, of arbitrary input size, and of both real and complex data (as well as of even/odd data, i.e. the discrete cosine/sine transforms or DCT/DST).

This package provides three versions of the fftw3 library depending on precision: libfft3, libfftw3f and libfftw3l for double, single and long-double precision libraries.

Online Documentation: http://www.fftw.org/fftw3_doc/

Local documentation:

See 'info fftw3', 'man fftw-wisdom' and 'man fftw-wisdom-to-conf'. See also documentation folder pointed to by shell variable $FFTW_DOC_DIR

Hints for compiling and linking:

Load the fftw module, and, if needed, the corresponding openmpi module.

After having loaded the appropriate module(s), you can use several environment variables to compile and link your application.

  • Compile serial program:
 $ gcc example.c -o example -I$FFTW_INC_DIR -L$FFTW_LIB_DIR -lfftw3 -lm
  • Compile program with support for POSIX threads:
 $ gcc example.c -o example -I$FFTW_INC_DIR -L$FFTW_LIB_DIR -lfftw3_threads -lfftw3 -lpthread -lm
  • Compile program with support for OpenMP threads:
 $ gcc example.c -o example -fopenmp -I$FFTW_INC_DIR -L$FFTW_LIB_DIR -lfftw3_omp -lfftw3 -lm
  • Compile program with support for MPI:
 $ mpicc example.c -o example -I$FFTW_INC_DIR -L$FFTW_LIB_DIR -lfftw3_mpi -lfftw3 -lm 
  • Run program with MPI support:
 $ mpirun -n <ncpu> ./example 

(Replace <ncpu> by number of processor cores.)

Replace -lfftw3, -lfftw3_threads, etc. by -lfftw3f, -lfftw3f_threads, etc. for single precision and by -lfftw3l, -lfftw3l_threads etc. for long-double precision codes, respectively.

These commands will compile your program with dynamic fftw library versions in which case you also have to have the fftw module loaded for running the program. Alternatively, you may want to link your program with static fftw library versions. With static fftw libraries it is only necessary to load the fftw module for compiling but not for executing the program.

  • Compile program with static fftw library versions (example for POSIX threads support):
 $ gcc example.c -o example -I$FFTW_INC_DIR $FFTW_LIB_DIR/{libfftw3_threads.a,libfftw3.a} -lpthread -lm 

or:

 $ gcc example.c -o example -I$FFTW_INC_DIR -L$FFTW_LIB_DIR -Wl,-Bstatic -lfftw3 -lfftw3_threads \
       -Wl,-Bdynamic -lpthread -lm 

Environment variables $FFTW_INC_DIR, $FFTW_LIB_DIR etc. are available after loading the module.

Sample code for various test cases is provided in folder pointed to by environment variable $FFTW_EXA_DIR.


3 GNU Scientific Library (GSL)

The GNU Scientific Library (or GSL) is a software library for numerical computations in applied mathematics and science. The GSL is written in the C programming language, but bindings exist for other languages as well.

Online-Documentation: http://www.gnu.org/software/gsl/

Local-Documentation:

See 'info gsl', 'man gsl' and 'man gsl-config'.

Tips for compiling and linking:

Load the gsl module. After having loaded the gsl environment module, you can use several environment variables to compile and link your application with the gsl library.

Your source code should contain preprocessor include statements with a gsl/ prefix, such as

 #include <gsl/gsl_math.h>

A typical compilation command for a source file example.c with the Intel C compiler icc is

 $ icc -Wall -I$GSL_INC_DIR  -c example.c 

The $GSL_INC_DIR environment variable points to location of the include path for the gsl header files.

The following command can be used to link the application with the gsl libraries,

 $ icc -L$GSL_LIB_DIR -o example example.o -lgsl -lgslcblas -lm 

The $GSL_LIB_DIR environment variable points to the location of the gsl libraries.

Also make sure to have the gsl module loaded before running applications build with this library.

Example

Create source code file 'intro.c':

#include <stdio.h>
#include <gsl/gsl_sf_bessel.h>

int main (void)
{
  double x = 5.0;
  double y = gsl_sf_bessel_J0 (x);
  printf ("J0(%g) = %.18e\n", x, y);
  return 0;
}

Load the gsl module for the Intel compiler, compile, link and run the program:

$ module load numlib/gsl/1.16-intel-13.1
Loading module dependency 'compiler/intel/13.1'.
$ icc -Wall -I$GSL_INC_DIR  -c intro.c
$ icc -L$GSL_LIB_DIR -o intro intro.o -lgsl -lgslcblas -lm
$ ./intro
J0(5) = -1.775967713143382642e-01