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.

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.

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:

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.

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.

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

You will also need to add the PopLibs device code to the graph program (see Adding PopLibs code to a graph program).