3. Preparing for running a program

Before you can run a program on the Pod, you must:

Unless you are using a Pod DA, you must also:

3.1. Enable the Poplar SDK

To use the Graphcore tools and Poplar libraries, several environment variables (such as library and binary paths) need to be set up. Scripts are provided that simplify this task.

To enable the Poplar SDK:

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. Establishing connectivity with the V-IPU controller

Note

A Pod DA system does not need the V-IPU software. If you are using a Pod DA, you can go directly to Section 4, Running a Poplar program on your Pod.

After installing the vipu tool, you need to confirm that you can connect to the V-IPU controller that is running on the Pod management server.

The system administrator must have created a user account for you and allocated some IPUs to that user ID. Then, you will need the following information from the system administrator:

  • V-IPU controller host name or IP address (api_host)

  • V-IPU controller port number (api_port)

  • User ID (api_user-id) and API access key (api_access_key)

You can test connectivity to the V-IPU controller with the vipu --server-version command.

There are two ways to pass the necessary information to the vipu command: either using command line options or using environment variables.

3.2.1. Using command line options

You can pass the server details you got from your system administrator as command line options:

  • --api_host

  • --api_port

  • --api_user-id

  • --api_access_key

For example:

$ vipu --server-version --api-host 10.1.2.3 --api-port 9090 --api-user-id alice --api-access-key 685XK4uCzN

3.2.2. Using environment variables

As an alternative, you can specify the server details in environment variables as:

$ export VIPU_CLI_API_HOST=10.1.2.3
$ export VIPU_CLI_API_PORT=9090
$ export VIPU_CLI_API_USER_ID=alice
$ export VIPU_CLI_API_ACCESS_KEY=685XK4uCzN
$ vipu --server-version

In both cases, you should get the version of the V-IPU controller that is running on the server.

3.3. Creating a partition

After you have established connectivity with the V-IPU controller, you must create a “partition” to allocate some IPUs to run your software. A partition defines a set of IPUs used for running end-user applications.

The simplest way to get started is to create a “reconfigurable” partition. This makes a set of IPUs available to users, in a flexible way, as a number of single-IPU device IDs and a set of multi-IPU device IDs if the partition is larger than a single IPU. The process to create partitions is described in detail in the Creating partitions section of the V-IPU User Guide.

For this example, we shall create a partition (called “pt”) with one IPU:

vipu create partition pt --size 1 --reconfigurable

After you have created the partition, you need to configure how Poplar connects to the IPUs. This is done using environment variables.

There are five environment variables that may need to be set:

  • IPUOF_VIPU_API_HOST: The IP address of the server running the V-IPU controller. Required.

  • IPUOF_VIPU_API_PORT: The port to connect to the V-IPU controller. Optional. The default is 8090.

  • IPUOF_VIPU_API_PARTITION_ID: The name of the partition to use. Required.

  • IPUOF_VIPU_API_GCD_ID: The ID of the graph compile domain (GCD) you want to use. Required for multi-GCD systems.

  • IPUOF_VIPU_API_TIMEOUT: Set the time-out for client calls in seconds. Optional. Default 200.

For example, for the partition “pt” that we created, the required environment variables would be:

$ export IPUOF_VIPU_API_HOST=10.1.2.3
$ export IPUOF_VIPU_API_PARTITION_ID=pt

We are using the default values for IPUOF_VIPU_API_PORT and IPUOF_VIPU_API_TIMEOUT and we do not need a value for IPUOF_VIPU_API_GCD_ID.

In a fully deployed system, you may want to define partitions containing sets of IPUs configured in specific ways.

See the V-IPU User Guide for full details of the V-IPU command-line software, allocating IPUs for your program, and running code on a Pod.