Main Content

# gpurng

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` 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)` 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`.```

example

````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)` initializes the state of the random number generator based on 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 state of the random number generator as a structure `S` with fields `Type`, `Seed`, and `State`.```
````S = 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 MATLAB Preferences 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 = 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` 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 to `gpurng`.

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.

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)

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`

## Version History

Introduced in R2011b

expand all