|
ViennaCL - The Vienna Computing Library
1.7.1
Free open-source GPU-accelerated linear algebra and solver library.
|
|
|
ViennaCL - The Vienna Computing Library
1.7.1
Free open-source GPU-accelerated linear algebra and solver library.
|
|
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
viennacl-support@lists.sourceforge.net 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:
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.
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 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 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.
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.
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 #defines.
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.
ViennaCL provides several examples for users to get started quickly. A list of examples and tutorials including their dependencies are as follows:
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.
viennacl/ source folder and start your project!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.
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 |
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.
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.
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:
build/ directory as build directory.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.The examples and tutorials should be executed from within the build/ directory of ViennaCL, otherwise the sample data files cannot be found.
1.8.6