ViennaCL - The Vienna Computing Library: Installation

ViennaCL - The Vienna Computing Library 1.7.1 Free open-source GPU-accelerated linear algebra and solver library. |

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Installation

This chapter shows how ViennaCL can be integrated into a project and how the examples are built. The necessary steps are outlined for several different platforms, but we could not check every possible combination of hardware, operating system and compiler. If you experience any trouble, please write to the maining list at

`vienn.nosp@m.acl-.nosp@m.suppo.nosp@m.rt@l.nosp@m.ists..nosp@m.sour.nosp@m.cefor.nosp@m.ge.n.nosp@m.et`

# Dependencies

ViennaCL uses the CMake build system for multi-platform support. Thus, before you proceed with the installation of ViennaCL, make sure you have a recent version of CMake installed.

To use ViennaCL, only a fairly recent C++ compiler (e.g. GCC version 4.2.x or above and Visual C++ 2008 and 2010 are known to work) is required.

The full potential of ViennaCL is available with the following optional libraries:

- CMake [8] as build system (optional, but highly recommended for building examples)
- OpenCL [18] [24] for accessing compute devices (GPUs); see the section on OpenCL for details.
- CUDA [23] for using CUDA-accelerated operations.
- OpenMP [25] for directive-based parallelism on CPUs.
- ublas (shipped with Boost [6] ) provides the same interface as ViennaCL and allows to switch between CPU and GPU seamlessly, see the tutorials.
- Armadillo [1], Eigen [11], or MTL 4 [22] can be used to fill ViennaCL types directly. Moreover, the iterative solvers in ViennaCL can directly be used with objects from these libraries.

# Generic Installation of ViennaCL

Since ViennaCL is a header-only library, it is sufficient to copy the folder `viennacl/` either into your project folder or to your global system include path. On Unix-based systems, this is often `/usr/include/` or `/usr/local/include/`. If the OpenCL headers are not installed on your system, you should repeat the above procedure with the folder `CL/`.

The situation on Windows strongly depends on your development environment. We advise users to consult the documentation of their compiler on how to set the include path correctly. With Visual Studio this is usually something like `C:\Program Files\Microsoft Visual Studio 9.0\VC\include` and can be set in `Tools -> Options -> Projects and Solutions -> VC++–Directories`. For using the CUDA backend, make sure that the CUDA SDK is installed properly and supports your host compiler suite. If you intend to use the OpenCL backend, the include and library directories of your OpenCL SDK should also be added there.

Note: If multiple OpenCL libraries are available on the host system, ViennaCL uses the first platform returned by the system by default. Consult the chapter on using multiple devices for configuring the use of other platforms.

# Get the OpenCL Library

In order to compile and run OpenCL applications, a corresponding library (e.g. `libOpenCL.so` under Unix based systems) is required. If OpenCL is to be used with GPUs, suitable drivers have to be installed. This section describes how these can be acquired. For Mac OS X systems there is no need to install an OpenCL capable driver and the corresponding library. The OpenCL library is already present if a suitable graphics card is present. The setup of ViennaCL on Mac OS X is outlined Mac OS X here.

## NVIDIA Driver

NVIDIA provides the OpenCL library with the GPU driver. Therefore, if an NVIDIA driver is installed on the system, the OpenCL library is usually installed as well. However, not all of the released drivers contain the OpenCL library. A driver known to support OpenCL and hence providing the required library is `260.19.21`. Note that the latest NVIDIA drivers no longer include the OpenCL headers anymore. Therefore, the official OpenCL headers from the Khronos group [18] are also shipped with ViennaCL in the folder `CL/` to simplify the installation process.

## AMD Accelerated Parallel Processing SDK (formerly Stream SDK)

AMD has provided the OpenCL library with the Accelerated Parallel Processing (APP) SDK~[3] earlier. Currently the OpenCL library is also included in the GPU driver. In doubt, make sure you have both the AMD APP SDK and the latest GPU driver installed. The latest tested version of the AMD APP SDK is 2.9, yet newer releases usually work as well. If ViennaCL is to be run on multi-core CPUs with OpenCL, no additional GPU driver is required. The installation notes of the APP SDK provides guidance throughout the installation process [4].

If the AMD APP SDK is installed in a non-system wide location on UNIX-based systems, be sure to add the OpenCL library path to the `LD_LIBRARY_PATH` environment variable. Otherwise, linker errors will occur as the required library cannot be found.

Note that the AMD APP SDK may not provide OpenCL certified double precision support [2] on some older GPUs.

