parallel.gpu.RandStream

Random number stream on a GPU

Description

Use parallel.gpu.RandStream to control the global GPU random number stream and create multiple independent streams on the GPU. When you generate random numbers on a GPU, the numbers are drawn from the GPU random number stream. This stream is different from the random stream of the client MATLAB^® session on the CPU.

To create random numbers on the GPU, use the random number generator functions rand, randi, and randn with gpuArray. By default, these functions draw numbers from the global GPU random number stream. To use a different stream, follow the syntaxes described in Object Functions. If you use a GPU random number stream, the results are returned as a gpuArray.

Creation

Use the following syntaxes to create a single parallel.gpu.RandStream object. If you want to create multiple independent streams simultaneously, use the parallel.gpu.RandStream.create function.

Syntax

s = parallel.gpu.RandStream(gentype)

s = parallel.gpu.RandStream(gentype,Name,Value)

Description

s = parallel.gpu.RandStream(gentype) creates a random number stream that uses the uniform pseudorandom number generator algorithm specified by 'gentype'.

s = parallel.gpu.RandStream(gentype,Name,Value) also specifies one or more optional Name,Value pairs to control properties of the stream.

Input Arguments

gentype — Random number generator algorithm

'Threefry' or 'Threefry4x64_20' | 'Philox' or 'Philox4x32_10' | 'CombRecursive' or 'mrg32k3a'

Random number generator algorithm, specified as one of the following three random number generator algorithms supported on the GPU.

Keyword	Generator	Multiple Stream and Substream Support	Approximate Period in Full Precision
"Threefry" or "Threefry4x64_20"	Threefry 4x64 generator with 20 rounds	Yes	2514 (2256 streams of length 2258)
"Philox" or "Philox4x32_10"	Philox 4x32 generator with 10 rounds	Yes	2193 (264 streams of length 2129)
"CombRecursive" or "mrg32k3a"	Combined multiple recursive generator	Yes	2191 (263 streams of length 2127)

For more information on the differences between generating random numbers on the GPU and CPU, see Random Number Streams on a GPU.

This argument sets the Type property.

Properties

Type — Random number generator algorithm

'Threefry4x64_20' | 'Philox4x32_10' | 'MRG32K3A'

This property is read-only.

Generator algorithm used by the stream specified as 'Threefry4x64_20', 'Philox4x32_10', or 'mrg32k3a'.

Set this property using the gentype argument when you create the stream.

Data Types: char

Seed — Random number seed

0 (default) | nonnegative integer | 'shuffle'

This property is read-only.

Random number seed, specified as the comma-separated pair consisting of 'Seed' and a nonnegative integer or as the string or character vector 'shuffle'. The seed specifies the starting point for the algorithm to generate random numbers. Specify 'Seed' as an integer when you want reproducible results. Specifying 'Seed' as 'shuffle' seeds the generator based on the current time.

Set this property as a name-value pair when you create the stream.

NumStreams — Number of Streams

positive integer

This property is read-only.

Number of streams in the group in which the current stream was created, specified as a positive integer. Create multiple streams at once using the function parallel.gpu.RandStream.create.

StreamIndex — Stream index

positive integer

Stream index of the current stream, specified as a positive integer. The stream index identified individual streams when you create multiple streams at once using the function parallel.gpu.RandStream.create.

State — Current state

vector

Current state of the random number stream, specified as a vector. The internal state determines the sequence of random numbers produced by the random number stream s. The size of this state vector depends on the generator chosen.

Saving and restoring the internal state of the generator with the State property allows you to reproduce a sequence of random numbers. When you set this property, the value, you assign to s.State must be a value read from s.State previously. Use reset to return a stream to a predictable state without having previously read from the State property.

NormalTransform — Normal transformation algorithm

'BoxMuller' | 'Inversion'

Normal transformation algorithm, specified as 'BoxMuller or 'Inversion'.

The normal transformation algorithm specifies the algorithm to use when generating normally distributed random numbers generated using randn. The 'BoxMuller' algorithm is supported for the 'Threefry and 'Philox' generators. The 'Inversion' algorithm is supported for the 'CombRecursive' generator. No other transformation algorithms are supported on the GPU.

