2. General Setup
In order to run this example, you must:
Log in to Graphcloud. Refer to the Graphcloud Access Quick Start for details.
Set up the environment (this is also described in the Graphcloud Setup Quick Start). If you have already set up the environment, you can go directly to Section 3, Running an application.`
The steps to set up the environment are:
Create a Python virtual environment if you don’t already have one for PopART 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.
Clone the tutorials repository into the
~/workspacedirectory.
$ 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.
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.
$ 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
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. 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 2.4, 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'
2.7. 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.
Create a Python virtual environment.
$ virtualenv -p python3.6 ~/workspace/[venv_name]where
[venv_name]is the name of the virtual environment.
Activate the virtual environment so you can use it.
$ source ~/workspace/[venv_name]/bin/activateNow all subsequent installations will be local to that virtual environment.
Deactivate the virtual environment with:
$ deactivate