# rng

Control random number generator

## Syntax

``rng("default")``
``rng(seed)``
``rng(seed,generator)``
``rng(generator)``
``rng(s)``
``t = rng``
``t = rng(___)``

## Description

example

````rng("default")` initializes the MATLAB® random number generator using the default algorithm and seed. The factory default is the Mersenne Twister generator with seed 0. For information about changing the default settings and reproducibility, see Default Settings for Random Number Generator and Reproducibility for Random Number Generator.The `rng` function controls the global stream, which determines how the `rand`, `randi`, `randn`, and `randperm` functions produce a sequence of random numbers. To create one or more independent streams separate from the global stream, see `RandStream` and `RandStream.create`.```
````rng(seed)` specifies the seed for the random number generator using the current generator algorithm. Specify `seed` as a nonnegative integer, such as `rng(1)`, to initialize the random number generator with that seed.Specify `seed` as `"shuffle"` to initialize the generator seed based on the current time. ```

example

````rng(seed,generator)` also specifies the algorithm for the random number generator to use. For example, `rng(2,"philox")` initializes the Philox 4x32 generator with a seed of `2`.```
````rng(generator)` specifies the algorithm for the random number generator to use with a seed of 0. This syntax is equivalent to `rng(0,generator)`. (since R2023b)```

example

````rng(s)` initializes the 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 = rng` or `s = rng(__)`.```

example

````t = rng` returns the current random number generator settings in a structure `t` with fields `Type`, `Seed`, and `State`.```
````t = rng(___)` returns the current random number generator settings in a structure `t` before changing the settings using the specified arguments. You can specify the output argument with any of the input argument combinations in the previous syntaxes.```

## Examples

collapse all

Initialize the random number generator using the default generator algorithm and seed.

`rng("default")`

Show the default random number generator settings. In this case, the random number generator is using the Mersenne Twister algorithm with seed 0.

`s = rng`
```s = struct with fields: Type: 'twister' Seed: 0 State: [625x1 uint32] ```

Create a 4-by-4 matrix of uniformly distributed random numbers between 0 and 1.

`r = rand(4)`
```r = 4×4 0.8147 0.6324 0.9575 0.9572 0.9058 0.0975 0.9649 0.4854 0.1270 0.2785 0.1576 0.8003 0.9134 0.5469 0.9706 0.1419 ```

Starting in R2023b, you can set the default algorithm and seed from the MATLAB Preferences window. If you do not change the MATLAB preferences, then `rng` uses the factory value of `"twister"` for the Mersenne Twister generator with seed 0, as in previous releases.

Specify the random number generator settings to make the results in this example repeatable. Set the generator seed to 2 and the algorithm to Mersenne Twister, and then save the generator settings.

```rng(2,"twister") s = rng```
```s = struct with fields: Type: 'twister' Seed: 2 State: [625x1 uint32] ```

Create a 1-by-5 row vector of random values between 0 and 1.

`x = rand(1,5)`
```x = 1×5 0.4360 0.0259 0.5497 0.4353 0.4204 ```

Change the generator seed and algorithm, and create a new random row vector.

```rng(1,"philox") xnew = rand(1,5)```
```xnew = 1×5 0.5361 0.2319 0.7753 0.2390 0.0036 ```

Now restore the original generator settings and create a random vector. The result matches the original row vector `x` created with the original generator.

```rng(s) xold = rand(1,5)```
```xold = 1×5 0.4360 0.0259 0.5497 0.4353 0.4204 ```

## Input Arguments

collapse all

Random number seed, specified as a nonnegative integer less than `2^32` or `"shuffle"`. When you specify `seed` as `"shuffle"`, the `rng` function initializes the generator seed based on the current time, resulting in a different sequence of random numbers after each call to `rng`.

Random number algorithm, specified as one of the options in the table. For more information on generator algorithms, see Creating and Controlling a Random Number Stream.

ValueGenerator NameGenerator Keyword
`"twister"`Mersenne Twistermt19937ar
`"simdTwister"`SIMD-Oriented Fast Mersenne Twisterdsfmt19937
`"combRecursive"`Combined Multiple Recursivemrg32k3a
`"multFibonacci"`Multiplicative Lagged Fibonaccimlfg6331_64
`"philox"`Philox 4x32 generator with 10 roundsphilox4x32_10
`"threefry"`Threefry 4x64 generator with 20 roundsthreefry4x64_20

For legacy generators used in MATLAB versions 4.0 and 5.0, use one of these options.

ValueGenerator NameGenerator Keyword
`"v4"`Legacy MATLAB version 4.0 generatormcg16807
`"v5uniform"`Legacy MATLAB version 5.0 uniform generatorswb2712
`"v5normal"`Legacy MATLAB version 5.0 normal generatorshr3cong

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

collapse all

### Default Settings for Random Number Generator

• You can change the default algorithm and seed for the random number generator from the MATLAB Preferences window. On the Home tab, in the Environment section, click . Select MATLAB > General, and then select a different option for Default algorithm and select a different value for Default seed in the Random Number Generation preference. (since R2023b)

When you first start a MATLAB session or call `rng("default")`, MATLAB initializes the random number generator using the default algorithm and seed that you have set in the MATLAB preferences. If you do not change the Random Number Generation preference, then `rng` uses the factory value of `"twister"` for the Mersenne Twister generator with seed 0, as in previous releases.

• If you use parallel workers (requires Parallel Computing Toolbox™), `rng("default")` initializes the Threefry 4x64 generator with 20 rounds and a seed value of 0. Changing the default generator settings in the MATLAB Preferences window does not affect the default behavior of the parallel workers. (since R2023a)

### Reproducibility for Random Number Generator

Use `rng("default")` at the start of your program if you want results to be repeatable within a MATLAB session. `rng("default")` uses the default algorithm and seed that are specified in your MATLAB preferences. However, this command does not guarantee the same results between different MATLAB sessions with different preferences.

Instead, use `rng(seed,generator)` or `rng(generator)` at the start of your program if you want results to remain the same in future MATLAB releases or when the default algorithm and seed have been changed in your MATLAB preferences. For example, use `rng("twister")` to use the Mersenne Twister generator with seed 0.

## Tips

• When you perform parallel processing, do not use `rng("shuffle")` to set the random number stream on different workers for independent streams because it seeds the random number generator based on the current time. The `rng` function uses the same seed when the command is sent to multiple workers simultaneously, such as inside a `parfor` job. For independent streams on the workers, use the default behavior or consider using a unique substream on each worker using `RandStream`.

• When you perform parallel processing, the default random number generators on the MATLAB client and MATLAB workers are different. By default, the MATLAB client uses the Mersenne Twister generator with seed 0 and the MATLAB workers use the Threefry 4x64 generator with 20 rounds with seed 0. Changing the default generator settings in the MATLAB preferences affects only the default behavior of the client and does not affect the default behavior of the parallel workers. If you need to generate the same random stream of numbers on the client and workers, you can use `rng` with the same generator algorithm and seed (or consider using `RandStream` with the same generator algorithm, seed, and normal transformation algorithm). For more information, see Control Random Number Streams on Workers (Parallel Computing Toolbox).

• To use `rng` instead of the `rand` or `randn` functions with the `"seed"`, `"state"`, or `"twister"` inputs, see Replace Discouraged Syntaxes of rand and randn.

## Version History

Introduced in R2011a

expand all