RuntimeOptions

#include <poplar/RuntimeOptions.hpp>
template<>
struct hash<poplar::RuntimeOptions>

Public Functions

size_t operator()(const poplar::RuntimeOptions&) const
namespace poplar

Poplar classes and functions.

class RuntimeOptions
#include <RuntimeOptions.hpp>

A group of properties that are reconfigurable in each engine execution.

Passing a RuntimeOptions reference to some of the Engine member functions will override the corresponding options configured when the Engine was created.

See also: Engine::prepare() , Engine::run()

RuntimeOptions can also be overridden with the environment variable POPLAR_RUNTIME_OPTIONS. For example: 

POPLAR_RUNTIME_OPTIONS='{"target.syncMethod":"polling"}'

Engine runtime options: Target

  • target.exceptionPollPeriodUs Integer [=250000]

    The period to use to poll for possible exceptions in the device, while waiting for the host sync, in microseconds.

  • target.hostSyncTimeout Float [=300.00]

    The amount of time to wait for a response from the IPU after running a program, in seconds. “0” means no timeout.

  • target.syncMethod (polling, hybrid, default) [=default]

    Controls how the host determines when an IPU wants to sync.

    • polling: Using polling to determine when an IPU wants to sync.

    • hybrid: Use a mixture of interrupts and polling to determine when an IPU wants to sync.

    • default: Choose a sensible default method based on the device type. Currently, we default to polling for all device types but this may change in future.

  • target.syncPollPeriodUs Integer [=0]

    The period to use when polling for a host sync, in microseconds.

Engine runtime options: Stream Callbacks

  • streamCallbacks.multiThreadMode (singleThread, collaborative, dedicated) [=singleThread]

    Specifies how the invocation of stream callbacks is parallelised. Be aware that using a multithreading mode other than singleThread requires that the stream callbacks connected to the engine are thread-safe.

    • singleThread: the main application thread is used to perform the invocation of stream callbacks. No other threads assist it.

    • collaborative: the main application thread and any specified number of worker threads collaborate in invoking any necessary stream callbacks.

    • dedicated: the main application thread will not assist worker threads and will focus on IPU-host exchange events.

  • streamCallbacks.numaAware (true, false) [=false]

    Can only be enabled in a multithread mode. Creates a separate thread pool for each NUMA node used by the devices the application is using.

  • streamCallbacks.numWorkerThreads Integer or “auto” [=0]

    The maximum number of threads to execute stream callbacks. A value of 0 means the main thread will execute all of the callbacks.

    Specifying the value auto will create as many threads as necessary to fill all the available CPU resources. This typically means one thread per CPU core.

    If the value of multiThreadMode is singleThread then the only allowed value is 0. All other values of multiThreadMode require a value greater than 0.

    If you enable the option streamCallbacks.numaAware, the worker threads are distributed as evenly as possible to multiple thread pools: one thread pool per NUMA node in use by the attached IPU devices.

Engine runtime options: Debug

There are various runtime errors, such as memory parity errors, that are caught at the system level of the IPU device (system on chip or SoC).

  • debug.checkForSOCErrorAtRun (true, false) [=false]

    If true, check for SoC errors before and after program execution.

  • debug.exceptOnSOCError (true, false) [=true]

    If true, throw an exception on a SoC error. If false, the error will be reported in the log instead.

Engine runtime options: Profiler

The profiler options control how Poplar generates the reports that can be viewed in the PopVision Graph Analyser (the graph and execution profiles)

  • profiler.replicaToProfile Integer [=All replicas]

    Specifies which replica (0-based index) will be profiled. Note that a high-level summary of several metrics and timings will still be provided for the whole execution. If not specified, all replicas will be profiled.

Public Functions

explicit RuntimeOptions(const OptionFlags &options)
RuntimeOptions(const RuntimeOptions &options)
RuntimeOptions(RuntimeOptions&&)
RuntimeOptions &operator=(const RuntimeOptions&)
RuntimeOptions &operator=(RuntimeOptions&&)
~RuntimeOptions()
bool operator==(const RuntimeOptions&)
inline const core::RuntimeOptions *getImpl() const

Public Static Attributes

static const char *EnvVarName

Private Members

std::unique_ptr<core::RuntimeOptions> impl
namespace core
namespace std
template<> RuntimeOptions >

Public Functions

size_t operator()(const poplar::RuntimeOptions&) const