Main Content

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 gpuArrays. 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.

Description

example

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

example

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

Input Arguments

expand all

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

KeywordGeneratorMultiple Stream and Substream SupportApproximate Period in Full Precision
'Threefry' or 'Threefry4x64_20'Threefry 4x64 generator with 20 roundsYes2514 (2256 streams of length 2258)
'Philox' or 'Philox4x32_10'Philox 4x32 generator with 10 roundsYes2193 (264 streams of length 2129)
'CombRecursive' or 'mrg32k3a'Combined multiple recursive generatorYes2191 (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

expand all

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

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.

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.

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.

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.

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

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

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.createCreate independent random number streams on a GPU
parallel.gpu.RandStream.listRandom number generator algorithms on the GPU
parallel.gpu.RandStream.getGlobalStreamCurrent global GPU random number stream
parallel.gpu.RandStream.setGlobalStreamSet 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:

randUniformly 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.

randiUniformly distributed pseudorandom integers
randnNormally distributed random numbers
randpermRandom 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

collapse all

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.

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,10)
rG = rand(1,10, 'gpuArray')
rC =
    0.1726    0.9207    0.8108    0.7169    0.8697    0.7920    0.4159    0.6503    0.1025    0.6166

rG =
    0.1726    0.9207    0.8108    0.7169    0.8697    0.7920    0.4159    0.6503    0.1025    0.6166

rnC = randn(1,10)
rnG = randn(1,10, 'gpuArray')
rnC =
    -0.9438    1.4095    0.8807    0.5736    1.1250    0.8133   -0.2124    0.3862   -1.2673    0.2966

rnG =
    -0.9438    1.4095    0.8807    0.5736    1.1250    0.8133   -0.2124    0.3862   -1.2673    0.2966
Introduced in R2011b