RandomGen

#include <poprand/RandomGen.hpp>

Functions for random number generation and applying random functions to tensors.

namespace poprand

Pseudo-random number generator (PRNG) functions.

Functions

poplar::Tensor dropout(poplar::Graph &graph, const poplar::Tensor *seed, const uint32_t seedModifier, const poplar::Tensor &input, const poplar::Tensor &reference, double keepProbability, double scale, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Apply dropout to a tensor.

The elements of tensor input are multiplied by a mask consisting of a sequence of randomly generated 1 or 0. The keep probability of the dropout P(1) = keepProbability. The contents of the mask depend on the keep probability, seed, seed modifier and layout of the reference tensor.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the dropout mask.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • input – The input tensor to be masked.

  • reference – A tensor that specifies the layout of the output tensor. Must be the same shape as the input.

  • keepProbability – The probability of keeping an input value.

  • scale – Scales the output tensor. This is typically the inverse of the dropout probability, (1 / P(1)).

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements randomly set to either zero or the scaled input value.

poplar::Tensor dropout(poplar::Graph &graph, const poplar::Tensor *seed, const uint32_t seedModifier, const poplar::Tensor &input, const poplar::Tensor &reference, double keepProbability, double scale, bool outputClonesRef, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Apply dropout to a tensor.

The elements of tensor input are multiplied by a mask consisting of a sequence of randomly generated 1 or 0. The keep probability of the dropout P(1) = keepProbability. The contents of the mask depend on the keep probability, seed, seed modifier and layout of the reference tensor.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the dropout mask.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • input – The input tensor to be masked.

  • reference – A tensor that specifies the layout of the output tensor. Must be the same shape as the input.

  • keepProbability – The probability of keeping an input value.

  • scale – Scales the output tensor. This is typically the inverse of the dropout probability, (1 / P(1)).

  • outputClonesRef – When true, the output tensor is a clone of the reference tensors. When false, the output tensor is a clone of the input tensor.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements randomly set to either zero or the scaled input value.

poplar::Tensor shapedDropout(poplar::Graph &graph, const poplar::Tensor *seed, const uint32_t seedModifier, const poplar::Tensor &input, const poplar::Tensor &reference, double keepProbability, double scale, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Apply shaped dropout to a tensor.

The elements of tensor input are multiplied by a mask consisting of a sequence of randomly generated 1 or 0. The keep probability of the dropout P(1) = keepProbability.

Shaped dropout allows row, column and dimension wise dropout, versus element-wise standard dropout. The shape of the dropout must be compatible (broadcastable) to input.

The contents of the mask depend on the keep probability, seed, seed modifier and layout of the reference tensor.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the dropout mask.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • input – The input tensor to be masked.

  • reference – A tensor that specifies the shape and layout of the dropout. Must be broadcastable to the input.

  • keepProbability – The probability of keeping an input value.

  • scale – Scales the output tensor. This is typically the inverse of the dropout probability, (1 / P(1)).

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements randomly set to either zero or the scaled input value.

poplar::Tensor uniform(poplar::Graph &graph, const poplar::Tensor *seed, uint32_t seedModifier, const poplar::Tensor &reference, const poplar::Type &outType, double minVal, double maxVal, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Uniform distribution in a given interval with maxVal > minVal.

Generates random data with uniform distribution in the interval [minVal, maxVal]. The output may be of type float, half or int.

For type int, data is generated in the interval [minVal, maxVal]. If (maxVal - minVal + 1) is a power of 2, the probability distribution is uniform. Otherwise, there will be a small bias in the probability generated, with the bias directly proportional to the ratio (maxVal - minVal + 1 ) / 2^32.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the distribution.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • reference – A tensor that specifies the layout of the output tensor.

  • outType – The type of the output tensor. One of float, half or int.

  • minVal – The minimum value of the distribution.

  • maxVal – The maximum value of the distribution.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements having a uniform distribution of random values.

poplar::Tensor logUniform(poplar::Graph &graph, const poplar::Tensor *seed, uint32_t seedModifier, const poplar::Tensor &reference, const poplar::Type &outType, double minVal, double maxVal, poplar::program::Sequence &prog, double base = M_E, const poplar::DebugContext &debugContext = {})

Log-uniform distribution over a closed interval [minVal, maxVal].

Generates random data log-uniformly distributed in the closed interval [minVal, maxVal]. The output may be of type float, half or int. The base of the log can be specified, but defaults to the natural base.

The actual interval of the samples depends on the representable values of the outType and is a subset of the initial interval; the interval will be squeezed inward to the next representable values of outType. For example, for half, the interval [2049.0, 4098.0] would be squeezed to [2050.0, 4096.0]. Depending on the interval’s representability, this may cause spikes in the distribution at the boundaries - careful choice of interval is suggested.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the distribution.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • reference – A tensor that specifies the layout of the output tensor.

  • outType – The type of the output tensor. One of float, half or int.

  • minVal – The minimum value of the distribution.

  • maxVal – The maximum value of the distribution.

  • prog – The program to add this operation to.

  • base – Optional base of the log / exponent of the underlying uniform distribution. Defaults to Euler’s number (natural base).

  • debugContext – Optional debug information.

Throws

  • poputil::poplibs_error – If minVal < 1

  • poputil::poplibs_error – If maxVal <= minVal

  • poputil::poplibs_error – If minVal and maxVal are not suitable for the outType (for example the range is too narrow)

Returns

A tensor the same size as reference with elements having a log-uniform distribution of random values of type outType.

poplar::Tensor bernoulli(poplar::Graph &graph, const poplar::Tensor *seed, uint32_t seedModifier, const poplar::Tensor &reference, const poplar::Type &outType, double prob, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Bernoulli distribution which has the value 1 with the specified probability.

Generates a tensor with random values of 0 and 1, determined by prob.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the distribution.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • reference – A tensor that specifies the layout of the output tensor.

  • outType – The type of the output tensor. One of float, half or int.

  • prob – Probability of an element being 1.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements set to either 0 or 1. The value 1 occurs with probablility prob.

poplar::Tensor normal(poplar::Graph &graph, const poplar::Tensor *seed, uint32_t seedModifier, const poplar::Tensor &reference, const poplar::Type &outType, double mean, double stdDev, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Normal distribution with given mean and standard deviation.

Generates random data with a normal (Gaussian) distribution. The mean is given by mean and the standard deviation by stdDev.

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the distribution.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • reference – A tensor that specifies the layout of the output tensor.

  • outType – The type of the output tensor. One of float or half.

  • mean – The mean value of the distribution.

  • stdDev – The standard deviation of the distribution.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements having a normal (Gaussian) distribution of random values.

poplar::Tensor truncatedNormal(poplar::Graph &graph, const poplar::Tensor *seed, uint32_t seedModifier, const poplar::Tensor &reference, const poplar::Type &outType, double mean, double stdDev, double alpha, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Truncated normal distribution.

Generates random data with a distribution derived from a normal distribution with mean mean and standard deviation stdDev. This normal distribution is truncated symmetrically about the mean at (mean - alpha * stdDev) and (mean + alpha * stdDev)

Parameters

  • graph – The graph to add this operation to.

  • seed – If not null, this is a pair of 32-bit integers used to seed the random number generator that generates the distribution.

  • seedModifier – Provides a further modification of the seed value. Ignored if seed is null.

  • reference – A tensor that specifies the layout of the output tensor.

  • outType – The type of the output tensor. One of float or half.

  • mean – The mean value of the distribution.

  • stdDev – The standard deviation of the distribution.

  • alpha – Defines the minimum and maximum values of the distribution.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.

Returns

A tensor with elements having a truncated normal (Gaussian) distribution of random values.

void setSeed(poplar::Graph &graph, const poplar::Tensor &masterSeed, uint32_t seedModifier, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {})

Sets the random number generator seed on all tiles.

Parameters

  • graph – The graph to add this operation to.

  • masterSeed – A 64-bit integer to seed the random number on every tile.

  • seedModifier – Provides a further modification of the seed value.

  • prog – The program to add this operation to.

  • debugContext – Optional debug information.