2. Software installation

In order to run models on an IPU-POD you will need to download and install some software packages. The software can be downloaded from the Graphcore software download portal.

You need to install the Poplar SDK, which includes the development tools and also command line tools for managing the IPU hardware.

You also need to install the user-level V-IPU software.

2.1. SDK installation

Download the SDK tarball and unpack it using the following command:

$ tar -xvzf poplar_sdk-[os]-[ver].tar.gz

Where [os] is the host OS and [ver] is the software version number of the package.

The main components under the SDK installation directory are shown in Table 2.1.

Table 2.1 SDK contents

File or directory

Description

gc_kernel-module-[os]-[ver]/

Directory containing the Graphcore drivers and utilities.

popart-[os]-[ver]/

Directory containing the PopART framework.

poplar-[os]-[ver]/

Directory containing the Poplar graph programming framework and PopLibs libraries

docs/

HTML and PDF documentation for the SDK tools and libraries. The documentation on the Graphcore documentation portal may contain updates made after the SDK release and includes other documents not packaged with the SDK.

tensorflow-1.15.5+[ver]-[arch].whl

File to install the Graphcore port of TensorFlow v1.15 for Python 3.

ipu_tensorflow_addons-1.15.5+[ver].whl

File to install the IPU TensorFlow Addons package for TensorFlow 1.15 for the IPU.

tensorflow-2.6.3+[ver]-[arch].whl

File to install the Graphcore port of TensorFlow v2.6 for Python 3.

ipu_tensorflow_addons-2.6.3+[ver].whl

File to install the IPU TensorFlow Addons package for TensorFlow 2.6 for the IPU.

poptorch-[ver]-[arch].whl

File to install PopTorch (to run PyTorch models on the IPU).

horovod-[ver].whl

File to install Horovod to support distributed training in PopART.

poplibs-source-code-[ver].zip

Source code for the PopLibs libraries (also available on GitHub).

license.html

The Graphcore end user license agreement (EULA).

release_notes.*

Release notes for this version of the SDK, in HTML and XML (Docbook) format.

Note

There are two versions of each of the TensorFlow wheel files, optimised for Intel and AMD processors respectively. These are indicated by the arch component of the filename. You must install the correct wheel file for your host processor type.

2.2. Setting up the SDK environment

To use the Graphcore tools and Poplar libraries, several environment variables (such as library and binary paths) need to be set up, as shown below:

$ cd poplar_sdk-[os]-[ver]
$ source poplar-[os]-[ver]/enable.sh
$ source popart-[os]-[ver]/enable.sh

Where [os] is the host OS and [ver] is the current software version number of each package.

You will need to source both the Poplar and the PopART enable scripts if you are using PyTorch or PopART.

Note

Each of these scripts must be sourced every time the Bash shell is reset. If you attempt to run any Poplar software without having first enabled these scripts, you’ll get an error from the C++ compiler similar to the following (the exact message will depend on your code).

fatal error: 'poplar/Engine.hpp' file not found

You can verify that Poplar has been successfully set up by running:

$ popc --version

This will display the version number of the installed software.

PopTorch and TensorFlow for the IPU are provided as Python wheel files that can be installed using pip as described in the following sections.

2.3. Setting up PyTorch for the IPU

PopTorch is part of the Poplar SDK. It provides functions to allow PyTorch models to run on the IPU.

Before running PopTorch, you must source the enable.sh scripts for Poplar and PopART as described in Section 2.2, Setting up the SDK environment.

PopTorch is packaged as a Python wheel file that can be installed using pip.

Note

PopTorch requires pip version 18.1 or later, so it important to make sure you have the latest version before installing PopTorch.

We recommend creating a virtual environment to isolate your PopTorch environment from the system Python environment. You can use the Python tool virtualenv for this. You can create a virtual environment and install PopTorch as shown below:

$ virtualenv -p python3 poptorch_test
$ source poptorch_test/bin/activate
$ python -m pip install -U pip
$ python -m pip install <sdk_path>/poptorch_x.x.x.whl

To confirm that PopTorch has been installed, you can use pip list, which should include the poptorch package in the output.

You can also test that the module has been installed correctly by attempting to import it in Python, for example:

$ python3 -c "import poptorch; print(poptorch.__version__)"

Note that you may get a warning message including the string “UserWarning: Failed to initialize NumPy” unless you have numpy installed. This warning can be safely ignored; it will not prevent you from using PopTorch. You can stop the warning being displayed by installing numpy into the virtualenv:

$ python -m pip install numpy

For more information, refer to PyTorch for the IPU: User Guide.

2.4. Setting up TensorFlow for the IPU

Before running TensorFlow, you must source the enable.sh script for Poplar as described in Section 2.2, Setting up the SDK environment.

To use the Graphcore port of TensorFlow, you must set up a Python virtual environment.

You can create a virtual environment in a directory called workspace with:

$ virtualenv -p python3.6 ~/workspace/tensorflow_env

