3. Preparing for running a program

Before you can run a program on the IPU-POD, you must:

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

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 test connectivity to the V-IPU controller with the vipu --server-version command.

You can do this in a few ways.

Firstly, 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

Secondly, 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

Finally, you can add the server details to a configuration file named .vipu.hcl which should be located in your $HOME directory:

$ cat ~/.vipu.hcl
api-host=10.1.2.3
api-port=9090
api-user-id=alice
api-access-key=685XK4uCzN

$ vipu --server-version

In all of these 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 allocate some IPUs to run your software by creating a partition. 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 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 because this is not a multi-GCD system.

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.