gpurng - Control random number generation on the GPU - MATLAB (original) (raw)

Control random number generation on the GPU

Syntax

Description

gpurng("default") initializes the GPU random number generator using the default algorithm and seed. The default algorithm is theThreefry generator with seed 0. 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](#mw%5Fa9419a4d-256f-43ae-b6de-f9f54b61a950)) specifies the seed for the GPU random number generator using the current generator algorithm.

• Specify seed as a nonnegative integer, such asgpurng(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 callgpurng.

gpurng([seed](#mw%5Fa9419a4d-256f-43ae-b6de-f9f54b61a950),[generator](#mw%5Fea49b8c7-ba44-4cc2-bfc0-399ec953b250)) 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.

example

gpurng([generator](#mw%5Fea49b8c7-ba44-4cc2-bfc0-399ec953b250)) 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](#mw%5Faf02355c-e935-4f1b-a120-e2176700c641)) initializes the state of the random number generator based on settings contained in a structure S with fields Type, Seed, andState. The structure S must be a structure that is returned by a previous call to S = gpurng orS = gpurng(__).

[S](#mw%5Faf02355c-e935-4f1b-a120-e2176700c641) = gpurng returns the current state of the random number generator as a structure S with fieldsType, Seed, andState.

[S](#mw%5Faf02355c-e935-4f1b-a120-e2176700c641) = gpurng(___) returns the current state 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 MATLABSettings Window window affect random numbers generated on the CPU only and do not affect calls to gpurng("default").

Examples

collapse all

Capture the GPU generator settings, and set the state 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 = struct with fields: Type: 'threefry' Seed: 0 State: [17×1 uint32]

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

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

The gpurng state does 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

collapse all

Random number seed, specified as a nonnegative integer 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 togpurng.

Example: gpurng(7)

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.

The default generator is Threefry.

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

Previous random number generator state, specified as a structure previously created using S = gpurng.

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

Data Types: struct

Output Arguments

collapse all

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

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

Data Types: struct

Extended Capabilities

Version History

Introduced in R2011b

expand all

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 togpurng(0,generator). For example,gpurng("philox") initializes the Philox 4x32 generator with a seed of 0.

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

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.