2. General Setup

In order to run this example, you must perform these steps:

  1. Log in to Graphcloud. Refer to the Graphcloud Access Quick Start for details.

  2. Setup the environment, if you haven’t already done so (as described in the Graphcloud Setup Quick Start). If you have already set up the environment, you can go directly to Section 3, TensorFlow 2 setup.

    The steps to set up the environment are:

    1. Create a workspace directory

    2. Install the Graphcore tutorials

    3. Install the Graphcore examples (optional)

    4. Define environment variables

    5. Enable Poplar

    6. Create a Python virtual environment if you don’t already have one for TensorFlow 2 and activate it

2.1. Create 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

2.2. Install 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 2.5, Enable Poplar.

2.3. Install the Graphcore examples (optional)

Note

The examples installed in this section are not used in this Quick Start guide. They are are included so you can try out some of the other models that are available for the IPU.

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 2.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 2.5, Enable Poplar. You can see the tagged versions here.

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

2.4. 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 2.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

2.5. Enable Poplar

On some systems you must explicitly 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. On other systems, the script is sourced as part of the login process.

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

where $SDK_DIR is the location of the Poplar SDK (Section 2.4, Define environment variables), [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

Warning

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.

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.

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

$ popc --version

This will display the version of the installed software.

2.6. Create 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, activate and deactivate a Python virtual environment.

  1. Create a Python virtual environment.

$ virtualenv -p python3.6 ~/workspace/[venv_name]

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

  1. Activate the virtual environment so you can use it.

$ source ~/workspace/[venv_name]/bin/activate

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

  1. Deactivate the virtual environment with:

$ deactivate