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. If you use a GPU random number stream, then the results are returned as a 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.

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.

example

s = parallel.gpu.RandStream(gentype,Name=Value) specifies options using one or more name-value arguments in addition to the generator algorithm argument. For example, to seed the random number generator based on the current time, set Seed to "shuffle".

example

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.

Example: s = parallel.gpu.RandStream("Philox")

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: s = parallel.gpu.RandStream("Philox",Seed="shuffle")

Random number seed, specified as a nonnegative integer or as "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.

This argument sets the Seed property.

The normal transformation algorithm to use when generating normally distributed random numbers generated using the randn function, specified as "BoxMuller" or "Inversion".

When gentype is "Threefry" or "Philox", the default is "BoxMuller". When gentype is "CombRecursive", the default is "Inversion".

The "BoxMuller" option supports the "Threefry" and "Philox" generator types only.

This argument sets the NormalTransform property.

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

This argument sets the StreamIndex property.

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. 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 specify the state, use a value previously read from a parallel.gpu.RandStream object. Alternatively, you can use reset to return a stream to a predictable state without having previously read from the State property.

This argument sets the State property.

Properties

expand all

This property is read-only after object creation. To set this property, use the gentype argument when you create the stream.

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

Data Types: char

To set this property, use the Seed argument when you create the stream or use the reset function.

Random number seed, specified as a nonnegative integer. The seed specifies the starting point for the algorithm to generate random numbers. Specify Seed as an integer when you want reproducible results.

The normal transformation algorithm to use when generating normally distributed random numbers generated using the randn function, specified as 'BoxMuller' or 'Inversion'.

When gentype is "Threefry" or "Philox", the default is 'BoxMuller'. When gentype is "CombRecursive", the default is 'Inversion'.

The 'BoxMuller' option supports the "Threefry" and "Philox" generator types only.

Data Types: char

This property is read-only after object creation.

Number of streams in the group in which the current stream was created, represented 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 identifies 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 specify the state, use a value previously read from a parallel.gpu.RandStream object. Alternatively, you can use reset to return a stream to a predictable state without having previously read from the State property.

This property is read-only.

Antithetic values, represented as 0 (false). 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.

Data Types: logical

This property is read-only.

Full precision generation, represented as 1 (true). 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.

Data Types: logical

Object Functions

parallel.gpu.RandStream.createCreate independent random number streams on a GPU
parallel.gpu.RandStream.listList random number generator algorithms on the GPU
parallel.gpu.RandStream.getGlobalStreamGet current 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 4x32 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,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

expand all

Version History

Introduced in R2011b

See Also

|

Topics