parallel.gpu.RandStream.create

Create independent random number streams on a GPU

Syntax

s = parallel.gpu.RandStream.create(gentype)

[s1,s2,...] = parallel.gpu.RandStream.create(gentype,NumStreams=N)

[___] = parallel.gpu.RandStream.create(gentype,Name=Value)

Description

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

Note

The parallel.gpu.RandStream object creation function is a more concise alternative when you want to create a single stream.

[s1,s2,...] = parallel.gpu.RandStream.create(gentype,NumStreams=N) creates N random number streams that use the random number generator algorithm specified by gentype. The streams are independent in a pseudorandom sense. The streams are not necessarily independent from streams created at other times.

[___] = parallel.gpu.RandStream.create(gentype,Name=Value) also specifies additional name-value arguments to control the creation of the stream in addition to the input arguments in the previous syntaxes. For example, to seed the random number generator based on the current time, set Seed to "shuffle".

Examples

Create Multiple Random Number Streams Simultaneously

You can create multiple independent random number streams that have the same generator, seed, and normal transformations. Here, several independent streams are created and then used to generate independent streams of random numbers.

First, create the streams as a cell array.

streams = parallel.gpu.RandStream.create("Philox",NumStreams=3, ...
          Seed=1,NormalTransform="Inversion",CellOutput=true)

streams =

  1×3 cell array

    {1×1 parallel.gpu.RandStream}    {1×1 parallel.gpu.RandStream}    {1×1 parallel.gpu.RandStream}

Now, you can use each stream to generate random numbers. In this example, you create a matrix in which each row is generated from a different random number stream.

x = zeros(3,10,"gpuArray");
for i=1:3
   x(i,:) = rand(streams{i},1,10);
end
x

x =
    0.9576    0.0054    0.2543    0.0540    0.1697    0.1365    0.7560    0.1312
    0.3084    0.3396    0.6758    0.5145    0.7909    0.7709    0.3386    0.1168
    0.5218    0.5625    0.7090    0.5854    0.5067    0.6528    0.5095    0.8777

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.

Example: parallel.gpu.RandStream.create("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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: parallel.gpu.RandStream.create("Philox",Seed=10) creates a single random number stream using the Philox 4x32 generator algorithm with seed 10.

NumStreams — Number of streams

1 (default) | positive integer

Number of independent streams to be created, specified as a positive integer. The streams are independent in a pseudorandom sense. The streams are not necessarily independent from streams created at other times.

StreamIndices — Indices of the streams

[1:N] (default) | vector of positive integers | positive integer

Indices of the streams created in this function call, specified as a positive integer or vector of positive integers. The default value is 1:N, where N is the value specified with the NumStreams parameter.

The values provided for StreamIndices must be less than or equal to the value provided for NumStreams.

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.

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.

CellOutput — Option to return streams as cell array

0 (false) (default) | 1 (true)

Option to return the stream objects as a cell array, specified as 0 (false) or 1 (true).

Output Arguments

s — Random number stream

parallel.gpu.RandStream object

Random number stream for generating random numbers on a GPU, returned as a parallel.gpu.RandStream object.

Tips

• If you create multiple streams by calling parallel.gpu.RandStream.create several times, the streams are not necessarily independent of each other. To create independent streams from separate calls of parallel.gpu.RandStream.create:

  • Specify the same set of values for gentype, NumStreams, and Seed in each case.

  • Specify a different value for StreamIndices that is between 1 and the NumStreams value in each case.

Version History

Introduced in R2011b