You have to activate the virtual environment before you can use it with:

$ source ~/workspace/tensorflow_env/bin/activate

Now all subsequent installations will be local to that virtual environment, until you deactivate it.

Warning

The versions of TensorFlow included in Poplar SDK 2.5 and earlier are not compatible with protobuf version 4 (see TensorFlow issue #56077). When you install a TensorFlow wheel from the Poplar SDK, you must ensure you have a compatible version of protobuf, downgrading if necessary.

  • For TensorFlow 2:

    $ python -m pip install "protobuf>=3.9.2,<3.20" --force-reinstall
    
  • For TensorFlow 1:

    $ python -m pip install "protobuf>=3.8.0,<3.20" --force-reinstall
    

You can do this before or after installing the Graphcore TensorFlow wheel.

We support TensorFlow 1 and TensorFlow 2. There are versions of these compiled for Intel and AMD processors to provide the best performance on those hosts. As a result, there are four Python wheel files that are included in the Poplar SDK that can be installed with pip.

Warning

You must install the correct wheel file for your host CPU. You can use the command lscpu to determine the CPU type, if you are not sure.

To install Graphcore’s TensorFlow distribution, you would use a command similar to the following:

$ python -m pip install tensorflow-<tf_ver>+gc<poplar_ver>+<build_info>+<arch>-<python_ver>-<platform>.whl

where <tf-ver> is the TensorFlow version, <poplar_ver> is the Poplar SDK version, <build_info> is information about the specific build, <arch> is the host CPU architecture (Intel or AMD), <python_ver> is the Python version, and <platform> is the platform. For example:

$ python -m pip install tensorflow-2.6.3+gc2.6.0+214768+ac0300b8f63+amd_znver1-cp36-cp36m-linux_x86_64.whl

would install TensorFlow 2.6.3 for Poplar SDK 2.6.0 for an Intel CPU on 64-bit Linux.

To confirm that tensorflow has been installed, you can use pip list, which should include the tensorflow package in the output, for example:

(tensorflow_env)$ pip list
Package        Version
-------------  ----------
numpy          1.19.5
pkg-resources  0.0.0
tensorflow     2.6.3
wheel          0.37.0

You can also test that the module has been installed correctly by importing it in Python, for example:

$ python -c "from tensorflow.python import ipu"

2.4.1. IPU Keras

In the TensorFlow 2.6 release, Keras was moved into a separate pip package. In the Poplar SDK 2.6 release, which includes the Graphcore distribution of TensorFlow 2.6, there is a Graphcore distribution of Keras which includes IPU-specific extensions.

Note

The Keras wheel must be installed after the TensorFlow wheel, but before the TensorFlow Addons wheel.

To install the Keras wheel, use a command similar to:

$ python -m pip install --force-reinstall --no-deps keras-<tf-ver>*.whl

where <tf-ver> is the TensorFlow 2 version. For example:

$ python -m pip install--force-reinstall --no-deps keras-2.6.0+gc2.6.0+214767+d36553ad-py2.py3-none-any.whl

would install the Keras wheel for TensorFlow 2.6 for the IPU for Poplar SDK 2.6.

You can test that the package has been installed correctly by importing it in Python, for example:

$ python3 -c "import keras"

If you get an “illegal instruction” or similar error, then try to install the Keras wheel again.

2.4.2. IPU TensorFlow Addons

Poplar SDK 2.4 onwards includes an additional package called IPU TensorFlow Addons. This contains a collection of addons created for TensorFlow for the IPU, such as IPU-specific Keras optimizers. To install this package you need to use a command similar to the following:

$ python -m pip install ipu_tensorflow_addons-<tf_ver>+gc<poplar_ver>+<build_info>-py3-none-any.whl

where <tf-ver> is the TensorFlow version, <poplar_ver> is the Poplar SDK version, and <build_info> is information about the specific build. For example:

$ python -m pip install ipu_tensorflow_addons-2.6.3+gc2.6.0+214767+3efc838-py3-none-any.whl

would install IPU TensorFlow Addons for TensorFlow 2.6.3 for the IPU for Poplar SDK 2.6.0.

Note that the IPU TensorFlow Addons wheels are not specific to a CPU architecture.

2.4.3. Next steps

For the next steps with TensorFlow, refer to the appropriate user guide:

2.5. Installing the V-IPU command-line tools

Note

You can omit this step if vipu is already installed on the system. You can check if it is installed by running vipu --version.

You can download the V-IPU client software from the Graphcore software download portal. It can be installed on any computer that can communicate with the V-IPU controller.

Extract the contents of the downloaded archive:

$ tar xzvf vipuusertools-$VERSION.tar.gz

Where $VERSION is the version of the software.

Add the directory containing the extracted package to the PATH environment variable:

$ export PATH=$PWD/vipu-$VERSION:$PATH

Now, confirm that the vipu executable is found and that it reports the expected version:

$ vipu --version