parallel.gpu.RandStream

Random number stream on a GPU

expand all in page

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 the RandStream object functions rand (RandStream), randi (RandStream), and randn (RandStream). 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

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 a character vector or string for any valid random number generator. Three random number generator algorithms are 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.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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.

Transformation algorithm for normally distributed random numbers generated using the randn (RandStream), specified as the comma-separated pair 'NormalTransform' and the algorithm names 'BoxMuller' or 'Inversion'. 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.

Properties

expand all

This property is read-only.

Generator algorithm used by the stream.

Data Types: char

This property is read-only.

Seed value used to create the stream

This property is read-only.

Number of streams in the group in which the current stream was created.

Index of the current stream from among the group of streams with which it was created.

Current state of the random number stream. 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.

Transformation algorithm used to generate normally distributed pseudorandom values using randn.

Data Types: char

This property is read-only.

Logical value indicating whether S generates antithetic pseudorandom values, that is, the usual values subtracted from 1 for uniform values. You cannot set this property.

Data Types: logical

This property is read-only.

Logical value indicating whether the random number stream generates values using its full precision. Two random numbers are consumed to ensure all bits of a double are set. 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
rand (RandStream)Uniformly distributed random numbers
randi (RandStream)Uniformly distributed pseudorandom integers
randn (RandStream)Normally distributed pseudorandom numbers
randperm (RandStream)Random permutation

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

See Also

|

Topics

Introduced in R2011b

Parallel Computing Toolbox Documentation
Support