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

\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 tutorials

There are several tutorials available in the Graphcore GitHub repository tutorials. These are listed in the Examples and Tutorials index.

  1. Clone the tutorials repository into the ~/workspace directory.

$ cd ~/workspace
$ git clone https://github.com/graphcore/tutorials.git
Cloning into 'tutorials'...

This will install the contents of the tutorials repository under ~/workspace/tutorials.

  1. Checkout the branch of the tutorials repository corresponding to the version of the Poplar SDK you have sourced.

$ git checkout sdk-release-[poplar-ver]

where [poplar-ver] is the version of the Poplar SDK that you have sourced in Section 5.6, Enable Poplar.

5.4. Installing the Graphcore examples

There are several examples available in the Graphcore GitHub repository examples. These are listed in the Examples and Tutorials index.

We shall clone the examples repository into the ~/workspace directory.

Listing 5.1 Cloning the examples
 $ cd ~/workspace
 $ git clone https://github.com/graphcore/examples.git
 Cloning into 'examples'...

Note

If you have not sourced the enable.sh for the latest version of the Poplar SDK, then you will have to checkout a tagged version of the examples repository for the Poplar SDK version that you are are using.

$ git checkout tags/[tag_name]

where [tag_name] is the name of the tagged version corresponding to the version of the Poplar SDK that you have sourced in Section 5.6, Enable Poplar. You can see the tagged versions here.

This will install the contents of the examples repository under ~/workspace/examples.

5.5. Define environment variables

In order to simplify working with the Poplar SDK and running tutorials and examples, we define the following environment variables:

  • SDK_DIR: defines the location of the Poplar SDK

  • TUTORIALS_DIR: defines the location of the cloned tutorials repository

  • EXAMPLES_DIR: defines the location of the cloned examples repository

Listing 5.2 Creating environment variables
  export SDK_DIR=/opt/gc/poplar_sdk-ubuntu_18_04-[poplar_ver]+[build]
  export TUTORIALS_DIR=~/workspace/tutorials
  export EXAMPLES_DIR=~/workspace/examples

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

5.6. Enable Poplar

You must source the Poplar enable script for TensorFlow 1, TensorFlow 2, PyTorch and PopART; also if you are working directly in the Poplar Graph Programming Framework.

$ source $SDK_DIR/poplar-ubuntu_18_04-[poplar_ver]+[build]/enable.sh

where $SDK_DIR is the location of the Poplar SDK (Section 5.5, Define environment variables), [poplar_ver] is the software version number of the Poplar SDK and [build] is the build information.

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

$ popc --version

This will display the version of the installed software.

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

Note

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

5.7. Enable PopART

You must source the PopART enable script if you are using PyTorch or PopART, but not if you are using TensorFlow or working directly in the Poplar Graph Programming Framework.

$ source $SDK_DIR/popart-ubuntu_18_04-[poplar_ver]+[build]/enable.sh

where $SDK_DIR is the location of the Poplar SDK (Section 5.5, Define environment variables), [poplar_ver] is the software version number of the Poplar SDK and [build] is the build information.

Note

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

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'