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

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

Input Arguments

gentype — Random number generator algorithm

"Threefry" | "Philox" | "CombRecursive"

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.

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

Name-Value Arguments

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")

Seed — Random number seed

0 (default) | nonnegative integer | "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.

NormalTransform — Normal transformation algorithm

"BoxMuller" | "Inversion"

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.

StreamIndex — Stream index

positive integer

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.

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

Type — Random number generator algorithm

'Threefry4x64_20' | 'Philox4x32_10' | 'MRG32K3A'

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

Seed — Random number seed

0 (default) | nonnegative integer

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.

NormalTransform — Normal transformation algorithm

'BoxMuller' | 'Inversion'

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

NumStreams — Number of Streams

positive integer

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.

StreamIndex — Stream index

positive integer

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.

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

Antithetic — Antithetic values

Read-only: 0 (false)

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

FullPrecision — Full precision generation

Read-only: 1 (true)

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.create	Create independent random number streams on a GPU
parallel.gpu.RandStream.list	List random number generator algorithms on the GPU
parallel.gpu.RandStream.getGlobalStream	Get 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 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:

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