setuptools

PyViennaCL uses the Python package setuptools for installation. Unless you are using Python 3.4, which comes with the required pieces, you may need to install setuptools. The best way to do so, which will also ensure you have the Python package manager pip installed, is to follow the instructions here.

OpenCL

By default, you will need an OpenCL implementation. PyViennaCL can still build and function without one, but will not perform to full effect.

For information on how to get an OpenCL implementation on Linux, see this howto. See also the installation section in the ViennaCL Manual on installation hints for Windows.

If you have an OpenCL installation that you installed and is not managed by your system’s package manager, then it is likely you will need to use the ‘–cl-lib-dir’ configure option.

If you do not wish to use OpenCL, then follow the Custom installation instructions below, and use the ‘–no-use-opencl’ configure option.

Extra requirements for building from source on Windows systems

In addition to the components required above, Windows builds require the use of the Windows SDK version specific to the version of your Python installation. For instance, when you run Python, if you see the following:

Python 2.7.6 (default, Nov 10 2013, 19:24:18) [MSC v.1500 32 bit (Intel)] on win32

then you are using a release of Python 2.7 and you are building for a 32-bit installation of that version. You must therefore choose the SDK version and set the build environment accordingly.

If you are building for a standard distribution (such as described in the example above) of Python 2.6, 2.7, 3.0, 3.1 or 3.2 (either 32- or 64-bit), you will need the Microsoft Windows SDK v7.0 for Windows 7 and .NET Framework 3.5 SP1.

If you are building for a standard distribution of Python 3.3 or later (32- or 64-bit), you will need the Microsoft Windows SDK v7.1 for Windows 7 and .NET Framework 4.

Having installed the correct SDK version, you will need to open an SDK command prompt and issue the following commands, according the architecture of your Python installation.

If you are building for a 32-bit Python installation, use:

$> set DISTUTILS_USE_SDK=1
$> setenv /x86 /release

If you are building for a 64-bit Python installation, use:

$> set DISTUTILS_USE_SDK=1
$> setenv /x64 /release

At this point, you will be able to follow the instructions detailed below under Installation. Issue all commands from within the SDK command window.

You might also be interested in the Python Tools for Visual Studio, though these are not required either for building or using PyViennaCL.

Quick installation using pip

The following command should usually be enough to install PyViennaCL, as long as you have setuptools and pip installed (see above):

$> pip install pyviennacl

If you have a recent installation of Python (2.7 or 3.3+), and a recent installation of pip (1.4+), then this should be painless.

Note that this command assumes you have OpenCL available, and if you are on Linux, an OpenCL SDK.

If this does not succeed, follow the instructions below.

Custom installation

These instructions assume a UNIX-like platform (such as a Linux distribution or Mac OS X), but will work on a well-configured Windows system with little modification.

If you are building from the release package, move on to the next paragraph. If you are building from git, then before doing anything else, navigate to your PyViennaCL folder and get the external submodules with:

$> git submodule update --init

(On Windows you usually want to use the git bash for this)

If you are in a hurry, then the following should just work:

$> python setup.py build
$> sudo python setup.py install

Otherwise, read the configuration options, configure, build and install:

$> ./configure.py --help
$> ./configure.py --some-options
$> python setup.py build
$> sudo python setup.py install

To build the HTML documentation using Sphinx, first install PyViennaCL as above, and then run:

$> cd doc
$> make html

after which HTML documentation will be in doc/_build/html. Or you can just access the documentation from within the Python interpreter after installation:

>>> import pyviennacl
>>> help(pyviennacl)