Warning
  Unfortunately, some versions of the AMD APP SDK are known to have bugs. For example, APP SDK 2.7 on Linux causes BiCGStab to fail on some devices.

## INTEL OpenCL SDK

ViennaCL works fine with the INTEL OpenCL SDK on Windows and Linux. The correct linker path is set automatically in `CMakeLists.txt` when using the CMake build system.

# Enabling OpenMP, OpenCL, or CUDA Backends

The default behavior since ViennaCL 1.4.0 is to use the CPU backend. OpenCL and CUDA backends need to be enabled by appropriate preprocessor #`define`s.

Preprocessor #`define` | Default computing backend
--- | ---
none | CPU, single-threaded
`VIENNACL_WITH_OPENMP` | CPU with OpenMP (compiler flags required)
`VIENNACL_WITH_OPENCL` | OpenCL
`VIENNACL_WITH_CUDA` | CUDA

The preprocessor constants can be either defined at the beginning of the source file (prior to any ViennaCL-includes), or passed to the compiler as command line argument. For example, on `g++` the respective command line option for enabling the OpenCL backend is `-DVIENNACL_WITH_OPENCL`. Note that CUDA requires the `nvcc` compiler. Furthermore, the use of OpenMP usually requires additional compiler flags (on `g++` this is for example `-fopenmp`).

Multiple backends can be used simultaneously. In such case, CUDA has higher priority than OpenCL, which has higher priority over the CPU backend when it comes to selecting the default backend.

# Building the Examples and Tutorials

ViennaCL provides several examples for users to get started quickly. A list of examples and tutorials including their dependencies are as follows:

Example/Tutorial | Dependencies
--- | ---
`tutorial/amg.cpp/cu` | -
`tutorial/armadillo-with-viennacl.cpp` | Armadillo
`tutorial/bandwidth-reduction.cpp` | -
`tutorial/bisect.cpp/cu` | -
`tutorial/blas1.cpp/cu` | -
`tutorial/blas2.cpp/cu` | uBLAS
`tutorial/blas3.cpp/cu` | uBLAS
`tutorial/custom-context.cpp` | OpenCL
`tutorial/custom-cuda.cu` | CUDA
`tutorial/custom-kernels.cpp` | OpenCL
`tutorial/eigen-with-viennacl.cpp` | Eigen
`tutorial/fft.cpp/cu` | OpenCL
`tutorial/iterative.cpp/cu` | uBLAS
`tutorial/iterative-armadillo.cpp` | Armadillo
`tutorial/iterative-custom.cpp/cu` | -
`tutorial/iterative-ublas.cpp` | uBLAS
`tutorial/iterative-eigen.cpp` | Eigen
`tutorial/iterative-mtl4.cpp` | MTL
`tutorial/lanczos.cpp/cu` | uBLAS
`tutorial/least-squares.cpp/cu` | uBLAS
`tutorial/libviennacl.cpp/cu` | -
`tutorial/matrix-free.cpp/cu` | -
`tutorial/matrix-range.cpp/cu` | uBLAS
`tutorial/mtl4-with-viennacl.cpp` | MTL
`tutorial/multithreaded.cpp/cu` | Boost
`tutorial/multithreaded_cg.cpp/cu` | Boost
`tutorial/nmf.cpp/cu` | -
`tutorial/power-iter.cpp/cu` | uBLAS
`tutorial/qr.cpp/cu` | uBLAS
`tutorial/scheduler.cpp` | -
`tutorial/spai.cpp` | OpenCL, uBLAS
`tutorial/sparse.cpp/cu` | uBLAS
`tutorial/structured-matrices.cpp` | OpenCL, uBLAS
`tutorial/tql2.cpp/cu` | -
`tutorial/vector-range.cpp/cu` | uBLAS
`tutorial/viennacl-info.cpp` | OpenCL
`tutorial/wrap-cuda-buffer.cu` | CUDA
`tutorial/wrap-host-buffer.cpp` | -
`benchmarks/blas3.cpp/cu` | -
`benchmarks/opencl.cpp` | OpenCL
`benchmarks/solver.cpp/cu` | uBLAS
`benchmarks/sparse.cpp/cu` | uBLAS
`benchmarks/vector.cpp/cu` | -

Dependencies for the examples in the `examples/` folder. Examples using the CUDA-backend use the `.cu` file extension. Note that all examples can be built and run using either of the CPU, OpenCL, and CUDA backend (if .cu file available) unless an explicit OpenCL-dependency is stated.

