1. Using the libraries

The Poplar library contains functions for creating and executing graphs, transferring data to and from the IPU, and managing the hardware. The PopLibs library contains higher-level mathematical and machine-learning functions.

For more information, see the Poplar and PopLibs User Guide.

1.1. Adding PopLibs code to a graph

Before using any of the PopLibs libraries you need to add the device code for the library to your program graph. Each library includes a function to do this. Your program will need to call this function for each of the libraries used. For example, if your program uses popops and poprand, then you will need to include the following in your program:

#include <popops/codelets.hpp>
#include <poprand/codelets.hpp>

... // create the graph object

popops::addCodelets(graph);
poprand::addCodelets(graph);

Where graph is the object containing your graph program.

1.2. Setting Options

Several functions have options to modify their behaviour. These are specified, using the poplar::OptionFlags class, as a series of option-value pairs, represented as strings.

There are three general classes of options:

  • Those that support debug, trace and profiling

  • Target-related options (memory use, for example)

  • Options to control optimisation

In addition, in PopLibs, there are options for fine-tuning the behaviour of specific functions such as convolution or matrix multiply.

1.2.1. Environment variables

Some options can also be specified using environment variables. This will override the values in the program. The currently support environment variables for setting options are:

1.2.2. Option values

The option values are typically either numeric or one of a list of enumerated values. The numeric values can be either an integer or a decimal value. Integer values can be prefixed with “0x” to indicate a hexadecimal value. The allowed range of values is documented, where relevant.

The options, and their allowed and default values, are documented as shown in the examples below:

  • opt.maxCompilationThreads Integer [=0] (an engine option)

  • availableMemoryProportion Decimal between 0 and 1 [=0.6] (a convolution option)

  • enableGenerateCodelet` (true, false) [=true] (an elementwise option)

This indicates the type of the numeric value (integer or decimal), or a list of the allowed values. The default value is shown in square brackets.

Some options have more complex values, such as a comma-separated list of integers or JSON structures. These are described in each case.

For example, the poplar::Engine::printProfileSummary function has an opt parameter to control the information displayed:

// Generate profile summary without execution steps but including
//  variable storage
engine.printProfileSummary(std::cout,
                {{"showExecutionSteps", "false"},{"showVarStorage","true"}});

An invalid_option exception may be thrown if the value of the option is not recognised or is out of range.

1.2.3. Unsupported options

There are a number of options in the C++ header files that are not documented here. These are unsupported. They are either deprecated (and so may disappear in future) or are intended purely for internal use by Graphcore, typically to support testing.

1.3. Linking

When compiling your program, you will need to add the libraries used to the linker command line. For example:

$ g++ -std=c++11 my-program.cpp -lpoplar -lpopops -lpoprand