parallel.gpu.RandStream.create

R2026b

Create independent random number streams on a GPU

Syntax

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

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

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

Description

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

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(generator,NumStreams=N) creates N random number streams that use the random number generator algorithm specified by generator. The streams are independent in a pseudorandom sense. The streams are not necessarily independent from streams created at other times.

[___] = parallel.gpu.RandStream.create(generator,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

generator — Random number generator algorithm

"threefry" | "philox" | "combRecursive"

Random number generator algorithm, specified as one of the following three random number generator names.

Name	Description	Algorithm	Multiple Stream and Substream Support	Approximate Period in Full Precision
"threefry"	Threefry 4x64 generator with 20 rounds	threefry4x64_20	Yes	2514 (2256 streams of length 2258)
"philox"	Philox 4x32 generator with 10 rounds	philox4x32_10	Yes	2193 (264 streams of length 2129)
"combRecursive"	Combined multiple recursive generator	mrg32k3a	Yes	2191 (263 streams of length 2127)

For more information on the differences between generating random numbers on the GPU and CPU, see Control Random Number Generation Across GPU and CPU.

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.

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 generator is "threefry" or "philox", the default is "BoxMuller". When generator is "combRecursive", the default is "Inversion".

The "BoxMuller" option supports the "threefry" and "philox" generators.

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 generator, NumStreams, and Seed in each case.

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

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The parallel.gpu.RandStream.create function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2011b