3. Quick start for beginners

This section provides more detail on the steps described in the Quick start for experts section.

Ensure you have completed the steps described in the getting started guide for your system as defined in the Prerequisites section before completing the steps in this section.

3.1. Enable Poplar SDK

On some systems you must explicitly enable the Poplar SDK before you can use PyTorch, PopART, TensorFlow 1 and TensorFlow 2; and if you are working directly in the Poplar Graph Programming Framework. On other systems, the SDK is enabled as part of the login process.

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

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

System	Enable SDK?	SDK location
Pod system	Yes	The SDK will be found 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 PopART.

Run the single script as:

$ 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

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-2.5.1/poplar-ubuntu_20_04-2.5.0+3723-e94d646535
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.

3.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 python[py_ver] ~/[base_dir]/[venv_name]

where [base_dir] is a location of your choice and [venv_name] is the name of the virtual environment. [py_ver] is the version of Python you are using and it depends on your OS.

Note

On Ubuntu 18 systems we support Python 3.6, and on Ubuntu 20 systems we support Python 3.8. You can get more information about the versions of tools supported in the Poplar SDK for different operating systems in the Release Notes.

You can check which OS you are running by using the command:

$ lsb_release -a

To start using a virtual environment, activate it with:

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

where [base_dir] is where you created the virtual environment and [venv_name] is the name of the virtual environment.

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

3.3. Clone Graphcore Tutorials repo

You need to clone the Graphcore tutorials repo on some systems as detailed in Table 3.2.

If you don’t need to clone the tutorials repo, then go straight to Section 3.4, Define environment variable.

Table 3.2 Systems that need the Graphcore tutorials and examples repositories to be cloned

System	Clone repos?	Comment
Pod system	Yes	You can clone the tutorials and examples repos in any location.
Graphcloud	Yes	You can clone the tutorials and examples repos in any location.
Gcore Cloud	No	The tutorials and examples have already been cloned in ~/graphcore/tutorials and ~/graphcore/examples respectively.

There are several tutorials available in the Graphcore tutorials repository on GitHub.

You can clone the tutorials repository into a location of your choice.

$ cd ~/[base_dir]
$ git clone https://github.com/graphcore/tutorials.git
$ cd tutorials
$ git checkout sdk-release-[poplar-ver]

where [base_dir] is a location of your choice and [poplar-ver] is the version of the Poplar SDK that you are using (Section 3.1, Enable Poplar SDK). This will install the contents of the tutorials repository under ~/[base_dir]/tutorials.

3.4. Define environment variable

You need to define the following environment variables:

• POPLAR_TUTORIALS_DIR: for the location of the cloned tutorials repository.

3.4.1. Define tutorials location

In order to simplify running the tutorial in this (and other Quick Starts) you need to define the location of the tutorials directory as an environment variable.

Pod systemsGraphcloudGcore Cloud

$ export POPLAR_TUTORIALS_DIR=~/[base_dir]/tutorials

[base_dir] is the location where you installed the Graphcore tutorials.

3.5. Run the application

Note

You should activate the Python virtual environment you created for PopART (Section 3.2, Create and enable a Python virtual environment) before performing the steps described in this section.

This section describes how to run a simple application, the MNIST example, using PopART.

1. Install example requirements

   You can now install the requirements that the model needs.

   $ cd $POPLAR_TUTORIALS_DIR/simple_applications/popart/mnist/
   $ pip install -r requirements.txt
   

2. Get the data

   $ ./get_data.sh
   

3. Run example

   You run the code with:

   $ python popart_mnist.py
   

   or with:

   $ python popart_mnist_conv.py
   

   There are some command line options which you can experiment with.

If the code has run successfully, you should see an output similar to that in Listing 3.1.

Listing 3.1 Example of output for PopART application.

Creating ONNX model.
Compiling the training graph.
Compiling the validation graph.
Running training loop.
Epoch #1
  Loss=16.2605
  Accuracy=88.88%
Epoch #2
  Loss=13.9930
  Accuracy=89.63%
Epoch #3
  Loss=13.1049
  Accuracy=89.83%
Epoch #4
  Loss=12.5232
  Accuracy=90.01%
Epoch #5
  Loss=12.1029
  Accuracy=90.12%
Epoch #6
  Loss=11.7830
  Accuracy=90.22%
Epoch #7
  Loss=11.5327
  Accuracy=90.40%
Epoch #8
  Loss=11.3332
  Accuracy=90.59%
Epoch #9
  Loss=11.1712
  Accuracy=90.65%
Epoch #10
  Loss=11.0370
  Accuracy=90.70%

You have run a model that demonstrates how to use the IPU to train a simple model on the MNIST dataset using PopART.

3.6. Try out other applications

Try out other examples in the Tutorials or Examples repositories. You may have to clone the Graphcore Examples repository if your installation doesn’t already include it as defined in Table 3.2.

There are several example applications available in the Graphcore examples repository on GitHub.

You can clone the examples repository into a location of your choice.

$ cd ~/[base_dir]
$ git clone https://github.com/graphcore/examples.git
$ cd examples
$ git checkout tags/[tag_name]

where [base_dir] is a location of your choice and [tag_name] is the name of the tagged version corresponding to the version of the Poplar SDK that you are using (Section 3.1, Enable Poplar SDK). You can see the tagged versions here. This will install the contents of the examples repository under ~/[base_dir]/examples.

3.7. Exit the virtual environment

When you are done, exit the Python virtual environment.

$ deactivate