Data Types: char

Antithetic — Antithetic values

false or 0 (default)

This property is read-only.

Antithetic values, specified as false or 0. This property indicates whether S generates antithetic pseudorandom values, that is, the usual values subtracted from 1 for uniform values.

This property is always 0. The stream does not generate antithetic values. You cannot modify this property.

Data Types: logical

FullPrecision — Full precision generation

true or 1 (default)

This property is read-only.

Full precision generation, specified as true or 1. This property indicates whether the random number stream generates values using full precision. Two random numbers are consumed to ensure all bits of a double are set.

This property is always 1. You cannot modify this property.

Data Types: logical

Object Functions

parallel.gpu.RandStream.create	Create independent random number streams on a GPU
parallel.gpu.RandStream.list	Random number generator algorithms on the GPU
parallel.gpu.RandStream.getGlobalStream	Current global GPU random number stream
parallel.gpu.RandStream.setGlobalStream	Set GPU global random number stream
reset (RandStream)	Reset random number stream

By default, when you create random numbers on the GPU using random number generation functions, such as rand, the random numbers are drawn from the global random number stream on the GPU. To specify a different stream, create a parallel.gpu.RandStream object and pass it as the first input argument. For instance, create a 4-by-1 vector of random numbers using the Philox generator algorithm.

s = parallel.gpu.RandStream('Philox');
r = rand(s,4,1);

These functions accept a parallel.gpu.RandStream object and generate random numbers on the GPU:

rand	Uniformly distributed random numbers	Supported syntaxes, where s is a parallel.gpu.RandStream object: X = rand(s) X = rand(s,n) X = rand(s,sz1,...,szN) X = rand(s,sz) X = rand(s,typename) For details on other input arguments, see rand, randi, and randn.
randi	Uniformly distributed pseudorandom integers
randn	Normally distributed random numbers
randperm	Random permutation of integers	Supported syntaxes, where s is a parallel.gpu.RandStream object: p = randperm(s,n) p = randperm(s,n,k) For details on other input arguments, see randperm.

Examples

Change the Global GPU Stream

You can change the global random number stream on the GPU. First, define the random number stream that you want to set as the new global stream.

newStr = parallel.gpu.RandStream('Philox')

newStr =

Philox4x32_10 random stream on the GPU
             Seed: 0
  NormalTransform: BoxMuller

Next, set this new stream to be the global stream.

parallel.gpu.RandStream.setGlobalStream(newStr);

Check that newStr is now the current global stream.

newStr

newStr =

Philox4x32_10 random stream on the GPU (current global stream)
             Seed: 0
  NormalTransform: BoxMuller

On a GPU, the functions rand, randi, and randn now draw random numbers from the new global stream using the 'Philox' generator algorithm.

Match the GPU and CPU Random Number Streams

If you have applications that require generating the same random numbers on the GPU and the CPU, you can set the streams to match. Create matching streams on both the GPU and CPU, and set them as the global stream in each case.

stCPU = RandStream('Threefry','Seed',0,'NormalTransform','Inversion');
stGPU = parallel.gpu.RandStream('Threefry','Seed',0,'NormalTransform','Inversion');

Only the 'Inversion' normal transformation algorithm is available on both the GPU and CPU.

Set these streams to be the global streams on the CPU and GPU, respectively.

RandStream.setGlobalStream(stCPU);
parallel.gpu.RandStream.setGlobalStream(stGPU);

Calling rand and randn now produces the same sets of numbers on both the GPU and the client MATLAB session.

rC = rand(1,8)
rG = rand(1,8, 'gpuArray')

rC =
    0.1726    0.9207    0.8108    0.7169    0.8697    0.7920    0.4159    0.6503

rG =
    0.1726    0.9207    0.8108    0.7169    0.8697    0.7920    0.4159    0.6503

rnC = randn(1,8)
rnG = randn(1,8, 'gpuArray')

rnC =
    -0.9438    1.4095    0.8807    0.5736    1.1250    0.8133   -0.2124    0.3862

rnG =
    -0.9438    1.4095    0.8807    0.5736    1.1250    0.8133   -0.2124    0.3862

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2011b