These examples can be built and run either manually, or using the provided CMake build setup. We recommend the CMake builds for all first-time users of ViennaCL.

Note
  It is not required to build any of the examples. Feel free to just take the `viennacl/` source folder and start your project!

## Manual Builds (no CMake)

The manual way of building the examples and tutorials is to directly invoke the compiler. For example, to build `examples/tutorial/amg.cpp using GCC or Clang it is enough to issue

    $> g++ /path/to/ViennaCL/examples/tutorial/amg.hpp -I/path/to/ViennaCL

where '/path/to/ViennaCL/` needs to be replaced with a proper absolute or relative path. This will then result in a binary executable `a.out`, in which the CPU-backend of ViennaCL will be used. To enable OpenCL or CUDA, pass the additional flags `-DVIENNACL_WITH_OPENCL` or `-DVIENNACL_WITH_CUDA`. In the former case you also need to pass `-lOpenCL` and eventually `-L/path/to/libOpenCL.so`. In the latter case you need to use the NVIDIA compiler wrapper `nvcc` instead of GCC or Clang in order to properly compile all CUDA kernels.

In a GUI-assisted integrated development environment (IDE) such as Visual Studio you need to set the include-directory for the source file appropriately. Please consult your IDE's manual for further information on how to do that.

Since such a manual compilation gets fairly tedious quickly, we recommend for a start to use the CMake-assisted builds described next.

## CMake-Assisted Builds

For building the examples, we suppose that CMake is properly set up on your system.

Before building the examples, customize the CMake setup according to your needs. Per default, all examples using uBLAS, Eigen and MTL4 are turned off. Please enable the respective examples based on the libraries available on your machine. A brief overview of the most important flags is as follows:

CMake Flag | Purpose
--- | ---
`ENABLE_CUDA` | Builds examples with the CUDA backend enabled
`ENABLE_OPENCL` | Builds examples with the OpenCL backend enabled
`ENABLE_OPENMP` | Builds examples with OpenMP for the CPU backend enabled
`ENABLE_EIGEN` | Builds examples depending on Eigen
`ENABLE_MTL4` | Builds examples depending on MTL
`ENABLE_UBLAS` | Builds examples depending on uBLAS

## Linux

To build the examples, open a terminal and change to:

    $> cd /your-ViennaCL-path/build/

Execute

    $> cmake ..

to obtain a Makefile and type

    $> make

to build the examples. If some of the dependencies in the table of examples above are not fulfilled, you can build each example separately:

    $> make blas1             #builds the blas level 1 tutorial
    $> make vectorbench       #builds vector benchmarks

Speed up the building process by using jobs, e.g. `make -j4`.

Execute the examples from the `build/` folder as follows:

    $> examples/tutorial/blas1
    $> examples/benchmarks/vectorbench

Note that all benchmark executables carry the suffix `bench`.

You may also use the CMake-GUI via `cmake-gui ..` within the `build/` folder in order to enable or disable optional libraries conveniently.

## Mac OS X

For the GCC compiler suite the Xcode [29] package has to be installed. To install CMake and Boost, external portation tools have to be used, for example, Fink [12] , DarwinPorts [10] , or MacPorts [21] . Such portation tools provide the aforementioned packages, CMake and Boost, for Mac OS.

If the CMake build system has problems detecting your Boost libraries, determine the location of your Boost folder. Provide the path using either the CMake GUI, or by passing `-DBOOST_DIR=/path/to/boost/` to the CMake executable.

The build process of ViennaCL on Mac OS is similar to Linux.

## Windows

In the following the procedure is outlined for Visual Studio: Assuming that an OpenCL SDK and CMake are already installed, Visual Studio solution and project files can be created using CMake as follows:

- Open the CMake GUI.
- Set the ViennaCL base directory as source directory.
- Set the `build/` directory as build directory.
- Click on 'Configure' and select the appropriate generator (e.g. Visual Studio 9 2008).
- If you set `ENABLE_CUDA`, `ENABLE_EIGEN`, `ENABLE_MTL4`, `ENABLE_UBLAS`, or `ENABLE_OPENCL` and the paths cannot be found, please select the advanced view and provide the required paths manually. You may have to specify the linker path for Boost manually within your Visual Studio IDE.
- Click again on 'Configure'. You should not receive an error at this point.
- Click on 'Generate'.
- The project files can now be found in the ViennaCL build directory, where they can be opened and compiled with Visual Studio (provided that the include and library paths are set correctly.

The examples and tutorials should be executed from within the `build/` directory of ViennaCL, otherwise the sample data files cannot be found.