3. Setup for Jupyter Notebooks

Before you run any application on a Jupyter Notebook, you must complete the following setup steps:

1. Enable the Poplar SDK

2. Create a Python virtual environment and activate it

3. Install the ML framework wheels

4. Install Jupyter

5. Start the Jupyter server

6. Connect to the Jupyter server

This assumes you do not have any of the software installed already. If you do, you can just skip the appropriate sections.

3.1. Enable the Poplar SDK

Note

It is best if you use the latest version of the Poplar SDK.

On some systems you must explicitly enable the Poplar SDK before you can use PyTorch or TensorFlow for the IPU, or 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 it.

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 is 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 PopTorch/PopART.

Source the single script as follows:

$ 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

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/poplar_sdk-ubuntu_20_04-3.2.0-7cd8ade3cd/poplar-ubuntu_20_04-3.2.0-7cd8ade3cd
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 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 python3 [venv_name]

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

Note

Make sure that the version of Python that is installed is compatible with the version of the Poplar SDK that you are using. See Supported tools in the Poplar SDK release notes for information about the supported operating systems and versions of tools.

To start using a virtual environment, activate it with:

$ source [venv_name]/bin/activate

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

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

3.3. Install the ML framework wheels

You need to install the Poplar SDK wheels if you are using PyTorch, PyTorch Geometric or TensorFlow in the virtual environment you have activated. Refer to the PyTorch Quick Start and TensorFlow 2 Quick Start for details of installing the relevant wheels. For this Quick Start guide, we are using PyTorch.

This section describes how to install a wheel file containing PopTorch, a set of extensions to enable PyTorch models to run on the IPU.

Note

You should activate the Python virtual environment you created for PyTorch (Section 3.2, Create a Python virtual environment) before performing the setup in this section.

The wheel file is included with the Poplar SDK and has a name of the form:

poptorch-[sdk_ver]+*.whl

where [sdk_ver] is the version of the Poplar SDK. An example of the wheel file is:

poptorch-3.2.0+109946_bb50ce43ab_ubuntu_20_04-cp38-cp38-linux_x86_64.whl

Install the PopTorch wheel file using the following command:

$ python -m pip install ${POPLAR_SDK_ENABLED?}/../poptorch-*.whl

where POPLAR_SDK_ENABLED is the location of the Poplar SDK defined when the SDK was enabled. The ? ensures that an error message is displayed if Poplar has not been enabled.

To confirm that PopTorch has been installed, you can use:

pip list | grep poptorch

For the example wheel file, the output will be:

poptorch       3.2.0+109946

You can also test that the module has been installed correctly by attempting to import it in Python, for example:

$ python3 -c "import poptorch; print(poptorch.__version__)"

3.4. Install Jupyter

After enabling the SDK and installing the desired wheel, install Jupyter Notebook and the IPython kernel:

$ python -m pip install jupyter ipykernel

Note

You can also use JupyterLab. Install JupyterLab and the IPython kernel with:

$ python -m pip install jupyter-lab ipykernel

3.5. Start the Jupyter server

You need to start the Jupyter server in the directory where you will be accessing the notebook. This will be the top most directory that you can access from your Jupyter server. To avoid restarting the notebook for every tutorial, it is simplest to navigate to the folder containing all tutorials. For this Quick Start guide, navigate to:

$ cd $POPLAR_TUTORIALS_DIR

Then, start a Jupyter server in “no browser” mode on a specified port:

$ jupyter-notebook --no-browser --port <port number>

For example:

$ jupyter-notebook --no-browser --port 44300

  [I 11:57:42.444 NotebookApp] Jupyter Notebook 6.4.4 is running at:
  [I 11:57:42.444 NotebookApp] http://localhost:44300/?token=cb37a6b1ffb29dc99dea3d8e4153cef232b9f067ecd50f64
  [I 11:57:42.444 NotebookApp]  or http://127.0.0.1:44300/?token=cb37a6b1ffb29dc99dea3d8e4153cef232b9f067ecd50f64
  [I 11:57:42.444 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
  [C 11:57:42.447 NotebookApp]

      To access the Notebook, copy and paste one of these URLs:
      http://localhost:44300/?token=cb37a6b1ffb29dc99dea3d8e4153cef232b9f067ecd50f64
      or http://127.0.0.1:44300/?token=cb37a6b1ffb29dc99dea3d8e4153cef232b9f067ecd50f64

Note

If you are using JupyterLab, then start it with:

$ jupyter-lab --no-browser --port <port number>

The URLs that appear are going to be used to connect to this server later.

At this point the Jupyter server is running and will block your terminal. You will need to keep the server running while you want your sessions to remain active. For more information on how to manage long running tasks on linux, check out this guide on how to run and control background processes on Linux.

3.6. Connect to the Jupyter server

In order to connect to the Jupyter server we will need to connect via SSH with port forwarding to your IPU host. To do this you must add the -NL option to the ssh command that you run from your local machine:

$ ssh -NL <port_on_local_machine>:localhost:<port_on_server> <user>@<ip>

where <port_on_local_machine> is the port on your local machine which the Jupyter server will forward to, <port_on_server> is the port on which the Jupyter server is running and <user>@<ip> is your username and the server IP address.

For example:

$ ssh -NL 8888:localhost:44300 [email protected]

where 8888 is the port on your local machine, 44300 is the port on which the Jupyter server is running, joes is the username and 123.456.789.012 is the IP address of the IPU host.

Note

This command must run continuously while you access the Jupyter server from your browser.

Now you are ready to Run the application.