gpurng

R2026b

Control random number generation on the GPU

Syntax

gpurng("default")

gpurng(seed)

gpurng(seed,generator)

gpurng(generator)

gpurng(s)

s = gpurng

s = gpurng(___)

Description

gpurng("default") initializes the GPU random number generator using the default algorithm and seed. The default algorithm is the Threefry 4x64 generator with seed 0. If the GPU is part of a cluster, each GPU in a cluster working on the same job has an independent random number stream. The random numbers produced are the same as if you had restarted MATLAB^®.

The gpurng function controls the global GPU stream, which determines how the rand, randi, randn, and randperm functions produce a sequence of random numbers on the GPU. To create one or more independent streams separate from the global GPU stream, see parallel.gpu.RandStream.

gpurng(seed) specifies the seed for the GPU random number generator using the current generator algorithm.

• Specify seed as a nonnegative integer, such as gpurng(1), to initialize the GPU random number generator with that seed.

• Specify seed as "shuffle" to initialize the generator seed based on the current time so that rand, randi, randn, and randperm produce different sequences of numbers after each time you call gpurng.

gpurng(seed,generator) also specifies the algorithm for the GPU random number generator to use. For example, gpurng(2,"philox") initializes the Philox 4x32 generator with a seed of 2.

gpurng(generator) specifies the algorithm for the GPU random number generator to use with a seed of 0. This syntax is equivalent to gpurng(0,generator). (since R2023b)

gpurng(s) restores the random number generator based on the settings contained in a structure s with fields Type, Seed, and State. The structure s must be a structure that is returned by a previous call to s = gpurng or s = gpurng(__).

s = gpurng returns the current settings of the random number generator as a structure s with fields Type, Seed, and State.

s = gpurng(___) returns the current settings of the random number generator in a structure s before changing the settings using the specified arguments.

Note

The default algorithm and seed for the random number generator in the MATLAB Settings Window window affect random numbers generated on the CPU only and do not affect calls to gpurng("default").

Examples

Create Predictable Arrays of Random Numbers on the GPU and CPU

Capture the GPU generator settings, and set the settings of the CPU random number generator to match the GPU generator settings. Create predictable arrays of random numbers on the CPU and GPU.

Restore the generator type and seed to their default values on both the CPU and the GPU.

gpurng("default") 
rng("default")

Save the default seed and generator type of the GPU random number generator.

GPUdef = gpurng

GPUdef = struct with fields:
     Type: 'threefry'
     Seed: 0
    State: [17×1 uint32]

Set the CPU random number generator to match the default GPU settings.

rng(GPUdef) 

Create an array of uniformly distributed random numbers on the GPU.

rGPU = rand(1,10,"gpuArray")

rGPU =

    0.3640    0.5421    0.6543    0.7436    0.0342    0.8311    0.7040    0.2817    0.1163    0.5671

Create an array of random numbers on the CPU.

rCPU = rand(1,10)

rCPU = 1×10

    0.3640    0.5421    0.6543    0.7436    0.0342    0.8311    0.7040    0.2817    0.1163    0.5671

The seed and generator type are the same for both the GPU and the CPU, so the arrays are the same.

isequal(rGPU,rCPU)

ans = logical
   1

The gpurng settings do not save the settings for the transformation applied to generate a normally distributed set of random numbers. Even though the seed and the generator type are the same on the GPU and the CPU, the set of normally distributed random numbers is different.

nGPU = randn(1,1000,"gpuArray");
nCPU = randn(1,1000);

figure
hold on
histogram(nGPU)
histogram(nCPU)
legend("GPU","CPU")
title("Normally Distributed Random Numbers")
xlabel("Value")
ylabel("Count")
hold off

The statistics of the normal distribution of random numbers are the same on the GPU and the CPU.

By default, the CPU uses the Ziggurat transformation, while the GPU uses the BoxMuller algorithm for the Threefry generator. The only transformation method supported on both the CPU and GPU is the Inversion transform.

You can change the transformation method on the GPU using parallel.gpu.RandStream.

Input Arguments

seed — Random number seed

0 (default) | nonnegative integer | "shuffle"

Random number seed, specified as a nonnegative integer less than 2^32 or "shuffle". The seed specifies the starting point for the algorithm to generate random numbers. Specify the seed as a nonnegative integer when you want reproducible results. The default seed is 0.

When you specify the seed as "shuffle", the software initializes the generator seed based on the current time, resulting in a different sequence of random numbers after each call to gpurng.

Example: gpurng(7)

generator — Random number generator

"threefry" (default) | "philox | "combRecursive"

Random number generator, specified as a character vector or string for any valid generator that supports multiple streams and substreams. Three random number generator algorithms are supported on the GPU.

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 Streams on Workers.

Example: gpurng("philox")

s — Previous random number generator settings

structure

Previous random number generator settings, specified as a structure previously created using s = gpurng.

Example: s = gpurng captures the current settings of the random number generator, and gpurng(s) restores the generator to those settings.

Data Types: struct

Output Arguments

s — Random number generator settings

structure

Random number generator settings, returned as a structure with fields Type, Seed, and State.

Example: s = gpurng captures the current settings of the random number generator, and gpurng(s) restores the generator to those settings.

Data Types: struct

Extended Capabilities

Thread-Based Environment

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

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

Version History

Introduced in R2011b

R2023b: Specify random number algorithm without specifying seed

Use the new syntax gpurng(generator) to specify the algorithm for the random number generator to use. This syntax allows you to set the random number algorithm without specifying the seed, where gpurng uses a seed of 0. This syntax is equivalent to gpurng(0,generator). For example, gpurng("philox") initializes the Philox 4x32 generator with a seed of 0.

R2019a: Default random number generator change for gpurng

Starting in R2019a, the default random number generator for parallel computations is changed to "threefry". This generator offers performance enhancements for parallel calculations over the previous default. In releases up to R2018b, the default random number generator for parallel computations is "combRecursive".

With a different default generator, MATLAB generates different random numbers sequences by default in the context of parallel computations. However, statistics of these calculations remain unaffected. Therefore, you might want to update any code that relies on the specific random numbers being generated, but most calculations on the random numbers are unaffected.

To set the generator to the settings used by default in R2018b and earlier on GPU arrays, use the following command.

gpurng(0,"combRecursive")

R2018a: parallel.gpu.rng is renamed to gpurng

Starting in R2018a, the function parallel.gpu.rng is renamed to gpurng. Replace all instances of parallel.gpu.rng with gpurng.

parallel.gpu.rng will continue to work but is not recommended.