rng

Control random number generator

Syntax

rng(seed)

rng(seed,generator)

s = rng

Description

rng(seed) specifies the seed for the MATLAB^® random number generator. For example, rng(1) initializes the Mersenne Twister generator using a seed of 1.

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,generator) also specifies the type of random number generator to use. For example, rng(0,'philox') initializes the Philox 4x32 random generator with a seed of 0.

s = rng returns the current random number generator settings in a structure s.

Examples

Set and Restore Generator Settings

Set the random number generator to the default seed (0) and algorithm (Mersenne Twister), then save the generator settings.

rng('default')
s = rng

s = struct with fields:
     Type: 'twister'
     Seed: 0
    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.8147    0.9058    0.1270    0.9134    0.6324

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 default generator.

rng(s)
xold = rand(1,5)

xold = 1×5

    0.8147    0.9058    0.1270    0.9134    0.6324

Input Arguments

seed — Generator initialization

0 (default) | positive integer | 'default' | 'shuffle' | structure

Generator initialization, specified as one of these options.

Value	Description
0	Initialize the generator with a seed of 0.
positive integer	Initialize the generator with the specified positive integer seed, such as 1.
'default'	Initialize the Mersenne Twister generator with a seed value of 0. Each MATLAB session starts with this default setting. If you use parallel workers (requires Parallel Computing Toolbox™), 'default' initializes the Threefry 4x64 generator with 20 rounds and a seed value of 0. (since R2023a)
'shuffle'	Initialize the generator based on the current time, resulting in a different sequence of random numbers after each call to rng.
structure	Initialize the generator based on the settings contained in a structure with fields Type, Seed, and State.

generator — Random number algorithm

'twister' (default) | 'simdTwister' | 'combRecursive' | 'multFibonacci' | 'philox' | 'threefry'

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.

Value	Generator Name	Generator Keyword
'twister'	Mersenne Twister	mt19937ar
'simdTwister'	SIMD-oriented Fast Mersenne Twister	dsfmt19937
'combRecursive'	Combined multiple recursive	mrg32k3a
'multFibonacci'	Multiplicative Lagged Fibonacci	mlfg6331_64
'philox'	Philox 4x32 generator with 10 rounds	philox4x32_10
'threefry'	Threefry 4x64 generator with 20 rounds	threefry4x64_20

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

Value	Generator Name	Generator Keyword
'v4'	Legacy MATLAB version 4.0 generator	mcg16807
'v5uniform'	Legacy MATLAB version 5.0 uniform generator	swb2712
'v5normal'	Legacy MATLAB version 5.0 normal generator	shr3cong

Tips

• When you perform parallel processing, do not use rng('shuffle') to set the random number stream on different workers to ensure independent streams since it seeds the random number generator based on the current time. This is especially true 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. If you need to generate the same random stream of numbers on the client and workers, you can use rng with the same generator type and seed (or consider using RandStream with the same generator type, 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.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Only the 'twister', 'v5normal', and 'v4' generators are supported.

• The generated code for rng('shuffle') might produce different seeds than MATLAB produces.

• For a MEX target:

  • If extrinsic calls are disabled or rng is called inside a parfor loop, the output of rng in the MEX function is not compatible with the rng function in MATLAB. You cannot pass the output of s = rng from the MEX function to rng in MATLAB.

  • If extrinsic calls are enabled and rng is not called from inside a parfor loop, only rng can access the data in the structure that rng returns.

  • If extrinsic calls are enabled and rng is not called from inside a parfor loop, generated MEX files use the same random number state as MATLAB in serial code. Otherwise, the generated MEX code and standalone code maintain their own random number state that is initialized to the same state as MATLAB.

Thread-Based Environment

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

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

Version History

Introduced in R2011a

R2023a: On MATLAB parallel workers, rng('default') sets random number generator settings to worker default

When you use the syntax rng('default') on MATLAB parallel workers (requires Parallel Computing Toolbox), MATLAB resets the random number generator settings to the worker default values. The default corresponds to the Threefry generator with 20 rounds and a seed value of 0.

In previous releases, when you use rng('default') on parallel workers, MATLAB changes the worker random number generator settings to the client default values. The default corresponds to the Mersenne Twister generator with a seed value of 0.