Main Content

parallel.gpu.RandStream.create

Create independent random number streams on a GPU

collapse all in page

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 pairs to control the creation of the stream, including the number of independent streams to create.

example

Examples

collapse all

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

collapse all

Random number generator, specified as a character vector or string for any valid random number generator that supports multiple streams and substreams. 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.

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' generator algorithm with seed 10.

Number of independent streams to be created, specified as the comma-separated pair consisting of 'NumStreams' and a non-negative integer. The streams are independent in a pseudorandom sense. The streams are not necessarily independent from streams created at other times.

Indices of the streams created in this function call, specified as the comma-separated pair consisting of 'StreamIndices' and a nonnegative integer or a vector of nonnegative 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'.

Random number seed for all streams initialized, specified as the comma-separated pair consisting of 'Seed' and a nonnegative integer. The seed specifies the starting point for the algorithm to generate random numbers.

Transformation algorithm for normally distributed random numbers generated using the randn function, 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.

Logical flag indicating whether to return the stream objects as elements of a cell array, specified as the comma-separated pair 'CellOutput' and the logical value 0 or 1. The default value is false.

Output Arguments

collapse all

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

See Also

| | | |