5. Setup

This chapter describes the setup steps that are needed before you can run any applications on the IPU.

5.1. Creating a workspace directory

The directory /localdata contains a directory named with your username that only you can access. Create a workspace directory here and create a symbolic link to it in your home directory to make access easier.

$ mkdir /localdata/<username>/workspace
$ ln -s /localdata/<username>/workspace ~/workspace

5.2. Setting up a shared workspace

You can create a shared area that can be used by other members of your team. You can do this with the following sequence of commands:

$ mkdir /localdata/shared
$ chown :ipupod /localdata/shared
$ chmod 2770 /localdata/shared

The first command creates the directory, the second sets the group ownership to ipupod, the group that all users are in, and finally the permissions are changed so that all members of the group can read and write to the directory, and ensures that all files created in the directory have the same permissions (the setguid bit).

You can create project directories under this directory, that can be accessed by all users in the group:

$ mkdir /localdata/shared/test_project

5.3. Installing the Graphcore examples and tutorials

There are examples and tutorials available in the Graphcore GitHub examples repository. See Other Resources for more information.

Clone the examples repository into the ~/workspace directory.

$ cd ~/workspace
$ git clone https://github.com/graphcore/examples.git
Cloning into 'examples'...
This will install the contents of the examples repository under ~/workspace/examples. The tutorials are in ~/workspace/examples/tutorials.

Checkout the tag or branch of the repository corresponding to the version of the Poplar SDK you are using.

The examples repository has tags of the form v3.2.0 for the code compatible with each SDK release.
$ git checkout tags/[tag_name]
where [tag_name] is the name of the tagged commit corresponding to the version of the Poplar SDK that you are using.

There is a list of tagged versions.
Since SDK 3.2, the examples repository also has branches corresponding to each SDK release. These have names of the form sdk-release-3.2.0
$ git checkout sdk-release-[poplar-ver]
where [poplar-ver] is the version of the Poplar SDK that you are using.

There is a list of active branches.

Note

If you are using a version of the Poplar SDK prior to 3.2, you will need to use the old GitHub tutorials repository. This has branches corresponding to each version of the SDK.

For example for Poplar SDK 3.1, checkout branch sdk-release-3.1.

5.4. Define environment variables

In order to simplify working with the Poplar SDK and running tutorials, we define the following environment variable for the location of the cloned tutorials:

  export POPLAR_TUTORIALS_DIR=~/workspace/examples/tutorials

We also use the environment variable POPLAR_SDK_ENABLED. This environment variable is defined when Poplar is enabled (Section 5.5, Enable Poplar) and defines the location of the poplar directory in the SDK directory.

5.5. Enable Poplar

You must explicitly source the Poplar enable script to use the Poplar SDK.

$ cd /opt/gc/poplar_sdk-ubuntu_18_04-[poplar_ver]+[build]
$ source poplar-ubuntu_18_04-[poplar_ver]+[build]/enable.sh

where [poplar_ver] is the software version number of the Poplar SDK and [build] is the build information.

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/sdk-3.0.0/poplar-ubuntu_18_04-3.0.0+5691-1e179b3b85
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.

Note

You must source the Poplar enable script for each new Bash shell. You can add the source command shown above to your .bashrc to do this on a more permanent basis.

5.6. Enable PopART

You must source the PopART enable script if you are using PyTorch or PopART. This is not required if you are using TensorFlow or working directly in the Poplar Graph Programming Framework, in which case you can skip this section.

$ source ${POPLAR_SDK_ENABLED?}/../popart-ubuntu_18_04-[poplar_ver]+[build]/enable.sh

where [poplar_ver] is the software version number of the Poplar SDK and [build] is the build information. POPLAR_SDK_ENABLED is an environment variable that is defined when Poplar is enabled (see Section 5.5, Enable Poplar) and and specifies the location of the poplar directory in the SDK directory. The ? ensures that an error message is displayed if Poplar has not been enabled.

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

$ python3 -c "import popart"

This will fail with the following error if PopART hasn’t been successfully configured:

ModuleNotFoundError: No module named 'popart'

Note

You must source the PopART enable script for each new Bash shell. You can add the source command shown above to your .bashrc to do this on a more permanent basis.

Search help