2. Environment setup

This section describes how to set up your system to be able to run the PyTorch Geometric tutorials in the Graphcore GitHub Examples repository.

Note

Before following the instructions in this chapter, you must be able to log into a system with access to IPUs. Details are given in the getting started guide for your system:

• Gcore Cloud: Getting Started with IPUs

• Getting Started with Graphcloud

• Getting Started with Bow Pod and IPU-POD Systems

Important

pip >= 18.1 is required for PopTorch dependencies to be installed properly. You can upgrade pip with:

$ pip install -U pip

2.1. Enable the Poplar SDK

Note

It is best if you use the latest version of the Poplar SDK.

On some systems you must explicitly enable the Poplar SDK before you can use PyTorch or TensorFlow for the IPU, or the Poplar Graph Programming Framework. On other systems, the SDK is enabled as part of the login process.

Table 2.1 defines whether you have to explicitly enable the SDK and where to find it.

Table 2.1 Systems that need the Poplar SDK to be enabled and the SDK location

System	Enable SDK?	SDK location
Pod system	Yes	The SDK is in the directory where you extracted the SDK tarball.
Graphcloud	Yes	/opt/gc/poplar_sdk-ubuntu_18_04-[poplar_ver]+[build] where [poplar_ver] is the software version number of the Poplar SDK and [build] is the build information.
Gcore Cloud	No	The SDK has been enabled as part of the login process.

To enable the Poplar SDK:

SDK Versions 2.6 and laterSDK Versions earlier than 2.6

For SDK versions 2.6 and later, there is a single enable script that determines whether you are using Bash or Zsh and runs the appropriate scripts to enable both Poplar and PopTorch/PopART.

Source the single script as follows:

$ source [path_to_SDK]/enable

where [path_to_SDK] is the location of the Poplar SDK on your system.

Note

You must source the Poplar enable script for each new shell. You can add this source command to your .bashrc (or .zshrc for SDK versions later than 2.6) to do this on a more permanent basis.

If you attempt to run any Poplar software without having first sourced this script, you will 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

If you try to source the script after it has already been sourced, then you will get an error similar to:

ERROR: A Poplar SDK has already been enabled.
Path of enabled Poplar SDK: /opt/gc/poplar_sdk-ubuntu_20_04-3.2.0-7cd8ade3cd/poplar-ubuntu_20_04-3.2.0-7cd8ade3cd
If this is not wanted then please start a new shell.

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

$ popc --version

This will display the version of the installed software.

2.2. Create and enable a Python virtual environment

It is good practice to work in a different Python virtual environment for each framework or even for each application. This section describes how you create and activate a Python virtual environment.

Note

You must activate the Python virtual environment before you can start using it.

The virtual environment must be created for the Python version you will be using. This cannot be changed after creation. Create a new Python virtual environment with:

$ virtualenv -p python3 [venv_name]

where [venv_name] is the location of the virtual environment.

Note

Make sure that the version of Python that is installed is compatible with the version of the Poplar SDK that you are using. See Supported tools in the Poplar SDK release notes for information about the supported operating systems and versions of tools.

To start using a virtual environment, activate it with:

$ source [venv_name]/bin/activate

where [venv_name] is the location of the virtual environment.

Now all subsequent installations will be local to that virtual environment.

2.3. Install the PopTorch wheel and validate

Note

You need to install the PopTorch wheel before you install the PopTorch Geometric wheel.

This section describes how to install a wheel file containing PopTorch, a set of extensions to enable PyTorch models to run on the IPU.

Note

You should activate the Python virtual environment you created for PyTorch (Section 2.2, Create and enable a Python virtual environment) before performing the setup in this section.

The wheel file is included with the Poplar SDK and has a name of the form:

poptorch-[sdk_ver]+*.whl

where [sdk_ver] is the version of the Poplar SDK. An example of the wheel file is:

poptorch-3.2.0+109946_bb50ce43ab_ubuntu_20_04-cp38-cp38-linux_x86_64.whl

Install the PopTorch wheel file using the following command:

$ python -m pip install ${POPLAR_SDK_ENABLED?}/../poptorch-*.whl

where POPLAR_SDK_ENABLED is the location of the Poplar SDK defined when the SDK was enabled. The ? ensures that an error message is displayed if Poplar has not been enabled.

To confirm that PopTorch has been installed, you can use:

pip list | grep poptorch

For the example wheel file, the output will be:

poptorch       3.2.0+109946

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__)"

2.4. Install the PopTorch Geometric wheel and validate

This section describes how to install a wheel file containing PopTorch Geometric, a set of extensions to enable PyTorch Geometric models to run on the IPU.

Warning

PopTorch Geometric and PopTorch wheels should always come from the same Poplar SDK version to guarantee version compatibility. Refer to the version compatibility table in the PyTorch Geometric for the IPU: User Guide for details.

Note

Poptorch Geometric is tied to a compatible version of Torch Geometric. So installing this PopTorch Geometric wheel will also install the required version of Torch Geometric.

The PopTorch Geometric wheel file is included with the Poplar SDK and has a name of the form:

poptorch_geometric-[sdk_ver]+*.whl

where [sdk_ver] is the version of the Poplar SDK. An example of the wheel file is:

poptorch_geometric-3.3.0+113432_960e9c294b_ubuntu_20_04-py3-none-any.whl

Install the PopTorch Geometric wheel file using the following command:

$ python -m pip install ${POPLAR_SDK_ENABLED?}/../poptorch_geometric-*.whl

where POPLAR_SDK_ENABLED is the location of the Poplar SDK defined when the SDK was enabled. The ? ensures that an error message is displayed if Poplar has not been enabled.

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

$ python -c "import poptorch_geometric; print(poptorch_geometric.__version__)"